Documentation: shared/global.php

shared/global.php - Included at the very beginning of each page

Use the control panel at control/index.php to change parameters used in this script, including:

the server/user/password used to access the database
the preferred language
the skin used to render the final page

Edit this script for things that have no configuration script yet:

to add a new type of anchor in your system

YACS assumes that it has to answer web requests if $_SERVER['REMOTE_ADDR'] has been set. Else it is running from the command line.

This script is a reference file of this system.

Voir aussi:

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

Testeurs:

Olivier
Arioch
Fernand Le Chien
Mordread Wallas
Raeky
Lilou
Pierre Robert
Anatoly

Reste à faire:

create hook for delete_for_anchor()

get_micro_time() - Get the current time stamp

function get_micro_time()

stripslashes_recursively() - Remove quoting recursively

function stripslashes_recursively($fields)

$fields - array of encoded fields
returns the transformed array

This function extends stripslashes() to arrays. Should probably be part of the next version of native PHP library?

encode_field() - Encode a form field

function encode_field($text)

$text - string some text to be encoded
returns the string to be displayed

This function encode special HTML chars, such as '&', '<', etc. It also preserves Unicode entities, meaning that if you have typed an euro sign in an article, you will still have an euro sign in the edit form instead of a mysterious €.

Use it to encode every textarea or input field in forms. Use it also to generate XML data, such as RSS feed.

load_skin() - Load a skin

function load_skin($variant='', $anchor=NULL, $options='')

$variant='' - string a skin variant, if any
$anchor=NULL - object anchor of the target item, if any
$options='' - string additional options for the target item, if any

This function will declare the Skin class related to the skin declared in $context['skin']. It does it by loading a file named 'skin.php'. For example, if you have stated: $context['skin'] = 'skins/myskin', then load_skin() will include 'skins/myskin/skin.php'.

The skin can be overriden by changing options of a section, or of an article. In both cases, use the keyword 'skin_foo' to have YACS look for the skin foo and related files.

The variant parameter determines the template used for page rendering. If 'foo' is provided, YACS will look for template template_foo.php in the target skin.

The variant can be overriden by changing options of a section, or of an article. In both cases, use the keyword 'variant_foo' to have YACS look for template template_foo.php in the target skin.

class Skin extends Skin_Skeleton

build_block()

function build_block($text, $variant='')

$text -
$variant='' -

build_box()

function build_box($title, $text, $variant='')

$title -
$text -
$variant='' -

build_link()

function build_link($url, $text=NULL, $variant=NULL, $href_title=NULL)

$url -
$text=NULL -
$variant=NULL -
$href_title=NULL -

build_list()

function build_list($items, $variant='', $default_icon=NULL)

$items -
$variant='' -
$default_icon=NULL -

initialize()

function initialize()

render_skin() - Actually render a page

function render_skin($script_cache_id=NULL, $stamp=NULL)

$script_cache_id=NULL - string the cache id to be used for the global page content
$stamp=NULL - int the time() to be used as the Last-Modified date of the page, if any

This function loads the template declared in $context['skin'].

It does it by loading a file named 'template.php'. For example, if you have stated: $context['skin'] = 'skins/myskin/', then render_skin() will include 'skins/myskin/template.php'.

Moreover, if a template is available for the current module, it will be loaded instead. For example, if the module is 'sections', and if there a file named 'template_sections.php', this one will be loaded instead of the standard 'template.php'.

The assumption here is that the executing script is either at the root level (e.g., the main index.php of the server) or at some level below (e.g., articles/index.php). Moreover, we are also assuming that the skin has been designed for the root level only. Therefore, it has to be adapted for other scripts. For example, has to be changed to . Of course, we would like to avoid doing such a change on-the-fly to stay efficient.

To cope with all these requirements, this function builds and uses a cached version of the modified skin, according to the following algorithm:

select the template file (e.g., 'skins/myskin/template.php')
if the file exists, use it (we are at the root level)
else if the cache file exists, use it (we are at one level down or below)
else build and use the cache file (e.g., 'skins/myskin/template_cache.php')

This function will also highlight some words in the page if we are coming from a search engine.
* Words to be highlighted can be found in $_SERVER['HTTP_REFERER'] if we are coming from Google (field 'q'), from Yahoo (field 'p') or from the YACS search page (field 'search'). Alternatively, this script will also consider $_REQUEST['highlight'].
* This function look for highlighted words in following page components: $context['text'] and $context['title']. The style class 'highlight' is used.
* This function is activated only at view.php scripts.

This function will attempt to handle web caching through following mechanisms:

* If $context['text'] has some content, and if there is no send_body() function, we assume that the page may be versioned. In this case a ETag headers is computed as being the hash of page content. Page content is defined as resulting from the concatenation of: $context['page_title'], $context['text'] and $context['extra']. Also, modification dates of shared/parameters.include.php and of skins/parameters.include.php, to reflect any change of one of the main configuration files. Lastly, the surfer capability is appended as well, to cope with login/logout correctly. If the content changes, the value of the ETag will change accordingly, and the new page will be provided. Else the transaction will break on code 304 Not Modified, savings some bytes and some time. This mechanism is very efficient for the front page and for some index pages, for which the content may vary but dates are difficult to evaluate.

* If a time stamp is provided, the script sets the Last-Modified attribute in responses and manages the If-Modified-Since attribute in requests. If two dates are the same (and if ETag attribute is not provided), the transaction will break on code 304 Not Modified, savings some bytes and some time. Else the new page will be transmitted to the requestor. This mechanism is very efficient for article pages, for which an edition date can be precisely assessed.

This script does not set or modify other attributes in responses. These attributes may be set directly in scripts according to following suggestions:

* Internet Explorer may have strange behaviour with the Expire attribute. It does not take into account very short-term expiration date and does not validate after the deadline. On the other hand, setting an expiration date is useful to fix the 'download a .zip file directly from the browser' bug. We recommend to set this attribute in all scripts related to file transfers and download, and to not set it at all in every other script.

* The Cache-Control attribute allows for cache-control. It has been primarily designed for HTTP/1.1 agents, and few proxies seem to handle it correctly at the moment. However to explicitly declare that the output of some script may be cached for three hours by intermediate proxies, you can use Safe::header("Cache-Control: public, max-age=10800");. On the other hand, if only the user-agent (i.e., the browser) is allowed to cache something, you can use Safe::header("Cache-Control: private, max-age=10800");.

* What to do with Pragma:? Well, almost nothing; this is used only by some legacy browsers. If you want an old browser to cache some object, use Safe::header("Pragma:");.

Post-processing hooks are triggered after all HTML is returned to the browser, including the poor-man's cron so the user who kicks off the cron jobs should not notice any delay.

Voir aussi:

preg_match to highlight code

render_raw() - Render raw content

function render_raw($type)

$type - string content type of the output

This function only installs the output handler.

finalize_page() - Finalize page rendering

function finalize_page($no_return=FALSE)

$no_return=FALSE - boolean TRUE to not return, FALSE to allow for subsequent execution steps

Voir aussi:

shared/cache.php

yacs_handler() - General purpose handler

function yacs_handler($content)

$content -
returns string the string to actually transmit

This handler is able:

to transcode data to another character set
to compress data, if asked for it
to set the Content-Length HTTP header

We have it because the standard 'ob_gzhandler' does not set the Content-Length header properly. Also, this function transcodes char to valid Unicode if necessary.

@parameter string the buffered page

Voir aussi:

http://dev.e-taller.net/gzhand...cGzHandler.phps

validate() - Check HTML/XHTML syntax

function validate($input)

$input - string the string to check
returns string the error message, if any

This function uses some PHP XML parser to validate the provided string. The objective is to spot malformed or unordered HTML and XHTML tags. No more, no less.

Voir aussi:

get_anchor() - Load one anchor from the database

function &get_anchor($id, $mutable=FALSE)

$id - string a valid anchor (e.g., 'section:12', 'article:34')
$mutable=FALSE - boolean TRUE to always fetch a fresh instance, FALSE to enable cache
returns an array of named variables, or NULL if the anchor is unknown

You should expand this function to take into account any new module that may behave as anchors for other information components.

This function saves on SQL requests by caching results locally in static memory.

You can prevent YACS to cache mutable objects by setting the second parameter to TRUE.

Voir aussi:

shared/anchor.php

delete_related_to() - Delete items related to one anchor

function delete_related_to($anchor)

$anchor - the anchor (e.g., 'article:12')
returns an error message, if any

get_action_label() - Get the label for an action

function get_action_label($action)

$action - string the action code example: 'article:publish', 'image:create'
returns a string

Following actions codes have been defined:

'article:create'
'article:update'
'article:publish'
'article:review'
'section:create'
'section:update'
'comment:create'
'comment:update'
'file:create'
'file:update'
'link:create'
'link:update'
'link:stamp'
'image:create'
'image:update'
'image:set_as_icon'
'location:create'
'location:update'
'table:create'
'table:update'
'user:create'
'user:update'

Voir aussi:

shared/anchor.php#touch