Remote Editing with Firedocs

Atompub

Firedocs uses the Atom Publishing Protocol (Atompub) for remote editing.

If you are not familiar with the Atom format, we recommend the following resources:

Protocol Extensions

A set of protocol extensions are available for advanced editing capabilities. You can pick a subset of those that meets your requirements.

Protocol extensions:

  • Auto-discovery of editable content
  • Pessimistic locking
  • Hierarchical traversal of the resource space
  • Explicit support for document attachments
  • Context documents
  • Content blocks
  • Styling of XML-based documents
  • Validation
  • Remote URI resolvers
  • Metadata constraints

Auto-Discovery

The first step to use the remote editing protocol is to determine what editable content is available on the server. This process can be automated by using service links: Service links are HTML <link> tags that point to the corresponding atompub service documents. Because Firedocs is browser integrated it can look for service links in visited pages and prepare editing in the background accordingly.

Service link for editing:
A GET request to the service.edit link returns a service document containing an Atom entry with the data needed for editing:

  <link type="application/x.atom+xml" rel="service.edit"
  title="Edit with Firedocs"
  href="…"/>

Service link for workspace discovery:
A GET request to the service link returns the workspace service document which is the entry point to the website resource hierarchy.

  <link type="application/atomserv+xml" rel="service"
  title="Atom Publishing Protocol Service Document"
  href="…"/>

Service Document for Editing

The edit service document contains the configuration data to edit a particular atom entry.

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>…</id>
  <title type="text">…</title>
  <summary>…</summary>
  <author>…</author>
  <category scheme="http://www.example.org/categories/language">de</category>

  <link rel="edit" href="…" type="application/atom+xml" />
  <link rel="assets" href="…" type="application/atomcoll+xml" />
  <link rel="children" href="…" type="application/atomcoll+xml" />
  <link rel="edit-media" href="…" type="…" />

  <content type="..." src="…" />

  <firedocs:firedocs xmlns:firedocs="www.firedocs.org/config/1.0">
    <firedocs:contentblocks href="…" />
  </firedocs:firedocs>
</entry>

Link types:

  • edit - Edit this atom entry (accepts GET and PUT requests).
  • edit-media - Edit the corresponding resource (accepts GET and PUT requests).
  • children - An atom feed containing the child nodes of this document, see section Hierarchical Traversal of the Resource Space (accepts GET and POST requests)
  • assets - An atom feed containing the local assets of this document, see section Document Attachments (accepts GET and POST requests).

Other:

  • firedocs:contentblocks - Link to a content blocks document, see section "Content Blocks"
    • Workspace Service Document

      The workspace service document is the entry point to the remote resource hierarchy. It contains a collection which has a link to the top-level resources in the resource hierarchy.

      Workspace service document:

      <service
        xmlns="http://www.w3.org/2007/app"
        xmlns:atom="http://www.w3.org/2005/Atom">
        <workspace>
          <atom:title>Authoring Workspace</atom:title>
          <collection href="…">
            <atom:title>Top Level Documents</atom:title>
            <accept>application/atom+xml;type=entry</accept>
            <categories fixed="yes">
              <atom:category
                scheme="http://www.example.org/categories/language"
                term="de" />
              <atom:category scheme="http://www.example.org/categories/language"
                term="en"/>
                    …
            </categories>
          </collection>
        </workspace>
      </service>
      

      Collection of top level resources:

      <collection xmlns="http://www.w3.org/2007/app">
        <member href="..." title="A top level document" />
        <member href="..." title="Another top level document"/> 
      </collection>
      

      Note: The members are atom entries (edit service documents).

      Hierarchical Traversal of the Resource Space

      Atompub lacks nested collections. The children link type allows for hierarchical traversal of the resource space. A children link points to a collection of child nodes that in turn have children links. The root node is represented by the workspace (see section Workspace Service Document.

      Children link type:

        <link rel="children" href="…" type="application/atomcoll+xml" />
      

      Children collection:

      <collection xmlns="http://www.w3.org/2007/app">
        <member href="..." title="A atom entry" />
        <member href="..." title="Another atom entry"/> 
      </collection>
      

      Note: Members are atom entries (edit service documents).

      Document Attachments

      The assets link type supports document attachments. Asset links point to an asset collections.

      Assets link type:

        <link rel="assets" href="…" type="application/atomcoll+xml" />
      

      Assets collection:

      <collection xmlns="http://www.w3.org/2007/app">
        <accept>image/png</accept>
        <accept>image/jpeg</accept>
        <accept>image/gif</accept>
        <accept>application/pdf</accept>
        <member href="..." title="A asset atom entry" />
        <member href="..." title="Another asset atom entry"/> 
      </collection>
      

      Pessimistic Locking

      Atompub lacks support for locking but locking can be expressed by using atom vocabulary. The key principle is to represent the lock as a collection containing one or zero entries, depending on whether the resource is locked or not.

      The collection is requested via an lock link type in the atom entry:

      <link rel="lock" href="…" type="application/atomcoll+xml"/>
      

      Locking a Resource

      To acquire a lock, a POST request is sent to the collection URI, including an empty entry:

      POST … HTTP/1.1
      <entry/> 
      

      If the collection already contains a lock, a 412 (Precondition failed) response code is sent. Otherwise, a new lock entry is created. The server application inserts the currently logged-in user as author of the entry. Here's an example response of the server:

      HTTP/1.1 201 Created
      Location: …
      <collection xmlns="http://purl.org/atom/app#"> 
        <member href="…" title="Lock for resource …"
          updated="2008-05-22T18:30:02Z" /> 
      </collection> 
      

      Unlocking a Resource

      To unlock the resource, a DELETE request is sent to the lock resource URI.

      Optional, to prohibit deleting locks of other users: If the user ID of the logged-in user doesn't correspond to the <author> element of the lock resource, a 403 (Forbidden) response code is sent.

      Lock Discovery

      To find out if a resource is locked, a GET request is sent to the lock collection URI. If it conains an entry, the resource is locked, otherwise it isn’t. To find out who locked a resource, the <author> element of the lock resource entry is examined.

      Behaviour of Locked Resources

      If the lock collection is empty, the server application accepts all (valid) PUT requests to the resource URI. If the lock collection contains a lock, the server application accepts only PUT requests to the resource URI if the logged-in user ID corresponds to the <author> element of the lock resource. Otherwise, a 403 (Forbidden) response is sent.

      Page Context Documents (HTML editing feature)

      A context document contains the non-editable markup which surrounds editable areas in the editor, usually the page header, navigation elements etc. Any existing HTML page can be turned into a context document by providing a page context link in the Atom entry. The editor includes the body content of the editable page into the page context document and displays the resulting assembled page.

      Page context link:

      <firedocs:page-context href="published.html#content" />
      

      Example page context document (HTML):

      <html>
        <body>
          <div id="header" >  .. page header..  <div/>
          <div id="menu" >  .. navigation..  <div/>
          <div id="content" >  
          .. editable content merged in here..
          <div/>
        </body>
      </html>
      

      Content Blocks

      Content blocks are pre-defined document snippets that can be inserted at certain positions in the document. Content blocks can be nested. The corresponding markup can be used in html and xml documents.

      Content blocks link:

      <firedocs:contentblocks href="…" />
      

      Content blocks (html):

      <html>
        <body>
           <contentBlock xmlns="http://www.firedocs.org/contentblocks/1.0" 
              title="Test Paragraph" 
              context="//body">
             <p>
             This is a  <b>html sample content block </b> with 
             some  <blink> <font color="red"> fun </font> </blink>. 
             </p>
           </contentBlock>
        </body>
      </html>
      

      Content blocks (xml - with nesting enabled):

      <contentBlocks
        xmlns="http://www.firedocs.org/contentblocks/1.0"
        xmlns:xhtml="http://www.w3.org/1999/xhtml"
        xmlns:cb="http://www.firedocs.org/contentblocks/1.0"
        xmlns:ex="http://www.example.org/document/1.0">
      
        <contentBlock title="Mail Form" name="mailform" context="//xhtml:p">
          <ex:form type="mail" name="Henri Hamster" addresses="henri@hamster.com"/>
        </contentBlock>
        <contentBlock title="Mail Forms" context="//xhtml:body">
           <repeat minOccurance="0" maxOccurance="5">
              <include ref="mailform"/>
            </repeat>
        </contentBlock>
        <insertObject contentType="video/quicktime">
          <xhtml:object type="video/quicktime" cb:href="data" width="320" height="260">
            <xhtml:param name="controller" value="true" />
              Error text.
          </xhtml:object>
        </insertObject>
        <insertAttachment>
          <xhtml:a class="asset" cb:href="href" cb:title=".">A Title</xhtml:a>
        </insertAttachment>
      </contentBlocks>
      

      Elements:

      • contentBlock: A content snippet. Attributes: @name, @title, @context
      • repeat: Repeated nesting. Attributes: @minOccurance, @maxOccurance
      • include: Nested block inclusion. Attributes: @ref (a named block)
      • insertObject: Content snippet for new inline object (image, movie, etc.). Attributes: @cb:contentType, @cb:title, cb:href
      • insertAttachment: Content snippet for new linked attachment. Attributes: @cb:contentType, @cb:title, cb:href

      Styling of XML-based Resources

      Firedocs has built-in WYSIWYG XML editor. This editor works with custom XSLT stylesheets that do a XML-to-XHTML transformation. Note that for historical reasons the XML editor uses a page context format different from the format described in the section Page Context Documents. When working with XML, the page context is a XML document that uses an XInclude directive for content inclusion. The page context can be applied before or after transforming to XHTML.

          <firedocs:firedocs xmlns:firedocs="www.firedocs.org/config/1.0"/>
          <firedocs:styles/>
            <firedocs:style href="…"/>
              <firedocs:parameter name="…" value="…" />
            </firedocs:style>
            <firedocs:page-context href="…" transformPageContext="true|false" />
          </firedocs:styles>
        </firedocs:firedocs>
      

      Elements:

      • firedocs:styles: stylesheet container
      • firedocs:style: stylesheet link
      • firedocs:parameter: stylesheet parameter
      • firedocs:page-context: page context - see below

      Page context document:

      <html xmlns="http://www.w3.org/1999/xhtml">
         <body>
            <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="..." />
         </body>
      </html>
      

      Validation

      Firedocs supports validation and schema directed editing of XML-based documents. A schema can be attached by using a schema link.

      Example schema link:

      <firedocs:schema type="relaxNG" href="..." />
      

      Note that Firedocs currently only supports Relax NG and that all schema related features require Java.

      Remote URI Resolvers

      Uri-resolver links point to service endpoint for link translation.
      Example URI resolver link:

      <firedocs:url-resolver protocol="lenya-document" href="..."/>
      

      Metadata Constaints

      Constraints for XML-based metadata can be set by placing a firedocs:metadata element in the workspace service document.
      Example:

      <firedocs:metadata>
        <firedocs:schema type="relaxNG" href="..."/>
      </firedocs:metadata>
      

      Location: workspace service document, following the workspace declarations.

(C) 2005-2008 Wired Inference, Inc.