WebDAV

WebDAV is an abbreviation for "Web-based Distributed Authoring and Versioning" (published as an open standard under RFC 2518). WebDAV is a set of extensions to the HTTP protocol which allows users to collaboratively edit and manage files on a web server. This is achieved by making use of a WebDAV compatible client / application. For example, it is possible to use recent versions of KDE's Konqueror or Microsoft's Internet Explorer. Using a WebDAV compatible client, the user connects to the server and is able to browse and manage files in a similar way as with a network share or an FTP server. In other words, what this protocol does is that it makes it possible to browse, create, remove, upload, download, rename, etc. files and directories on a web server. One of the most important advantages of this technology is that it uses port 80 for network traffic. This means that if you are able to surf the site from your workstation, you can also use WebDAV to administer it. It does not require firewall reconfiguration.

eZ Publish and WebDAV

From version 3.2 and up, eZ Publish provides a built in WebDAV server. This implementation allows users to communicate with eZ Publish using a WebDAV compatible client. Once connected, it is possible to browse and manage the node tree of a site. The tree will be displayed as if it were a filesystem (as directories and files).

When a user connects to the eZ Publish WebDAV server for the first time, the system will display a list of the siteaccesses that have been made available for WebDAV. This list can be configured using the "SiteList[]" directive under "[SiteSettings]" in a configuration override for "site.ini". Please note that the system does not ask for a username/password combination at this stage. In other words, anyone with network access will be able to see the names of the available siteaccesses. The following screenshot shows what the user will see if there are two available siteaccesses, "example" and "plain_user".

WebDAV - Virtual top folder

When a siteaccess is chosen, the system will attempt to authenticate the user by asking for a username/password combination. The next screenshot shows this.

WebDAV - Login

The provided username and password must belong to a valid eZ Publish user that exists for the selected siteaccess. Furthermore, the user must have sufficient privileges in order to be able to see the contents of the node tree. The following screenshot shows a WebDAV client displaying the contents of the root node of an eZ Publish siteaccess called "plain_user".

WebDAV - Top level nodes

As the screenshot indicates, the user will be able to browse and manage the contents of the "Content" and "Media" top level nodes. The next screenshot shows an example of what the user will see after doing some exploration of the node structure of the "Content" top level node.

WebDAV - Content node tree

Browsing and downloading

The default behavior is that all nodes are displayed as directories. The reason for this is because in eZ Publish any object can be placed under any other object by the way of nodes. Displaying the nodes as directories makes it possible to explore the structure of the node tree. However, not all nodes are displayed as directories.

Nodes that reference objects containing datatypes that store files will be displayed as files instead of directories. This means that for example nodes that make use of the image, media or the file datatype will be displayed as files. When downloaded, eZ Publish will send the file that is contained in the attribute which is represented by a datatype capable of storing a file. If several attributes are represented by such datatypes, it is the contents of the first attribute that will be used.

The "FolderClasses[]" directive in "webdav.ini" can be used to configure which types of nodes that should be shown as directories in the WebDAV client. The default configuration assures that nodes referencing folder objects are always displayed as directories. Adding a class that makes use of a datatype capable of storing a file will result in an override of the behavior described in the previous paragraph. In other words, this setting makes it possible to display different types of nodes as directories even if they contain files.

Uploading

Any type of file can be uploaded to the system. Files will be stored using instances of the file class. In other words, every time a file is uploaded, eZ Publish will create a file object where the file attribute will contain the uploaded data. In addition, a node will be created at the location where the file was uploaded in the tree. This is the default behavior. However, not all file types will be created as file objects.

It is possible to configure the system so that it creates different kinds of objects based on the type of the uploaded file. For example, the default configuration makes sure that uploaded images are created as image objects. This behavior is controlled by mapping MIME types to classes. The mappings can be configured using the "MimeClassMap[]" directive under "CreateSettings" in a configuration override for "upload.ini". The "DefaultClass" directive determines which class that should be used if there is no suitable mapping. This is usually set to "file", which means that unrecognized file types will be created as file objects. The following example shows the default mappings.

MimeClassMap[]
MimeClassMap[image]=image
MimeClassMap[video/quicktime]=quicktime
MimeClassMap[video/x-msvideo]=windows_media
MimeClassMap[video/vnd.rn-realvideo]=real_video
MimeClassMap[application/vnd.rn-realmedia]=real_video
MimeClassMap[application/x-shockwave-flash]=flash

Each entry in the "MimeClassMap[]" array must be further specified using a block that reveals details about the class that is being mapped to. The blocks must contain the following information:

• The identifier of the target class (appended with "_ClassSettings").
• The class attribute identifier which will get the file data.
• The class attribute identifier which will get the name.
• A pattern that defines the name of the object.

The following example shows the default class map block for images.

[image_ClassSettings]
FileAttribute=image
NameAttribute=name
NamePattern=<original_filename_base>

The example above will tell eZ Publish that when an image is uploaded, the actual file data should be put into an attribute identified by the string "image". The name of the image should be stored using an attribute called "name" (as before, it is the identifier of the attribute that is used). The "NamePattern" tells the system about how it should generate the name for uploaded images. It may contain plain text and special tags enclosed by angle brackets ("<" and ">"). The following table reveals the tags that can be used.

Custom upload handling

It is possible to use custom upload handlers in order to process uploaded files in a special way. Custom upload handlers must be provided as extensions. A handler must be automatically triggered whenever a certain type of file is uploaded to the system. This can be done by making use of the "MimeUploadHandlerMap[]" directive under "[CreateSettings]" in "upload.ini". For example, the following line will make sure that uploaded images (regardless of type) are handled by a class called "ezimageuploadhandler" located in "ezimageuploadhandler.php".

MimeUploadHandlerMap[image]=ezimageuploadhandler

It is also possible to have only a specific type of file be processed by the upload handler. The following example demonstrates how to only handle JPEG images.

MimeUploadHandlerMap[image/jpeg]=ezimageuploadhandler

The upload handler itself must be put in a directory called "uploadhandlers" in an extension, like this:

eZ Publish
|
 -extensions
  |
   -example
    |
     -uploadhandlers
      |
       -ezimageuploadhandler.php

The following code shows the skeleton of a custom upload handler.

include_once( 'kernel/classes/ezcontentuploadhandler.php' );
 
class eZExampleUploadHandler extends eZContentUploadHandler
{
    function eZExampleUploadHandler()
    {
        $this->eZContentUploadHandler( 'Example file handling', 'example' );
    }
 
    /*!
      Handles the uploading of example files.
    */
    function handleFile( &$upload, &$result,
                         $filePath, $originalFilename, $mimeInfo,
                         $location, $existingNode )
    {
        // Implement your import/conversion routine here
        copy( $filepath, "var/cache/example.jpeg" );
    }
}