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:

Getting to know the Atom Publishing Protocol, Part 1. IBM Tutorial.
Atompub Specification
Google's Gdata APIs can serve as example for Atompub related work

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.

Firedocs

Developers