Documentation: shared/anchor.php

class Anchor - The anchor interface used by a related item

Anchors are used throughout this server to loosely link related items of information. For example, articles can be linked to sections. Threads of messages can be linked to articles, sections or categories, etc.

An anchor is simply encoded as a type followed by an id. For example, putting 'section:23' in the anchor field of an article means that this article is tied to the section with the id 23.

To retrieve items related to one anchor, you will have to query the database with specific SELECT statement. Usually, well-written scripts will provide a function to do that.

For example, in a page showing the section content, you will retrieve the first 30 articles related to this section with following code:

include 'articles/articles.php';
$rows = Articles::select_related_by_title('section:'.$id, 0, 30);
$context['text'] .= Skin::build_list($rows, 'compact');

To retrieve anchor information linked to one item, things are a little bit more complicated. You would like to link threads to sections (to build a bulletin board), to articles (to let people react on published pages) or to categories (to build dedicated bulletin boards). But at the same time, you would like to have a consistent interface to retrieve information from sections, articles, or categories. The Anchor class defined here is aiming to define a standard interface to related items that want to display context information coming from various sources.

Webmasters can expand the get_anchor() function defined in shared/global.php to ease the integration of new anchors in their system.

The Anchor class defines following member functions that can be used in scripts related to linked items:

get_behaviors() -- to build the stack of all behaviors
get_bullet_url() -- to reuse bullets set for anchors in sub-items
get_focus() -- to retrieve the contextual path in content tree
get_handle() -- to control access to protected resources
get_icon_url() -- to reuse icons set for anchors in sub-items
get_label() -- to adapt attached items to anchor's context
get_neighbours() -- to locate next and previous items, if any
get_overlay() -- to apply a default overlay option
get_path_bar() -- to build a path bar linked to the anchor
get_prefix() -- to insert text from the anchor, if any
get_reference() -- to put 'article:12' or 'section:45' in the database
get_suffix() -- to insert additional text from the anchor, if any
get_teaser() -- to put comments in context
get_thumbnail_url() -- to reuse thumbnails set for anchors in sub-items
get_title() -- to reuse the anchor title
get_url() -- to get the address of the viewing page for the anchor
get_value() -- to fetch the value of one attribute
has_option() -- to cascade options from an anchor to related items
is_editable() -- to cascade rights from an anchor to related items
is_public() -- to prevent actions on restricted sections
is_viewable()
touch() -- to reflect changes in the anchor

For example, suppose you are in a page that displays the full content of one thread of messages. If this thread is linked to an article, you would like to embed in your page useful information coming from this article.

// get an anchor (an article, a section, etc.)
$anchor = get_anchor('article:123');

// show the path bar
$context['path_bar'] = array_merge($context['path_bar'], $anchor->get_path_bar());

// use the title of the anchor as the title for this page
$context['page_title'] = $anchor->get_title();

// link this page to the anchor
$context['text'] .= '<a href="'.$anchor->get_url().'">'.i18n::s('Back').'</a>';

// display the anchor icon, if any
if($icon = $anchor->get_icon_url())
 $context['text'] .= '<img src="'.$icon.'" alt="" />';

// use text from the anchor to better introduce the thread
$context['text'] .= $anchor->get_prefix('thread');

// the surfer may edit this item if he/she is an editor of the section
if($anchor->is_editable()) {
 ...
}

// adapt the layout depending on anchor options
if($anchor->has_option('with_thread_alternate_layout')) {
 ...
} else {
 ...
}

// use text from the anchor for the bottom of the page
$context['text'] .= $anchor->get_suffix('thread');

// reflect the thread update in the anchor
$anchor->touch('thread:update');

To dig into details you should probably check following implementations of the Anchor interface:

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

get_behaviors() - Get behaviors for this anchor, and for parent anchors

function get_behaviors()

returns a string containing behaviors of this item, and of parent items

This function is used to compile the entire list of behaviors started to the current anchor.

This function uses the cache to save on database requests.

get_bullet_url() - Get the url to load the bullet icon set for the anchor

function get_bullet_url()

returns a valid url to be used in an

tag

A common concern of modern webmaster is to apply a reduced set of icons throughout all pages. This function is aiming to retrieve the bullet image characterizing one anchor. To be overloaded into derivated class

get_editors() - Get the list of editors for this anchor

function get_editors()

returns NULL, of the editors string

This function is used to transmit the list of editors from an anchor to another one. For example, if someone has been allowed to edit some section, it will appear as a valid editor of any article created in this section.

get_focus() - Get the focus for this anchor

function get_focus()

returns array of anchor references (e.g., array('section:123', 'article:456') )

This function lists containers of the content tree, from top level down to this item.

get_handle() - Get the handle of this anchor

function get_handle()

returns a secret handle, or NULL

The goal is to support direct access to some protected resource. One example of this situation is a web form sent by mail. In this case, the surfer has not been authenticated to the form, but if the handle is provided he will be granted access to it.

Voir aussi:

actions/accept.php

get_icon_url() - Get the url to load the icon set for the anchor

function get_icon_url()

returns a valid url to be used in an

tag

A common concern of modern webmaster is to apply a reduced set of icons throughout all pages. This function is aiming to retrieve the full-size icon characterizing one anchor. It should be used in pages to display one single image near the top of the page.

For example, if you are displaying a thread related to an article, you can display at the top of the page the article icon with the following code:

$anchor = get_anchor($thread['anchor']);
if($icon = $anchor->get_icon_url())
 $context['text'] .= '<img src="'.$icon.'" alt="" />';

To be overloaded into derivated class

get_label() - Provide a custom label

function get_label($variant, $id, $title='')

$variant - string the module that is invoking the anchor (e.g., 'comment')
$id - string the target label (e.g., 'edit_title', 'item_name', 'item_names')
$title='' - string an optional title, if any
returns string the foreseen label

get_neighbours() - Get data related to next and previous items, if any

function get_neighbours($type, $item)

$type - string the item type (eg, 'image', 'file', etc.)
$item - array the anchored item asking for neighbours
returns an array (previous_url, previous_label, next_url, next_label, option_url, option_label)

This function is used to add navigation links to pages.

In most cases, its result is passed to Skin::neighbours(), like in following example:

// buttons to display previous and next images, if any
if(is_object($anchor)) {
     $neighbours = $anchor->get_neighbours('location', $item);
    $context['text'] .= Skin::neighbours($neighbours, 'sidebar');
}

Voir aussi:

skins/skin_skeleton.php

get_overlay() - Get the default overlay type for anchored items, if any

function get_overlay($name='content_overlay')

$name='content_overlay' - string name of the attribute that contains overlay class
returns a string

This function is mainly used to associate overlays with sections.

get_parent() - Get the reference of the container of this anchor

function get_parent()

returns a string such as 'article:123', or 'section:456', etc.

To be overloaded into derivated class

get_path_bar() - Get the path bar for this anchor

function get_path_bar()

returns an array of $url => $label

This function is used to build a path bar relative to the anchor. For example, if you are displaying an article related to a section, the path bar has to mention the section. You can use following code to do that:

$anchor = get_anchor($article['anchor']);
$context['path_bar'] = array_merge($context['path_bar'], $anchor->get_path_bar());

To be overloaded into derivated class

get_poster() - Get the initial poster

function get_poster()

returns an array of poster attributes, or NULL

get_prefix() - Get the prefix text

function get_prefix($variant='')

$variant='' - string an indication to the anchor of the expected result
returns a string

This function is used to enhance the presentation of an item linked to an anchor. For example, a thread item can have a neat text, coming from the anchor, to introduce it:

$anchor = get_anchor($thread['anchor']);
$context['text'] .= $anchor->get_prefix('thread');

To be overloaded into derivated class

get_reference() - Get the reference for this anchor

function get_reference()

returns a string such as 'article:123', or 'section:456', etc.

This function is used to retrieve a reference to be placed into the database. For example:

$anchor = get_anchor($article['anchor']);
$context['text'] .= '<input type="hidden" name="anchor" value="'.$anchor->get_reference().'" />';

To be overloaded into derivated class

get_suffix() - Get suffix text

function get_suffix($variant='')

$variant='' - string an indication to the anchor of the expected result
returns a string

This function is used to enhance the presentation of an item linked to an anchor. For example, a thread item can have a neat text, coming from the anchor, to conclude the page:

$anchor = get_anchor($thread['anchor']);
$context['text'] .= $anchor->get_suffix('thread');

To be overloaded into derivated class

get_teaser() - Get some introductory text from this anchor

function &get_teaser($variant = 'basic')

$variant = 'basic' - string an optional variant
returns NULL, of some text

This function is used to introduce comments, or any sub-item related to an anchor.

This basic version does not care about the provided parameter.

get_thumbnail_url() - Get the url to load the thumbnail set for the anchor

function get_thumbnail_url()

returns a valid url to be used in an <img> tag

A common concern of modern webmaster is to apply a reduced set of icons throughout all pages. This function is aiming to retrieve the small-size icon characterizing one anchor. It should be used in pages to display several images into lists of anchored items.

Note: This function returns a URL to the thumbnail that is created by default when an icon is set for the anchor. However, the webmaster can decide to NOT display anchor thumbnails throughout the server. In this case, he/she has just to suppress the thumbnail URL in each anchor and that's it.

To be overloaded into derivated class

get_title() - Get the title for this anchor

function get_title()

returns a string

This function is used to display a title relative to the anchor. For example, if you are displaying a thread related to an article, you will use the title of the article as the general page title. You can use following code to do that:

$anchor = get_anchor($thread['anchor']);
$context['page_title'] = $anchor->get_title();

To be overloaded into derivated class if title has a different name

get_url() - Get the url to display the main page for this anchor

function get_url($action='view')

$action='view' - string the targeted action ('view', 'print', 'edit', 'delete', ...)
returns an url to view the anchor page

This function is used to link a page to a main one. For example, if you are displaying a thread related to an article, you can add a link to display the article with the following code:

$anchor = get_anchor($thread['anchor']);
$context['text'] .= '<a href="'.$anchor->get_url().'">'.i18n::s('Back').'</a>';

To be overloaded into derivated class

get_value() - Get the value of one attribute

function get_value($name, $default_value=NULL)

$name - string attribute name
$default_value=NULL - mixed default value, if any
returns mixed attribute value, of default value if attribute is not set

This function avoids direct looking at internal storage.

has_layout() - Check if an anchor implements a given layout

function has_layout($option)

$option - string the layout we are looking for
returns TRUE or FALSE, or the value of the matching option if any

To be overloaded into derivated class, if necessary

has_option() - Check that an option has been set for this anchor

function has_option($option)

$option - string the option we are looking for
returns TRUE or FALSE, or the value of the matching option if any

This function is used to control, from the anchor, the behaviour of linked items.

For example, the layout of a thread may vary from one section to another. To check that, you can use following code:

$anchor = get_anchor($thread['anchor']);
if($anchor->option('with_thread_alternate_layout') {
 ...
} else {
 ...
}

Another potential usage is to select a skin variant. For example, if the options field has been set with the value 'variant_red_background', the variant can be retrieved from anchored items with the following code:

$anchor = get_anchor($thread['anchor']);
if($variant = $anchor->option('variant') {
 load_skin($variant);
} else {
 load_skin('my_type');
}

This function recursively invokes upstream anchors, if any. For example, if the option 'skin_boxes' is set at the section level, all articles, but also all attached files and images of these articles, will feature the skin 'boxes'.

To be overloaded into derivated class, if necessary

has_value() - Check the value of one attribute

function has_value($name, $value)

$name - string attribute name
$value - mixed expected value
returns boolean TRUE or FALSE

is_editable() - Check that the surfer is an editor of an anchor

function is_editable($user_id=NULL)

$user_id=NULL - int optional reference to some user profile
returns TRUE or FALSE

This function is used to control the authority delegation from the anchor. For example, if some editor is assigned to a complete section of the web site, he/she should be able to edit all articles in this section. you can use following code to check that:

$anchor = get_anchor($article['anchor']);
if($anchor->is_editable() {
 ...
}

A logged member is always considered as an editor if he has created the target item.

An anonymous surfer is considered as an editor if he has provided the secret handle.

To be overloaded into derivated class if field has a different name

is_public() - Determine if public access is allowed to the anchor

function is_public()

returns TRUE or FALSE

This function is used to enable additional processing steps on public pages only. For example, only public pages are pinged on publication.

To be overloaded into derivated class if field has a different name

is_viewable() - Check that the surfer is allowed to display the anchor

function is_viewable()

returns TRUE or FALSE

This function is used to control the authority delegation from the anchor.

To be overloaded into derivated class if field has a different name

load_by_content() - Load the related item

function load_by_content($item, $anchor=NULL)

$item - array attributes to set this instance
$anchor=NULL - array attributes of the anchor, if any

This function is useful to create an object from an array of values

load_by_id() - Load the related item

function load_by_id($id)

$id -

To be overloaded into derivated class

touch() - Change the edit stamp of this anchor

function touch($action, $origin, $silently = FALSE)

$action - string the description of the last action
$origin - string the id of the item related to this update
$silently = FALSE - boolean TRUE for a silent update
returns string either a null string, or some text describing an error to be inserted into the html response

This function is used to reflect changes from sub-items into related items. For example, if a thread is linked to a section, one update of this thread will be considered as an update of the section itself.

$anchor = get_anchor($thread['anchor']);
$anchor->touch('thread:update');

Following actions have been defined:

'article:create'
'article:update'
'article:publish'
'section:create'
'section:update'
'file:create'
'file:update'
'image:create'
'image:update'
'image:set_as_icon'
'user:create'
'user:update'

It is assumed that the surfer (i.e., Surfer::get_name()) is the author of the modification.

To be overloaded into derivated class