The Well-Formed Web

I was not happy with the old implementation of template editing in RESTLog. The reason is that it restricted editing to just two files and they have to be an HTML file and an RSS file. The definition of the interface is too closely tied to my implementation and if RESTLog is to become a generic interface for blogging applications then the interface has to be more generic. I was bitten by the narrowness of the interface myself, as I realized I have a CSS file that I need to edit for my templates.

The new interface is to have the client application do a GET on RESTLog.cgi/template for a content-type of text/xml. The XML file returned will contain a list of all the URIs of template files that can be edited. The application can go GETs and PUTs on those URLs to edit the files. The format of the XML file describing the available templates is:

<templates
xmlns="http://www.purl.org/RESTLog/templates/1.0" >
   <res href="...template.html">HTML Template.</res>
   <res href="...index.rss">RSS Template.</res>
   <res href="...base.css">CSS Stylesheet.</res>
   .
   .
   .
   <res href="...other.svg">SVG Logo.</res>
</templates>

This solution is much more flexible. The files and their descriptions are completely driven by the server. This solution also gave me an idea on how to handle archives.

Right now the only way to edit a post on the client side is to drap and drop a link to the post on the UI. Unfortunately this doesn't work on all versions of IE. It also doesn't work when you forget to include a title on the post, which means there is no link to the post on the web page, which means no way to edit that post. In the future the client should present a list of old posts for the user to choose from. With archives the server could also supply a straight list of URLs like was done above for the templates but after time that list would grow very long and cumbersome. If the archive list became too long it would be slow to download and tedious for the user to seach through to find the item they wanted to edit. The archive listing is just the URIs of each post, not the content. For example I plan on converting bitworking.org to RESTLog eventually and bringing all my old content into the system. That will be close to 1,000 posts. The idea of the Archive Format is a way for the client to present a list to the user of old posts for them to edit. I don't want to download all my content, 1,000 posts, just to present a list to the user for them to select which one article they want to edit/delete.

Note that I didn't use RSS for the format of this file. Even if I did strip out the content and only kept the title and link and use RSS as the archive format then it would just present a linear list of items and for 1,000+ items a linear list wouldn't be very useful for the user to search through. That's why the Archive Format allows a nesting structure, so the posts can be grouped by date, category, etc.

My solution in this case is to use a format similar to the one above for archives but to add two more elements. The first would be the 'group' element and it would be used to group 'res' elements. The second would be the 'more' element, which would contain a URL that could be dereferenced to get more archive listings.

The 'group' element could be used to group items by date, say into months, or by categories. The 'group' elements can be nested arbitrarily. On the client side the 'group' elements could be presented in an explorer like tree structure, the 'group's behaving like the directories and the 'res' elements behaving like the files.

The 'more' elements could also be presented as directories but ones where the information is retrieved after the user tries to expand the tree below that element.

That seems a bit muddled so here is a concrete example. Is this case the server has returned an archive file that is formatted to only have the ten most recent posts listed. The rest of the archives are retrievable from dereferencing the 'more' URL.

<archives
xmlns="http://www.purl.org/RESTLog/archives/1.0">
   <group title="Last Ten Stories">
      <res href="RESTLog.cgi/100">My Most Recent Post</res>
      <res href="RESTLog.cgi/99">My Next Most Recent Pos</res>
      .
      .
      .
      <res href="RESTLog.cgi/91">Some Post In The Recent Past</res>
   </group>
   <more href="RESTLog.cgi/moreViews">All Items</more>
</archives>

Note that the grouping structure of the file returned is completely determined by the server.