================================
Image and Link Libraries in Kupu
================================

Definitions
-----------

Library

  A static or dynamic collection of resources and collections defined
  at a top level. Libraries have no parents from a UI perspective,
  where as the collection they represent might have a parent
  collection.

Collection

  A static or dynamic collection of resources and collections.

Resource

  A named and URI-locatable object with associated metadata, such as
  title, description, preview, size, etc.


Process overview 
----------------

1. The user opens a drawer in Kupu. Kupu requests a list of available
   libraries. The server answers with a list of libraries possibly
    containing URIs at which to get the content listing of each library.

2. Upon user request, Kupu loads the contents of a library and present
   it to the user. Already opened libraries are not reloaded from the
   server

3. A user selects a resource at which point Kupu presents the
   associated metadata and may optionally load a preview image.

4. Double clicking on a collection or selecting a new library triggers
   step 2 again.


List of libraries
-----------------

Kupu issues a simple HTTP GET request to a URL defined in the
'libraries' attribute. The server returns XML conforming to the
following schema::

<grammar xmlns="http://relaxng.org/ns/structure/1.0">

  <start>
    <ref name="librariesDocumentElement" />
  </start>

  <define name="librariesDocumentElement">
    <element name="libraries">
      <zeroOrMore>
        <ref name="library" />
      </zeroOrMore>
    </element>
  </define>

  <define name="library"
    <element name="library">
      <interleave>
        <ref name="commonToAllItems" />
        <choice>
          <ref name="collectionItems" />
          <ref name="load_items_from_uri" />
        </choice>
      </interleave>
      </element>
  </define>

  <define name="commonToAllItems">
    <attribute name="id">
      <!-- Must be unique among all libraries, resources and collections. -->
      <text />
    </attribute>

    <interleave>
      <element name="uri">
        <text />
      </element>

      <element name="title">
        <text />
      </element>

      <element name="icon">
        <text />
      </element>
    </interleave>
  </define>

  <define name="collectionItems">
    <element name="items">
      <zeroOrMore>
        <ref name="collectionItem" />
      </zeroOrMore>
    </element>
  </define>

  <define name="loadItemsFromUri">
    <element name="load_items_from_uri">
      <text />
    </element>
  </define>

  <define name="collectionItem">
    <choice>
      <element name="resource">
        <ref name="commonToAllItems" />
        <ref name="extraResourceInfo" />
      </element>
      <element name="collection">
        <ref name="commonToAllItems" />
        <ref name="loadItemsFromUri" />
      </element>
    </choice>
  <define>

  <define name="extraResourceInfo">
    <interleave>
      <optional>
        <element name="preview">
          <text />
        </element>
      </optional>

      <optional>
        <element name="size">
          <text />
        </element>
      </optional>

      <optional>
        <element name="type">
          <text />
        </element>
      </optional>
    </interleave>
  </define>

</grammar>


For example::

<libraries>

  <library id="http://path/to/folder">
    <title>Current Folder</title>
    <icon>http://path/to/icon.jpg</icon>
    <load_items_from_uri>http://server/current/folder/resources.kupu</load_items_from_uri>
  </library>

  <library id="http://path/to/other/someotherfolder">
    <title>Some Other Folder</title>
    <icon>http://path/to/icon.jpg</icon>
    <load_items_from_uri>http:/server/other/folder/resources.kupu</load_items_from_uri>
  </library>

  <library id="recentitems">
    <title>Recent Items</title>
    <icon>http://path/to/icon.jpg</icon>
    <items />
  </library>

</libraries>


Kupu parses this XML to a DOM and display it using an XSLT
stylesheet. The DOM tree is stored throughout the whole Kupu session.


User opens on a library
-----------------------

In case a collection or library has been active before, it is
deselected (by removing the 'selected' attribute on the DOM node). The
DOM node of the library the user has chosen is selected (by setting
the 'selected' attribute).

Also, deselect the before selected library by unsetting the
'selectedLibrary' attribute on it and setting it on the newly selected
library. This is to support visual marking of the used library while
being able to change folders.

In case its <library> element provides the <load_items_from_uri>
subelement, an HTTP GET to that URI is made, the returned XML
retrieved, turned into a DOM tree and the resulting <items> node of
the result appended to the library DOM node. That step is not made in
case the <library> node directly provides the <items> node.

Now, the XSLT is executed again, presenting the newly selected node
(by querying for the node with the 'selected' attribute) and its
contents.

When a library's contents has to be retrieved with an extra request,
it is returned according to the following schema (using definitions
from above)::

<grammar xmlns="http://relaxng.org/ns/structure/1.0">

  <start>
    <ref name="libraryDocumentElement" />
  </start>

  <define name="libraryDocumentElement">
    <element name="library">
      <ref name="commonToAllItems" />
      <ref name="collectionItems" />
    </element>
  </define>

</grammar>


For example::

<library id="some_unique_id">
  <title>Current folder</title>
  <uri>http://server/current/folder</uri>
  <icon>http://server/folder.ico</icon>
  <items>
    <resource id="another_unique_id">
      <title>Foo img</title>
      <uri>http://server/current/folder/foo.jpg</uri>
      <icon>http://server/image.ico</icon>
    </resource>
    <collection id="a_collections_unique_id">
      <title>Some collection</title>
      <uri>http://server/current/folder/collection</uri>
      <icon>http://server/folder.ico</icon>
    </collection>
  </items>
</library>


User opens a collection
-----------------------

Unselect the previously selected collection and try to execute one of
three cases in order:

  o The node of selected collection is queried for an attribute
  'loadedInNode'. If it exists, it refers to an id of a node which
  already contains that collection's items. Select that node and
  execute the XSLT to present changes.

  o The selected collection node does not have a 'loadedInNode'
  attribute. Therefore, the selected collection's URI is read and the
  document element's children are queried with an XPath to check
  whether the collection with that URI was already loaded before and
  attached to the document element. If so, the selected collection
  node receives an attribute 'loadedInNode' with the value of the
  corresponding collection node below the document element, which is
  selected (by setting the 'selected' attribute). The XSLT is executed
  to present the changes.

  o The selected collection node has no 'loadedInNode' attribute and
  there is no preloaded collection node of that URI. The selected
  node's <load_items_from_uri> subelement is read. An HTTP GET request
  is made to that URI and the items XML data retrieved and turned into
  a DOM tree. The <collection> node of that resulting tree is given a
  new unique ID, appended to the document element of the library DOM
  tree and selected (by setting the 'selected' attribute). The
  selected collection node receives an attribute 'loadedInNode' with
  the value that newly generated id. The XSLT is executed to present
  the changes.

When a collection's contents has to be retrieved with an extra
request, it is returned according to the following schema (using
definitions from above):

<grammar xmlns="http://relaxng.org/ns/structure/1.0">

  <start>
    <ref name="collectionDocumentElement" />
  </start>

  <define name="collectionDocumentElement">
    <element name="collection">
      <ref name="commonToAllItems" />
      <ref name="collectionItems" />
    </element>
  </define>

</grammar>


For example::

<collection id="some_unique_id">
  <title>Some folder</title>
  <uri>http://server/some/folder</uri>
  <icon>http://server/folder.ico</icon>

  <items>
    <resource id="another_unique_id">
      <title>Foo img</title>
      <uri>http://server/some/folder/foo.jpg</uri>
      <icon>http://server/image.ico</icon>
    </resource>

    <collection id="a_subfolders_unique_id">
      <title>Some subfolder</title>
      <uri>http://server/some/folder/subfolder</uri>
      <icon>http://server/folder.ico</icon>
      <load_items_from_uri>http://server/some/folder/resources.kupu</load_items_from_uri>
    </collection>
  </items>

</library>


If a collection's parent collection shall be accessible, then the
server has to return an entry for it explicitly.


Searching
---------

For searching, Kupu sends an HTTP POST request to the server (to a
configurable URI). The server does the search based on the POST form
values and return the results as if they were the contents of a
library. The document element of the returned XML, <library>, does not
have to have a unique id nor an icon subelement.

Kupu treats the search result as a library, with the exception of
generating a unique id and icon for it. The search result library is
attached to the root node of the DOM tree and thus visible and later
accessible via the library list.


Implementation on the Plone side
--------------------------------

On the Plone side, a set of Page Templates is responsible for
generating the XML. They are aided by a special tool, KupuLibraryTool.

In order to use the XML generation for inclusion of media objects,
such as images and photos, as well as for searching documents that one
can link to from Kupu, the library tool keeps a mapping from resource
types to portal types. It provides a management interface in which the
site administrator can define, which portal types are to be treated as
collections, as linkable documents, as insertable media objects, etc.

The library tool also keeps a list of available libraries on the
site. The site administrator can add, modify and delete libraries in
the tool's management interface.


In order to be able to present special previews for resources without
having to load the resource itself in Kupu, a portal type can provide
an action 'preview', such that the preview URI would look like
http://server/object/preview. If a portal_type does not provide that
action, preview is disabled for it.