[Sommaire] [Imprimer]

   1  SiteMgr "Hooks" Requirements
   2  ----------------------------
   3  
   4  Introduction
   5  ------------
   6      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.
   7  
   8  Existing System
   9  ---------------
  10      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.
  11      
  12  Actors
  13  ------
  14      The full requirements document for SiteMgr specifies three "Actors."  See the main requirements document for details.  Briefly:
  15  
  16      Viewer: Someone who is viewing the generated web site.  This person could be an anonymous user or a logged-in user.
  17  
  18      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.
  19  
  20      Administrator: Someone with full administrative permissions in eGroupWare.  This is the person who creates and edits categories and determines who has what permissions.
  21  
  22  Viewer Requirements
  23  -------------------
  24      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.
  25  
  26  Contributor Requirements
  27  ------------------------
  28      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.  
  29  
  30      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.
  31  
  32  Administrator Requirements
  33  --------------------------
  34      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.
  35  
  36  phpGW App Developer Requirements
  37  --------------------------------
  38      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.
  39  
  40      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.
  41  
  42      And that's it.  
  43  
  44  Clarifications from the mailing list
  45  ------------------------------------
  46      Modules will not be using the {?hook=...} syntax.  I could perhaps
  47  enable something like that as a poweruser alternative, but probably won't.
  48  The Contributor, ie the person who is allowed to edit the page, will have a
  49  list of modules he/she can add to a page.  So in the page editor the page
  50  contents would be shown as a list of modules, like so:
  51  
  52  -------
  53  Page Name: _________________
  54  Page Title: ________________
  55  Page Subtitle: _____________
  56  -------
  57  Module1     [properties] [remove]           [move down]
  58  Module2     [properties] [remove] [move up] [move down]
  59  TextModule  [properties] [remove] [move up] [move down]
  60  HTMLModule  [properties] [remove] [move up] [move down]
  61  Module1     [properties] [remove] [move up]
  62  
  63  [add module] [preview page]
  64  -------
  65  [finished]
  66  -------
  67  
  68      So each module would have a properties page where content would be
  69  entered or parameters specified or whatever.
  70  
  71      Is this clearer?  The TextModule would have a properties sheet that
  72  looked like the existing page editor, minus the page title stuff.  Please
  73  pass this on to Michael.  I will try to add this to the requirements doc to
  74  make it clearer.
  75  
  76  =======
  77  
  78     OK, I don't have an interface worked up just yet, but you can get started
  79  anyway.  The interface will be pretty straight forward.  You will need to
  80  create a file with a single class in it.  Later I will let you know what to
  81  name the class and the file and how to get them listed as a module (by
  82  registering the hook).  The class will need to have a couple of functions.
  83  One of them will be moduleName(), another will be propertiesList(), and
  84  finally and most importantly there will be moduleOutput($properties).
  85  
  86  Nevermind the first two for now.  The moduleOutput function will take an
  87  array of properties and values of those properties.  In the case of the
  88  forums app the properties might be what forum to display, whether or not to
  89  show the index, show a particular message, how many to show, nested... Etc.
  90  For now, just make sure you know what the property names and possible values
  91  are.  This information will be retrieved by SiteMgr via the propertiesList()
  92  function. 
  93  
  94  The moduleOutput function will return an array.  The array that is
  95  returned will depend on the output type.  I would prefer to return a class
  96  object, but for now just write your class and have it return an array.  The
  97  array must have a 'displayType' element that takes one of the following
  98  values.  The rest of the array elements will be dictated by this one value.
  99  
 100  displayType == 'basic'
 101  content //standard html
 102  DisplayType == 'block' // standard html in a box
 103  title
 104  content
 105  displayType == 'article'
 106  title
 107  subtitle
 108  status
 109  submitted-by
 110  submitted-date
 111  
 112  And there may be more in the future.
 113  
 114  That's all that is needed to create a module...
 115