Annotation of ExtFile/doc-1.1/README.txt, revision 1.1.1.1
1.1 dwinter 1: ExtFile/ExtImage Product, Version 1.1.x
2: Copyright (c) 2001 Gregor Heine (mac.gregor@gmx.de). All rights reserved.
3: ExtFile Home: http://www.zope.org/Members/MacGregor/ExtFile/index_html
4:
5:
6: =============================
7: Contents
8: =============================
9:
10: 1. Product Description
11: 2. Requirements
12: 3. Installation Instructions
13: 4. Usage
14: 4.1. Creation of an ExtFile/ExtImage object
15: 4.2. Public methods ('View' permission)
16: 4.3. Management methods
17: 4.4. The 'Download ExtFile/ExtImage' permission
18: 5. Additional settings
19: 5.1. Directory structure
20: 5.2. Filename generation
21: 5.3. Undo handling
22: 6. Method appendix
23: 6.1. ExtFile/ExtImage public methods
24: 6.2. Additional public methods for ExtImage
25: 7. Supported image formats
26:
27:
28: =============================
29: 1. Product Description
30: =============================
31:
32: The ExtFile Product stores large files in an external file-repository and is
33: able to display icons for different MIME-Types.
34: The ExtImage Product additionally creates preview-thumbnails from various
35: images and displays them.
36:
37: ExtFile and ExtImage basically work like the Zope File and Image products. The
38: difference is, that the File/Image Products stores the (binary) file inside the
39: ZODB, wheras ExtFile/ExtImage stores it externally in a repository directory
40: (default: <zope-dir>/var/reposit). Only meta data (like title and description)
41: are stored in the Database. This prevents the Database swelling up quickly,
42: when many large files are uploaded and thus increasing database performance.
43:
44: And what about LocalFS? Doesn't it do the same thing?
45: The difference between ExtFile/ExtImage and LocalFS is that you create one
46: LocalFS object to access many files, whereas you create one ExtFile object per
47: file. LocalFS works like a window through which you get access to files outside
48: the Database. ExtFile/ExtImage on the other hand has a one-to-one relation
49: between files and objects - you create one ExtFile/ExtImage object for each
50: file.
51:
52: ExtFile/ExtImage has full Zope Cut/Copy/Paste and Undo Support.
53:
54:
55: =============================
56: 2. Requirements
57: =============================
58:
59: Any Zope 2.x will do. (Tested with 2.1.6, 2.2.2 and 2.3.0)
60: The ExtImage Product requires PIL (Python Imaging Library,
61: http://www.pythonware.com/products/pil/index.htm) to create preview-images.
62:
63:
64: =============================
65: 3. Installation Instructions
66: =============================
67:
68: Unzip the tarball in your Products directory and restart zope.
69: If you like to configure the handling and structuring of the external files in
70: the repository see 5. Additional settings
71:
72:
73: =============================
74: 4. Usage
75: =============================
76:
77: 4.1. Creation of an ExtFile/ExtImage object
78: Create an instance of ExtFile or ExtImage by adding an ExtFile-item (resp.
79: ExtImage) in the Zope management screen.
80: Choose a file (required) and enter an id, a title and a description (optional).
81: If no id is entered, the filename is used as id.
82: For ExtImage you can choose, if you do not want any preview, if ExtImage shold
83: generate a preview image from the given file or if you want to specify a second
84: file, which is used as the preview image. In that case you can either use this
85: image as it is or you can let ExtImage resize it to a different size.
86: If you want the preview image to be generated, you must enter its (x,y)size and
87: choose, if you want to keep the aspect ratio of the image for the preview-image
88: or if you want it scaled to the exact size entered.
89: To set an extra permission check for the download of the file, enable
90: "Use 'Download ExtFile/ExtImage' permission" (see 4.4.)
91:
92: 4.2. Public methods ('View' permission)
93: The raw file is called through the 'index_html' method, the icon by the
94: 'icon_gif' method and the preview image by the 'preview' method (only available
95: in ExtImage). To view the meta data of a file, call the 'view' method.
96: For a complete list of all public methods and attributes, see 4.6. and 4.7
97:
98: 4.3. Management methods
99: To be able to fully access and use the management methods the permissions
100: 'View management screens', 'Change ExtFile/ExtImage' and 'FTP access' must be
101: enabled.
102: In the upload-tab of the management screen you can upload a new version of the
103: file (or the preview in ExtImages) via local upload or http upload.
104:
105: 4.4. The 'Download ExtFile/ExtImage' permission
106: Usually, you want everybody with the 'View' permission to be able to download
107: the file (or view the image) stored in an ExtFile/ExtImage object.
108: In some cases (e.g. commercial websites) the administrator would want to let
109: people with 'View' permission only to see the preview image, or the
110: meta-information of the file, or an icon for it and allow only users with a
111: special permission to view/download the file itself.
112: In these cases, enable the "Use 'Download ExtFile/ExtImage' permission" while
113: creating a new ExtFile/ExtImage object and set that permission for the role,
114: you want to give access to the file. You enable/disable this permission check
115: later by setting 'use_download_permission_check' in the properties tab to
116: either 1 (enabled) or 0 (disbaled).
117:
118: =============================
119: 5. Additional settings
120: =============================
121:
122: 5.1. Directory structure
123: At the moment there are three ways to structure the files in the repository.
124: You can switch between those modes by setting the constant 'REPOSITORY' (in
125: line 69 of ExtFile.py) to the respective value.
126: - FLAT (default): The 'classic mode'. All files are stored in one single
127: directory which is by default var/reposit/
128: - SYNC_ZODB: Starting from the base repository dir (default is var/reposit) the
129: file is stored in a directory that corresponds to the url of its object.
130: E.g. if you add an ExtFile object in the folder spamFolder/eggsFolder, the
131: file goes to var/reposit/spamFolder/eggsFolder.
132: Please note, that this does not mean, that the directory structure of the
133: repository is kept in sync with the ZODB afterwards. Renaming a parent folder
134: or moving the ExtFile object to a different folder has no effect on the files
135: in the repository. They stay where they are, troughout the lifetime of the
136: object.
137: - SLICED: The first two characters of the filename (resp. the id) determine
138: in which sub-directory (starting from the base repository directory) the file
139: is stored. E.g. the file spam.txt is stored in var/reposit/s/p/,
140: eggs.txt is stored as var/reposit/e/g/.
141: This gives you up to approx. 70 subdirecories in the base repository, each
142: containing up to approx. 70 subdirecories in wich the files are stored.
143:
144: 5.2. Filename generation
145: You can customize the filename of the files in the repository. A unique
146: filename is generated, each time an ExtFile/ExtImage object is added.
147: The format of this filename is specified by a format string stored in the
148: constant FILE_FORMAT in line 73 of ExtFile.py.
149: It may contain the following elements:
150: %u - The name of the user, that adds the object.
151: %p - The relative-url-path of the object, separated by underscores. E.g. if you
152: add an ExtFile object in the folder spamFolder/eggsFolder, %p is expanded
153: to 'spamFolder_eggsFolder'.
154: %n - The name of the added file (or the id of the object), without the
155: extension. E.g. if the id is spam.txt, %n is expanded to 'spam'.
156: %e - The extension of the added file including the dot, e.g. '.txt'.
157: %c - A counter starting at 0
158: %t - The current date and time as a 10 digit number (mmddHHMMSS)
159: The format string may contain any of the first four elements and must contain
160: one of the two last elements (counter or time). The last two elements are used
161: to generate a unique filename, simply by increasing the value as long as a file
162: with that name already exists.
163: Examples:
164: %n%c%e -> spam.txt, eggs1.txt, multiple.dots23.txt, ... (default)
165: %t%n%e -> 0101000001spam.txt, 1231235959eggs.txt, ... (classic)
166: %n(%u)%c%e -> spam(gregor).txt, eggs(a_user)100.txt, ...
167: %p_%n%c%e -> folder1_folder2_spam.txt, folderA_folderB_eggs1.txt, ...
168:
169: 5.3. Undo handling
170: To be able to support Zope's undo functionality, the external file is not
171: deleted, when the object is deleted in the Zope management interface, but it is
172: renamed to 'filename.undo'.
173: You can set a 'level of undo' which determines in wich cases the external file
174: is overwritten/deleted or renamed to '.undo'.
175: The constant UNDO_POLICY in line 75 of ExtFile.py can be set to one of the
176: following values:
177: - NO_BACKUPS: ExtFile/ExtImage never makes '.undo' files. If you delete an
178: object, the file in the repository is deleted aswell, if you upload a new
179: version of the file, the old version is overwritten. In this case an undo
180: of a deleted object causes a broken ExtFile object because the external file
181: doen't exist any more. (This option has been removed, because it produced
182: broken objects after a cut/paste or rename operation.)
183: - BACKUP_ON_DELETE (default): When an object is deleted, the external file is
184: renamed to '<filename>.undo'. This guarantees, that objects always have a
185: valid reference to a file in the repository even if they are deleted this
186: transaction is undo'ed afterwards. But if you update the file with a new
187: version, the old version is overwritten and even if the update operation is
188: undo'ed, the object still references the new version of the file.
189: - ALWAYS_BACKUP: On every transaction that alters the external file, a backup
190: of the original file is left in the repository. So if you upload a new
191: version and then undo this transaction the object references the old version
192: of the file again. On the other hand, this can lead to unreferenced non-undo
193: files in the repository.
194: You should occasionally (e.g. when packing the ZODB) delete the '.undo' files
195: in the repository directory (default: var/reposit).
196: Thou it is possible to upload a new version of the file, this is only
197: recommended, when you want to update the file with a new version. Don't use the
198: upload function to replace the file with a completely different one, because
199: the id of the objects remains the same.
200:
201: =============================
202: 6. Method appendix
203: =============================
204:
205: 6.1. ExtFile/ExtImage public methods
206:
207: - index_html():
208: Returns the (binary) file
209:
210: - icon_gif(), index_html(icon=1):
211: Returns the icon for the file's MIME-Type
212:
213: - link(text=self.title_or_id, **args):
214: Return a HTML link tag to the file: <a href="link/to/object">text</a>,
215: **args are all other parameters for the <a> tag.
216:
217: - icon_html():
218: HTML '<img>' tag wrapper around icon_gif with a link to index_html:
219: <a href="link/to/object"><img src="link/to/object/icon_gif"></a>
220:
221: - is_broken():
222: Returns true if external file is 'broken', otherwise 1
223: (this can happen, when a file in the repository direcory was accidentially
224: deleted or a database undo was performed, after the .undo file was deleted)
225:
226: - getContentType:
227: Returns the MIME-Type of the file.
228:
229: - rawsize(), get_size(), getSize():
230: returns the size of the file in bytes.
231:
232: - size():
233: returns a 'stringified' filesize (e.g. '1.23 MB')
234:
235: 6.2. Additional public methods for ExtImage
236:
237: - preview(), index_html(preview=1):
238: Returns the binary preview image.
239:
240: - tag(preview=0, height=None, width=None, alt=None, scale=0, xscale=0,
241: yscale=0, border="0", **args):
242: Generate an HTML IMG tag for this image, with customization. Arguments to
243: tag() can be any valid attributes of an IMG tag.'src' is always the
244: absolute pathname of the object. 'preview' is either 0 for the image or 1
245: for the preview. Defaults are applied intelligently for 'height', 'width',
246: and 'alt'. If specified, the 'scale', 'xscale', and 'yscale' keyword
247: arguments will be used to automatically adjust the output height and width
248: values of the image tag. **args are all other parameters for the <img> tag.
249:
250: - preview_html():
251: Same as tag(preview=1)
252:
253: - width(), height(), prev_width(), prev_height():
254: The dimensions (in pixel) of the image or the preview.
255:
256: - prev_rawsize(), prev_size():
257: Same methods for the preview as for the image.
258:
259: - is_webviewable():
260: Returns 1 if the image is viewable in a webbrowser (gif, jpeg or png),
261: otherwise 0
262:
263:
264: =============================
265: 7. Supported image formats
266: =============================
267:
268: The ExtImage product can create a preview from the image you upload. To be able
269: to do this, it requires Python Imaging Library (PIL) installed and working.
270: Depending on your PIL configuration most common image file formats are
271: supported. In short: every image file format that can be read by your PIL
272: installation can be used by ExtImage to create preview images.
273: These are (to name the most common): BMP, GIF, JPEG, TIFF, PNG, PCX, PNG, PSD
274: The preview image is always created in the JPEG format.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to README.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / ExtFile / doc-1.1