community.egroupware.org: Community wiki

  
Community wiki
Sitemgr Introduction
back to ManualSitemgr

This introductory section describes some concepts, you will need to understand if you want to get the most out of sitemgr. If you are just interested in a quick installation introduction go to Sitemgr Administrator Manual.

History

  1. The first version of SiteMgr was developed by a group of students: Team 10 in the UC Irvine Systems Design Course, ICS 125.
  2. Michael Totschnig (totschnig.michael@uqam.ca) wrote the multilingual facets of SiteMgr and created the modularized architecture.
  3. Ralf Becker (RalfBecker@outdoor-training.de) extended the Edit mode into the easy-to-use default user-interface of SiteMgr. He also developed the compatibility with Mambo Open Source 4.5 templates and some of the new modules like the wiki, the new amazon or the template selection.

Templates

SiteMgr builds web sites from templates. Those are stored in the directory sitemgr/sitemg-site/templates. Each of them has a sub-directory of its own. SiteMgr support two kind of templates:
  1. its own native format which is described in the next section.
  2. Mambo Open Source (www.mamboserver.com) MOS Ver. 4.5 templates. There are hundreds of templates available for download (http://www.joomlaos.de/index.php?set_albumName=album01&option=com_gallery&Itemid=37&include=view_album.php). To install, unpack the downloaded zip-archive into the sitemgr-site/templates directory. There's a series of articels from Arthur Konze about, how to develop these templates. Joomla is the successor of Mambo, the most information about mambo-templates and information about how to develop those can be found on websites of the Joomla project now.


Sitemgrs native template format

The file main.tpl defines the template of the whole site, there can be other files that define code for separate areas of the page or for specific modules. Templates contain four kinds of variables. These are explained here since the types 2,3,4 and 5 can be used both in the template and in the page content as generated modules.

  1. contentarea: areaname These define where administrator and contributor provided content goes. The names and the number of contentareas a template defines are almost arbitrary.
  2. modulename(?arguments)These let you hardcode a call to a module into a template. Arguments are in the HTTP GET query string syntax (?key1=value1&key2=value2). At the moment, if you use this type of variables, you have to urlencode the query string yourself. Future versions of SiteMgr might provide a simpler notation. For example,lang_block} creates the select box for multilingual sites.
  3. ?(phpgw|sitemgr:)link This lets you create links either to other pages of your website, or to eGroupWare applications:
  • Links to SiteMgr either start with '?sitemgr:' or only with '?'. You can either link to a page with ?page_name=downloads} and {?page_id=4, to a category's index (?category_id=5), to the site index (?index), to the site's table of contents (?toc). Just / or ?sitemgr: links to the administrator defined home page.
  • Links to eGW start with '?phpgw:' . You have to name the application followed by a comma, and optionally arguments the application can interpret. For example ?phpgw:/addressbook,order=n_given&sort=ASC.
  1. variable Finally there are some simple variables you can use to retrieve metainformation about the page or about the user's context:
    • title the page title
    • subtitle the page subtitle
    • sitename the sitename the administrator has chosen for the site
    • sitedescription the sitedescription
    • user the user's account name
  2. lang_translatable_string This lets you make the template internationalized. The translatable string is sent through eGroupWare's lang function. Thus you can add it to the lang files in the setup directory and install it through the setup programm.


Modules

The main function of a SiteMgr module is to generate dynamic web site content. To make the development of new modules, and the use of modules easy and convenient, SiteMgr defines an “abstract” class module which each module should extend. This parent of all modules, provides one essential service: It hooks the module into the content managment interface and permits the editing of the module's arguments that determine what content will be generated. Thus in order to create a new module, all you have to do, is to extend the abstract super module, define the modules arguments, and write a get_content function that returns the content that should be displayed on the website. More on this in the chapter about Module development.


Arguments/Content

A module can be seen as a transformation of input arguments into generated content. It is important to understand that the input arguments can be of completely different kinds. On the one hand there can be arguments that are as close as possible to the generated content. For example the html module's only argument is named “htmlcontent” and in normal circumstances it is not transformed at all but handed over as is to the page generation engine. On the other hand arguments can play any conceivable role in the generation of content that is driven by data coming from other eGroupWare applications. They can be used to select between different categories of content, they can choose a certain format of presentation, they can function as search terms, etc.


Properties

A module can define properties. Properties are accessible to the modules get_content function in the same way as arguments, but they differ from them in two ways:

  • Properties are edited by the site administrator. Their intended role is to put certain constrains on the workings of the module, so that a site administrator can enforce certain rules. For example the standard html module defines a property called striphtml. If this boolean property is set the module replaces all html in the generated content with entities.
  • Properties are not defined with respect to a certain generated content block, but are defined either on a site-wide level or on the level of specific categories. Additionally you can differenciate on each scope properties for each content area. When a content block is generated, properties are searched for in a cascading way, i.e. when the block is specific to a specific page and contentarea and the module's properties are not defined for the combination of the contentarea and the page's category, then properties defined for higher scopes are looked for in a certain order. More on this in the chapter about Administration.


Blocks, content areas and scope

There are three ways a module can generate content that will be displayed on a web page:

  1. A template can contain hardcoded calls to modules that will generate content visible on each page. Thus you could put dynamic content that is visible across the whole site on a place of its own directly into the template. But beware that restrictions defined by the administrator also apply to these hardcoded module calls.
  2. A template defines several content areas. This is an important difference between the modularized SiteMgr and previous versions where there was only one place where contributor edited content went (page_content) and two places for administrator configured blocks (right_blocks, left_blocks). Now templates can define any practical number of content areas with arbitrary names. And there is no longer much difference between central and peripheral areas. All can show administrator and contributor provided block content. With one exeption: The name “center” is special in that special pages that get generated by special URLs like “?toc” and “?index” or “?category_id=number” always put their page content (which is internally generated by nothing else than a module) into this content area. If your template does not have a content area called “center” these special URLs won't work. Content areas can display module output, as edited by the page's contributors. We refer to each output of a module as a block. Here is another important difference to how SiteMgr used to work: Until now there was a sharp distinction between page content which replaces the template variable page_content, and side blocks which got defined in a special file called blockconfig and replaced the template variables right_blocks and left_blocks. Now from the perspective of the page generation engine there is no longer any difference between content areas, all display blocks of content are generated by modules. The blocks own content area displays can be defined on different levels of scope: There are site wide blocks that are visible across the whole site, category wide blocks, that are visible on pages that belong to the category or any of its children, and finally are page blocks that define what distinguishes the page from other pages, and normally will be that what you'd call the page's main content.
  3. The block content generated by a module can contain template variables of the same type as those that can be hardcoded. This is mostly useful for modules like the html module, where the contributor specified argument is nearly identical to the generated content. Thus a contributor can embed module calls inside the content of a certain block. This is done only once without any recursion, i.e. if an embedded module call returns itself a template variable it is not parsed and processed again.


Versioning

SiteMgr handles block content in versions. This means that you can have different versions of one block at the same time, but only one of them is visible on the website. This allows for working on several changes to the website and viewing them in a draft mode, before commiting them all at once to the production site. SiteMgr distinguishes five states for versions:

draft: A draft version will not appear at the website at all. Draft versions are there for content you are not yet sure about.

prepublished: A prepublished version will appear on the website if you view it in draft mode. A prepublished version is registered for publication, and it will change to published state, once you commit it.

published: A published version is visible on your website both in production mode and draft mode.

preunpublished: You put a version into preunpublished mode, if you want to remove it or replace it, but want to do this only by commiting other changes at the same time.
archived: Archived versions will no longer appear anywhere but a special archive interface that allows you to reactivate archived content.

There are no versions of categories or pages, but they can be in any of these five states. This means you can create a new category or a new page, but it will not appear on the website until you commit it.

Only one version of a content block can be in published, prepublished or preunpublished state at a time. There is one exeption: a prepublished and preunpublished version can exist together. When you commit the change, the prepublished version will become published and the preunpublished version will get archived.


Transformer

The architecture for SiteMgr modules provides the distinction between some form of raw content a module produces and the way it should get displayed on the web site, with the future possibility to plug other display types into the same framework. The idea is that the raw content of a module gets passed through different transformers, possibly even several transformers in a sequence at the time of content generation. Additionally this provides for a use of modules outside of sitemgr, for example remote retrieval of information with something like XML-RPC.

At the moment, a module does not need to use transformers on its own, it can directly generate html content, but if it does, SiteMgr provides for an easy way to chain different transformers together. Thus a module can be constructed in different layers of functionality. For example a module's get_content function could return data in XML, and it defines a XSLT transformation to reorganize this data, and a second transformer for creating a user interface for display.

Transformers are also used on the level of the site template, insofar as each contentarea can have an associated transformer, which wraps the different content blocks into a common display format. This does the same thing as the file sideblock.tpl in former versions of sitemgr.


Translations

SiteMgr in its new modularized architecture continues to be fully multilingual. It is very simple to have a new module use this feature. All that is needed is to use a special flag in the definition of the module's arguments. All arguments that have this flag will be stored in a language specific database table, and can be translated in the translation manager, very similar to the way category and page definitions could already be translated to several languages.


You are here