HOME

5h-3LL 1.0
DIR: /srv/http/vyvoj.adent.cz/egroupware/pfi/sitemgr/doc
/srv/http/vyvoj.adent.cz/egroupware/pfi/sitemgr/doc/
Current File : /srv/http/vyvoj.adent.cz/egroupware/pfi/sitemgr/doc/hooks-requirements.txt
SiteMgr "Hooks" Requirements
----------------------------

Introduction
------------
	SiteMgr was created to allow a community of people to maintain a website so that different people or groups have permissions to read or edit different parts of a site.  There's an almost limitless list of potential features that could be added to make the program better and more useful.  I can't begin to work on such a daunting list of features.  So instead, I'll create a system that allows for "plugins" of some sort.

Existing System
---------------
	The current system allows for categories with pages.  Each page has a title, subtitle, and content.  The content is whatever HTML people want to put in.
	
Actors
------
	The full requirements document for SiteMgr specifies three "Actors."  See the main requirements document for details.  Briefly:

	Viewer: Someone who is viewing the generated web site.  This person could be an anonymous user or a logged-in user.

	Contributor: Someone who is logged in and has been granted "write" permissions to one or more site categories so that they can add, remove, and edit pages within those categories via the eGroupWare SiteMgr program.

	Administrator: Someone with full administrative permissions in eGroupWare.  This is the person who creates and edits categories and determines who has what permissions.

Viewer Requirements
-------------------
	From the viewer perspective the site will be much the same, though perhaps more useful and more dynamic.  That might include polls, news blurbs, articles, downloads, statistics, etc.

Contributor Requirements
------------------------
	From the perspective of the contributor, when editing a page there should be a chance to do more than just add html.  In fact, there should be a list of "modules" including an HTML module that functions like the old system.  On any given page one or more of these modules can be displayed.  If the contributor wants the page to have a news module, followed by an HTML module, followed by another news modules and yet another HTML module... fine.  

	For each module that the contributor elects to add to a page the contributor can specify the order of the modules and properties for each module.  There is a separate properties page for each module and the properties page is specific to the module itself.  The properties page of the HTML module, for example, would have a text box that the contributor would use to enter HTML.

Administrator Requirements
--------------------------
	The administrator needs to be able to specify, for each category, which modules are allowed for that category.  Furthermore, for each module of each category the Administrator can restrict the available options on the properties sheet.  For example, a news module may have different news topics.  The administrator might only allow contributors to display news from a particular topic within a particular category.  Or perhaps a shortened list of topics or something.

phpGW App Developer Requirements
--------------------------------
	eGroupWare application developers should be able to turn their applications, or subsets of their applications, into modules.  Making a module should be as easy as possible and should be done by way of the eGroupWare "hooks" system.  One application can make as many hooks as desired.  Each hook translates into a module.  The developer creates an array of properties that will be shown on the properties page.  Each property will have a name, description, input type (option box, etc.), input list, and whether or not it can be constrained by an administrator.  Then there will be a function that is called for the hook.  It will be passed that preference array with the values selected by the contributor.  It will return a display class.

	The display class will take a number of forms.  There will be a display type that specifies how the module will be formatted.  For example, there can be no formatting, news-block formatting, standard center block formatting, and so forth.  There will always be a content property filled out.  Depending on the format, there may be a title, subtitle, status, submitted-by, submitted-date, and other properties as well.

	And that's it.  

Clarifications from the mailing list
------------------------------------
    Modules will not be using the {?hook=...} syntax.  I could perhaps
enable something like that as a poweruser alternative, but probably won't.
The Contributor, ie the person who is allowed to edit the page, will have a
list of modules he/she can add to a page.  So in the page editor the page
contents would be shown as a list of modules, like so:

-------
Page Name: _________________
Page Title: ________________
Page Subtitle: _____________
-------
Module1     [properties] [remove]           [move down]
Module2     [properties] [remove] [move up] [move down]
TextModule  [properties] [remove] [move up] [move down]
HTMLModule  [properties] [remove] [move up] [move down]
Module1     [properties] [remove] [move up]

[add module] [preview page]
-------
[finished]
-------

	So each module would have a properties page where content would be
entered or parameters specified or whatever.

	Is this clearer?  The TextModule would have a properties sheet that
looked like the existing page editor, minus the page title stuff.  Please
pass this on to Michael.  I will try to add this to the requirements doc to
make it clearer.

=======

   OK, I don't have an interface worked up just yet, but you can get started
anyway.  The interface will be pretty straight forward.  You will need to
create a file with a single class in it.  Later I will let you know what to
name the class and the file and how to get them listed as a module (by
registering the hook).  The class will need to have a couple of functions.
One of them will be moduleName(), another will be propertiesList(), and
finally and most importantly there will be moduleOutput($properties).

Nevermind the first two for now.  The moduleOutput function will take an
array of properties and values of those properties.  In the case of the
forums app the properties might be what forum to display, whether or not to
show the index, show a particular message, how many to show, nested... Etc.
For now, just make sure you know what the property names and possible values
are.  This information will be retrieved by SiteMgr via the propertiesList()
function. 

The moduleOutput function will return an array.  The array that is
returned will depend on the output type.  I would prefer to return a class
object, but for now just write your class and have it return an array.  The
array must have a 'displayType' element that takes one of the following
values.  The rest of the array elements will be dictated by this one value.

displayType == 'basic'
content //standard html
DisplayType == 'block' // standard html in a box
title
content
displayType == 'article'
title
subtitle
status
submitted-by
submitted-date

And there may be more in the future.

That's all that is needed to create a module...