Annotation of kupu/doc/LIBRARIES.txt, revision 1.1
1.1 ! dwinter 1: ================================
! 2: Image and Link Libraries in Kupu
! 3: ================================
! 4:
! 5: Abstract
! 6: --------
! 7:
! 8: This document describes the Library feature of the Kupu WYSIWYG
! 9: editor. It defines the behaviour on both the client and the server and
! 10: serves as a specification for the XML protocol that is used for their
! 11: interaction.
! 12:
! 13:
! 14: Motivation
! 15: ----------
! 16:
! 17: Kupu is a visual editor for content management systems, with a target
! 18: audience of regular users without a high technical profile. For this
! 19: audience, Word is the incumbent.
! 20:
! 21: In addition to text, Kupu users need a simple, usable, and
! 22: high-performance system for getting images and hyperlinks into their
! 23: pages. Sometimes they want to *browse* to find these assets.
! 24: Sometimes they want to *search*, particularly for large collections.
! 25:
! 26: Regarding usability, open source CMS projects don't have many
! 27: browser-side developers with good usability backgrounds. Since Kupu
! 28: is an oscom.org project, it is a goal to move the UI rendering from
! 29: the server (where talent would be dispersed among projects) to the
! 30: client (where one UI can work for many servers). Therefore, the Kupu
! 31: Library only requests XML from the CMS, not HTML.
! 32:
! 33: Note: Though Kupu will work with IE 5.5 sans service packs, Kupu
! 34: requires MS XML 3.0 or higher. Any IE 5.5 that is up-to-date on
! 35: security updates, and any IE 6 or Mozilla 1.3+ can use the Kupu
! 36: Library.
! 37:
! 38:
! 39: Definitions
! 40: -----------
! 41:
! 42: Library
! 43:
! 44: A static or dynamic collection of resources and collections defined
! 45: at a top level. Libraries have no parents from a UI perspective,
! 46: where as the collection they represent might have a parent
! 47: collection.
! 48:
! 49: Collection
! 50:
! 51: A static or dynamic collection of resources and collections,
! 52: modelled after WebDAV collections.
! 53:
! 54: Resource
! 55:
! 56: A named and URI-locatable object with associated metadata, such as
! 57: title, description, preview, size, etc.
! 58:
! 59:
! 60: Process overview
! 61: ----------------
! 62:
! 63: 1. The user opens a drawer in Kupu. Kupu requests a list of available
! 64: libraries. The server answers with a list of libraries possibly
! 65: containing URIs at which to get the content listing of each library.
! 66:
! 67: 2. Upon user request, Kupu loads the contents of a library and present
! 68: it to the user. Already opened libraries are not reloaded from the
! 69: server
! 70:
! 71: 3. A user selects a resource at which point Kupu presents the
! 72: associated metadata and may optionally load a preview image.
! 73:
! 74: 4. Double clicking on a collection or selecting a new library triggers
! 75: step 2 again.
! 76:
! 77: 5. Clicking on a resource and clicking "Insert" (for an image) or
! 78: "Link" (for links) updates the document and closes the drawer.
! 79:
! 80: 6. If the cursor is on a link or image, the drawer allows editing the
! 81: image/link attributes.
! 82:
! 83:
! 84: List of libraries
! 85: -----------------
! 86:
! 87: Kupu issues a simple HTTP GET request to a URL defined in the
! 88: 'libraries' attribute of the iframe. The server returns XML conforming
! 89: to the following schema::
! 90:
! 91: <grammar xmlns="http://relaxng.org/ns/structure/1.0">
! 92:
! 93: <start>
! 94: <ref name="librariesDocumentElement" />
! 95: </start>
! 96:
! 97: <define name="librariesDocumentElement">
! 98: <element name="libraries">
! 99: <zeroOrMore>
! 100: <ref name="library" />
! 101: </zeroOrMore>
! 102: </element>
! 103: </define>
! 104:
! 105: <define name="library"
! 106: <element name="library">
! 107: <interleave>
! 108: <ref name="commonToAllItems" />
! 109: <choice>
! 110: <ref name="collectionItems" />
! 111: <ref name="itemsSource" />
! 112: </choice>
! 113: </interleave>
! 114: </element>
! 115: </define>
! 116:
! 117: <define name="commonToAllItems">
! 118: <attribute name="id">
! 119: <!-- Must be unique among all libraries, resources and collections. -->
! 120: <text />
! 121: </attribute>
! 122:
! 123: <interleave>
! 124: <element name="uri">
! 125: <text />
! 126: </element>
! 127:
! 128: <optional>
! 129: <element name="label">
! 130: <text />
! 131: </element>
! 132: </optional>
! 133:
! 134: <element name="title">
! 135: <text />
! 136: </element>
! 137:
! 138: <optional>
! 139: <element name="icon">
! 140: <text />
! 141: </element>
! 142: </optional>
! 143: </interleave>
! 144: </define>
! 145:
! 146: <define name="collectionItems">
! 147: <element name="items">
! 148: <zeroOrMore>
! 149: <ref name="collectionItem" />
! 150: </zeroOrMore>
! 151: <optional>
! 152: <element name="uploadbutton" />
! 153: </optional>
! 154: </element>
! 155: </define>
! 156:
! 157: <define name="itemsSource">
! 158: <element name="src">
! 159: <text />
! 160: </element>
! 161: </define>
! 162:
! 163: <define name="collectionItem">
! 164: <choice>
! 165: <element name="resource">
! 166: <ref name="commonToAllItems" />
! 167: <ref name="extraResourceInfo" />
! 168: </element>
! 169: <element name="collection">
! 170: <ref name="commonToAllItems" />
! 171: <ref name="itemsSource" />
! 172: </element>
! 173: </choice>
! 174: <define>
! 175:
! 176: <define name="extraResourceInfo">
! 177: <interleave>
! 178: <optional>
! 179: <element name="preview">
! 180: <text />
! 181: </element>
! 182: </optional>
! 183:
! 184: <optional>
! 185: <element name="size">
! 186: <text />
! 187: </element>
! 188: </optional>
! 189:
! 190: <optional>
! 191: <element name="type">
! 192: <text />
! 193: </element>
! 194: </optional>
! 195: </interleave>
! 196: </define>
! 197:
! 198: </grammar>
! 199:
! 200:
! 201: For example::
! 202:
! 203: <libraries>
! 204:
! 205: <library id="http://path/to/folder">
! 206: <title>Current Folder</title>
! 207: <icon>http://path/to/icon.jpg</icon>
! 208: <src>http://server/current/folder/resources.kupu</src>
! 209: </library>
! 210:
! 211: <library id="http://path/to/other/someotherfolder">
! 212: <title>Some Other Folder</title>
! 213: <icon>http://path/to/icon.jpg</icon>
! 214: <src>http:/server/other/folder/resources.kupu</src>
! 215: </library>
! 216:
! 217: <library id="recentitems">
! 218: <title>Recent Items</title>
! 219: <icon>http://path/to/icon.jpg</icon>
! 220: <items />
! 221: </library>
! 222:
! 223: </libraries>
! 224:
! 225:
! 226: Kupu parses this XML to a DOM managed in JavaScript and displays it
! 227: using an XSLT stylesheet. The DOM tree is stored throughout the whole
! 228: Kupu session.
! 229:
! 230:
! 231: Browser-side architecture
! 232: ------------------------------------
! 233:
! 234: When the drawer is opened, Kupu loads the XML data about the libraries
! 235: into a JS property that holds an XML DOM. The Sarissa cross-browser
! 236: abstraction for XML (http://sarissa.sf.net) is used.
! 237:
! 238: As the user clicks, more XML data are loaded if that collection hasn't
! 239: been visited yet. The loaded XML is then appended into the XML DOM.
! 240: The node that was clicked on has an attribute set to mark it as
! 241: selected. Kupu then runs an XSLT on the XML DOM to re-generate the
! 242: drawer contents (as HTML), and updates the HTML node with the output.
! 243: The use of XSLT and XPath give increased performance, lower line
! 244: count, and better IE/Mozilla compatibility.
! 245:
! 246: As an implementation note, XML is extremely compressible. With
! 247: mod_deflate and other server-compression approaches, at least a
! 248: thousand entries can be encoded in 100 Kb.
! 249:
! 250: User opens on a library
! 251: -----------------------
! 252:
! 253: In case a collection or library has been active before, it is
! 254: deselected (by removing the 'selected' attribute on the DOM node). The
! 255: DOM node of the library the user has chosen is selected (by setting
! 256: the 'selected' attribute). Also, visually deselect the before selected
! 257: library (by unsetting a CSS class) and mark the newly selected library
! 258: (with a CSS class).
! 259:
! 260: In case its <library> element provides the <src> subelement, an HTTP
! 261: GET to that URI is made, the returned XML retrieved, turned into a DOM
! 262: tree and the resulting <items> node of the result appended to the
! 263: library DOM node. That step is not made in case the <library> node
! 264: directly provides the <items> node.
! 265:
! 266: Now, the XSLT is executed again, presenting the newly selected node
! 267: (by querying for the node with the 'selected' attribute) and its
! 268: contents.
! 269:
! 270: When a library's contents has to be retrieved with an extra request,
! 271: it is returned according to the following schema (using definitions
! 272: from above)::
! 273:
! 274: <grammar xmlns="http://relaxng.org/ns/structure/1.0">
! 275:
! 276: <start>
! 277: <ref name="libraryDocumentElement" />
! 278: </start>
! 279:
! 280: <define name="libraryDocumentElement">
! 281: <element name="library">
! 282: <ref name="commonToAllItems" />
! 283: <ref name="collectionItems" />
! 284: </element>
! 285: </define>
! 286:
! 287: </grammar>
! 288:
! 289:
! 290: For example::
! 291:
! 292: <library id="some_unique_id">
! 293: <title>Current folder</title>
! 294: <uri>http://server/current/folder</uri>
! 295: <icon>http://server/folder.ico</icon>
! 296: <items>
! 297: <resource id="another_unique_id">
! 298: <title>Foo img</title>
! 299: <uri>http://server/current/folder/foo.jpg</uri>
! 300: <icon>http://server/image.ico</icon>
! 301: </resource>
! 302: <collection id="a_collections_unique_id">
! 303: <title>Some collection</title>
! 304: <uri>http://server/current/folder/collection</uri>
! 305: <icon>http://server/folder.ico</icon>
! 306: </collection>
! 307: </items>
! 308: </library>
! 309:
! 310:
! 311: User opens a collection
! 312: -----------------------
! 313:
! 314: Unselect the previously selected collection and try to execute one of
! 315: three cases in order:
! 316:
! 317: * The node of selected collection is queried for an attribute
! 318: 'loadedInNode'. If it exists, it refers to an id of a node which
! 319: already contains that collection's items. Select that node and
! 320: execute the XSLT to present changes.
! 321:
! 322: * The selected collection node does not have a 'loadedInNode'
! 323: attribute. Therefore, the selected collection's URI is read and the
! 324: document element's children are queried with an XPath to check
! 325: whether the collection with that URI was already loaded before and
! 326: attached to the document element. If so, the selected collection
! 327: node receives an attribute 'loadedInNode' with the value of the
! 328: corresponding collection node below the document element, which is
! 329: selected (by setting the 'selected' attribute). The XSLT is executed
! 330: to present the changes.
! 331:
! 332: * The selected collection node has no 'loadedInNode' attribute and
! 333: there is no preloaded collection node of that URI. The selected
! 334: node's <src> subelement is read. An HTTP GET request is made to that
! 335: URI and the items XML data retrieved and turned into a DOM tree. The
! 336: <collection> node of that resulting tree is given a new unique ID,
! 337: appended to the document element of the library DOM tree and
! 338: selected (by setting the 'selected' attribute). The selected
! 339: collection node receives an attribute 'loadedInNode' with the value
! 340: that newly generated id. The XSLT is executed to present the
! 341: changes.
! 342:
! 343: When a collection's contents has to be retrieved with an extra
! 344: request, it is returned according to the following schema (using
! 345: definitions from above)::
! 346:
! 347: <grammar xmlns="http://relaxng.org/ns/structure/1.0">
! 348:
! 349: <start>
! 350: <ref name="collectionDocumentElement" />
! 351: </start>
! 352:
! 353: <define name="collectionDocumentElement">
! 354: <element name="collection">
! 355: <ref name="commonToAllItems" />
! 356: <ref name="collectionItems" />
! 357: </element>
! 358: </define>
! 359:
! 360: </grammar>
! 361:
! 362: This grammar is modeled after the WebDAV response grammar, without
! 363: using the namespace parts of WebDAV. For example::
! 364:
! 365: <collection id="some_unique_id">
! 366: <title>Some folder</title>
! 367: <uri>http://server/some/folder</uri>
! 368: <icon>http://server/folder.ico</icon>
! 369:
! 370: <items>
! 371: <resource id="another_unique_id">
! 372: <title>Foo img</title>
! 373: <uri>http://server/some/folder/foo.jpg</uri>
! 374: <icon>http://server/image.ico</icon>
! 375: </resource>
! 376:
! 377: <collection id="a_subfolders_unique_id">
! 378: <title>Some subfolder</title>
! 379: <uri>http://server/some/folder/subfolder</uri>
! 380: <icon>http://server/folder.ico</icon>
! 381: <src>http://server/some/folder/resources.kupu</src>
! 382: </collection>
! 383: </items>
! 384:
! 385: </library>
! 386:
! 387:
! 388: If a collection's parent collection shall be accessible, then the
! 389: server has to return an entry for it explicitly.
! 390:
! 391:
! 392: Searching
! 393: ---------
! 394:
! 395: For searching, Kupu sends an HTTP POST request to the server (to a
! 396: configurable URI). The server does the search based on the POST form
! 397: values and return the results as if they were the contents of a
! 398: library. The document element of the returned XML, <library>, does not
! 399: have to have a unique id nor an icon subelement.
! 400:
! 401: The POST request can contain an optional parameter for the size of the
! 402: result set. The server can enforce an upper limit itself, and if the
! 403: request parameter is higher, ignore it. By default, this value is 500.
! 404:
! 405: Kupu treats the search result as a library, with the exception of
! 406: generating a unique id and icon for it. The search result library is
! 407: attached to the root node of the DOM tree and thus visible and later
! 408: accessible via the library list.
! 409:
! 410:
! 411: Implementation on the Plone side
! 412: --------------------------------
! 413:
! 414: On the Plone side, a set of Page Templates is responsible for
! 415: generating the XML. They are aided by a special tool, KupuLibraryTool.
! 416:
! 417: In order to use the XML generation for inclusion of media objects,
! 418: such as images and photos, as well as for searching documents that one
! 419: can link to from Kupu, the library tool keeps a mapping from resource
! 420: types to portal types. It provides a management interface in which the
! 421: site administrator can define, which portal types are to be treated as
! 422: collections, as linkable documents, as insertable media objects, etc.
! 423:
! 424: The library tool also keeps a list of available libraries on the
! 425: site. The site administrator can add, modify, delete and reorder
! 426: libraries in the tool's management interface. The searching aspect of
! 427: Kupu Libraries is handled by the portal catalog.
! 428:
! 429: Permissions used by the library tool:
! 430:
! 431: - Kupu: Query libraries
! 432:
! 433: This permission is required for all users who want to query
! 434: libraries from the library tool.
! 435:
! 436: - Kupu: Manage libraries
! 437:
! 438: This permissions is required for all administrators who need to add,
! 439: edit and delete existing libraries.
! 440:
! 441: In order to be able to present special previews for resources without
! 442: having to load the resource itself in Kupu, a portal type can provide
! 443: an action called 'kupupreview', pointing to the URL where the object's
! 444: preview can be retrieved. If a portal_type does not provide that
! 445: action, preview is disabled for it.
! 446:
! 447: Example: Preview action for CMFPhoto showing each photo's thumbnail
! 448: version:
! 449:
! 450: - Go to the portal_types tool and click on the 'Photo' portal
! 451: type. Then click on its 'Actions' tab.
! 452:
! 453: - Down below enter information for a new action:
! 454:
! 455: Name: Kupu Preview
! 456: Id: kupupreview
! 457: Action: string:${object_url}/variant/thumbnail
! 458: Condition: [empty]
! 459: Permission: View
! 460: Category: object
! 461: Visible? False
! 462:
! 463: - Hit the 'Add' button.
! 464:
! 465:
! 466: Futures
! 467: -------
! 468:
! 469: * Cached XSLT (need Sarissa support for this)
! 470:
! 471: * Deeper standards support (WebDAV/DASL)
! 472:
! 473:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvs/cvsweb/icons/back.gif){kind=icon}
Return to LIBRARIES.txt CVS log ![[TXT]](/cvs/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvs/cvsweb/icons/dir.gif){kind=icon}
Up to [Repository] / kupu / doc