Solprovider Lenya Kongregate Registration for Free Flash Games and Chat with solprovider

Developer Mailing List 2

This is another temporary article composed of my writing on the Dev ML. There were many replies to a few of my posts on a Dev ML Thread about Lenya Terminology. I answered most of them, and basically shut down the discussion. Here are my replies, with information already in the Glossary removed. Some of it is why I defined the terms as I did.

Historically, "Content" refers only to a collection of "Documents", and "Resources" referred a collection of "Assets". If "Assets" are not included, we should keep the term "Content". Either term ("Content" or "Resources") is good for the collection of Documents and Assets, but changing it to "Resources" may reduce confusion with the historical definition of "Content".

"Navigation" is better/shorter than "Navigation Element", but has the issue that it is commonly used for the collection of all methods to navigate a website (Navigation Elements and static links).

In Lenya, a Website consists of one or more Publications. A Publication is a collection of Resources (Documents and Assets), and any special functionality. Documents and Assets are maintained by Language (Translations), and each edit creates a new Revision for historical documentation and the ability to rollback to an older Revision. Indexes provide selection of Documents for use by various functionality, including Navigation Elements which provide easy access to the Documents through the web interface.

"Indexes can have a flat or hierarchical structure.": Indexes implies dynamic, where structure implies static. Since I want there to be multiple configurable methods of retrieving the relationships between Documents, Indexes is the better choice so the technology will follow.

In Lenya1.2:
"Resources" is the file system directory name for "Assets". It was only seen by developers, and was never defined well. The directory name should disappear in Lenya1.4 if the Assets are moved to the repository. I like Resource as the superclass for Documents and Assets.

"Content Item" implies an "Item" of "Content". 1.2's "Content" contained "Documents", so "Content Item" is an alternate name for a "Document". "Item" is used by other systems for a piece of data (a cell in a table in most databases), and XML uses Item as a superclass for Nodes, Elements, Properties/Attributes.

In Lenya 1.2, "content" was the name of the directory containing the documents, but the same argument that "resources" was only a directory name and never seen by editors applies.

As much as I dislike using two words where one is sufficient, I agree a CMS should use the word "content" somewhere. Although our marketing could use "Lenya is more than a Content Management System; it is also a Resource Management System." That means nothing but could influence business managers.

I am pushing for dynamic Sitetrees are generating data similar to 1.2's sitetree.xml. A Sitetree Node is a node as used in menu.xsl and other Navigation Elements.

- Publication
- - Content
- - - Document (has Type, DocumentUNID, DocumentID properties)
- - - - Translation (has Language and LiveRevision properties)
- - - - - Revision (has CreationDate and Editor properties)
- - - Asset (has Type, UNID, ID properties)
- - - - Translation (has Language and LiveRevision properties)
- - - - - Revision (has CreationDate and Editor properties)

- Assets have Revisions and Workflow like Documents.
- The URL for Assets is based on the Publication. Usage could be as simple as "/mypicture.gif" for the server's default pub, or "/mypub/mypicture.gif" for other pubs. That would require the default "live" Module checks extensions for handling. There are many possible algorithms:
- - "live" retrieves the data;
- - "live" passes to "assets" which retrieves the data;
- - "live" passes to "assets" passes to "images" which retrieves the data.
Any of these options are easier than 1.2's Make Link "docid/assetname.ext".

"Asset is a financial term."
Accountants use the word to mean anything of positive value, as opposed to "Liabilities" which are anything of negative value. Lenya 1.2's GUI used the term for anything uploadable stored as a file. I suggest using the term for any user-driven content that is not XML. That supersets the Lenya 1.2 usage in a way understandable by the public.

"Assets as part of Pages."
"Pages contain one or more Documents."
These statements confuse storage and development needs with presentation.

A Document is XML. An Asset is not XML.
- In Lenya 1.2, Assets were associated with a Document. This causes major headaches for users because they must use the docID in the URL to make a link.
- I suggested making Assets children of Publication/Content, just like Documents. Then both Documents and Assets can have a parent class that provides multiple languages (Translations) and versions (Revisions). The major difference is that Documents can be processed by XSL statements (map:translate). It is impossible to do XSL Transformations on non-XML data.

A "Page" is the unit a visitor sees on the Website. Pages are created by Modules. A Module can aggregate Documents and the results of other Modules to create a Page. The Page can include links to Assets and other Pages. Pages are dynamically generated by Modules. Although it is possible (and useful for testing) to have a Module that dumps a Document to the visitor, no Website would use that Module in production. All decent Websites provide some navigation, preferably without dead ends (one reason to avoid PDFs), and the minimum production Module should add a "Home" or "Back" link to every Page.

The important point is that "Page" is not something storable in Lenya (except in the non-functional cache where the HTML and other content generated by Lenya is stored for performance.)
A PDF is not a Document, because a PDF is not XML. Most PDFs would be uploaded as Assets.

A Module may transform a Document (or multiple Documents and possibly Assets) into a PDF. The result could be saved in Lenya as an Asset, but performance could be improved without creating another static resource by saving the results in the non-functional cache. The URL of the PDF would be the URL of the PDF-creating Module and any parameters it requires to create the specific PDF.

If a PDF is uploaded, then it is an Asset.

If the PDF is dynamically generated, then it is accessed though a Module:
The parameter(s) could be:
- a single Document identifier that is transformed to PDF using XSL.
- several resources (Document and Assets) sequentially added to PDF.
- a key identifying a configuration document.
- anything else imaginable.

It seems likely the parent Node of Documents and Assets will be named "Content", and the superclass for Documents and Assets will be named "ContentItem" (although I still prefer "Resource" to reduce the word count and remove the capital 'I'):
First, we need a superclass for objects placed in Content. This superclass contains identifiers, security information, and Translations (Nodes for different languages). Each Translation contains Revisions (Nodes for historical versions of each Translation).

For the name of the superclass, we were discussing "ContentItem" or "Resource". Now you suggest "Asset" right after a discussion that wanted to define Assets as parts of a Document. Lenya 1.2 defines an Asset as an uploaded file. Why would we create a new definition of "Asset"? Are we trying to confuse everybody?

Second, we need to separate XML and non-XML. Storage could use <resource type="XML"> and <resource type="non-XML">, but programming requires different class names for each.

XML data can be aggregated, transformed, and serialized. "Document" is well-defined in XML and Lenya 1.2 as an XML Document. Why would we change that? Documents then have Types based on the DTD, (and possibly a PI or other XML.) In Lenya 1.2, the doctype parameter decided the Type. In 1.4, every Document should know its Type, but can be overridden (ignored) by Modules. XML data can be edited using the CMS GUI.

For Non-XML data (Assets), there will be different functions. Non-XML data needs to be downloadable (serialized as binary?). It cannot be transformed. It might be converted to Base64 for use as XML, but would use the BinaryToBase64 Module, which is not part of core. Assets can be uploaded; they cannot be edited using the CMS GUI.

Third, there are several options for the datastore:
1. Content/Resource[Type="XML|Not XML"]
My experience suggests using Elements will prove much easier (less code) than using an Attribute for something so basic. It is the difference between:
<xsl:apply-templates select="resource[type='xml']"/>
<xsl:apply-templates select="document">
It is one extra test (repeated extremely often) that can be avoided by better design.

2. Content/Document and Content/Asset
It should be easy to get all the Nodes of one Type.

3. Content/Documents/Document and Content/Assets/Asset
This makes it extremely easy to get all the Nodes of one Type, but makes functions where the ContentType (or ResourceType) is irrelevant much more difficult. If you want a list of the latest updates, you need to search Documents and Assets separately and then merge the lists and resort the result. A simple search for Resources that have a new Revision ready but unpublished becomes difficult. And it adds a Node that exists only to categorize other Nodes; I cannot think of anything useful to add to these extra Nodes.

Fourth (repeating #2), regardless of how they are stored, programming requires separate classes because too much functionality is different. Identification, security, language support, workflow, and relations can be handled by the superclass, but how they are used within Lenya and how they are sent to visitors is very different. Why store them in a struture that requires extra programming throughout Lenya?

<< Notes: Dev ML 1Notes: Dev ML 3 >>

Contact Solprovider
Paul Ercolino