Documentation: overlays/overlay.php

class Overlay - The overlay interface used by articles

Overlays are a straightforward way to extend YACS content pages. For example, articles can be transformed to recipes, or to other pages that has to include some structured data.

Overlay data is saved along standard articles as a serialized snippet. The encoding and decoding of this field requires a specialized class.

The overlay interface masks these details and offers convenient methods to create, access and save piggy-back data.

As visible in articles/edit.php, the creation of a new overlay or the update of an existing one is achieved through following sequence:

// create a new overlay
$overlay = Overlay::bind($overlay_type);

// get form fields used to updated the overlay
$fields = $overlay->get_fields($item);

// get a label for some ordinary field
$label = $overlay->get_label('title', 'edit');

...

// process posted data
$overlay->parse_fields($_POST);

// save article and serialized overlay as well
$_POST['overlay'] = $overlay->save();
$_POST['overlay_id'] = $overlay->get_id();
Articles::post($_POST);

// save overlay state
$overlay->remember('insert', $item);

As visible into articles/view.php, an overlay is handled with following calls:

// extract overlay data from a record
$overlay = Overlay::load($item);

// get text related to this instance
$text = $overlay->get_text('view');

// get additional tabs
$text = $overlay->get_tabs('view');

Also, post-processing steps can include the removal of the hosting record, as shown in articles/delete.php

// extract overlay data from a record
$overlay = Overlay::load($item);

// post-processing steps specific to the overlay
$overlay->remember('delete', $item);

As a consequence, this class has two constructors:

bind() -- create an instance from scratch
load() -- create an instance from one article of the database

The interface itself is made of following member functions, that have to be overloaded into child functions:

allows() -- re-enforce access rights
get_extra_text() -- to be integrated into page side
get_fields() -- build a form to modify overlay content
get_id() -- to retrieve an overlay
get_label() -- specialize the overlaid page
get_list_text() -- to be integrated into a list of items
get_live_introduction() -- change page introduction
get_live_title() -- change page title
get_tabs() -- add information in panels
get_text() -- use overlay data in normal pages
get_trailer_text() -- to be appended after the description
get_type() -- basic information
get_view_text() -- to be integrated into the main page, between introduction and description
parse_fields() -- capture form content
render() -- delegate rendering to the overlay
remember() -- for specific post-processing steps

Following functions are aiming to simplify external calls:

export() -- to generate some XML
save() -- to serialize overlay content

This script is a reference file of this system.

License: GNU Lesser General Public License

Authors:

Bernard Paques
GnapZ

Testers:

Neige1963

overlays/overlay.php - Attributes specific to this overlay

allows() - Allow or block operations

function allows($type, $action)

$type - string the kind of item to handle ('decision', ...)
$action - string the foreseen operation ('edit', 'new', ...)
returns TRUE if the operation is accepted, FALSE otherwise

bind() - Create a new overlay from scratch

function bind($type)

$type - string overlay type
returns a brand new instance

This function creates an instance of the Overlay class based on the given type. For the type 'foo', the script file 'overlays/foo.php' is loaded.

Example:

// create a new overlay
$overlay = Overlay::bind('recipe');

The provided string may include parameters after the type. These parameters, if any, are saved along overlay attributes.

Example:

// this overlay will preserve past events
$overlay = Overlay::bind('day without_past_dates');

See also:

export() - Export an overlay as XML

function export()

returns some XML to be inserted into the resulting page

get_extra_text() - Text to be inserted aside

function &get_extra_text($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

get_fields() - Build the list of fields for one overlay

function get_fields($host)

$host - the hosting attributes
returns a list of ($label, $input, $hint)

This function is used to create forms aiming to change overlay data. To be overloaded into derivated class.

See also:

articles/edit.php

get_id() - Identify one instance

function get_id()

This function returns a string that identify uniquely one overlay instance. When this information is saved, it can be used later on to retrieve one page and its content.

@returns a unique string, or NULL

See also:

articles/edit.php

get_label() - Get an overlaid label

function get_label($name, $action='view')

$name - string the target label
$action='view' - string the on-going action
returns the label to use, or NULL if no default label has been found

This function changes strings used to describe an overlaid item.

Accepted action codes:

'edit' modification of an existing object
'delete' deletion form
'new' creation of a new object
'view' rendering of the object

To be overloaded into derivated class

See also:

get_list_text() - Display the content of one overlay in a list

function &get_list_text($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

get_live_introduction() - Display a live introduction

function &get_live_introduction($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

get_live_title() - Display a live title

function &get_live_title($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

get_tabs() - Add some tabbed panels

function &get_tabs($variant='view', $host=NULL)

$variant='view' - string the on-going action
$host=NULL - array the hosting record
returns an array of array('tab_id', 'tab_label', 'panel_id', 'panel_content') or NULL

Display additional information in panels.

Accepted action codes:

'view' - embedded into the main viewing page
'edit' - embedded into the main form page

See also:

overlays/overlay.php

get_text() - Display the content of one overlay

function &get_text($variant='view', $host=NULL)

$variant='view' - string the variant code
$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

Accepted variant codes:

'extra' - displayed aside
'introduction' - as a live introduction
'list' - part of a list
'title' - as a live title
'trailer' - displayed at the bottom
'view' - in the main viewing panel

To be overloaded into derivated class

get_trailer_text() - Text to come after page description

function &get_trailer_text($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

get_type() - Retrieve overlay type

function get_type()

@returns string

See also:

articles/edit.php

get_view_text() - Display the content of one overlay in main view panel

function &get_view_text($host=NULL)

$host=NULL - array the hosting record, if any
returns some HTML to be inserted into the resulting page

To be overloaded into derivated class

load() - Restore an instance

function load($host, $name='overlay')

$host - array the hosting array
$name='overlay' - string the attribute which contains overlay data
returns a restored instance, or NULL

This function unserializes piggy-back data and uses it to populate an overlay instance.

// get the record from the database
$item =& Articles::get($id);

// extract overlay data from $item['overlay']
$overlay = Overlay::load($item);

See also:

parse_fields() - Capture form content

function parse_fields($fields)

$fields - array data transmitted to the server through a web form

This function is used to actually change some overlay data.

To be overloaded into derivated class.

See also:

articles/edit.php

render() - Render some page component

function render($type, $reference, $page=1)

$type - string type of component to render, e.g., 'articles'
$reference - string anchor reference, such as 'section:123'
$page=1 - int page
returns mixed some text, or NULL

See also:

articles/view.php

remember() - Remember an action once it's done

function remember($variant, $host)

$variant - string the action 'insert', 'update' or 'delete'
$host - array the hosting record
returns FALSE on error, TRUE otherwise

This function enables a cascaded synchronization with some external storage facility. For example, a secondary table can be created in the database to derive information from some overlay instance.

To be overloaded into derivated class

See also:

save() - Serialize overlay content

function save()

returns the serialized string

See also:

articles/edit.php

Browse the source of this script · Server software