[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Phpgroupware-cvs] CVS: sitemgr/doc modules.dvi,1.2,1.3 modules.html,1.
|
From: |
Michael Totschnig <address@hidden> |
|
Subject: |
[Phpgroupware-cvs] CVS: sitemgr/doc modules.dvi,1.2,1.3 modules.html,1.2,1.3 modules.lyx,1.2,1.3 modules.pdf,1.2,1.3 modules.ps,1.2,1.3 modules.sgml,1.2,1.3 modules.txt,1.2,1.3 |
|
Date: |
Sat, 18 Jan 2003 20:10:04 -0500 |
Update of /cvsroot/phpgroupware/sitemgr/doc
In directory subversions:/tmp/cvs-serv21057/doc
Modified Files:
modules.dvi modules.html modules.lyx modules.pdf modules.ps
modules.sgml modules.txt
Log Message:
add some code to make migration of existing templates easier
add function find_template_dir
Index: modules.dvi
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.dvi,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
Binary files /tmp/cvsyh8vhK and /tmp/cvsgDoCOj differ
Index: modules.html
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** modules.html 18 Jan 2003 05:24:38 -0000 1.2
--- modules.html 19 Jan 2003 01:10:02 -0000 1.3
***************
*** 66,75 ****
><DT
><A
! HREF="#AEN79"
>User manual</A
></DT
><DT
><A
! HREF="#AEN108"
>Administrator manual<A
NAME="ADMINISTRATOR-MANUAL"
--- 66,75 ----
><DT
><A
! HREF="#AEN77"
>User manual</A
></DT
><DT
><A
! HREF="#AEN196"
>Administrator manual<A
NAME="ADMINISTRATOR-MANUAL"
***************
*** 79,83 ****
><DT
><A
! HREF="#AEN142"
>Template designer manual<A
NAME="TEMPLATE-DESIGNER-MANUAL"
--- 79,83 ----
><DT
><A
! HREF="#AEN232"
>Template designer manual<A
NAME="TEMPLATE-DESIGNER-MANUAL"
***************
*** 87,91 ****
><DT
><A
! HREF="#AEN157"
>Application developper manual<A
NAME="APPLICATION-DEVELOPPER-MANUAL"
--- 87,91 ----
><DT
><A
! HREF="#AEN249"
>Application developper manual<A
NAME="APPLICATION-DEVELOPPER-MANUAL"
***************
*** 110,114 ****
NAME="AEN13">Template</H3
><P
! >Sitemgr builds web sites from templates. Those are stored in the directory
sitemgr/sitemg-site/templates. Each of them has a directory of its own. 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 and 4 and 5 can be used both in the template as in the page content a
module generates.</P
><P
></P
--- 110,114 ----
NAME="AEN13">Template</H3
><P
! >Sitemgr builds web sites from templates. Those are stored in the directory
sitemgr/sitemg-site/templates. Each of them has a directory of its own. 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 and 4 can be used both in the template as in the page content a
module generates.</P
><P
></P
***************
*** 142,149 ****
><LI
><P
- >{lang_translatable_string} This lets you make the template
internationalized. The translatable string is sent through phpgroupware's lang
function. Thus you can add it to the lang files in the setup directory and
install it through the setup programm.</P
- ></LI
- ><LI
- ><P
>{variable} Finally there are some simple variables you can use to retrieve
metainformation about the page or about the user's context:</P
><P
--- 142,145 ----
***************
*** 184,188 ****
CLASS="SECT2"
><A
! NAME="AEN45">Module</H3
><P
>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 chapter<A
--- 180,184 ----
CLASS="SECT2"
><A
! NAME="AEN43">Module</H3
><P
>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 chapter<A
***************
*** 196,200 ****
CLASS="SECT2"
><A
! NAME="AEN49">Argument/Content</H3
><P
>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 phpgroupware 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.</P
--- 192,196 ----
CLASS="SECT2"
><A
! NAME="AEN47">Argument/Content</H3
><P
>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 phpgroupware 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.</P
***************
*** 205,209 ****
CLASS="SECT2"
><A
! NAME="AEN52">Properties</H3
><P
>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:</P
--- 201,205 ----
CLASS="SECT2"
><A
! NAME="AEN50">Properties</H3
><P
>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:</P
***************
*** 229,233 ****
CLASS="SECT2"
><A
! NAME="AEN61">Blocks, content areas and scope</H3
><P
>There are three ways a module can generate content that will be displayed on
a web page:</P
--- 225,229 ----
CLASS="SECT2"
><A
! NAME="AEN59">Blocks, content areas and scope</H3
><P
>There are three ways a module can generate content that will be displayed on
a web page:</P
***************
*** 257,261 ****
CLASS="SECT2"
><A
! NAME="AEN71">Transformer</H3
><P
>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. </P
--- 253,257 ----
CLASS="SECT2"
><A
! NAME="AEN69">Transformer</H3
><P
>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. </P
***************
*** 270,274 ****
CLASS="SECT2"
><A
! NAME="AEN76">Translations</H3
><P
>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.</P
--- 266,270 ----
CLASS="SECT2"
><A
! NAME="AEN74">Translations</H3
><P
>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.</P
***************
*** 280,284 ****
CLASS="SECT1"
><A
! NAME="AEN79">User manual</H2
><P
>The most important difference for site contributors between the modularized
sitemgr and its older versions is that in the page manager now there are two
different interfaces for each page:</P
--- 276,280 ----
CLASS="SECT1"
><A
! NAME="AEN77">User manual</H2
><P
>The most important difference for site contributors between the modularized
sitemgr and its older versions is that in the page manager now there are two
different interfaces for each page:</P
***************
*** 298,301 ****
--- 294,321 ----
><P
>The second difference is that now a contributor can also define content
blocks for the whole category he has write access for. These category wide
blocks will be seen on each page that belongs to the category or to any of its
subcategories. There are also side wide content blocks that only the site
administrator can create.</P
+ ><DIV
+ CLASS="SECT2"
+ ><HR><H3
+ CLASS="SECT2"
+ ><A
+ NAME="AEN86">Creating a new page</H3
+ ><P
+ >to be completed</P
+ ></DIV
+ ><DIV
+ CLASS="SECT2"
+ ><HR><H3
+ CLASS="SECT2"
+ ><A
+ NAME="AEN89">Editing page metadata</H3
+ ><P
+ >to be completed</P
+ ></DIV
+ ><DIV
+ CLASS="SECT2"
+ ><HR><H3
+ CLASS="SECT2"
+ ><A
+ NAME="AEN92">Editing page content</H3
><P
>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.</P
***************
*** 335,338 ****
--- 355,488 ----
><P
>After these, 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.</P
+ ><P
+ >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:</P
+ ><P
+ ></P
+ ><DIV
+ CLASS="VARIABLELIST"
+ ><DL
+ ><DT
+ >administration</DT
+ ><DD
+ ><P
+ >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
phpgw users or adminstrators.</P
+ ></DD
+ ><DT
+ >amazon</DT
+ ><DD
+ ><P
+ >shows ads for books on the Amazon website. There is a comment in the modules
source file about how it works.</P
+ ></DD
+ ><DT
+ >appdir</DT
+ ><DD
+ ><P
+ >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.</P
+ ></DD
+ ><DT
+ >calendar</DT
+ ><DD
+ ><P
+ >produces a calendar where each days links to phpgroupware's calendar
application</P
+ ></DD
+ ><DT
+ >currentsection</DT
+ ><DD
+ ><P
+ >produces an index of the pages in the current section.</P
+ ></DD
+ ><DT
+ >forum</DT
+ ><DD
+ ><P
+ >another demonstration of what sitemg's modules are intended for: This module
displays the discussions of phpgroupware'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.</P
+ ></DD
+ ><DT
+ >galerie</DT
+ ><DD
+ ><P
+ >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.</P
+ ></DD
+ ><DT
+ >google</DT
+ ><DD
+ ><P
+ >displays a form for querying the google website.</P
+ ></DD
+ ><DT
+ >hello</DT
+ ><DD
+ ><P
+ >a simple “Hello world” module used below in this manual.</P
+ ></DD
+ ><DT
+ >html</DT
+ ><DD
+ ><P
+ >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.</P
+ ></DD
+ ><DT
+ >index_block</DT
+ ><DD
+ ><P
+ >a index of the whole site, formatted for peripheric areas of your web
site.</P
+ ></DD
+ ><DT
+ >index</DT
+ ><DD
+ ><P
+ >is automatically used with the index GET parameter. You probably would not
have to use this block otherwise.</P
+ ></DD
+ ><DT
+ >lang_block</DT
+ ><DD
+ ><P
+ >displays a select box for changing the user's site language.</P
+ ></DD
+ ><DT
+ >login</DT
+ ><DD
+ ><P
+ >displays a login block</P
+ ></DD
+ ><DT
+ >news</DT
+ ><DD
+ ><P
+ >publishes news you edit with phpgroupware's news_admin application. You can
choose a category to display.</P
+ ></DD
+ ><DT
+ >redirect</DT
+ ><DD
+ ><P
+ >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.</P
+ ></DD
+ ><DT
+ >sitetree</DT
+ ><DD
+ ><P
+ >displays a tree like menu to the website.</P
+ ></DD
+ ><DT
+ >toc_block</DT
+ ><DD
+ ><P
+ >the site's table of contents, formatted for peripheric areas of your web
site.</P
+ ></DD
+ ><DT
+ >toc</DT
+ ><DD
+ ><P
+ >is automatically used with the toc GET parameter. You probably would not
have to use this block otherwise.</P
+ ></DD
+ ><DT
+ >xml</DT
+ ><DD
+ ><P
+ >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. </P
+ ></DD
+ ></DL
+ ></DIV
+ ></DIV
></DIV
><DIV
***************
*** 341,345 ****
CLASS="SECT1"
><A
! NAME="AEN108">Administrator manual<A
NAME="ADMINISTRATOR-MANUAL"
></A
--- 491,495 ----
CLASS="SECT1"
><A
! NAME="AEN196">Administrator manual<A
NAME="ADMINISTRATOR-MANUAL"
></A
***************
*** 350,354 ****
CLASS="SECT2"
><A
! NAME="AEN111">Installation</H3
><P
></P
--- 500,504 ----
CLASS="SECT2"
><A
! NAME="AEN199">Installation</H3
><P
></P
***************
*** 406,410 ****
><LI
><P
! >You're almost set to go. Log in to phpGroupWare as an administrator. Make
sure you gave yourself the sitemgr and sitemgr-link applications so that you
see them on your navbar. Go to the sitemgr application and select "Configure
SiteMgr". Fill in “URL to sitemgr-site” and “Filesystem path
to sitemgr-site directory”, and the anonymous user's name and password.
Then click on save, and you should now select the template for your site.</P
></LI
><LI
--- 556,564 ----
><LI
><P
! >You're almost set to go. Log in to phpGroupWare as an administrator. Make
sure you gave yourself the sitemgr and sitemgr-link applications so that you
see them on your navbar. Go to the sitemgr application and select "Configure
SiteMgr". Fill in “URL to sitemgr-site” and “Filesystem path
to sitemgr-site directory”, and the anonymous user's name and password.
Then click on save, and you should know select the template for your site.</P
! ></LI
! ><LI
! ><P
! >After installation sitemgr does not immediately know about all available
modules since those can be defined by other applications. The setup routine
only installs the modules html,index and toc that every site will need. In
order to register all availabe modules select “Manage site-wide module
properties” from the administrative menu, and then follow the
“Register new modules” link.</P
></LI
><LI
***************
*** 419,423 ****
CLASS="SECT2"
><A
! NAME="AEN132">Maintenance</H3
><P
>As a site administrator, you have three privileges/responsibilies:</P
--- 573,577 ----
CLASS="SECT2"
><A
! NAME="AEN222">Maintenance</H3
><P
>As a site administrator, you have three privileges/responsibilies:</P
***************
*** 449,453 ****
CLASS="SECT1"
><A
! NAME="AEN142">Template designer manual<A
NAME="TEMPLATE-DESIGNER-MANUAL"
></A
--- 603,607 ----
CLASS="SECT1"
><A
! NAME="AEN232">Template designer manual<A
NAME="TEMPLATE-DESIGNER-MANUAL"
></A
***************
*** 468,472 ****
><LI
><P
! >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 necessarily 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.</P
></LI
><LI
--- 622,630 ----
><LI
><P
! >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 necessarily 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<A
! NAME="AEN243"
! HREF="#FTN.AEN243"
! >[1]</A
! >.</P
></LI
><LI
***************
*** 485,489 ****
CLASS="SECT1"
><A
! NAME="AEN157">Application developper manual<A
NAME="APPLICATION-DEVELOPPER-MANUAL"
></A
--- 643,647 ----
CLASS="SECT1"
><A
! NAME="AEN249">Application developper manual<A
NAME="APPLICATION-DEVELOPPER-MANUAL"
></A
***************
*** 522,526 ****
></TABLE
><P
! >Once your module is registered 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?</P
><P
>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:</P
--- 680,688 ----
></TABLE
><P
! >Once your module is registered<A
! NAME="AEN255"
! HREF="#FTN.AEN255"
! >[2]</A
! > 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?</P
><P
>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:</P
***************
*** 643,651 ****
><DD
><P
! >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->cookie 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 do remain in a stable state while the user interacts with
other modules on the same page.</P
><P
>The variables you define in these arrays can be identical to those in
$this->arguments. 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 enumerating 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.</P
><P
! >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 you use different modules on the same page, that use the
same variable names, you would not run into problems. 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.</P
><TABLE
BORDER="0"
--- 805,813 ----
><DD
><P
! >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->cookie 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.</P
><P
>The variables you define in these arrays can be identical to those in
$this->arguments. 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 enumerating 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.</P
><P
! >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.</P
><TABLE
BORDER="0"
***************
*** 660,664 ****
function module_hello()
{
- $this->name = "hello";
$this->arguments = array(
'name' => array(
--- 822,825 ----
***************
*** 706,709 ****
--- 867,876 ----
></DD
><DT
+ >find_template_dir()</DT
+ ><DD
+ ><P
+ >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.</P
+ ></DD
+ ><DT
>get_output($type='html')</DT
><DD
***************
*** 765,768 ****
--- 932,979 ----
></DIV
></DIV
+ ><H3
+ CLASS="FOOTNOTES"
+ >Notes</H3
+ ><TABLE
+ BORDER="0"
+ CLASS="FOOTNOTES"
+ WIDTH="100%"
+ ><TR
+ ><TD
+ ALIGN="LEFT"
+ VALIGN="TOP"
+ WIDTH="5%"
+ ><A
+ NAME="FTN.AEN243"
+ HREF="#AEN243"
+ >[1]</A
+ ></TD
+ ><TD
+ ALIGN="LEFT"
+ VALIGN="TOP"
+ WIDTH="95%"
+ ><P
+ >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.php and
left_bt.inc.php.</P
+ ></TD
+ ></TR
+ ><TR
+ ><TD
+ ALIGN="LEFT"
+ VALIGN="TOP"
+ WIDTH="5%"
+ ><A
+ NAME="FTN.AEN255"
+ HREF="#AEN255"
+ >[2]</A
+ ></TD
+ ><TD
+ ALIGN="LEFT"
+ VALIGN="TOP"
+ WIDTH="95%"
+ ><P
+ >Modules should be stored in an application's inc directory, and be named
class.module_modulename.inc.php in order that sitemgr can find them.</P
+ ></TD
+ ></TR
+ ></TABLE
></BODY
></HTML
Index: modules.lyx
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.lyx,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** modules.lyx 18 Jan 2003 05:24:38 -0000 1.2
--- modules.lyx 19 Jan 2003 01:10:02 -0000 1.3
***************
*** 78,83 ****
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 and 4 and 5 can be used both
! in the template as in the page content a module generates.
\layout Enumerate
--- 78,83 ----
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 and 4 can be used both in
! the template as in the page content a module generates.
\layout Enumerate
***************
*** 125,134 ****
\layout Enumerate
- {lang_translatable_string} This lets you make the template internationalized.
- The translatable string is sent through phpgroupware's lang function.
- Thus you can add it to the lang files in the setup directory and install
- it through the setup programm.
- \layout Enumerate
-
{variable} Finally there are some simple variables you can use to retrieve
metainformation about the page or about the user's context:
--- 125,128 ----
***************
*** 427,430 ****
--- 421,439 ----
There are also side wide content blocks that only the site administrator
can create.
+ \layout Subsection
+
+ Creating a new page
+ \layout Standard
+
+ to be completed
+ \layout Subsection
+
+ Editing page metadata
+ \layout Standard
+
+ to be completed
+ \layout Subsection
+
+ Editing page content
\layout Standard
***************
*** 482,485 ****
--- 491,603 ----
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 phpgw 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
+
+ calendar produces a calendar where each days links to phpgroupware's calendar
+ application
+ \layout Description
+
+ currentsection produces an index of the pages in the current section.
+ \layout Description
+
+ forum another demonstration of what sitemg's modules are intended for: This
+ module displays the discussions of phpgroupware'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 phpgroupware'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 Section
***************
*** 575,579 ****
, and the anonymous user's name and password.
! Then click on save, and you should now select the template for your site.
\layout Enumerate
--- 693,720 ----
, and the anonymous user's name and password.
! Then click on save, and you should know select the template for your site.
! \layout Enumerate
!
! After installation sitemgr does not immediately know about all available
! modules since those can be defined by other applications.
! 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
***************
*** 722,726 ****
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.
\layout Itemize
--- 863,881 ----
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
***************
*** 832,839 ****
\layout Standard
! Once your module is registered 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
--- 987,1004 ----
\layout Standard
! Once your module is registered
! \begin_inset Foot
! collapsed false
!
! \layout Standard
!
! Modules should be stored in an application's inc directory, 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
***************
*** 994,998 ****
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 do remain in a stable state
while the user interacts with other modules on the same page.
\begin_deeper
--- 1159,1163 ----
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
***************
*** 1014,1019 ****
variables.
The advantage of using it is that it provides a namespace for each module,
! so that if you use different modules on the same page, that use the same
! variable names, you would not run into problems.
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
--- 1179,1184 ----
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
***************
*** 1041,1047 ****
\layout Code
- $this->name = "hello";
- \layout Code
-
$this->arguments = array(
\layout Code
--- 1206,1209 ----
***************
*** 1146,1149 ****
--- 1308,1317 ----
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
Index: modules.pdf
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.pdf,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
Binary files /tmp/cvsqjui7N and /tmp/cvsW87HCt differ
Index: modules.ps
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.ps,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** modules.ps 18 Jan 2003 05:24:38 -0000 1.2
--- modules.ps 19 Jan 2003 01:10:02 -0000 1.3
***************
*** 2,6 ****
%%Creator: dvips(k) 5.86 Copyright 1999 Radical Eye Software
%%Title: modules.dvi
! %%Pages: 14
%%PageOrder: Ascend
%%BoundingBox: 0 0 612 792
--- 2,6 ----
%%Creator: dvips(k) 5.86 Copyright 1999 Radical Eye Software
%%Title: modules.dvi
! %%Pages: 16
%%PageOrder: Ascend
[...2038 lines suppressed...]
! Black 69 w(For)32 b(compatibility)g(with)g(how)g(sitemgr)f(used)g(to)h
! (work,)f(the)g(\002le)h(sideblock.tpl)f(which)728 3097
! y(uses)25 b(the)f(two)g(variables)f(block_title)h(and)g(block_content)g
! (is)h(still)f(r)o(ecognized)f(as)h(a)f(tem-)728 3188
! y(plate)e(for)f(a)g(transformation)i(of)e(the)h(two)h(contentar)o(eas)e
! (left)g(and)h(right.)g(The)f(transformer)728 3280 y(is)25
! b(automatically)g(cr)o(eated)d(by)j(the)g(template)f(class.)g(Thus)h
! (you)g(could)g(use)g(one)g(\002le)f(side-)728 3371 y(block.tpl)d
! (instead)g(of)g(the)g(two)g(\002les)g(right_bt.inc.php)g(and)f
! (left_bt.inc.php.)p Black 596 3504 a(2.)p Black 69 w(Modules)45
! b(should)h(be)e(stor)o(ed)h(in)g(an)g(application's)g(inc)g(dir)o
! (ectory)-9 b(,)44 b(and)h(be)f(named)728 3595 y
! (class.module_modulename.inc.php)21 b(in)g(or)o(der)f(that)g(sitemgr)i
! (can)e(\002nd)h(them.)p Black 3601 5585 a Fe(15)p Black
! eop
! %%Page: 16 16
! 16 15 bop Black 0 TeXcolorgray Black 197 -132 a Fe(Intr)o(oduction)19
! b(to)h(sitemgr)h(modules)p Black Black 197 5585 a(16)p
Black eop
%%Trailer
Index: modules.sgml
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.sgml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** modules.sgml 18 Jan 2003 05:24:39 -0000 1.2
--- modules.sgml 19 Jan 2003 01:10:02 -0000 1.3
***************
*** 6,10 ****
See http://www.lyx.org/ for more information -->
<articleinfo><title>Introduction to sitemgr modules</title><date>January 1,
2003</date><author><firstname>Michael</firstname>
<surname>Totschnig</surname></author><abstract><para>This text provides an
overview of sitemgr's proposed new modularized architecture and contains the
information users, administrators, template designers and application
devellopers need in order to get started using sitemgr as a flexible web site
managment system that can easily make any information and business logic
phpgroupware knows about publicly accessible. This text also serves as a
request for comments, so that sitemgr's new generation can be adapted quickly
to the needs of PHPgroupware's user community. Please be aware that at the
moment the new sitemgr is still experimental and that there are some areas of
its functionnality that need further
developpment.</para></abstract></articleinfo>
! <sect1><title>Introduction</title><para>For the next generaton of
phpgroupware's web site managment application sitemgr, we propose a new page
generation architecture whose fundamental idea is that all dynamic web site
content is built by modules. In this section, I will sketch a short outline of
how this architecture works and I will present the concepts it makes use
of.</para><sect2><title>Template</title><para>Sitemgr builds web sites from
templates. Those are stored in the directory sitemgr/sitemg-site/templates.
Each of them has a directory of its own. 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 and 4 and 5 can be used both in
the template as in the page content a module
generates.</para><orderedlist><listitem><para>{contentarea: areaname}
These define where administrator and contributor provided content go. The names
and the number of contentareas a template defines are almost
arbitrary.</para></listitem><listitem><para>{appname.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,{sitemgr.lang_block] creates the select box for multilingual
sites.</para></listitem><listitem><para>{?(phpgw|sitemgr:)link} This
lets you create links either to other pages of your website, or to phpgroupware
applications:</para><orderedlist><listitem><para>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.</para></listitem><listitem><para>Links to
phpgw 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}.</para></listitem></orderedlist></listitem><listitem><para>{lang_translatable_string}
This lets you make the template internationalized. The translatable string is
sent through phpgroupware's lang function. Thus you can add it to the lang
files in the setup directory and install it through the setup
programm.</para></listitem><listitem><para>{variable} Finally there
are some simple variables you can use to retrieve metainformation about the
page or about the user's
context:</para><orderedlist><listitem><para>{title} the page
title</para></listitem><listitem><para>{subtitle} the page
subtitle</para></listitem><listitem><para>{sitename}the sitename the
administrator has chosen for the
site</para></listitem><listitem><para>{footer}the administrator
edited footer</para></listitem><listitem><para>{header}the
administrator edited
header</para></listitem><listitem><para>{user}the user's account
name</para></listitem></orderedlist></listitem></orderedlist></sect2>
<sect2><title>Module</title><para>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
chapter<link linkend="Application-developper-manual">5</link>.</para></sect2>
<sect2><title>Argument/Content</title><para>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 phpgroupware 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.</para></sect2>
--- 6,10 ----
See http://www.lyx.org/ for more information -->
<articleinfo><title>Introduction to sitemgr modules</title><date>January 1,
2003</date><author><firstname>Michael</firstname>
<surname>Totschnig</surname></author><abstract><para>This text provides an
overview of sitemgr's proposed new modularized architecture and contains the
information users, administrators, template designers and application
devellopers need in order to get started using sitemgr as a flexible web site
managment system that can easily make any information and business logic
phpgroupware knows about publicly accessible. This text also serves as a
request for comments, so that sitemgr's new generation can be adapted quickly
to the needs of PHPgroupware's user community. Please be aware that at the
moment the new sitemgr is still experimental and that there are some areas of
its functionnality that need further
developpment.</para></abstract></articleinfo>
! <sect1><title>Introduction</title><para>For the next generaton of
phpgroupware's web site managment application sitemgr, we propose a new page
generation architecture whose fundamental idea is that all dynamic web site
content is built by modules. In this section, I will sketch a short outline of
how this architecture works and I will present the concepts it makes use
of.</para><sect2><title>Template</title><para>Sitemgr builds web sites from
templates. Those are stored in the directory sitemgr/sitemg-site/templates.
Each of them has a directory of its own. 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 and 4 can be used both in the
template as in the page content a module
generates.</para><orderedlist><listitem><para>{contentarea: areaname}
These define where administrator and contributor provided content go. The names
and the number of contentareas a template defines are almost
arbitrary.</para></listitem><listitem><para>{appname.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,{sitemgr.lang_block] creates the select box for multilingual
sites.</para></listitem><listitem><para>{?(phpgw|sitemgr:)link} This
lets you create links either to other pages of your website, or to phpgroupware
applications:</para><orderedlist><listitem><para>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.</para></listitem><listitem><para>Links to
phpgw 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}.</para></listitem></orderedlist></listitem><listitem><para>{variable}
Finally there are some simple variables you can use to retrieve
metainformation about the page or about the user's
context:</para><orderedlist><listitem><para>{title} the page
title</para></listitem><listitem><para>{subtitle} the page
subtitle</para></listitem><listitem><para>{sitename}the sitename the
administrator has chosen for the
site</para></listitem><listitem><para>{footer}the administrator
edited footer</para></listitem><listitem><para>{header}the
administrator edited
header</para></listitem><listitem><para>{user}the user's account
name</para></listitem></orderedlist></listitem></orderedlist></sect2>
<sect2><title>Module</title><para>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
chapter<link linkend="Application-developper-manual">5</link>.</para></sect2>
<sect2><title>Argument/Content</title><para>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 phpgroupware 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.</para></sect2>
***************
*** 16,28 ****
<sect2><title>Translations</title><para>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.</para></sect2>
</sect1>
! <sect1><title>User manual</title><para>The most important difference for site
contributors between the modularized sitemgr and its older versions is that in
the page manager now there are two different interfaces for each
page:</para><orderedlist><listitem><para>When you create a new page or when you
click on the Edit button which is associated with an existing page, you no
longer edit the page content, but only some basic metainformation about the
page as its name, title, subtitle and sort order, and you can change the
category the page belongs to.</para></listitem><listitem><para>There is a new
interface that gets displayed when you click on a page's “Manage
content” button. It is here that you create the content blocks for each
page.</para></listitem></orderedlist><para>The second difference is that now a
contributor can also define content blocks for the whole category he has write
access for. These category wide blocks will be seen on each page that belongs
to the category or to any of its subcategories. There are also side wide
content blocks that only the site administrator can create.</para><para>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.</para><para>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. There are four standard interface elements you can edit
for each block:</para><variablelist><varlistentry><term>Title
</term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>Actif
</term><listitem><para>When you create a new block, it is not immediately
visible on the web site. This makes sense since you need to edit its arguments
first. When you are finished defining a blocks arguments, you have to check the
actif flag to make it visible. This can also be practical if you want to hide
some content temporarily from the web site without deleting it from the
database.</para></listitem></varlistentry><varlistentry><term>Seenby
</term><listitem><para>You can control the visibility of each block for the
different user roles defined by sitemgr: site administrators, phpgroupware
users (which include site administrators) and the anonymous user. Evidently you
can also make the block visible for everyone which is the default.
</para></listitem></varlistentry><varlistentry><term>Sortorder
! </term><listitem><para>Here you can change the order in which the blocks are
displayed by defining a different integer for each
block.</para></listitem></varlistentry></variablelist><para>After these, 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.</para></sect1>
<sect1><title>Administrator manual<anchor
id="Administrator-manual"></title><sect2><title>Installation</title><orderedlist><listitem><para>Once
you have the sitemgr directory inside your phpgroupware install you can setup
it like any other phpgroupware application with the setup program
(http://yourmachine/phpgw-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.</para><programlisting><![CDATA[cd sitemgr
]]><![CDATA[mv sitemgr-link ..
]]></programlisting><para>and then install sitemgr-link with
setup</para></listitem><listitem><para>Log in to phpGroupWare as an admin and
create an anonymous phpgw 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 phpGW users to the generated
site.</para></listitem><listitem><para>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 phpGW 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. </para></listitem><listitem><para>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/phpgroupware/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.</para></listitem><listitem><para>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</para><programlisting><![CDATA['phpgw_path'
=> '../../',
! ]]></programlisting><para>so that the value of
$sitemgr_info['phpgw_path'] is
'/path/to/phpgroupware/'</para></listitem><listitem><para>You're almost set to
go. Log in to phpGroupWare as an administrator. Make sure you gave yourself the
sitemgr and sitemgr-link applications so that you see them on your navbar. Go
to the sitemgr application and select "Configure SiteMgr". Fill in
“URL to sitemgr-site” and “Filesystem path to sitemgr-site
directory”, and the anonymous user's name and password. Then click on
save, and you should now select the template for your
site.</para></listitem><listitem><para>That's it. Go to the Category manager,
add a category or three and check who can view and edit them, then go to the
page manager, add a page or three to each category, set up your site header,
site footer, etc., and go view your recently created site by clicking on the
sitemgr-link application. Voilà!</para></listitem></orderedlist></sect2>
<sect2><title>Maintenance</title><para>As a site administrator, you have
three privileges/responsibilies:</para><orderedlist><listitem><para>Define site
wide content blocks. These are edited in the same interface as category and
page specific blocks.</para></listitem><listitem><para>Choose permitted
modules: If you choose “Manage site-wide module properties” from
sitemgr's main menu, you will see several rows which all contain four elements:
a select box, a button labelled “Select allowed modules', another select
box and a button labelled “Configure module properties”. 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.
In the category manager, there is a button “Manage Modules”
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.
--- 16,51 ----
<sect2><title>Translations</title><para>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.</para></sect2>
</sect1>
! <sect1><title>User manual</title><para>The most important difference for site
contributors between the modularized sitemgr and its older versions is that in
the page manager now there are two different interfaces for each
page:</para><orderedlist><listitem><para>When you create a new page or when you
click on the Edit button which is associated with an existing page, you no
longer edit the page content, but only some basic metainformation about the
page as its name, title, subtitle and sort order, and you can change the
category the page belongs to.</para></listitem><listitem><para>There is a new
interface that gets displayed when you click on a page's “Manage
content” button. It is here that you create the content blocks for each
page.</para></listitem></orderedlist><para>The second difference is that now a
contributor can also define content blocks for the whole category he has write
access for. These category wide blocks will be seen on each page that belongs
to the category or to any of its subcategories. There are also side wide
content blocks that only the site administrator can
create.</para><sect2><title>Creating a new page</title><para>to be
completed</para></sect2>
! <sect2><title>Editing page metadata</title><para>to be
completed</para></sect2>
! <sect2><title>Editing page content</title><para>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.</para><para>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. There are four standard interface elements you can edit for each
block:</para><variablelist><varlistentry><term>Title
</term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>Actif
</term><listitem><para>When you create a new block, it is not immediately
visible on the web site. This makes sense since you need to edit its arguments
first. When you are finished defining a blocks arguments, you have to check the
actif flag to make it visible. This can also be practical if you want to hide
some content temporarily from the web site without deleting it from the
database.</para></listitem></varlistentry><varlistentry><term>Seenby
</term><listitem><para>You can control the visibility of each block for the
different user roles defined by sitemgr: site administrators, phpgroupware
users (which include site administrators) and the anonymous user. Evidently you
can also make the block visible for everyone which is the default.
</para></listitem></varlistentry><varlistentry><term>Sortorder
! </term><listitem><para>Here you can change the order in which the blocks are
displayed by defining a different integer for each
block.</para></listitem></varlistentry></variablelist><para>After these, 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.</para><para>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:</para><variablelist><varlistentry><term>administration
! </term><listitem><para>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 phpgw users or
adminstrators.</para></listitem></varlistentry><varlistentry><term>amazon
! </term><listitem><para>shows ads for books on the Amazon website. There is a
comment in the modules source file about how it
works.</para></listitem></varlistentry><varlistentry><term>appdir
! </term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>calendar
! </term><listitem><para>produces a calendar where each days links to
phpgroupware's calendar
application</para></listitem></varlistentry><varlistentry><term>currentsection
! </term><listitem><para>produces an index of the pages in the current
section.</para></listitem></varlistentry><varlistentry><term>forum
! </term><listitem><para>another demonstration of what sitemg's modules are
intended for: This module displays the discussions of phpgroupware'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.</para></listitem></varlistentry><varlistentry><term>galerie
! </term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>google
! </term><listitem><para>displays a form for querying the google
website.</para></listitem></varlistentry><varlistentry><term>hello
! </term><listitem><para>a simple “Hello world” module used below
in this manual.</para></listitem></varlistentry><varlistentry><term>html
! </term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>index_block
! </term><listitem><para>a index of the whole site, formatted for peripheric
areas of your web
site.</para></listitem></varlistentry><varlistentry><term>index
! </term><listitem><para>is automatically used with the index GET parameter.
You probably would not have to use this block
otherwise.</para></listitem></varlistentry><varlistentry><term>lang_block
! </term><listitem><para>displays a select box for changing the user's site
language.</para></listitem></varlistentry><varlistentry><term>login
! </term><listitem><para>displays a login
block</para></listitem></varlistentry><varlistentry><term>news
! </term><listitem><para>publishes news you edit with phpgroupware's news_admin
application. You can choose a category to
display.</para></listitem></varlistentry><varlistentry><term>redirect
! </term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>sitetree
! </term><listitem><para>displays a tree like menu to the
website.</para></listitem></varlistentry><varlistentry><term>toc_block
! </term><listitem><para>the site's table of contents, formatted for peripheric
areas of your web site.</para></listitem></varlistentry><varlistentry><term>toc
! </term><listitem><para>is automatically used with the toc GET parameter. You
probably would not have to use this block
otherwise.</para></listitem></varlistentry><varlistentry><term>xml
! </term><listitem><para>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.
</para></listitem></varlistentry></variablelist></sect2>
! </sect1>
<sect1><title>Administrator manual<anchor
id="Administrator-manual"></title><sect2><title>Installation</title><orderedlist><listitem><para>Once
you have the sitemgr directory inside your phpgroupware install you can setup
it like any other phpgroupware application with the setup program
(http://yourmachine/phpgw-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.</para><programlisting><![CDATA[cd sitemgr
]]><![CDATA[mv sitemgr-link ..
]]></programlisting><para>and then install sitemgr-link with
setup</para></listitem><listitem><para>Log in to phpGroupWare as an admin and
create an anonymous phpgw 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 phpGW users to the generated
site.</para></listitem><listitem><para>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 phpGW 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. </para></listitem><listitem><para>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/phpgroupware/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.</para></listitem><listitem><para>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</para><programlisting><![CDATA['phpgw_path'
=> '../../',
! ]]></programlisting><para>so that the value of
$sitemgr_info['phpgw_path'] is
'/path/to/phpgroupware/'</para></listitem><listitem><para>You're almost set to
go. Log in to phpGroupWare as an administrator. Make sure you gave yourself the
sitemgr and sitemgr-link applications so that you see them on your navbar. Go
to the sitemgr application and select "Configure SiteMgr". Fill in
“URL to sitemgr-site” and “Filesystem path to sitemgr-site
directory”, and the anonymous user's name and password. Then click on
save, and you should know select the template for your
site.</para></listitem><listitem><para>After installation sitemgr does not
immediately know about all available modules since those can be defined by
other applications. The setup routine only installs the modules html,index and
toc that every site will need. In order to register all availabe modules select
“Manage site-wide module properties” from the administrative menu,
and then follow the “Register new modules”
link.</para></listitem><listitem><para>That's it. Go to the Category manager,
add a category or three and check who can view and edit them, then go to the
page manager, add a page or three to each category, set up your site header,
site footer, etc., and go view your recently created site by clicking on the
sitemgr-link application. Voilà!</para></listitem></orderedlist></sect2>
<sect2><title>Maintenance</title><para>As a site administrator, you have
three privileges/responsibilies:</para><orderedlist><listitem><para>Define site
wide content blocks. These are edited in the same interface as category and
page specific blocks.</para></listitem><listitem><para>Choose permitted
modules: If you choose “Manage site-wide module properties” from
sitemgr's main menu, you will see several rows which all contain four elements:
a select box, a button labelled “Select allowed modules', another select
box and a button labelled “Configure module properties”. 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.
In the category manager, there is a button “Manage Modules”
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.
***************
*** 30,34 ****
The lists of permitted lists are never merged, if you define one list for a
given context, this list is used in this
context.</para></listitem><listitem><para>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 “Configure module
properties” 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.</para></listitem></orderedlist></sect2>
</sect1>
! <sect1><title>Template designer manual<anchor
id="Template-designer-manual"></title><para>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:</para><itemizedlist><listitem><para>The whole page template is now
stored in a file main.tpl in the template's
directory.</para></listitem><listitem><para>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.</para></listitem><listitem><para>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 necessarily 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.</para></listitem><listitem><para>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_admin.news' would go into a
subdirectory 'news_admin/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
“default/news_admin/news'.</para></listitem><listitem><para>You can
hardcode module calls into the template if your site should have the same
dynamic content on one specific place.</para></listitem></itemizedlist></sect1>
<sect1><title>Application developper manual<anchor
id="Application-developper-manual"></title><para>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
“Hello World”.</para><programlisting><![CDATA[<?php
]]><![CDATA[
--- 53,57 ----
The lists of permitted lists are never merged, if you define one list for a
given context, this list is used in this
context.</para></listitem><listitem><para>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 “Configure module
properties” 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.</para></listitem></orderedlist></sect2>
</sect1>
! <sect1><title>Template designer manual<anchor
id="Template-designer-manual"></title><para>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:</para><itemizedlist><listitem><para>The whole page template is now
stored in a file main.tpl in the template's
directory.</para></listitem><listitem><para>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.</para></listitem><listitem><para>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 necessarily 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<footnote><para>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.php and
left_bt.inc.php.</para></footnote>.</para></listitem><listitem><para>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_admin.news' would go into a subdirectory 'news_admin/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 “default/news_admin/news'.</para></listitem><listitem><para>You can
hardcode module calls into the template if your site should have the same
dynamic content on one specific place.</para></listitem></itemizedlist></sect1>
<sect1><title>Application developper manual<anchor
id="Application-developper-manual"></title><para>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
“Hello World”.</para><programlisting><![CDATA[<?php
]]><![CDATA[
***************
*** 52,56 ****
]]><![CDATA[ }
]]><![CDATA[}
! ]]></programlisting><para>Once your module is registered 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?</para><para>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:</para><variablelist><varlistentry><term>add_transformer($transformer)
</term><listitem><para>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:</para><variablelist><varlistentry><term>apply_transform($title,$content)
</term><listitem><para>A transformer that is not a block transformer should
normally ignore the title argument, and construct its return value from the
content
argument.</para></listitem></varlistentry></variablelist></listitem></varlistentry><varlistentry><term>set_block($block,$produce=False)
--- 75,79 ----
]]><![CDATA[ }
]]><![CDATA[}
! ]]></programlisting><para>Once your module is
registered<footnote><para>Modules should be stored in an application's inc
directory, and be named class.module_modulename.inc.php in order that sitemgr
can find them.</para></footnote> 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?</para><para>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:</para><variablelist><varlistentry><term>add_transformer($transformer)
</term><listitem><para>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:</para><variablelist><varlistentry><term>apply_transform($title,$content)
</term><listitem><para>A transformer that is not a block transformer should
normally ignore the title argument, and construct its return value from the
content
argument.</para></listitem></varlistentry></variablelist></listitem></varlistentry><varlistentry><term>set_block($block,$produce=False)
***************
*** 79,88 ****
]]><![CDATA[}
]]></programlisting><para>This would make sure that the module argument name
would always be
lowercase.</para></listitem></varlistentry><varlistentry><term>get_content(&$arguments,$properties)
! </term><listitem><para>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->cookie 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 do remain in a stable state while the user interacts with other modules
on the same page.</para><para>The variables you define in these arrays can be
identical to those in $this->arguments. 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 enumerating 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.</para><para>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 you use different modules on
the same page, that use the same variable names, you would not run into
problems. 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.</para><programlisting><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[class module_hello extends Module {
]]><![CDATA[ function module_hello()
]]><![CDATA[ {
- ]]><![CDATA[ $this->name = "hello";
]]><![CDATA[ $this->arguments = array(
]]><![CDATA[ 'name' => array(
--- 102,110 ----
]]><![CDATA[}
]]></programlisting><para>This would make sure that the module argument name
would always be
lowercase.</para></listitem></varlistentry><varlistentry><term>get_content(&$arguments,$properties)
! </term><listitem><para>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->cookie 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.</para><para>The variables you define in these arrays can be
identical to those in $this->arguments. 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 enumerating 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.</para><para>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.</para><programlisting><![CDATA[<?php
]]><![CDATA[
]]><![CDATA[class module_hello extends Module {
]]><![CDATA[ function module_hello()
]]><![CDATA[ {
]]><![CDATA[ $this->arguments = array(
]]><![CDATA[ 'name' => array(
***************
*** 116,120 ****
]]></programlisting></listitem></varlistentry><varlistentry><term>build_post_element($key,$default=False)
</term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>link($modulevars)
! </term><listitem><para>helps you construct URLS with GET parameters that use
the service described above. modulevars is an array of variable values keyed on
variable
names.</para></listitem></varlistentry><varlistentry><term>get_output($type='html')
</term><listitem><para>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.</para></listitem></varlistentry></variablelist><para>To summarize,
there are the following requirements for a sitemgr
module:</para><orderedlist><listitem><para>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 phpgroupware
application.</para></listitem><listitem><para>Its constructor should define the
following member variables:</para><orderedlist><listitem><para>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.</para></listitem><listitem><para>properties:
the module's properties the site administrator can edit in order to constrain
or configure the functionnality of the
module</para></listitem><listitem><para>title: The module's default title that
can be overriden for each content
block.</para></listitem><listitem><para>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).</para></listitem></orderedlist></listitem><listitem><para>It needs a
get_content function that has access to arguments and properties ans produces
the block content.</para></listitem><listitem><para>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</para></listitem><listitem><para>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.</para></listitem></orderedlist><para>These are the
building blocks which should allow for some flexibility in constructing modules
that make phpgroupware managed data visible on a sitemgr web
site.</para></sect1>
--- 138,143 ----
]]></programlisting></listitem></varlistentry><varlistentry><term>build_post_element($key,$default=False)
</term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>link($modulevars)
! </term><listitem><para>helps you construct URLS with GET parameters that use
the service described above. modulevars is an array of variable values keyed on
variable
names.</para></listitem></varlistentry><varlistentry><term>find_template_dir()
! </term><listitem><para>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.</para></listitem></varlistentry><varlistentry><term>get_output($type='html')
</term><listitem><para>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.</para></listitem></varlistentry></variablelist><para>To summarize,
there are the following requirements for a sitemgr
module:</para><orderedlist><listitem><para>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 phpgroupware
application.</para></listitem><listitem><para>Its constructor should define the
following member variables:</para><orderedlist><listitem><para>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.</para></listitem><listitem><para>properties:
the module's properties the site administrator can edit in order to constrain
or configure the functionnality of the
module</para></listitem><listitem><para>title: The module's default title that
can be overriden for each content
block.</para></listitem><listitem><para>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).</para></listitem></orderedlist></listitem><listitem><para>It needs a
get_content function that has access to arguments and properties ans produces
the block content.</para></listitem><listitem><para>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</para></listitem><listitem><para>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.</para></listitem></orderedlist><para>These are the
building blocks which should allow for some flexibility in constructing modules
that make phpgroupware managed data visible on a sitemgr web
site.</para></sect1>
Index: modules.txt
===================================================================
RCS file: /cvsroot/phpgroupware/sitemgr/doc/modules.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** modules.txt 18 Jan 2003 05:24:39 -0000 1.2
--- modules.txt 19 Jan 2003 01:10:02 -0000 1.3
***************
*** 40,45 ****
of the page or for specific modules. Templates contain
four kinds of variables. These are explained here since
! the types 2,3 and 4 and 5 can be used both in the
! template as in the page content a module generates.
1. {contentarea: areaname} These define where
--- 40,45 ----
of the page or for specific modules. Templates contain
four kinds of variables. These are explained here since
! the types 2,3 and 4 can be used both in the template as
! in the page content a module generates.
1. {contentarea: areaname} These define where
***************
*** 76,86 ****
{?phpgw:/addressbook,order=n_given&sort=ASC}.
! 4. {lang_translatable_string} This lets you make the
! template internationalized. The translatable string
! is sent through phpgroupware's lang function. Thus
! you can add it to the lang files in the setup
! directory and install it through the setup programm.
!
! 5. {variable} Finally there are some simple variables
you can use to retrieve metainformation about the
page or about the user's context:
--- 76,80 ----
{?phpgw:/addressbook,order=n_given&sort=ASC}.
! 4. {variable} Finally there are some simple variables
you can use to retrieve metainformation about the
page or about the user's context:
***************
*** 291,294 ****
--- 285,298 ----
content blocks that only the site administrator can create.
+ 2.1 Creating a new page
+
+ to be completed
+
+ 2.2 Editing page metadata
+
+ to be completed
+
+ 2.3 Editing page content
+
The interface for creating content blocks is the same
on each level of scope, besides that when editing
***************
*** 347,350 ****
--- 351,443 ----
need not necessarily be the case.
+ 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:
+
+ 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 phpgw users or adminstrators.
+
+ amazon shows ads for books on the Amazon website.
+ There is a comment in the modules source file about
+ how it works.
+
+ 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.
+
+ calendar produces a calendar where each days links to
+ phpgroupware's calendar application
+
+ currentsection produces an index of the pages in the
+ current section.
+
+ forum another demonstration of what sitemg's modules
+ are intended for: This module displays the
+ discussions of phpgroupware'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.
+
+ 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.
+
+ google displays a form for querying the google website.
+
+ hello a simple "Hello world" module used below in this manual.
+
+ 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.
+
+ index_block a index of the whole site, formatted for
+ peripheric areas of your web site.
+
+ index is automatically used with the index GET
+ parameter. You probably would not have to use this
+ block otherwise.
+
+ lang_block displays a select box for changing the
+ user's site language.
+
+ login displays a login block
+
+ news publishes news you edit with phpgroupware's
+ news_admin application. You can choose a category to display.
+
+ 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.
+
+ sitetree displays a tree like menu to the website.
+
+ toc_block the site's table of contents, formatted for
+ peripheric areas of your web site.
+
+ toc is automatically used with the toc GET parameter.
+ You probably would not have to use this block otherwise.
+
+ 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.
+
3 Administrator manual<Administrator-manual>
***************
*** 407,413 ****
and "Filesystem path to sitemgr-site directory", and
the anonymous user's name and password. Then click on
! save, and you should now select the template for your site.
! 7. That's it. Go to the Category manager, add a
category or three and check who can view and edit
them, then go to the page manager, add a page or
--- 500,516 ----
and "Filesystem path to sitemgr-site directory", and
the anonymous user's name and password. Then click on
! save, and you should know select the template for
! your site.
!
! 7. After installation sitemgr does not immediately know
! about all available modules since those can be
! defined by other applications. The setup routine only
! installs the modules html,index and toc that every
! site will need. In order to register all availabe
! modules select "Manage site-wide module properties"
! from the administrative menu, and then follow the "
! Register new modules" link.
! 8. That's it. Go to the Category manager, add a
category or three and check who can view and edit
them, then go to the page manager, add a page or
***************
*** 519,523 ****
transformations to the content, but this would
probably have counter-intuitive effects on your
! page's contributors.
* Other than that a template directory can contain
--- 622,634 ----
transformations to the content, but this would
probably have counter-intuitive effects on your
! page's contributorsFor 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.php and left_bt.inc.php.
! .
* Other than that a template directory can contain
***************
*** 592,601 ****
}
! Once your module is registered 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?
Now let's examine more in detail how the standard
--- 703,715 ----
}
! Once your module is registeredModules should be stored in an application's
inc
! directory, and be named class.module_modulename.inc.php
! in order that sitemgr can find them.
! 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?
Now let's examine more in detail how the standard
***************
*** 738,742 ****
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 do remain
in a stable state while the user interacts with other
modules on the same page.
--- 852,856 ----
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.
***************
*** 759,768 ****
could directly read HTTP variables. The advantage of
using it is that it provides a namespace for each
! module, so that if you use different modules on the
! same page, that use the same variable names, you
! would not run into problems. 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
--- 873,882 ----
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
***************
*** 783,788 ****
{
- $this->name = "hello";
-
$this->arguments = array(
--- 897,900 ----
***************
*** 859,862 ****
--- 971,981 ----
modulevars is an array of variable values keyed on
variable names.
+
+ 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.
get_output($type='html') This is the function that is
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Phpgroupware-cvs] CVS: sitemgr/doc modules.dvi,1.2,1.3 modules.html,1.2,1.3 modules.lyx,1.2,1.3 modules.pdf,1.2,1.3 modules.ps,1.2,1.3 modules.sgml,1.2,1.3 modules.txt,1.2,1.3,
Michael Totschnig <address@hidden> <=
- Prev by Date:
[Phpgroupware-cvs] CVS: sitemgr/sitemgr-site/inc class.Template3.inc.php,1.2,1.3
- Next by Date:
[Phpgroupware-cvs] CVS: sitemgr/inc class.module.inc.php,1.1,1.2 class.module_amazon.inc.php,1.1,1.2class.module_appdir.inc.php,1.2,1.3 class.module_calendar.inc.php,1.1,1.2class.module_forum.inc.php,1.2,1.3 class.module_news.inc.php,1.1,1.2
- Previous by thread:
[Phpgroupware-cvs] CVS: sitemgr/sitemgr-site/inc class.Template3.inc.php,1.2,1.3
- Next by thread:
[Phpgroupware-cvs] CVS: sitemgr/inc class.module.inc.php,1.1,1.2 class.module_amazon.inc.php,1.1,1.2class.module_appdir.inc.php,1.2,1.3 class.module_calendar.inc.php,1.1,1.2class.module_forum.inc.php,1.2,1.3 class.module_news.inc.php,1.1,1.2
- Index(es):