xmlportal.net Knowledge Base

Here you can find written documentation about XMLPortal and its components, along with whatever related to this site that deserves to mention.

How does it work?

This XMLPortal context has a traversal navigator below the breadcrumps and above this page. This navigator moves pages one by one as might occur when you read a book. By clicking the next arrow you will traverse all pages in hierarchycal order. By convention, we called Books the first level contexts within Documents. Books' children are Chapters and so on. However, XMLPortal isn't limited to an specific number of descendants and can grow as much as documentation requires. This also leads to the idea of Books within Books.

Another difference in this context is the bottom component, currently showing a Print version option. Print version does traverse the currently viewed context and renders all descendants together, in reading order. The resulting is optimized for printing purposes.

Currently available books

Overview

XMLPortal is an application framework based on components. Web Application Developers would not start from scratch, instead will implement standard interfaces. Some of the great advantages of using XMLPortal are the existing set of components and site administration. XMLPortal users can expand the site at will, by adding childs to existing pages and selecting whether these childs my or not show in navigators.

Navigators might be a good example of what a component is. DefaultNavigator is a class that queries the page constructor, IConstructor interface, in order to create lists of contexts based on a single level, a tree of contexts or a tree-traversing navigator. Due layout strategy, navigators can be configured at top level and operate at n-level. See more on navigators at Default Navigator

Offerings for developers

Take a look at the XMLPortal building structure. By creating a new component, you are reusing a lot of already working code. Your application will integrate smoothly into already existing web sites, using standard components as: Portal Mailing System, Automated Mailing Lists, Web Search System, Page Scripting, Macro Scripting, etc.

Offerings for web masters and/or final users

Web masters will enjoy using the existing set of components. It gives them full power on web site appearence while makes quite easy creating new pages and their content. Navigation issues are fully supported by XMLPortal configuration files, with attributes like: Show In Navigators, Tell Robots NOT_TO_INDEX / NOT_TO_FOLLOW, Supported Languages, Internationalized Names, etc.

Page's content is also greatly assisted. When no component is defined, XMLPortal's DefaultElement takes place. DefaultElement implements what is required to create page content. Repository for images and documents, easy syntax (no HTML, though is permited), version control, author tracking, multi-language support, etc.

One of the magic things that make XMLPortal easy to use and powerful is the structure is build on. When XMLPortal takes control you are always in a Context . As for creating web pages, you'll need to understand what a context is and its relation with other contexts.

A context is a web page. We didn't called web page because it seemed too simple for such a marvellous creature, but is nothing more than a web page. Anyway, as to continue making things complicated where they should be easy, we will call this web page a context.

Construction

Context builds up with two different kinds of elements. The actual elements and the layout elements. Despite their names, they respond to a very usual situation. You know how your site should look and don't want to repeat the design for each page. These elements are the layout elements. They are defined at top level, in site's home, and inherited for lower levels.

The image shows what the layout elements are, surrounding the actual content, which is not more than the actual element mentioned above.

By default, the actual element is HTML content, text, written with the special XMLPortal syntax.

Pages

XMLPortal sites allow creating as many contexts as you might require, remember a context is equivalent to a page. There is no other limit than the available space and your imagination. Creating pages involve thinking where you want to contruct them. To understand this you might think of your site as a tree. The trunk is the home page. First branches will be home its children and so on. Your tree can have many branches, XMLPortal will take care to make easy the navigation among them.

We already mentioned this, but a reminder will help having things in place: Context are web pages and they render layout elements and actual elements. XMLPortal default configuration defines several layout elements that help web branding and navigation.

Default layout elements

Top banner: Editable. Usually used for branding, logo, languages.
Tabs navigator: Renders root its children, that is, any context created as a child of home context.
Breadcrumps navigator: Renders current page its path. Helps understanding in which part of the site we are.
Lateral menu: Renders current first level context its children. In short, renders selected tab's children. By default preloads and shows 2 levels. This menu has been told not to show when have nothing to show. For this reason will only appear when there are children to navigate.
Bottom banner: Editable. Foot notes.

Default actual element

XMLPortal treats new contexts as web pages, allowing editable content. When creating a new context you will get an editable space, with new, edit and delete buttons.

Actual element choices

Although, it's possible to add different elements to a context. Currently allowed elements are:

Each context has several attributes that define its behaviour.

Attribute	Description
Order	Controls context ordering. It's an alphanumeric value, write numbers with leading zeros. ex. 001, 002 and so on.
Show in navigators	When selected the context is shown in navigators. It's useful when you have pages you don't want them accessed directly.
Show always	Even if the context is protected by a role, it will show in navigators. With this attribute set to true, a context will force visitors to login if they want to see the content.
Context role	Protects a context using user's roles.
Language	Coma separated list of languages used in this context. This value is inherited from parent context. If you set a language in root context, web site's `home`, will be used in the whole site, unless you override the value.
Redirection	Redirects to a different context when context is selected. Useful for empty contexts that serve as parents of real content.
Not to index / Not to follow	Values passed to search engines. `Not to index` tells not to keep the page indexed. `Not to follow` tells not to follow page's links.
Show print version option	When checked, shows a link to printer version. Print version will render current page and all its descendants in reading order.
Show control version system	When checked, shows different versions of this page, including language, author and modification date.
Name	Context's name. Yoy may need to specify as many names as languages the context has. Name is what appears on menus, tabs, popup menus, etc.

When you want to show an image in a page, you need first to upload the image file. Where this file goes to it's called repository. Each context has its own repository. So, you have as many repositories as web pages. Each one with its own structure and content.

Currently, the only way to access the repository is by adding an image to the page and then clicking on the image icon. This will soon be solved with an special access to repositories.

XMLPortal 3.0 is entirely driven by components

The standard components included with XMLPortal are:

An XMLPortal component is a Java class implementing a set of interfaces. Depending on which interfaces implement, the component will be renderable, administrable, navigable, defendable, etc.

These interfaces are:

WorkFlows

XMLPortal renders macros each time a page is requested. Macros start with {@ special characters and expand into text or HTML code. Macros can even include content from a file, HTML page or JSP page. In order to understand what macros are for see what current macros do:

Content macros help creating pages that are rendered using content scattered elsewhere.

Macro	Description
{@render:context[:stopper]}	Renders context content. If stopper is set to true, stops when finding a line starting with <end/>.
{@frame:url:width:height}	Creates a frame with url content. If url starts with '/' application context is automatically inserted. Width and height control frame dimensions.
{@include:path_to_file}	Include file content.

Listing macros use XMLPortal context tree in order to list related contexts.

Macro	Description
{@list:behavioural_keywords: navigational_keywords:selection_keywords}	Renders a list of selectable contexts
{@anchor:behavioural_keywords: navigational_keywords:selection_keywords}	Renders a line of selectable contexts

Understanding what `behavioural keywords` are

Behavioural keywords stand for keywords controlling how information displays. The way behaviours will extend in future versions might be controlled in this section.

Behavioural keyword	Description
verbose	Writes the whole path to context, starting from current context.
popup	Popup effect on resulting links is to open a popup instead of opening a new context.

Understanding what `navigational keywords` and `selection keywords` mean

Navigational keywords end up as a list, colon separated, of keywords pointing to existing contexts. As starting point, path_to_contexts initializes to current context, that is, the web page where macro displays.

Here comes a brief description of what each keyword does and after some clear examples:

Navigation keywords move current selection from context to context.

Navigation keyword	Description
parent	Moves to current selection's parent
root	Moves to root context
locate	Moves next token path
match	Moves to matching context from current selection

Selection keywords actually return contexts, one or several. A zero results it's considered an error an macro will displays with m_error class, which defaults to red color and a warning image. Otherwise, macro expands into m_list class.

Render keyword	Description
self	Returns current selection
children	Returns current selection's children
all	Returns all descendant contexts
leaf	Returns all descendant contexts having no children
ancestors	Returns current selection's ancestors
siblings	Returns current selection's siblings, including itself
search	Returns matching contexts from current selection

Learning by example

Macro

Description

{@list:self}

Listing

{@anchor:self}
Listing

self returned current selection which defaults to current context

{@list:parent:children}

{@anchor:parent:children}
[ Content, Listing, Navigational, Generic ]

parent took us into current context its parent, while children returned a list of its children

Navigational macros aim to definitely free XMLPortal from complicated configuration files and head to html markup templates.

Macro	Description
{@navigator:location}	Renders a bread crumbs navigator as an HTML unordered list.
{@navigator:traversal:show-title}	Renders a traversal navigator as an HTML table with three columns. When `show-title` is true renders context name as well.
{@navigator:options:decorators: level:preloaded:show-current}	Renders a menu as HTML unordered list. When `decorators` is true aditional DIVs are added at top and bottom. `level` tells starting at which level options are shown. `preloaded` indicates how many children are to be shown. If `show-current` is set to true, children passing `preloaded` value will show along with ancestors and siblings, as opposed to not showing any child with level over `level + preloaded`.
{@navigator:tabulator:level}	Renders a tabulator as HTML unordered list.`level` tells at which level tabs are shown.

Generic use macros.

Macro	Description
{@webroot}	Translates into web application's context
{@res:resource_key[:mode]}	Gets resource value and renders as mode. Mode is an integer optional parameter. Mode's values are: 0 - No transform. 1 - Capitalized. 2 - To upper case. 3 - To lower case.
{@random:limit}	Writes a random number starting at zero and up to limit minus one.
{@context:level}	Writes context identifier. Contexts exceeding level are dismissed.
{@user:name\|id]}	Writes currently logged user's name or identifier.
{@if:role:attribute: true_expression:false_expression}	Writes true or false expressions depending on whether role:attribute pair are satisfied.

Before getting crazy trying to make work what do not, read this list of known issues:

XMLPortal standard components

Default style for tabular navigator does not position correctly under IE.
Layout has no configuration screen, you must manually modify _internal/context.xml file.
Print Version doesn't expand macros correctly.

DefaultElement or standard XMLPortal page

Repository doesn't support more than one level subdirectory.
Repository gives no access to global repository, although is accesible through wiki syntax using grepository(path).

Applies

Default style for workplan renders issues list at bottom under IE.

If you have found an issue that should appear on this list, please send me an email at lluis dot turro at xmlportal dot net.