Catviz Manual

Joost Horward


Table of Contents

Introduction
Credits
Overview
Installing Catviz
Requirements
Installation
Using Catviz
The control panel
The Module Manager
The User Administrator
The News List Administrator
The Approval Administrator
The Webpages Administrator
The Menu Administrator
Understanding Catviz
Architecture
Execution flow
Calling a form
Database
Security
The Template System
Writing a Catviz module
File structure of a module
Coding Standard
Coding the module
Modules in the Catviz package
The Webpages module

Introduction

Welcome to catviz. I am very excited about this release, and I hope you like it. I would really like to receive feedback. Please leave a message at www.catviz.org. You can email me at <joost@catviz.org>

This is the Catviz administrator and developer documentation. The class library is documented by phpdoc (www.phpdoc.org). The result is available here

Credits

The TDateField uses Mihai Bazon's excellent JavaScript DHTML pop-up calendar (from students.infoiasi.ro/~mishoo/site/calendar.epl).

The penguin icon graphics in the Aqua team are the excellent work of Everaldo Coelho (www.everaldo.com)

The Treeview Javascript is a package called dTree which is the excellent work of Geir Landrö (www.destroydrop.com/javascript/tree/)

Although Catviz is a newly built content manager phpWebSite has been an inspiration in many ways. Without my previous experience with phpWebSite Catviz would not be what it is today.

Overview

Catviz is a PHP/MySQL based content manager. Its primary aim is to provide a rich platform for the development of interactive websites.

It is very different from any other PHP/MySQL content manager because of the following features:

  • Clean approach, built from the ground up.

  • Full Object-Oriented approach. Each module is represented by a class (derived from a module skeleton class). Each module contains form objects, which in turn contain field objects etc. The high level of reuseability that results from this approach shows in the small amount of lines needed to code indidivual modules.

  • Full API documentation, created using Docbook and phpdoc.

  • Consistent user interface thanks to the OOP approach mentioned above.

  • Database entry integration. Classes are provided for everything you need to allow database data entry.

  • Fully integrated security/access control management. Since this is completely embedded in the forms system it needs very little attention from the module author. Access is granted to users and groups on a per-functionality and per-document basis, using Access Classes and Document Classes.

  • Site Search facility

  • Centralized Approval facility

  • Very flexible templating system, which integrates nicely with the form classes.

  • Automated form tracking (the form stack) for navigation purposes.

The functionality currently available is:

  • Class library

  • Module manager

  • Menu manager

  • User manager

  • News

  • Site Search

  • Approval

  • Phonebook

  • Static web pages with tree index

Installing Catviz

Installation is pretty straightforward. All settings are in conf/config.php. Check all settings in this filer and point your browser at [yoursite]/install/install.php. Check the settings shown click to continue.

Catviz is now installed. One user account is created admin with password catviz. Change the password NOW.

Requirements

Catviz is developed on a RedHat 8 system with Apache 2.0.40, PHP 4.2.2 and MySQL 3.23.52. I would recommend to switch register_globals off for security's sake. There are no external requirements.

Installation

Installation is pretty straightforward. All settings are in conf/config.php. Check all settings in this file and point your browser at [yoursite]/install/install.php. This creates the database for you. Make sure the var/ tree is writeable by the web server (e.g. the 'apache' or 'http' user)

Using Catviz

Catviz has one interface which is shared by all users. Extra features appear in the menus depending on your rights. Typically, after logging in you will see a menu like this:

The control panel

The control panel gives access to the administrative functions of each module. A subset of modules may show up depending on your access rights. A typical one is shown below:

The Module Manager

The module manager allows switching modules on and off, as well as installing new modules. The Module Priority allows you to determine the order in which module is loaded/instantiated. The module manager needs to be the first one - The menu module needs to be loaded after all the modules it refers to are loaded. Each module has a set of Access Classes which are used for the security system.

The User Administrator

Each user has to be entered through this interface, there is no self-signup procedure yet. Each user is automatically a member of 'Everyone' (once logged in), you don't need to make users a member explicitly. The user administrator is also used to define document classes., see the security section below. Each module defines a set of access classes. The ones that are curently present are:

Table 1. Acess Classes overview per module

Moduleuser (modulename_user)admin (modulename_admin)
Module ManagerShow controlpanelAdd/remove/modify modules
User Admin-Add/remove/modify users
NewsSubmit new articleApprove, edit,delete,create articles
ApprovalApproval listApproval list
WebpageCreate root webpageAdd/remove/modify webpages
Menu-Add/remove/modify menu items
PhonebookShow phonebookAdd/remove/modify phonebook items
SearchN/AN/A

The News List Administrator

This simply shows a full list of news articles, regardless of their status, allowing the News admin to edit ore delete them.

The Approval Administrator

The approval administrator collects items to be approved from all modules, and shows the resulting overview. Click on each item to show a form which allows the content to be approved or rejected. This form is different per module as each module delivers it's own inerface.

The Webpages Administrator

The webpages administrator shows a full list of the webpages, allowing the webpages admin to edit or delete them. Alternatively, you may use the edit icon whis is shown in the title bar of the webpage when you have edit rights on the page shown. You can prepare a webpage offline and paste it in here. When you are using images, put them in the same directory as your HTML document and upload them (in the file list). The filenames will be automatically corrected in your webpage to show up correctly in Catviz.

The Menu Administrator

The module administrator shows a list of menu items. You can add/edit/remove these items. Some items are not shown by default but activated by the corresponding module. When your menu item points at a form, Catviz checks if you have the appropriate rights, and does not show the menu item if this is not the case.

Understanding Catviz

Architecture

Catviz consists of a class library (catviz_lib.php), a small core module controller (index.php), a set of modules which provide the standard functionality, and a set of templates. Each module is represented by a class that is a descendant of TModule. Each module contains forms (TForm descendants) and fields (TField descendants).

The content of each form is mapped on a content variable. A template determines where each content variable is placed on the generated page.

Execution flow

When a connection is made to a Catviz server the first time, a session is created (Catviz-Content-Manager). The session store contains a formstack, the catviz_info object and a an array of module objects. In each module the 'static' forms are created and each 'static' form is instantiated as an object in the module object (this is repeated each time a user logs in our out). Then, the action method of each module is called, and finally the layout manager creates the page to be shown. Most forms are generated on the fly to speed up the initial connection and to minimize the session store space usage.

Calling a form

Each form is uniquely identified by the combination of modulename and formname. Each form has a number of actions it can perform, such as 'edit', 'show', 'submit'. To show a particular form the following parameters are needed:

Table 2. 

ParameterDescription
moduleThe name of the module
[modulename]_opThe operation, usually 'form'
form_nameThe name of the form
form_actionThe action (edit, show, submit,...)
foreign_key_valueForeign key (database forms only)

Database

The database ineraction requires a few things in the database design. A unique identifier is needed for each row in each table, and that identifier needs to be numeric and auto incrementing. The name is something_id (that'st not a system requirement but a naming convention). Foreign keys in tables need to be named after their keyfields in the master table for the master/details views to operate properly.

Tables for modules are named mod_modulename_... toa avoid collisions of tablenames between modules.

Security

The security system consists of 3 parts: the user manager, the forms access control and the data access control.

The user manager

The usermanager is responsibe for usernames, login, groups, & encrypted passwords A user can be member of any number or more groups. Each user gets a number of access controls assigned which determine the access to the forms. You can think of an access control as an abstract user group such as news admin, news user etc.

The forms access control system

The forms access control system consists of a list of access controls which is attached to each form. These controls have flags (read/write) that determine which type of access is granted to the owner of that control. For example, a news approval form would have news_admin read/write and news_user read only set. Why this complication and why not assigned form rights to user groups straightaway? you might ask. The reason is simple,. if I would do that I would dictate how user groups are used, and the system would quickly become cumbersome to use. Now, you set up the groups the way that is most appropriate for your web/inranetsite and organization and after that assign users to organisational groups.

The document access control system

The document access control system is similar to the forms access control. Each document (a web page, a news article) has a document class assigned. A document class is an abstraction for a group of documents that share a common set of access characteristics. Possible Document classes are "Product specification", "Software Development Internal", "Commercial", "HR Public", "HR Internal" etc. etc.

Each user or user group gets document classes assigned along with access rights read and write.

This way, determining access rights for a document is a one-step process so a document author does not need to consider organisational impact - that is done per document class.

When a user logs in the total set of document classes to which the user has accessed is determined (from the user and group rights) and this information is kept in the session store for fast reference.

A standard document class 'Public' is available read-only to every user (even anonymous). Write access to the 'Public' document class has to be set in the user manager.

The Template System

The templating system is integrated with the forms, so variables do not have to be translated and even form methods can be called from the templates. Each template is divided into sections. Each section is separated by special formatted HTML comments, to allow any HTML editor to edit the templates without a problem. Sections start with <--&sectionname--> and end with <--/sectionname-->. Each section is processed in a sequence determined by the form code. So even when you have foorter before header for example, header still comes out first. HTML outside the section markers is not used at all. You can add HTML outside the tags if that helps to keep your HTML editor happy. Inside each section form elements are placed using curly brackets around fieldnames, like:{fieldname}. Methods of the form class and variables in the form object can be called using {!functionname()} or {!variablename} These are evaluated as the form is generated. The form definition file is read at form creation time, split into sections and stored in the session store. This way re-interpretation is prevented. As a consequence, When you change a template it will only take effect when the forms are re-initialized (log in as other user, drop session). There are 3 levels of templates: the page template, the box template and the form template.

Page Template

The page template is an odd one, it holds the template for the page. in curly brackets are the content variable names rather than the fieldnames. There are no zones. The page template is called page_template.html and is searched for in the following locations:

themes/[themename]/mod/[modulename]/templates/page_template.html

themes/[themename]/templates/page_template.html

The first one found is used. This mechanism allows each module to have its own page layout when the module has focus.

Box Template

The box template determines the looks of each box (the table surrounding each form). It has three sections: header,body and footer. The default box uses the following tags to obtain information from the form:

Table 3. 

{!getNavBar()}gets the content of the navigation bar icons (back, home)
{!getActionBar()}gets the content of the navigation bar icons (new etc.)
{!title}gets the form title
{!prologue}gets the value of $this->prologue;
{!content}gets the value of $this->content e.g. the form content
{!epilogue}gets the value of $this->epilogue;

The box template is searched for in the following locations:

themes/[themename]/mod/[modulename]/templates/[formname].html themes/[themename]/templates/box-layout.html This allows individual forms to be independently redesigned.

Form Templates

Form templates determine the look of the form (inside of the box). Form templates are searched for in the following locations:

themes/[themename]/mod/[modulename]/templates/[formname].html

mod/[modulename]/templates/[formname].html

The Security System The security system consists of 3 parts: the user manager, the forms access control and the data access control.

Writing a Catviz module

File structure of a module

Each module lives in a subdirctory under /mod. The following subdirectories are present:

php

Holds all the files with the actual PHP code

doc

Holds the documentation for the module

img

Holds any module-specific image files. Most image files live with the theme or in the var area

conf

Holds the confuiguration file config.php

templates

Holds all the module specific templates

Coding Standard

The coding standard used is the standard described in the PEAR documentation with a few additions.

Indents are 4 spaces wide.

Class names are of the form T[Name]. Module class names have the form MOD_[Name]

Instances of modules (module objects) are named mod_[name]

Class names always start with a capital letter.

Class methods and functions are named using the 'camel' convention, e.g. lowercaseCapitalizedCapitalized.

Attribute names are all lowercase with underscores where needed.

Documentation is generated using PHPDocumentor (phpdoc.org). A small reminder for myself what command line is needed: php phpdoc -t [targetdir] -o HTML:Smarty:default -d [classdir]

Coding the module

The main code lives in php/MOD_[modulename].

TModule

TModule is the baseclass that you can use to derive your module from.

class MOD_mymodule extends TModule{
var ...

/**
* Constructor for the MyModule class
*
*/
function MOD_mymodule(){
TModule::TModule("mymodule");

}

function initializeForms(){
Tmodule::InitializeForms();
.
.
.
}

function initializeForm($formname){
switch ($formname){
/**
* Create the Webpage edit form
*/
case 'webpage_edit':
.
.
}
}

Add forms in initialzeForms and/or initializeForm. It is important to understand the difference between the two:

InitializeForms is called when a new session is started and whenever a new user logs in or out.

IntializeForm($formname) is called when a form is not found in the module.

You should always use initializeForm unless you have good reasons not to. initializeForm helps to create forms just-in-time and keep the initial connection time short, keeps the memory requirements low and the session size small. Initializing forms up front in initializeForm only makes sense for 'static' forms - usually blocks that are always shown - such as the main menu.

This means that it is safe to determine user rights here and allow/disallow form access/creation based on that. But any code you put here is never re-exectuted in a sesion, so this code should not attempt to respond to any user input.

TForm

Creation of a database form with handler for submitting can be as simple as:

$thefields=array("first_name","last_name","address","phonenumber");
$this->forms["edit_addressbook_entry"]=
&new TDBEditForm("addresbook","edit_addressbook_info",$thefields,"mod_addressbook","","address_id");
TModule just holds an array of instantiated forms. Each form has a name, and methods that provide edit, submit etc. functionality. TModule just binds them together, and provides little functionality itself. The Action function is called by Catviz. There are virtual functions before_action and after_action provided. In particular after_action is handy, it's a good place to create a custom block if you need one. If the action is 'form', TModule will look at form_name and form_action and call the appropriate form. Each form 'knows' the content variable for which it is creating content. Like TModule, TForm and it's descendants have an Action method which acts as a message/command dispatcher. All form objects are created before usage. They are contained in the session, so variables in the forms are persistant throughout a session.

Modules in the Catviz package

The Webpages module

The webpages module provides a mechanism for maintaining and displaying webpages and blocks. Pages are structured in a tree structure which is visualised by a DHTML/Javascript tree (using dTree by Geir Landro). The structure is created with a multi-admin and multi-usergroup scenario in mind. Typically, this is used in an Intranet environment where various persons/departments manage their own part of the site.

In normal view, the tree shows all pages which are 'active' (flag in mod_webpages) and which have a document_class for which you have read rights.

For someone who has webpages_user rights all inactive pages show as well. A webpages_user is in fact a webpage author. He can only create pages with a document_class for which he has write rights. The parent page can only be a page of a class for which he has write rights. Sounds complicated? It simply comes down to the authors administering their own tree.

Users with webpages_admin rights can create root entries.