#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass docbook
\begin_preamble
<!entity header system "header.sgml">
\end_preamble
\language english
\inputencoding default
\fontscheme default
\graphics dvips
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip smallskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
SiteMgr manual
\layout Date

22.
 February 2004
\layout Author


\begin_inset ERT
status Open

\layout Standard
<firstname>Ralf</firstname> <surname>Becker</surname>
\end_inset 


\layout Section

Introduction
\layout Standard

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 section
 
\begin_inset ERT
status Open

\layout Standard
<link linkend="Installation">Installation</link>
\end_inset 


\layout Subsection

History
\layout Enumerate

The first version of SiteMgr was developed by a group of students: Team
 10 in the UC Irvine Systems Design Course, ICS 125.
 
\layout Enumerate

Michael Totschnig (totschnig.michael@uqam.ca) wrote the multilingual facets
 of SiteMgr and created the modularized architecture.
\layout Enumerate

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.
\layout Subsection

Templates
\layout Standard

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:
\layout Enumerate

his own native format which is decript in the next paragraph.
 
\layout Enumerate

Mambo Open Source (
\begin_inset LatexCommand \htmlurl[www.mamboserver.com]{http://www.mamboserver.com}

\end_inset 

) MOS Ver.
 4.5 templates.
 There are hunderets of templates availible for download (
\begin_inset LatexCommand \htmlurl[www.mamboportal.com]{http://www.mambofiles.com/index.php?option=com_remository&Itemid=26&func=selectfolder&filecatid=9}

\end_inset 

).
 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 develope these
 templates: 
\begin_inset LatexCommand \htmlurl[www.mamboportal.com]{http://www.mambofiles.com/content/category/2/34/28/}

\end_inset 

.
\layout Subsubsection

SiteMgr's native template format
\layout Standard

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 as in the page content a module generates.
\layout Enumerate

{
\series bold 
contentarea
\series default 
: areaname} These define where administrator and contributor provided content
 go.
 The names and the number of contentareas a template defines are almost
 arbitrary.
\layout Enumerate

{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.
\layout Enumerate

{?(
\series bold 
phpgw|sitemgr
\series default 
:)link} This lets you create links either to other pages of your website,
 or to eGroupWare applications:
\begin_deeper 
\layout Enumerate

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.
\layout Enumerate

Links to eGW start with '?phpgw:' .
 You have to name the application followed by a comma, and optionnally arguments
 the application can interpret.
 For example {?phpgw:/addressbook,order=n_given&sort=ASC}.
\end_deeper 
\layout Enumerate

{variable} Finally there are some simple variables you can use to retrieve
 metainformation about the page or about the user's context:
\begin_deeper 
\layout Enumerate

{title} the page title
\layout Enumerate

{subtitle} the page subtitle
\layout Enumerate

{sitename}the sitename the administrator has chosen for the site
\layout Enumerate

{sitedescription} the sitedescription 
\layout Enumerate

{user}the user's account name
\end_deeper 
\layout Enumerate

{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.
\layout Subsection

Module
\layout Standard

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 
\begin_inset Quotes eld
\end_inset 

abstract
\begin_inset Quotes erd
\end_inset 

 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_conten
t function that returns the content that should be displayed on the website.
 More on this in the chapter about
\begin_inset ERT
status Open

\layout Standard
<link linkend="Module-developper-manual">Module developpment</link>
\end_inset 

.
\layout Subsection

Argument/Content
\layout Standard

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 
\begin_inset Quotes eld
\end_inset 

htmlcontent
\begin_inset Quotes erd
\end_inset 

 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.
\layout Subsection

Properties
\layout Standard

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:
\layout Itemize

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.
\layout Itemize

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
\begin_inset ERT
status Open

\layout Standard
<link linkend="Administrator-manual">Administration</link>
\end_inset 

.
\layout Subsection

Blocks, content areas and scope
\layout Standard

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

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.
\layout Enumerate

A template defines several content areas.
 This is one important differenced between the modularized sitemgr and previous
 versions where there were 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 more much difference between central and peripheric areas.
 All can show administrator and contributor provided block content.With one
 exeption: The name 
\begin_inset Quotes eld
\end_inset 

center
\begin_inset Quotes erd
\end_inset 

 is special in that special pages that get generated by special URLs like
 
\begin_inset Quotes eld
\end_inset 

?toc
\begin_inset Quotes erd
\end_inset 

 and 
\begin_inset Quotes eld
\end_inset 

?index
\begin_inset Quotes erd
\end_inset 

 or 
\begin_inset Quotes eld
\end_inset 

?category_id=number
\begin_inset Quotes erd
\end_inset 

 always put there 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 
\begin_inset Quotes eld
\end_inset 

center
\begin_inset Quotes erd
\end_inset 

 these special URLs won't work.
\newline 
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 varialbes right_block
s and left_blocks.
 Now from the perspective of the page generation engine there is no more
 any difference between content areas, all display blocks of content generated
 by modules.
\newline 
The blocks one 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.
\layout Enumerate

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 a embedded module call returns itself a template variable it is not
 parsed and processed again.
\layout Subsection

Versioning
\layout Standard

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:
\layout Description

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

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.
\layout Description

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

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 in the same time.
\layout Description

archived: Archived versions will no longer appear anywhere but a special
 archive interface that allows you to reactivate archived content.
\layout Standard

There are no versions of categories or pages, but they do 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.
\layout Standard

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.
\layout Subsection

Transformer
\layout Standard

The architecture for sitemgr modules provides for 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.
 
\layout Standard

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.
\layout Standard

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.
\layout Subsection

Translations
\layout Standard

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.
\layout Section

User manual
\layout Subsection

Manage categories and pages
\layout Subsubsection

Create a new category
\layout Standard

to be completed
\layout Subsubsection

Edit a category
\layout Standard

to be completed
\layout Subsubsection

Delete a category
\layout Standard

to be completed
\layout Subsubsection

Create a new page
\layout Standard

to be completed
\layout Subsubsection

Edit a page
\layout Standard

to be completed
\layout Subsubsection

Editing page content
\layout Standard

There are two interfaces for creating and editing content blocks.
 The first one is called 
\begin_inset Quotes eld
\end_inset 

content manager
\begin_inset Quotes erd
\end_inset 

 and works inside the eGW interface, the second works in interaction with
 the generated web site and we call it 
\begin_inset Quotes eld
\end_inset 

editing mode
\begin_inset Quotes erd
\end_inset 

.
\layout Paragraph

The content manager
\layout Standard

The interface for creating content blocks is the same on each level of scope,
 besides that when editing blocks on a lower level you can see all the blocks
 that have been defined on a higher level, and will be displayed on the
 website together with the blocks you are editing.
 I will refer to this interface as the content manager.
\layout Standard

In each content manager, there is a section for each content area, where
 you can add blocks selected from a menu of all available modules.
 Once you have added a new block, it appears amidst all other blocks of
 the content area.
 Those defined on higher level scopes are only displayed, those pertaining
 to the scope (site-wide, category or page) you are managing are editable.
 
\layout Paragraph

Editing mode
\layout Standard

In order to use editing mode, you must add a site-wide administration block
 to your website (viewable only by registered users).
 This block has a dropdown menu where you can switch between production
 mode (viewing the website in its public state), draft mode (viewing the
 website in the prepublished state, i.e.
 how it will look after you commit any pending changes) and edit mode.
 In edit mode, you will see the same content as in draft mode, but in front
 of each content block you will see a link 
\begin_inset Quotes eld
\end_inset 

Edit block
\begin_inset Quotes erd
\end_inset 

.
 Activating this link will pop up a new window for editing it.
\layout Paragraph

Editing a block
\layout Standard

In both the content manager and the editing window that opens in editing
 mode, the interface for editing the block is the same.
 There are three standard interface elements you can edit for each block:
\layout Description

Title Each module defines a default title for blocks it generates.
 The block title is not necessarily displayed in each content area.
 It depends on the block transformer defined for the content area by the
 site template you use.
 Here you can override the default title with a customized title that will
 only be used by the block you are editing
\layout Description

Seenby You can control the visibility of each block for the different user
 roles defined by sitemgr: site administrators, eGroupWare users (which
 include site administrators) and the anonymous user.
 Evidently you can also make the block visible for everyone which is the
 default.
 
\layout Description

Sortorder Here you can change the order in which the blocks are displayed
 by defining a different integer for each block.
\layout Standard

When you first create a content block, sitemgr automatically creates a version
 for it.
 For each version, you have to edit the module specific arguments, each
 of which is preceded by an explanatory label.
 The input elements for arguments can be of different types: checkboxes,
 selectboxes, textareas, textfields.
 In the case of text input, you can use the same template variables as are
 used in the site template.
 But be aware that this only works if the module puts the same variable
 into its output, which need not necessarily be the case.
\layout Standard

Even if not all blocks may make sense for each content area, the content
 manager does not impose on itselft any constraints on which modules you
 use for which area (Administrators can restrict the available modules for
 categories and content areas).
 For example you can use modules that are optimized for side block areas
 in the central area and you could use a simple html content block on side
 areas.
 The following modules are shiped with sitemgr:
\layout Description

administration simply creates a link to sitemgr's administration interface.
 Thus you probably would not want to make it visible for anonymous user's
 but only for eGW users or adminstrators.
\layout Description

amazon shows ads for books on the Amazon website.
 There is a comment in the modules source file about how it works.
\layout Description

appdir a demonstration of how sitemgr's architecture can be used to realize
 a simple application for creating a directory of information.
 It should be adaptable to other needs.
 At the moment, you need PHP's XSLT extension to use this module.
\layout Description

bookmarks lets you show content from eGW's bookmarks application
\layout Description

calendar produces a calendar where each days links to eGroupWare's calendar
 application
\layout Description

currentsection produces an index of the pages in the current section.
\layout Description

download you can use this module for creating links to files you store with
 eGW's filemanager
\layout Description

filecontents this module lets you include the content of a file on your
 webserver into your website
\layout Description

forum another demonstration of what sitemg's modules are intended for: This
 module displays the discussions of eGroupWare's forum application on the
 web site.
 It does not permit to post, since to implement this, in my humble opinion,
 the forum application has to be redesigned slightly.
\layout Description

galerie creates a picture galery.
 You have to name both the filesytem path and the URL to a directory, where
 images that have a common filename, and are numbered beginning with one,
 are stored.
 Once the directory has been found, you can edit a subtext for each image.
\layout Description

google displays a form for querying the google website.
\layout Description

hello a simple 
\begin_inset Quotes eld
\end_inset 

Hello world
\begin_inset Quotes erd
\end_inset 

 module used below in this manual.
\layout Description

html probably the most important module, since it plays the role, formerly
 the simple page content area had, ie.
 you add html content to the page.
\layout Description

index_block a index of the whole site, formatted for peripheric areas of
 your web site.
\layout Description

index is automatically used with the index GET parameter.
 You probably would not have to use this block otherwise.
\layout Description

lang_block displays a select box for changing the user's site language.
\layout Description

login displays a login block
\layout Description

news publishes news you edit with eGroupWare's news_admin application.
 You can choose a category to display.
\layout Description

redirect makes the page redirect to another URL.
 This is useful, if you want an entry in your menus that links to a page
 outside your sitemgr site.
 If you use this module you shouldn't put any other blocks on the same page.
\layout Description

sitetree displays a tree like menu to the website.
\layout Description

toc_block the site's table of contents, formatted for peripheric areas of
 your web site.
\layout Description

toc is automatically used with the toc GET parameter.
 You probably would not have to use this block otherwise.
\layout Description

xml is only a demonstration of how a module could serve XML content stored
 on your webserver.
 It does not do anything useful besides creating a browser from one file
 to the other.
 Files have to be named like images in the galerie module.
 You need PHP's xslt extension to use this module.
 
\layout Paragraph

Handling versions
\layout Standard

For each content block you can create a new version simply by clicking on
 the 
\begin_inset Quotes eld
\end_inset 

Create new version link
\begin_inset Quotes erd
\end_inset 

.
 Once you have several versions of a block, you can change their status
 at any time.
 If you want to immediately publish a block, you choose 
\begin_inset Quotes eld
\end_inset 

published
\begin_inset Quotes erd
\end_inset 

.
 If you want to register a version for being published at the next commit,
 you choose 
\begin_inset Quotes eld
\end_inset 

prepublished
\begin_inset Quotes erd
\end_inset 

.
 A version that is 
\begin_inset Quotes eld
\end_inset 

preunpublished
\begin_inset Quotes erd
\end_inset 

 is visible on the website, but will be archived at the next commit.
 Thus if you want to replace some content at the next commit, you have to
 put the published version into 
\begin_inset Quotes eld
\end_inset 

preunpublished
\begin_inset Quotes erd
\end_inset 

 and create a new version that you put into 
\begin_inset Quotes eld
\end_inset 

prepublished
\begin_inset Quotes erd
\end_inset 

 state.
 Archived versions will be no longer visible in the content managment interface,
 but will not be deleted from your database.
 They can be reactivated in the 
\begin_inset Quotes eld
\end_inset 

Manage archived content
\begin_inset Quotes erd
\end_inset 

 interface.
\layout Subsection

Manage translations
\layout Standard

to be completed
\layout Subsection

Commit changes
\layout Standard

In this interface you see a list of all categories, pages and blocks that
 are in prepublished or preunpublished state.
 You can return to any of them for further editing or changing their status,
 and you can choose between them for commiting.
 Prepublished content will go public, preunpublished content will go to
 the archive.
\layout Subsection

Manage archived content
\layout Standard

to be completed
\layout Section

Administrator manual
\begin_inset LatexCommand \label{Administrator-manual}

\end_inset 


\layout Subsection

Installation
\begin_inset LatexCommand \label{Installation}

\end_inset 


\layout Enumerate

Once you have the sitemgr directory inside your eGroupWare install you can
 setup it like any other eGroupWare application with the setup program (http://y
ourmachine/eGW-path/setup/).
 You should also install the sitemgr-link application, which is is inside
 sitemgr and has to be moved up in the directory hierarchy.
\begin_deeper 
\layout Code

cd sitemgr
\layout Code

mv sitemgr-link ..
\layout Standard

and then install sitemgr-link with setup
\end_deeper 
\layout Enumerate

Log in to eGroupWare as an admin and create an anonymous eGW user and assign
 it a password.
 The only app (I assume) that they should have access to is sitemgr-link.
 sitemgr-link is a dummy application that redirects eGW users to the generated
 site.
\layout Enumerate

Users who you wish to see sitemgr (aka contributors) must be given acces
 to sitemgr, users who you want to be able to link to the sitemgr site from
 eGW must be given rights to sitemgr-link.
 The easiest way to do this is to go to User groups and give groups permissions
 to use the applications.
 
\layout Enumerate

The sitemgr-site is the directory that serves the dynamic web site.
 It is located inside sitemgr and works without moving it somewhere else.
 But it can be located anywhere.
 For example, you could put it in /var/www/html.
 You could make the root location of your web server point to it, if you
 wish (ie, http://yourmachine/ refers to /var/www/html/sitemgr-site if you
 moved the directory, or to /path/to/eGroupWare/sitemgr/sitemgr-site if
 you did not).
 Make a mental note of the directory where you put it and the url that it
 is accessed by.
\layout Enumerate

In the sitemgr-site directory is a file called config.inc.php.
 You only have to edit it if you moved the directory.
 Change the value of the line
\begin_deeper 
\layout Code

'eGW_path'           => '../../',
\layout Standard

so that the value of $sitemgr_info['eGW_path'] is '/path/to/eGroupWare/'
\end_deeper 
\layout Enumerate

You can handle different websites with sitemgr.
 The first thing to do is to define your new website.
 SiteMgr defines a default website upon installation, but you will probably
 have to redefine it.
 Log in as a eGW administrator and go into eGroupWare's admin application
 and choose 
\begin_inset Quotes eld
\end_inset 

Define websites
\begin_inset Quotes erd
\end_inset 

 in the sitemgr section.
 You should see the default website listed, and can choose to edit it.
 A website is defined by the following values:
\begin_deeper 
\layout Description

Site_name This is not used on the website, but only helps identify a website
 inside the administration interface.
\layout Description

Filesystem_path_to_sitemgr-site_directory If you did not move the sitemgr-site
 directory above you can leave this unchanged.
\layout Description

URL_to_sitemgr-site You can also leave this unchanged if you want to access
 your public website with a url that looks like http:/your.eGW.url/sitemgr/sitemgr
-site.
 If you want a different URL, you either have to move the sitemgr-site directory
 or to use an alias or a virtual server in your webserver's configuration.
\layout Description

Anonymous_user's_username the account name you created above.
\layout Description

Anonymous_user's_password and the corresponding password
\layout Description

Site_administrators Here you choose the users and/or groups that should
 have administrator rights for the website.
 They do not have to be adminstrators in eGW's sense.
\end_deeper 
\layout Enumerate

You can know log in as on one of the user's you gave administrator rights
 for the website..
 Go to the sitemgr application and select "Configure SiteMgr".
 Here you can set different values that affect how your site will be presented.
\begin_deeper 
\layout Description

Site_name is used mainly for metadata
\layout Description

Site_description is used mainly for metadata
\layout Description

Default_home_page here you can select the page that will show up first one
 your website.
 Evidently there won't be any choice until you create some pages.
\layout Description

Template_select lets you choose between the different site designs that
 come with sitemgr or any you will create yourself.
\layout Description

Site_languages If you want a multilingual site, you have to set them here.
 This will let you use the translation interface for translating your content
 and you can put a selectbox on your website where it's visitors can choose
 between different languages.
\end_deeper 
\layout Enumerate

After installation sitemgr does not immediately know about all available
 modules.
 The setup routine only installs the modules html,index and toc that every
 site will need.
 In order to register all availabe modules select 
\begin_inset Quotes eld
\end_inset 

Manage site-wide module properties
\begin_inset Quotes erd
\end_inset 

 from the administrative menu, and then follow the 
\begin_inset Quotes eld
\end_inset 

Register new modules
\begin_inset Quotes erd
\end_inset 

 link.
\layout Enumerate

That's it.
 Go to the Outline manager (
\begin_inset Quotes eld
\end_inset 

Manage categories and pages), add a category or three and check who can
 view and edit them, then add a page or three to each category, create some
 content for each page.
 You can also have content that is visible everwhere on your website (
\begin_inset Quotes eld
\end_inset 

Manage site-wide content
\begin_inset Quotes erd
\end_inset 

) or on all pages that belong to a category (
\begin_inset Quotes eld
\end_inset 

Manage categories and pages
\begin_inset Quotes erd
\end_inset 

 => 
\begin_inset Quotes eld
\end_inset 

Manage category wide content
\begin_inset Quotes erd
\end_inset 

).
 Take care to put all categories and pages and blocks you create into published
 state, otherwise they will not be visible on the website.
\layout Enumerate

Go view your recently created site by clicking on the sitemgr-link application.
 Voilà!
\layout Subsection

Maintenance
\layout Standard

As a site administrator, you have three privileges/responsibilies:
\layout Enumerate

Define site wide content blocks.
 These are edited in the same interface as category and page specific blocks.
\layout Enumerate

Choose permitted modules: If you choose 
\begin_inset Quotes eld
\end_inset 

Manage site-wide module properties
\begin_inset Quotes erd
\end_inset 

 from sitemgr's main menu, you will see several rows which all contain four
 elements: a select box, a button labelled 
\begin_inset Quotes eld
\end_inset 

Select allowed modules', another select box and a button labelled 
\begin_inset Quotes eld
\end_inset 

Configure module properties
\begin_inset Quotes erd
\end_inset 

.
 The first select box and its adjacent button in each row permits to choose
 lists of permitted modules.
 The first row defines a master list for the whole site which is used when
 no more specific lists are found for content areas or categories.
 The following rows each pertain to the different content areas of your
 site template.
 Here you can choose to allow some modules for one content areas, and other
 modules for another one.
\newline 
In the category manager, there is a button 
\begin_inset Quotes eld
\end_inset 

Manage Modules
\begin_inset Quotes erd
\end_inset 

 associated with each category.
 There you can use the same interface to define lists specific to one category
 (and all its subcategories, unless overriden).
 Again you have the choice between one list that pertains to all content
 areas, and specific lists for each category.
\newline 
When sitemgr has to find a specific value of permitted lists in a given
 context (a given contentarea in a given category) the following algorithm
 is used: First it aks for a value defined for the pair contentarea/category.
 If none is defined, it climbs up the category hierarchy until the site
 wide value, each time looking for a value defined for the pair contentarea/cate
gory.
 If none can be found, it returns to the given category the search started
 from, and now asks for values defined for the given category but independent
 from the contentarea.
 If there is still none defined, it repeats the same traversal up the category
 hierarchy.
 This means that by simply defining one global master list of permitted
 modules, you can configure the whole site, if you do not need more fine
 grained control.
\newline 
The lists of permitted lists are never merged, if you define one list for
 a given context, this list is used in this context.
\layout Enumerate

Define module properties: The lookup algorithm for module properties is
 exactly the same as for the lists of permitted modules.
 For each module you can set properties for the whole site, for content
 areas, for categories, or for combinations of content areas and categories.
 You access the property editor from the same page where you choose the
 list of permitted modules.
 You just use the second select box in each row.
 By selecting one module and clicking the 
\begin_inset Quotes eld
\end_inset 

Configure module properties
\begin_inset Quotes erd
\end_inset 

 button, you will open a interface for editing the module's properties which
 ressembles the interface for editing module arguments in the content manager.
 Be aware that only some modules define properties.
\layout Section

Template designer manual
\begin_inset LatexCommand \label{Template-designer-manual}

\end_inset 


\layout Standard

One main idea behind sitemgr's modularized architecture is that all dynamic
 content on the website is produced by a module.
 This permits for a very structural way of defining functionality and for
 an easy way of extending functionality.
 With respect to former versions of sitemgr, this means that the templates
 have to be slightly modified:
\layout Itemize

The whole page template is now stored in a file main.tpl in the template's
 directory.
\layout Itemize

The variables page_content, left_blocks,right_blocks have to be replaced
 by content areas: {contentarea:center}, {contentarea:left}, {contentarea:right}.
 Only the contentarea center has a special semantics, since it is the hardcoded
 value for the display of table of contents and side index.
 All other contentareas can have arbitrary names, and you can have any practical
 number of them.
\layout Itemize

A contentarea serves to display the content blocks, the site administrator
 and contributors define.
 Each contentarea can have its own way of wrapping html code around each
 content block.
 This at the moment defined in a class that implements the transformer interface
, i.e.
 defines a function apply_transform($title,$content).This class' name is
 areaname_bt (for blocktransformer) and it is stored in file areaname_bt.inc.php
 inside the template directory.
 The function apply_transform just has to wrap the desired html around the
 content.
 It is free to ignore the title, for example the block title does not necessaril
y make sense in a page's central content area.
 A block transformer could apply other transformations to the content, but
 this would probably have counter-intuitive effects on your page's contributors
\begin_inset Foot
collapsed false

\layout Standard

For compatibility with how sitemgr used to work, the file sideblock.tpl which
 uses the two variables block_title and block_content is still recognized
 as a template for a transformation of the two contentareas left and right.
 The transformer is automatically created by the template class.
 Thus you could use one file sideblock.tpl instead of the two files right_bt.inc.ph
p and left_bt.inc.php.
\end_inset 

.
\layout Itemize

Other than that a template directory can contain template files that are
 specific to a certain module.
 For example the news module uses a file newsblock.tpl which is a standard
 API template.
 It is up to a module's developpers what kind of templates he wants to use.
 We propose to use a namespace for these module specific template files.
 For example a template used by module 'news' would go into a subdirectory
 'modules/news' in each template directory.
 If the module does not find a template it needs in the site template's
 directory, it should look for a default template file, for example in 
\begin_inset Quotes eld
\end_inset 

default/modules/news'.
\layout Itemize

You can hardcode module calls into the template if your site should have
 the same dynamic content on one specific place.
\layout Section

Module developper manual
\begin_inset LatexCommand \label{Module-developper-manual}

\end_inset 


\layout Standard

SiteMgr's parent module class, defines all the important functionality a
 module needs in its lifetime.
 Thus creating a new module can be as easy as creating a class that extends
 the standard module, defines the module's arguments if there are any, and
 has a function get_content that produces the module's content.
 Let's start with 
\begin_inset Quotes eld
\end_inset 

Hello World
\begin_inset Quotes erd
\end_inset 

.
\layout Code

<?php
\layout Code

\layout Code

class module_hello extends Module 
\layout Code

{      
\layout Code

    function module_hello()  
\layout Code

    {               
\layout Code

        $this->arguments = array(
\layout Code

            'name' => array(
\layout Code

                'type' => 'textfield', 
\layout Code

                'label' => 'The person to say hello to'
\layout Code

            )
\layout Code

        );
\layout Code

        $this->title = "Hello world";
\layout Code

        $this->description = "This is a simple sample module";   
\layout Code

    }
\layout Code

\layout Code

    function get_content($arguments,$properties)    
\layout Code

    {
\layout Code

        return lang('Hello') .
 ' ' .
 $arguments['name'];
\layout Code

    }
\layout Code

}
\layout Standard

Once your module is registered
\begin_inset Foot
collapsed false

\layout Standard

Modules must be stored in the directory /path/to/eGroupWare/sitemgr/modules
 and be named class.module_modulename.inc.php in order that sitemgr can find
 them.
\end_inset 

 and added to the list of permitted modules for some context, users can
 create blocks from this module: They will see in the content manager a
 textfield where they edit the argument name, and once the block is activated,
 it will generate the hello phrase on the website.
 Easy, isn't it?
\layout Standard

Now let's examine more in detail how the standard module is constructed.
 This will help you understand in what way you can extend it to create more
 powerful modules.
 It defines the following functions:
\layout Description

add_transformer($transformer) This function adds a transformer class to
 the module's transformer chain, so that when a block is generated from
 this module, its content will be passed through $transformer.
 This function is automatically called for block transformers, but you can
 use it on your own, if you want to separate in your module raw content
 from different forms of output.
 There is only one function a transformer class has to provide:
\begin_deeper 
\layout Description

apply_transform($title,$content) A transformer that is not a block transformer
 should normally ignore the title argument, and construct its return value
 from the content argument.
\end_deeper 
\layout Description

set_block(&$block,$produce=False) This function is called by the content
 manager (with $produce=False) and by the page generation (with $produce=True)
 for each content block, so that the module knows everything about the block
 it has to edit or generate (above all its context and its arguments).
 If your module overrides this function, it should always call the parent
 class' set_block function first with parent::set_block($block,$produce).
 If you want to configure your module with respect to the block, you can
 do this here.
 This is also the place where your module should add the transformers it
 needs for generating output.
 For example:
\layout Code

function set_block(&$block,$produce=False)
\layout Code

{ 
\layout Code

    parent::set_block($block,$produce)
\layout Code

    if ($produce)
\layout Code

    {
\layout Code

        $this->add_transformer(new my_transform());
\layout Code

    }
\layout Code

}
\layout Description

get_properties() This function looks up the value of the module's properties
 for the context of a block.
 There should not be much reason to override this function.
\layout Description

get_user_interface() This function is responsible for creating the interface
 you use in the content manager when you edit a module's arguments.
 If you want this interface to show more than your module's arguments, youcan
 override this function.
 It must return an array of interface elements where each element is an
 array with two values associated to the keys label and form.
 You can even dynamically construct arguments, sitemgr's sample gallery
 module shows how to do this.
\layout Description

get_admin_interface($defaults) This function creates the interface for editing
 module properties, it works in a similar way to get_user_interface.
\layout Description

get_translation_interface($fromblock,$toblock) This function creates the
 interface for the translation manager.
 If your module makes use of sitemgr multilingual feature, and you have
 overriden get_user_interface, you'll probably have to override this function
 too.
\layout Description

build_input_element(($input,$default,$elementname) This is a helper function
 for above functions.
 If you override one of above functions you can use build_input_element
 in the same way as the parent module does.
\layout Description

validate(&$data) This function is called when a module's arguments are edited.
 The parent class simply returns true.
 When you override this function, you can alter the arguments, a reference
 to which is passed to the function, but you can also return false, and
 set the module's validation_error variable.
 In this case, the arguments will not be saved and the validation error
 is displayed to the user.
 For example we could add the following lines to our hello module:
\begin_deeper 
\layout Code

function validate(&$data) 
\layout Code

{ 
\layout Code

    if (preg_match("/[[:upper:]]/",$data['name']))
\layout Code

    {
\layout Code

        $data['name'] = strtolower($data['name']);
\layout Code

        $this->validation_error = "Name has been translated to lower case";
\layout Code

    }
\layout Code

    return true;
\layout Code

}
\layout Standard

This would make sure that the module argument name would always be lowercase.
\end_deeper 
\layout Description

get_content(&$arguments,$properties) This is the function every module needs.
 It produces the module's content.
 It is passed two arrays, one with the arguments for the block the module
 is generating, and the other with the properties that apply for the block's
 context.
 At the moment there is no constraint on what type of date the get_content
 function returns.
 It can be html, xml, an array, etc.
 But if it does not return html, you have to provide a transformer capable
 to produce html from the data get_content produces.
 The arguments are passed as a reference, because the get_content function
 can change them, and they can get stored automatically as session variable.
 This is because the parent module provides one other service: Your module
 can rely on an automatic handling of HTTP GET, POST and COOKIE variables,
 and of session variables.
 All you'd have to do is to define the arrays $this->get, $this->post, $this->co
okie and $this->session.
 All members of these variables will be fetched from the GET, POST or COOKIE
 parameters, or from session variables and stored for you in the $arguments
 array.
 The entries of $this->session additionnaly will be stored after get_content
 returns to get_output.
 This can be very useful if you want your module to remain in a stable state
 while the user interacts with other modules on the same page.
\begin_deeper 
\layout Standard

The variables you define in these arrays can be identical to those in $this->arg
uments.
 In this case, if they are defined in the HTTP session context, they will
 override the values the page contributor has defined for the page.
 But they can be different variables that do not need an initial value provided
 by the page contributor.
 Whereas $this->get,$this->cookie and $this->session are simple arrays enumerati
ng the variable names, $this->post is special because it can contain the
 element definition in the same way as $this->arguments, which can be used
 to programatically construct the form elements.
\layout Standard

Your module does not need to use this service, it could directly read HTTP
 variables.
 The advantage of using it is that it provides a namespace for each module,
 so that if different modules that use the same variable names are used
 on the same page, no problems occur.
 If you use this service you can construct URLS automatically with the modules
 link function (see below), and if you construct the user interface, you
 have to provide the correct form element names for this service to work.
 The build_post_element function can help you do this.
 For example lets extend our hello module, so that the site user can choose
 his own name.
 Since we can no longer rely on the validation that is automatically done
 on contributor provided input.
 we call validate from the get_content function.
\layout Code

<?php
\layout Code

\layout Code

class module_hello extends Module  {
\layout Code

    function module_hello()
\layout Code

    {
\layout Code

        $this->arguments = array(
\layout Code

            'name' => array(
\layout Code

                'type' => 'textfield',
\layout Code

                 'label' => 'The person to say hello to'
\layout Code

            )
\layout Code

        );
\layout Code

       $this->post = array('name' => array('type' => 'textfield'));
\layout Code

       $this->session = array('name');
\layout Code

       $this->title = "Hello world";
\layout Code

       $this->description = "This is a simple sample module";
\layout Code

    }
\layout Code

    function get_content(&$arguments,$properties)
\layout Code

    {
\layout Code

       $this->validate($arguments);
\layout Code

       return lang('Hello') .
 ' ' .
 $arguments['name'] .
 '<br><form action="' .
\layout Code

           $_SERVER['REQUEST_URI'] .
 '" method="post">' .
\layout Code

               $this->build_post_element('name',lang('Enter a name') .
\layout Code

           '</form>';
\layout Code

    }
\layout Code

\layout Code

    function validate(&$data)
\layout Code

    {
\layout Code

       if (preg_match("/[[:upper:]]/",$data['name']))
\layout Code

       {
\layout Code

           $data['name'] = strtolower($data['name']);
\layout Code

           $this->validation_error = "Name has been translated to lower
 case";                }
\layout Code

       return true;
\layout Code

   }
\layout Code

}
\end_deeper 
\layout Description

build_post_element($key,$default=False) You can use this function from your
 module's get_content function to construct form elements.
 This works with the argument definition you put into $this->post.
 If you do not provide a default the current blocks value for the argument
 will be filled in.
\layout Description

link($modulevars) helps you construct URLS with GET parameters that use
 the service described above.
 modulevars is an array of variable values keyed on variable names.
\layout Description

find_template_dir() if a module uses a different template (of whatever kind)
 for different site themes, this function can help finding the template
 directory inside the theme's directory, if it follows the namespace described
 above, or if it cannot be found name the default directory.
\layout Description

get_output($type='html') This is the function that is actually called by
 the page generation engine, since it not only calls the module's get_content
 function, but makes sure that all transformers that have been added to
 the modules transformer_chain get called.
 For type argument is not really used at the moment, but future versions
 of sitemgr could be extended so that modules could produce output in different
 formats by specifying different transformers for each output type.
 Your module should not need to override get_output.
\layout Standard

To summarize, there are the following requirements for a sitemgr module:
\layout Enumerate

It is written as a class called module_name and extends the class Module.
 It must be put into a file called class.module_name.inc.php and put into the
 inc directory of any eGroupWare application.
\layout Enumerate

Its constructor should define the following member variables:
\begin_deeper 
\layout Enumerate

arguments: the module's arguments a contributor can edit in order to create
 content blocks from the module.
 Each argument needs to define a label and the type of input element used
 to edit it in the content manager.
 Parameters for these input elements (like size for textfields, cols and
 rows for textareas can be defined).
 Translatable arguments can be specially flagged with a i18n entry in the
 arguments definition array
\begin_inset Foot
collapsed false

\layout Standard

If a module wants to make use of sitemgr's translation feature, it must
 additionally set the module member variable i18n to true.
\end_inset 


\layout Enumerate

properties: the module's properties the site administrator can edit in order
 to constrain or configure the functionnality of the module
\layout Enumerate

title: The module's default title that can be overriden for each content
 block.
\layout Enumerate

description: A short descriptive text, that is displayed in the content
 manager and module manager (for example when you put the mouse over an
 entry in the module select lists).
\end_deeper 
\layout Enumerate

It needs a get_content function that has access to arguments and properties
 and produces the block content.
\layout Enumerate

If the content returned by get_content is something different from HTML,
 the module has to define transformer classes, and should add them to the
 module's transformer chain.
 This can be done in the constructor, but the best place for it is the set_block
 function
\layout Enumerate

The parent module class provides a user interface for editing module arguments.
 If a module needs a customized interface or wants to construct arguments
 dynamically, it can override the get_user_interface function.
\layout Standard

These are the building blocks which should allow for some flexibility in
 constructing modules that make eGroupWare managed data visible on a sitemgr
 web site.
\the_end