Introduction
XIMS data was not only designed for monolitic content. One key target was to be able to have information areas (portlets) that can be added to any page as prefered as well as combined to complex pages commonly known as Portals. This document describes the concept of portlets and portals in XIMS.
XIMS itself will not handle the presentation of a portlet, but helps organizing the content a certain portlet offers the user. This may differ from what a xsl rendered version may display to a user. Therefore XIMS offers an abstract view on a portlet or portal.
This document is split into two major parts: (a) A major outline about the concept of Portals and portlets in XIMS and (b) an introduction into the technical implementation of these special object-types.
[ top ]
Concept of Portals and Portlets
Poratals and Portlets should provide a different view on data stored in different places and/ or different ways. This is often called content syndication.
Portlets
What are Portlets
A portlet is a special view on a set of data. On webpages portlets commonly appear as boxes aside of the main content of a page. E.g. a site navigation showing the toplevel documents and folders, is such a special portlet.
Technically a portlet is not part of the content of the page its shown with. From that view a portlet is part of the interface and needs to be loaded by the associated stylesheet. From that point a portlet is similar to a widget of graphical userinterfaces. XIMS itself stores only the information which information should made available to the real widget (which is part of the stylesheet) - once more XIMS splits information and presentation.
For the content manager this means he has to decide how to organize the information that will be shown in the portlet. To understand this workflow there is need to explain how portlets work.
XIMS implements portlets as filter on objects. This means a portlet is similar to a symbolic link: it points to the object it should filter. Then a user may specify rules to control the content available in the portlet. This filter behaves differently depending of the general type of the object it points to. From the view of a Portlet there are only two different types of objects: content and container. A filter on a content object (like a document) will only filter the column data of the object the portlet points to. If the portlet points to a container object (such as folder, DepartmentRoots etc.) the filter will not filter the object itself but the child objects (descendants?) of the given object. Therfore a portlet pointing to a container has an object filter in addition to the content filter as already described.
While a content filter restricts the data of an object that is stored in the portlet, the object filter allows to define a subset of objects, that are made available. For example a news portlet may only display those documents of the referred folder that have the new flag set. How these filters are build are described below in more detail.
Where to use them
Portlets are always useful when information should be made available in the same (or at least similar) way on a set of pages. Portlets help to organize such views.
Therefore a portlet is always usefull if such a view is shared by many content pages or if data has to be collected from different content objects. The latter is important for portal pages (see below).
Portals
What are Portals
After discussing portlets, portals are the next step. Basicly a portal is a page containing only references to portlets (no other protlet types). In common such pages are found as the startpages of a certain site which is where the name originally comes from. In XIMS such pages may appear at any level an user preferres.
Inside XIMS a portal is stored as a container that can only contain symbolic links to portlets. In the exported filesystem the portal will be transformed into a XML document containing a bunch of x-includes. This means the portlets of a portal are not loaded by the stylesheet. Instead they are provided directly by the portal document.
When to use Portals
Portals are useful if there is content spread over various object or folders and should be shown under a single location as an overview.
[ top ]
Technical Outline
Portlets
Common Implementation
All Portlets are special symbolic links. Different to symbolic links they don't make the referred content just available. Instead they are ment to offer a special filtered view on the stored content. There are two variations of these filters: Content filter and Object Filter. From the view of the filesystem portlets are pseudo container, containing parts of the data of other objects.
The different filter types do not affect each other. A content filter must be aware about the different object types, since not all object types have all columns present.
Object Filter
An object filter decides which objects are stored inside the portlet.
Content Definition
The Content Definition restricts the object data stored in the portlet itself. Such a filter limits the information of a given object that will be stored in the portlet. This gives the user control about the information that is directly available in the portlet. One can understand this section as the projection part in SQL Queries.
Content Definition work global. This means no difference is made between the various object types on the description level or on the hierarchical level. Thus an user can specify either if a column should be existent in a portlet or not.
The definition works global, since only the object types specified in this section will be available in the portlet - no matter where they are found in the hierarchy.
Common Filter Flow
The filters are commonly run as a SAX filter before output.
- Parsing of the object-filter conditions
- Fetch the object id's from the database
- Check which information each object should contain
- Fetch the objects as required from the database
Exporter
There are two stages of the portlet export. First there is the generic export such as for any other object as well. In this case the filters are run to decide which content is stored inside the portlet. After the initial export the portlet enters an auto-export mode.
Portlet Types
Headlines
not done yet
Journals
not done yet
Link Lists
not done yet
Object Portlets
An object portlet is a little special to the other portlet types. First it is a link to a special object, that is not a container. Because of this an object portlet has only Content Filter.
Filter Language
A user should be able to define the filters applied on a portlet through the interface. Internally this information is stored as XML in the body field of the portlet. This information must using a kontextfree definition. Also the two types of filter types has to be represented in this as well.
TODO: filter schema
Content Definition
The content of the portlet is described in a special section of the portlet definition: the content-definition.
the content definition contains 4 items:
column
object-type
depth
resolve-links
The column has a required attribute name. This name has to hold the column name, that should be extra loaded with the portlet. One needs only to specify extra columns. A portlet will always contain a set of basic columns such as location or object title for an object.
The column tag has no content. For each extra column to be loaded in the portlet on MUST specify a new column tag.
The object-type entry tells the content definition which object types the portlet MUST contain. This is a positive list. each object regardless of its level has to match one of the specified object-types. if no object type is defined all objects will be loaded.
The depth entry has a single attribute level that contains the numeric value of childobject levels to load into the object. There MUST exist maximum one depth entry for the entire portlet.
The depth specified here defines only the level up to which data will be loaded. The portlet filter itself will only work on the first level of objects loaded into the portlet.
If no depth is specified the default depth is set to 1.
Another entry that changes default content of the portlet is resolve-links. This entry either exists or not. It has no data and contains no attributes. It is mainly a flag that tells the portlet to treat the target of Symbolic Links as objects in the hierarchy.
The Filter definition
Besides the Definitions what content exists inside the portlet. a portlet must also have a mechanism to define how to restrict the objects to be loaded into the portlet. This is done by the portlet filter. One can think of a portlet filter as of the WHERE clause in SQL queries.
The Filter definition contains several tags:
column
the column tag MUST have the name attribute that contains the column name to filter. The tag MUST contain at least one value entry. each value must be found exact in the column to match. if more than one value is defined, at least one of the values has to match. If no value entry can be found the specific column filter will be ignored.
If a column contains character data optionaly a value entry can be wrapped into a has tag. in this case the value has to appear somewhere in the column. (similar to SQL like)
The portlet filter will check the value types. as soon a value is off an invalid datatype, the entire condition will be ignored.
object-type
The object type defines a type of which an object MUST be to be filtered. The object-type MUST contain the attribute name. This attribute MUST contains a single object type name (e.g. Document).
If more than one object type is specified, a filtered object must match at least one of the object-types to be filtered.
For filters that work only on the first child level this is equivalent to the object-type entry in the content definition.
child-object
This entry defines some condition at least one child object must match to filter the object. each child-object may contain column or object type entires but at least one of them.
to specify more complex conditions one can wrap any element inside logical conditions: Not, And and Or. On default all entries are in Or relation. This allows restrict the filter.
A simple Example
the following example shows a simple filter to show how the filter schema works.
<content>
<column name="new"/>
<column name="last_modified_by_id"/>
<column name="abstract"/>
<column name="keywords"/>
</content>
<filter>
<column name="new">
<value>1</value>
</column>
<column name="title">
<has><value>Foo</value></has>
</column>
<object-type name="Document"/>
</filter>
This example loads the extra information about the object's New flag, its last modifier, the abstract and the keywords of each object found. All this is done for all objects in scope.
If no filter would be set this would load all this information for all objects inside the object refered by the portlet. In the example though is a filter specified: we want all objects that are either of type 'document', have the new Flag set or have the string 'Foo' somewhere in the string. this means the portlet specified here will contain all documents plus all other objets that match the condition for the title column and those objects that have the new-flag set to 1. As one can imagine this may return pretty much data.
If we want all object's of type 'document' that are considered as 'new' (new==1) and contain the string Foo in their title, we need to wrap the filter condition into an And:
<content>
<column name="new"/>
<column name="last_modified_by_id"/>
<column name="abstract"/>
<column name="keywords"/>
</content>
<filter>
<And>
<column name="new">
<value>1</value>
</column>
<column name="title">
<has><value>Foo</value></has>
</column>
<object-type name="Document"/>
</And>
</filter>
If everything is infact combined by a logical And now, it is usefull to place the object type information into the content definition:
Note that the And-Tag has to wrap all entries that must be valid at the same time.
<content>
<object-type name="Document"/>
</content>
<filter>
<column name="new">
<value>1</value>
</column>
<column name="title">
<has><value>Foo</value></has>
</column>
</filter>
This will filter all document objects that are either new or have 'Foo' somewhere in their title. Placing the object type into the content definition gives the portlet a hint what is really your content.
<content>
<object-type name="Document"/>
<object-type name="SimpleXML"/>
<depth level="2"/>
</content>
<filter>
<And>
<Or>
<column name="new">
<value>1</value>
</column>
<column name="title">
<has><value>Foo</value></has>
</column>
</Or>
<object-type name="document"/>
</And>
</filter>
What is this doing? It is similar to the previous filter, but if filters also all child objects for the filtered documents, that are either Documents or SimpleXML objects. In fact this is the same query as the previous one, since Document objects cannot have other documents or simple XML as child objects. But i think this illustrates how complex object types can efficiently be filtered.
Portals
Technically a portal is a special Folderobject that may contain only portlet ojects. Since a single portlet may is used in various places, the portal itself may contain only symbolic links to the Portlets it should contain. Because of this restriction a Portal may only contain existing portlets, that live outside the portal itself.
If a portal is published it will not be published as a directory, but as a XML file that x-includes each currently published and referred Portlet instead of containing the real data inside the document. Because of this the portal needs only to be updated if a portlet is initially published (not on republish!). Doing this a Portal is automaticly updated as soon one related portlet is updated, too. As well this reduces the times the portlet filter have to be processed.
An example portal document may look like this:
<document>
<objectlist>
<xinclude:include href="/path/to/portlet.xml"/>
<xinclude:include href="/path/to/portlet2.xml"/>
<xinclude:include href="/path/to/portlet3.xml"/>
<xinclude:include href="/path/to/portlet4.xml"/>
</objectlist>
</document>
[ top ]
