Skip to content. | Skip to navigation

Personal tools
You are here: Home Operations Web site documentation Using WebDAV to publish documents to the Plone server

Using WebDAV to publish documents to the Plone server

What is WebDAV?

WebDAV allows users to remotely manage files on a WWW server (such as the LCO Plone server), instead of using the web interface. This can be useful for managing files which are generated from other formats (such as AsciiDoc). This document assumes that the user is already familiar with (X)HTML and the Plone server web interface.

What WebDAV software can I use with Plone?

Mac OS X

Installation instructions for two command-line WebDAV programs (cadaver and nd) can be found in my Mac software install instructions. Other Mac programs, such as Transmit, can transfer files to and from a WebDAV server, but cadaver and nd can also set properties of documents on the server (most importantly for our purposes, the document title).

Warning

Do not use the Finder in Mac OS X to connect to the Plone server. Although the Finder supports WebDAV connections, the Plone web server has a number of problems with WebDAV connections from the Finder:

  • The Finder will attempt to create .DS_Store files on the Plone web server as you navigate from folder to folder. Plone does not always handle these files properly.

  • When uploading a document, the Finder will attempt to create a resource fork for the file. Plone does not always handle resource forks properly.

  • When uploading from a Mac OS X 10.5 (Leopard) computer, the resulting file may have no contents, because Plone does not properly handle the “Chunked Transfer Encoding” transfer protocol that Leopard uses for uploading.

Linux

Compiling and installing cadaver and nd in Linux should be similar to Mac OS X. In addition, Linux offers davfs2, which allows a remote WebDAV server to be mounted as a file system on the local machine.

Warning

It is very important to follow my instructions for installing nd. The Plone server misinterprets the message that the current version of nd sends to set a document property (such as the title); this can cause serious problems with Plone and is difficult to fix. My custom install script patches the nd source code to fix this problem.

If you are installing in another operating system (such as Linux), you will need to download the nd source code, extract the patch from my install script, and apply it before compiling.

What types of files can I upload using WebDAV?

Any type of file (for example, HTML files, PDF files, images, or archives) can be uploaded to the web server, and links to uploaded files can be added to existing pages in the web site.

Special considerations for HTML files

Because HTML files uploaded to the server will usually be viewed as pages in the web site, and will be displayed surrounded by other page elements (such as the page header and the navigation bar), some special care needs to be taken before uploading them to the Plone server.

  • The HTML file should not contain a header (the information between the <HEAD> and </HEAD> tags, and the tags themselves), nor should it contain <BODY> or </BODY> tags. It should only contain the actual HTML content to be displayed.

  • The HTML file must otherwise contain valid HTML. Invalid HTML (such as unclosed or improperly nested tags) may cause the page to be displayed incorrectly or not at all.

How do I upload a file and set its title?

Tip When you are first experimenting with WebDAV, you should use the backup web server alyth.lco.cl instead of the live web server, so that any mistakes can be easily undone and won’t affect the live server. Make sure that you let Herman Rojas know what you are doing; he can restore alyth.lco.cl from backup should something unrecoverable go wrong.

Where do I upload documents?

Warning
Collections, pages, and files

In the Plone server, collections (folders), pages (content created using the web interface), and files (content uploaded from external files using the web interface or WebDAV) are all separate types of objects, and each is stored differently in the Plone server.

Do not try to use WebDAV to edit or overwrite a page created using the web interface; instead, upload a new file on the web server using WebDAV as outlined here, adjust the links in other pages to point to the uploaded file, and then delete the original page using the web interface.

Once you have published a file on the Plone server using WebDAV, you can freely overwrite it with new content by uploading a new file with the same name.

In order to publish a file to the web server, you will first need to find a collection (folder) in which to put it. When browsing the Plone web site, it can be difficult to distinguish collections from other documents (pages and files) based on the URL or displayed content. However, if you are logged in to the Plone server web interface (using the “log in” link at the upper right), as you browse the web site, collections will have contents as the left-hand tab, while other documents (pages and files) will typically have view as the left-hand tab. (If the document you are viewing doesn’t have tabs, you don’t have permission to modify it, and need to consult Herman Rojas to give you the proper permission.) Once you are viewing a collection in your browser, you can simply copy the URL of the collection from your browser’s address bar.

Caution Don’t press any of the tabs before copying the URL of the collection; the view tab should be the selected tab.

This document does not cover creating new collections on the Plone web server, though this can be done either using the web interface or through WebDAV.

Using Transmit

Connecting to the Plone server

To connect to the Plone server using Transmit, simply fill in the information in the Connect panel which appears on the right after Transmit opens. To connect directly to a collection, paste the directory portion of the URL of the collection (i.e. without the http:// and the host name), into the Initial Path field.

Tip Alternatively, you can start Transmit with the Initial Path field blank; this will connect you to the root collection on the server. After connecting, you can navigate the collections in the web site using the graphical interface.
Example: Connecting to my home folder
Transmit screenshot
Uploading a file

After connecting to the Plone server, files can be dragged and dropped from the left pane (the local machine) into the right pane to upload them to the Plone server. After uploading a file, the title of the document will be the same as the filename; to change it, you will have to use the Plone web interface, or one of the command-line tools below.

Using cadaver

If you are familiar with using ftp from the command line, you will find cadaver to be very similar.

Starting cadaver

To connect to the Plone server using cadaver, type the command “+cadaver ”, where +[URL] is the URL of the collection to which you want to connect. You will be prompted for your WebDAV username and password.

Tip Alternatively, you can start cadaver with the home page URL (“cadaver http://www.lco.cl/”). Once logged in, you can use ls to list the contents of a collection, and cd to change the current collection, just as on the UNIX command line.
Uploading a files

Files can be uploaded by typing with the command “+put ” in +cadaver. The file will have the same name on the server as it does on your machine.

Setting the title

Setting the title of a document is a bit more complicated. To set a property of a document in cadaver, you use the propset command. However, in WebDAV, document properties are grouped into namespaces, so before setting the title, you must set the correct namespace as shown below.

set namespace http://www.zope.org/propsets/default
propset [filename] title "[title]"
Note Due to limitations of the WebDAV protocol, the title can only contain ASCII characters (no accents, tildes, or other international characters). If you want a document title which contains international characters, you will have to use the Plone web interface.

A sample cadaver session in which I upload a document to my home folder on the Plone web server and set its title:

Example: Uploading a file using cadaver
% cadaver http://www.lco.cl/Members/geychaner/
Authentication required for Zope on server `www.lco.cl':
Username: geychaner
Password:
dav:/Members/geychaner/> put tcscomm.html
Uploading tcscomm.html to `/Members/geychaner/tcscomm.html':
Progress: [=============================>] 100.0% of 18356 bytes succeeded.
dav:/Members/geychaner/> set namespace http://www.zope.org/propsets/default
dav:/Members/geychaner/> propset tcscomm.html title "TCS communications"
Setting property on `tcscomm.html': succeeded.
dav:/Members/geychaner/> exit
Connection to `www.lco.cl' closed.

Using nd

nd is a command-line tool for accessing a WebDAV server. It is not as easy to use interactively as cadaver, but is better for using in script files (unless you’re good at writing expect scripts). nd will prompt for a user name and password each time it is invoked on the command line.

Uploading a file

The nd command for uploading a file is quite simple:

nd -p "[source file]" "[target URL]"

The [target URL] must contain the full filename (the URL of the collection plus the file name) that the file will have on the server, and any spaces in the [target URL] must be replaced by the string “+%20+”. (The [source file] and [target URL] are quoted to ensure the shell doesn’t mangle them in an unexpected way.)

Setting the title

The nd command for setting the title of a document is only slightly more complicated than uploading a file:

nd -e title="[title]" -N "http://www.zope.org/propsets/default" "[target URL]"

The [target URL] must be exactly the same as above, and the [title] can only contain ASCII characters.

An example script using nd

This is an example script which uses asciidoc to process an AsciiDoc document to XHTML and nd to publish the processed XHTML document to a Plone server. The script takes as input the name of the source text document (including directory) and the URL of a collection on the server. It processes the document to XHTML using the asciidoc command line tool and adds the proper <div> tags at each end. It then uses nd to upload the processed XHTML document to the server, and finally sets the title of the file on the server to the first line of the original AsciiDoc source file. The file on the server will have the same name as the source document, with the extension changed to .html.

One problem with the script is that it has to ask for your WebDAV username and password twice, once for each operation. It also has very poor error checking; it should check for the existence of the collection before attempting to upload the file (though that would require asking for the username and password a third time).

Example: nd file upload script
#!/bin/bash
# Parse the command line
if [ $# -lt 2 ]; then
    echo "Usage: adocpub [asciidoc-opts] src-file targ-url-dir"
    exit
fi
adocopts=
while [ $# -gt 2 ]; do
    adocopts+=" $1"
    shift
done
src=$1
dst=$2
if [ ! -f "$src" ]; then
    echo "Error: source file '$src' does not exist."
    echo "Usage: adocpub [asciidoc-opts] src-file targ-url-dir"
    exit
fi
# Find our target URL by appending the file name
srcbase=`basename "$src"`
targbase=${srcbase%.*}.html
tempf=/tmp/$targbase
targ=${dst// /%20}/${targbase// /%20}
title=`head -1 "$src" | tr -cd "[:print:]"`
# Process the file using AsciiDoc
echo '<div class="asciidoc">' > "$tempf"
asciidoc -o - -s --unsafe -a quirks! -a iconsdir=/lco/portal_skins/plone_images/asciidoc \
        $adocopts "$src" >> "$tempf"
echo '</div>' >> "$tempf"
# Publish the file
echo "Publishing HTML document '$targbase' to '$targ'."
nd -p "$tempf" "$targ"
echo "Setting '$targ' title to '$title'."
nd -e title="$title" -N "http://www.zope.org/propsets/default" "$targ" | grep Status:
rm "$tempf"
Document Actions