Page tree
Skip to end of metadata
Go to start of metadata

Web-based Distributed Authoring and Versioning (WebDAV) is an extension of the HTTP/1.1 protocol. The purpose of this protocol is to present Web content as a writable medium in addition to being a readable medium. WebDAV on Wikipedia and the WebDAV website provide information on this protocol. The WebDAV module implements the protocol for accessing Magnolia's repository on an author instance. This allows users to edit resources and templates on the client computer.

Examples of WebDAV usage include:

  • A content editor editing a document in the dam workspace.
  • A developer editing a Groovy file in the scripts workspace.
  • A designer editing CSS files located in the resources workspace using a design tool installed on their computer.
  • A developer editing Freemarker templates located in the templates workspace using a local tool that provides FreeMarker syntax highlighting and helper functions.

Installing

Maven is the easiest way to install the module. Add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-webdav</artifactId>
  <version>2.1.3</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Install the following jars from the zip:

  • magnolia-module-webdav-2.x
  • jackrabbit-webdav-2.8.0
  • jackrabbit-jcr-server-2.8.0

The module is dependent on a number of 3rd party libraries that should already be installed.

  • jcl-over-slf4j-1.7.5
  • commons-io-2.4.jar
  • jackrabbit-spi-2.8.0.jar
  • jackrabbit-spi-commons-2.8.0.jar
  • slf4j-api-1.7.5.jar
  • tika-core-1.4.jar

Failure to add all of the jar files will lead to serious errors. For example, if you do not add the jackrabbit-jcr-server jar, when you try to access http://localhost:8080/author/.webdav/templates you will see the following error:

java.lang.NullPointerException	
info.magnolia.cms.filters.ServletDispatchingFilter.doFilter(ServletDispatchingFilter.java:123) 
info.magnolia.cms.filters.AbstractMgnlFilter.doFilter(AbstractMgnlFilter.java:91)

Exposed workspaces

The module allows you to access the following workspaces in the magnolia repository:

  • resources
  • templates
  • scripts
  • dam

The content available is the same content you see in these apps:

Once the client establishes a WebDAV connection to the repository, the content is displayed like local content and you can edit it locally.

You cannot access files that are children of other files in Magnolia.

Always create and delete files in Magnolia in order to maintain consistency. The WebDAV client will display the new files. You can then edit them on the client computer.

Access URL

Use the URLs listed below to access a Magnolia workspace with WebDAV.

Format:

  • http://<host name>:<port>/<contextPath>/.webdav/<workspace>

Examples:

  • http://localhost:8080/magnoliaAuthor/.webdav/templates
  • http://localhost:8080/magnoliaAuthor/.webdav/resources
  • http://localhost:8080/magnoliaAuthor/.webdav/scripts
  • http://localhost:8080/magnoliaAuthor/.webdav/dam

Configuration

Installation of the WebDAV module adds the following configurations:

Mappings

The module provides mapping classes for each exposed workspace. The mappings are configured in /modules/webdav/config/mappings.

The mapping configurations for templates, scripts and dam are similar. 

Node nameValue

 webdav

 

 config

 

 mappings

 

 resources

 

 templates

 

 class

 info.magnolia.module.webdav.mapping.SimpleStringPropertyMapping

 dataType

 text

 fileExtensionForExport

 ftl

 workspace

 templates

 scripts

 

 dam

 

 class

 info.magnolia.module.webdav.mapping.DamMapping

 dataType

{http://www.jcp.org/jcr/1.0}content 

 workspace

 dam

Properties:

class

required

A class that defines a mapping for WedDAV:

  • info.magnolia.module.webdav.mapping.SimpleStringPropertyMapping exposes a String property as the file's content and uses a single file extension. Used in the templates and scripts workspaces.
  • info.magnolia.module.webdav.mapping.ResourcesMapping maps file extensions to resource file names and vice-versa.
  • info.magnolia.module.webdav.mapping.DamMapping mapping for dam workspace.
workspace

required

Workspace that is accessed via WebDAV.

dataType

required

WebDAV data type.

The mappings configuration for resources is more complex because the resources workspace supports a number of resource types. You can view them in Resources

The configuration is in /modules/webdav/config/mappings/resources.

Node nameValue

 webdav

 

 config

 

 mappings

 

 resources

 

 templateNameToExtension

 

 cssTemplate

 

 extension

css

 template

resources:css

 htmlTemplate

 

 jsTemplate

 

 processedCssTemplate

 

 processedJsTemplate

 

 processedHtmlTemplate

 

 extensionToDefaultTemplate

 

 css

resources:css

 html

resources:html

 js

resources:js

 class

info.magnolia.module.webdav.mapping.ResourcesMapping

 dataType

binary

 textStringProperty

 text

 workspace

 resources

Nodes and properties:

  • mappings:
    • resources:
      • templateNameToExtension: Maps template name to extension.
        • <template type>:
          • extension: Template file extension.
          • template: Template name.
      • extensionToDefaultTemplate: Maps file extension to template name.
        • <resource type>: <template name>.
        • ...
      • class: ResourcesMapping maps a single string property to the file content and the file extension to to the template name, and vice-versa.
      • dataType: WebDAV data type.
      • textStringProperty: Defines the text string property.
      • workspace: Workspace that is accessed.

Callback filter

The WebDAV module defines it's own security client callback filter that ensures Magnolia authentication when users access a workspace with WebDAV. Users login with their Magnolia credentials.

The filter is registered in the filter chain in /server/filters/securityCallback/clientCallbacks/webdav.

Node nameValue

 server

 

 filters

 

 content

 

 ....

 

 securityCallback

 

 clientCallbacks

 

 public

 

 webdav

 

 class

info.magnolia.module.webdav.security.WebdavClientCallback

 davAgentPattern

.*DAV.*

 form

 

 class

info.magnolia.cms.security.SecurityCallbackFilter

Properties:

  • webdav:
    • class: WebdavClientCallback is the callback for WebDAV clients. It accepts if the header is set correspondingly. Accepts is evaluated depending on WebDAV specific headers. Adds a realmName to the header of the response (like BasicClientCallback), but does not extend AbstractHttpClientCallback.
    • davAgentPattern: The pattern that triggers the filter.

Connecting to a workspace

You need to configure your client computer to communicate with Magnolia workspaces. Once the connection is made, content within the workspaces can be modified as if it resided on the client computer. Depending on the type of client, content can be edited directly or transferred to the client and then transferred back to the workspace. This allows users to use their preferred editing tools on the client computer instead of editing within Magnolia.

In most cases, the connection consists of mapping the client's internal filesystem to a workspace in the repository. Folders and files in the repository appear as any other folder or file on the client. There must be a separate mapping for each workspace.

OS X

To map a workspace in OS X:

  1. Go to Finder.
  2. Click Go > Connect To Server.
  3. Enter the workspace URL in the Server Address field.
  4. Click Connect.
  5. Enter Magnolia username and password when requested.

Repeat this procedure for each workspace.

Linux

To map a workspace in Linux:

  1. Install davfs2.
  2. Mount a workspace:
    mount -t davfs2 <directory>
    where directory is the directory that should be mapped to the workspace.
  3. Enter Magnolia username and password when requested.

Windows

Connecting to a WebDAV server with Windows is problematic. You can try the options below or connect using a WebDav client. 

Mapping a drive

To map a network drive:

  1. Click Start > Computer > Map network drive.
  2. Select a drive and enter the workspace URL in the Folder field.
  3. Click Finish.

If the mapping completes successfully you can see the selected drive in Windows Explorer. If the mapping does not complete successfully try adding the repository as a network location.

Network location

To add a network location:

  1. Click Start > Computer > Map network drive.
  2. Click Connect to a Web site that you can use to store your documents and pictures.
  3. Select Choose a custom network location.
  4. Enter the workspace URL in the Internet or network address field.

If neither methods succeeds, see the support matrix of alternative tools on the Magnolia Wiki.

Mini-Redirector is a Microsoft WebDAV client that is provided as part of Windows 8, Windows 7 and Windows Vista. The client is not installed by default on Windows Server 2008 and later versions. To enable it install the Desktop Experience feature.

If you are using BitKinex, for Server-Site Map configuration you need to set the Type path to Directory WebDAV. By default the path is set to File.