Silva File Object

  Meta::
  
    Valid for:  Silva 0.9.3
    Author:     Jan-Wijbrand Kolman
                Martijn Faassen
    Email:      jw+infrae.com
    CVS:        $Revision: 1.7 $ $Date: 2003/11/14 21:26:29 $

  Introduction

    Silva's main objective is to store, manipulate and publish
    structured, mainly textual, content. However not all content, such
    as files and images, is deeply structured in such a way. The File
    object can be used to store arbitrary files in an unstructured
    manner into Silva.  Authors may reference these File objects with
    hyperlinks from documents. This way, site visitors are able to
    download and view or use this file.

    A web browser can recognize what kind of file content it is
    dealing with by using the file's mime type. Using the mime type
    the browser can be configured to take special action for
    particular files; it could for instance open the file in Word in
    case of a Word document, or play an MP3 file in an MP3 music
    player. The Silva File object determines the mime type of the file
    automatically and provides it to the user's browser.  The mime
    type of the file object is also used by Silva to display a
    relevant icon in the ZMI. If the mime type is not recognized, it
    will default to 'application/octet- stream'.

  Creation

    In order to create a File object, select the Silva File object
    from the new object menu in the ContentsTab of a container. This
    will bring up the add screen to create a silva file. There the
    user can fill in the id and title as with any Silva object and
    provide a file on the local computer of the user to upload. Unlike
    what is the case for other Silva objects the id field is not
    actually required. Instead the user can just provide the file for
    upload and Silva will derive the id from its filename automatically.

    In case of large files, the upload action to Silva may take a
    while. After that, the file object will have been created as a
    Silva asset. The asset will appear in the bottom of the
    ContentsTab of the container.

  Editor

    The editor tab of the File object does not provide much more
    functionality than a way to change the file's title and a button
    to upload a new version of the file. If by any chance the new file
    has a different type Zope will automatically detect the new mime
    type and change the File object's icon correspondingly.

  Storage

    By default, Silva stores file content in the Zope Object Database
    (ZODB). Because the file content is potentially very large it may
    be preferable to store the contents on the file system instead, to
    avoid excessively growing the size of the ZODB. A site
    administrator can configure the storage behavior of the file
    object per Silva installation, or even more fine-grainedly on a
    Silva folder basis if necessary. Note that whether the file
    content is stored in ZODB or on the file system is completely
    transparent to a Silva author.

    To store file content on the filesystem the ExtFile product [1]
    needs to be installed in Zope. If this product is not installed,
    it will automatically choose the ZODB for storing file contents.
    After installing ExtFile, go to service_files of your Silva root
    and check the `Enable filesystem storage' box.
    
    Note that you can create a new Silva File Service (called
    'service_files') in any container. Thus it is possible to enable
    or disable file system storage of a particular Silva subsite
    selectly or to save the file contents in a different location on
    the filesystem.
    
  API

    A File object overrides the Silva 'index_html()'. This method, and
    the more explicit "download()" method invoke a file download on
    the Visitor's webbrowser. The 'get_download_url()' and
    'get_download_link()' method return (for e.g. page templating) an
    URL and a complete '<a href>' tag respectively.

    The file's mime type maybe retrieved with the 'get_content_type()'
    method.
    
  Caveats / ToDo

    * Each File object stored on the file system contains the path to
    the file. Thus moving the file on the file system, will break the
    corresponding Silva File object.

    * For correct mime types and file extensions, the File object uses
    the Python 'mimetools' and 'mimetypes' modules. I'm not sure how
    up-to-date these lists are.

  References

    [1] "ExtFile":http://www.zope.org/Members/shh/ExtFile/ExtFile-1.2.0b2.tar.gz

<br />
Copyright &copy; 2002, 2003 Infrae. All rights reserved.<br />
See also "LICENSE.txt":license.txt
