Documentation: sections/sections.php

Class Sections - The database abstraction layer for sections

How do sections differ from categories?

Sections are the top-level containers of articles.

Sections provide following advanced features:

* Access restriction - Some sections are public, while others are reserved to authenticated members or only to associates. Of course, YACS ensures that access rules are cascaded to anchored articles. Create protected sections each time you want to restrict access to some information.

* Overlay extension - Articles and sub-sections can be extended using the overlay interface. You just have to edit a section and to mention, in the content overlay field, the name of the PHP class to use. For example, drop 'recipe' to transform a section to a cookbook, or 'poll' to create a section dedicated to polls. Of course, you can create overlays of your own. The index of supported overlays is at overlays/index.php.

* Skin variant - Each section can have its own skin, that will be cascaded to related articles as well. Basically, this gives you the power of selecting quite rich rendering options for your site. For example, you can select one blog style for section A, and another blog style for section B. If you have a single skin, and want to transmit the variant you want to use, add the 'variant_XXXX' to the options field, where XXXX is your actual option. If you prefer to use a particular skin at some section, use 'skin_YYYY' instead, where YYYY is the name of the target skin.

Pre-defined sections

At the moment following section nick names are used throughout yacs:

'clicks' - to put orphan links when clicked - created automatically in links/links.php
'covers' - the articles displayed at the very first page of the site
'extra_boxes' - boxes only displayed at the front page, in the extra panel
'files' - a sample library of files
'forum' - a sample forum
'gadget_boxes' - boxes only displayed at the front page, as gadgets
'letters' - pages sent by e-mail to subscribers - created automatically in letters/new.php
'links' - a sample library of links
'menus' - the articles used to build the main menu of the server
'my_section' - a sample plain section
'navigation_boxes' - boxes on the left of the page
'partners' - our preferred partners
'polls' - some of the polls published on this site
'queries' - pages sent by surfers to submit their queries to the webmaster - created automatically in query.php
'recipes' - a sample cookbook

How to lock a section?

A section can be locked to avoid new posts. This feature only concerns regular members of the community, as associates and editors are always allowed to add, change of remove any page. Note that locked sections do not appear in w.bloggar lists, even to authenticated associates.

How to manage options for sections?

The options fields are a convenient place to save attributes for any section without extending the database schema. As sections are commonly used to anchor some pages, their options can also be checked through the has_option() member function of the Anchor interface. Check shared/anchor.php for more information.

Options for section content (articles, etc.) are distinct from options for the section itself.

You can combine any of following keywords in fields for content, with the separator (spaces, tabs, commas) of your choice:

* anonymous_edit - Allow anonymous surfers to handle pages, files, etc., attached to the section. The section itself cannot be modified anonymously. Use this setting to configure Wiki-like sections.

* auto_publish - Every post is automatically published, without control from an associate. Posters can prevent publication by adding the option 'draft' to their post.

* members_edit - Allow authenticated members to handle pages, files, etc., attached to the section. Use this setting to create Wikis restricted to the community.

* no_comments - Prevent surfers to react to posted articles.

* no_neighbours - Use this setting to avoid previous / next links added by YACS to navigate a section.

* with_bottom_tools - Add tools at the bottom of each article to mail and convert text to PDF, Palm, MS-Word or to a printer. These tools are not displayed by default. You may find useful to activate them to further help surfers to reuse published material.

* with_extra_profile - Display poster profile in the extra panel of the template. This setting is suitable to blogs. By default YACS does not display poster profile.

* with_prefix_profile - Display poster profile at the top of the page, after page title. This setting is suitable to original publications, white papers, etc. By default YACS does not display poster profile.

* with_rating - Allow for page rating by surfers. By default YACS does not display rating tools. Use this setting to involve your community in the improvement of your site.

* with_suffix_profile - Display poster profile at the bottom of the page, after main content. This setting is suitable to original publications, white papers, etc. By default YACS does not display poster profile.

You can combine any of following keywords in fields for section options, with the separator (spaces, tabs, commas) of your choice:

* articles_by_title - Order pages by alphabetical order instead of using edition time information.

* files_by_title - Order files by alphabetical order instead of using edition time information. To be used jointly with 'with_files', to activate the posting of files.

* links_by_title - Rank links by alphabetical order instead of using edition time information. To be used jointly with 'with_links', to activate the posting of links.

* skin_<xxxx> - Select one skin explicitly. Use this option to apply a specific skin to a section. Articles anchored to this section will use the same skin.

* variant_<xxxx> - Select one skin variant explicitly. Usually only the variant 'sections' is used throughout sections. This can be changed to 'xxxx' by using the option variant_<xxxx>. Then the underlying skin may adapt to this code by looking at $context['skin_variant']. Basically, use variants to change the rendering of individual articles of your site, if the skin allows it.

* with_comments - The section index page is a thread, and can be commented. By default YACS allows comments only in content pages. However, in some situations you may ned to capture surfers feed-back directly at some particular section. Set the option with_comments to activate the commenting system. Please note that threads based on sections differ from threads based on articles. For example, they are not listed at the front page.

* with_files - Files can be attached to the section index page. By default YACS allows for file attachment only in content. But you may have to create a special set of files out of a section. If this is the case, add the option with_files manually and upload shared files.

* with_links - Links can be posted to the section index page. By default inks can be attached only to content pages. But you may have to create a special set of bookmarks out of a section. If this is the case, add the option with_links manually and add shared links.

How to change sections layout?

* boxesandarrows

* manual

* jive

* yabb - This section acts a threaded forum, or bulletin board. Each article is a topic. Comments are attached to articles to build a straightforward threaded system.

Handling sections at the index page

This applies to sections that are not at the top level of the hierarchy. For anchored sections, the parameter 'index_panel' defines how their content is handled on index pages of their parent section.

* 'main' - The default value. Use the layout specified in the field 'articles_layout' of the parent section ('daily', 'boxesandarrows', etc.)

* 'extra' - Summarize most recent entries in an extra box at the index page. May prove to be useful with discussion boards.

* 'extra_boxes' - Same as the previous one, except that YACS creates one extra box per article.

* 'gadget' - Summarize most recent entries in a gadget box at the index page. May prove to be useful with discussion boards for example.

* 'gadget_boxes' - Same as the previous one, except that YACS creates one gadget box per article.

* 'icon_bottom' - List thumbnails of related articles at the bottom of the page. Useful to feature logos of partners on index pages.

* 'icon_top' - List thumbnails of related articles at the top of the page. Useful to feature logos of partners on index pages.

* 'news' - List articles in the area dedicated to flashy news

* 'none' - Do not list section content at the front page. Useful to cache some sections, such as the archives newsletters.

How to order sections?

Usually sections are ranked by edition date, with the most recent section coming first. You can change this 'natural' order by modifying the value of the rank field.

What is the result obtained, depending on the value set?

* 10000 - This is the default value. All sections created by YACS are ranked equally.

* Less than 10000 - Useful to order sections, and to make them listed at the front page. Ordered, since the lower rank values come before higher rank values. Pages that have the same rank value are ordered by dates, with the newest item coming first. Moreover, the very first sections of the list can be listed at the front page either in tabs, if the template manages this, or in the page menu, if activated at the configuration panel for skins.

* More than 10000 - To reject sections at the end of the site map.

Handling sections at the front page

By default section content is automatically featured at the front page. This can be changed through the 'home_panel' field.

* 'main' - The default value. Use the main layout specified in the configuration panel for skins ('alistapart', 'boxesandarrows', etc.)

* 'extra' - Summarize most recent entries in an extra box at the front page. May prove to be useful with discussion boards.

* 'extra_boxes' - Same as the previous one, except that YACS creates one extra box per article.

* 'gadget' - Summarize most recent entries in a gadget box at the front page. May prove to be useful with discussion boards for example.

* 'gadget_boxes' - Same as the previous one, except that YACS creates one gadget box per article.

* 'icon' - List thumbnails of related articles at the bottom of the page. Useful to feature logos of partners at the front page.

* 'news' - List articles in the area dedicated to flashy news Actual rendering depends of parameters 'news_at_home' and 'news_count_at_home', set in skins/configure.php

* 'none' - Do not list section content at the front page. Useful to cache some sections, such as the archives newsletters.

Handling sections at the site map

By default top most sections (aka, not anchored to another section) are publicly listed at the site map. Change the field 'index_map' to 'N' to prevent this behaviour. Hidden sections are listed among other special sections to preserve access from associates.

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:

Fw_crocodile
Tingadon
Mark

Reste à faire:

vérifier que les sections verrouillées ne peuvent pas être destinataires d'images postées par les membres

delete() - Delete one section

function delete($id)

$id - the id of the section to delete
returns an error message, if any

Voir aussi:

sections/delete.php

get() - Get one section

function &get($id)

$id - int or string the id or nick name of the section
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

get_anchors_for_anchor() - List sections as anchors

function &get_anchors_for_anchor($anchor=NULL, $variant='main')

$anchor=NULL - string the main anchor (e.g., 'section:123')
$variant='main' - string the target area (e.g., 'main')
returns an array of anchors (e.g., array('section:456', 'section:789'))

This function is mainly used to build the front page and section index pages. It is call to list sections and, in a second time, articles related to these sections are actually listed.

If the anchor parameter is null, this function will locate sections having the given variant in the field 'home_panel'. Else it will locate sections having the given variant in the field 'index_panel'.

It accepts following variants:

'extra' - one extra box per section
'extra_boxes' - one extra box per article
'icon_bottom' - list thumbnails at the bottom of the page
'icon_top' - list thumbnails at the top of the page
'gadget' - one gadget box per section
'gadget_boxes' - one gadget box per article
'main' - the main part of the index page
'news' - flashy news
'none' - sections are not displayed at all

Normally this function is used before listing related articles. Ths is why we are not checking 'index_map' here.

Voir aussi:

get_children_of_anchor() - List anchors that are part of the content tree

function &get_children_of_anchor($anchor=NULL, $variant='main')

$anchor=NULL - string the main anchor (e.g., 'section:123')
$variant='main' - string filter to apply
returns an array of anchors (e.g., array('section:456', 'section:789'))

This function is mainly used to list all containers of the content tree at once. It is call to list sections and, in a second time, articles related to these sections are actually listed.

The variant is used to filter sections, as follows:

'main' - list sections that send articles in main panel
'index' - list sections that are listed in the main panel

Voir aussi:

sections/feed.php

get_default() - Get the default section

function get_default()

returns NULL on error, else the id of the default section

The default section is the one that has the nick name 'default'.

Else it is the first top level section that appears at the site map (actually, at sections/index.php).

Voir aussi:

files/edit.php

get_options() - Get sections as options of a <SELECT> field

function get_options($default=NULL, $to_avoid=NULL)

$default=NULL - string the current anchor to an existing section (e.g., 'section:12')
$to_avoid=NULL - string the reference of the current section (i.e., 'section:234'), to be avoided
returns the HTML to insert in the page

Only sections matching following criteria are returned:

section is visible (active='Y')
section is restricted (active='R'), but surfer is a logged user
section is restricted (active='N'), but surfer is an associate
an expiry date has not been defined, or is not yet passed

This function uses the cache to save on database requests.

Voir aussi:

get_options_for_anchor() - Get options recursively

function get_options_for_anchor($anchor, $spaces, $default, $to_avoid)

$anchor - string the current anchor to an existing section (e.g., 'section:12')
$spaces - string spaces to prepend before section name -- to reflect depth
$default - string the reference of the default section
$to_avoid - string the reference of the current section (i.e., 'section:234'), to be avoided
returns the HTML to insert in the page

This function is called internally by Sections::get_options(), above.

get_url() - Get the url to view a section

function get_url($id, $action='view')

$id - int the id of the section to view
$action='view' - string the expected action ('view', 'print', 'edit', 'delete', ...)
returns an anchor to the viewing script

By default, a relative URL will be provided (e.g. 'sections/view.php?id=512'), which may be not processed correctly by search engines. If the parameter 'with_friendly_urls' has been set to 'Y' in the configuration panel, this function will return an URL parsable by search engines (e.g. 'sections/view.php/512').

Voir aussi:

control/configure.php

is_assigned() - Has the surfer been assign to this section?

function is_assigned($id, $surfer_id=NULL)

$id - int the id of the target section
$surfer_id=NULL - int optional id to impersonate
returns TRUE or FALSE

This would be the case either:

if he is a member and has been granted the editor privilege
if he is a subscriber and has been granted the reader privilege

list_by_title_for_anchor() - List sections by title at a given level of the hierarchy

function &list_by_title_for_anchor($anchor, $offset=0, $count=20, $variant='full', $capability=NULL, $silent=FALSE)

$anchor - the section anchor to which these sections are linked
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant='full' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability=NULL - string '?' or 'A', to support editors and to impersonate associates, where applicable
$silent=FALSE - boolean TRUE to not report on SQL error, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Actually list sections by rank, then by title, then by edition date. If you select to not use the ranking system, sections will be ordered by title only. Else sections with a low ranking mark will appear at the beginning of the list, and sections with a high ranking mark will be put at the end of the list.

Only sections matching following criteria are returned:

section is visible (active='Y')
or section is restricted (active='R'), but surfer is a logged user
or section is hidden (active='N'), but surfer is an associate
section is publicly available (index_map != 'N')
an activation date has not been defined, or is over
an expiry date has not been defined, or is not yet passed
if called remotely (capability not NULL), section is not locked

For associates to see other sections, function Sections::list_inactive_by_title_for_anchor() is called from the site map (sections/index.php), and from sections index pages (sections/view.php).

Voir aussi:

list_inactive_by_title_for_anchor() - List inactive sub-sections by title for a given anchor

function &list_inactive_by_title_for_anchor($anchor, $offset=0, $count=20, $variant='full', $capability='?')

$anchor - the section anchor to which these sections are linked
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant='full' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability='?' - string '?' or 'A', to support editors and to impersonate associates, where applicable
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Actually list sections by rank, then by title, then by edition date. If you select to not use the ranking system, sections will be ordered by title only. Else sections with a low ranking mark will appear first, and sections with a high ranking mark will be put at the end of the list.

To be used by associates to access special sections (menu, boxes, etc.)

Only sections matching following criteria are returned:

an activation date has been set in the future
or an expiry date has been defined, and the section is now dead
or the section has been removed from index maps (index_map='N')

Alternatively, all sub-sections are listed if the parent section does not feature sections (sections_layout='none').

Voir aussi:

list_selected() - List selected sections

function &list_selected(&$result, $layout='full', $capability='?')

&$result - resource result of database query
$layout='full' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability='?' - string '?' or 'A', to support editors and to impersonate associates, where applicable
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Accept following layouts:

'compact' - to build short lists in boxes and sidebars
'full' - include anchor information -- also the default value
'menu' - returns the url and the title - used mainly at services/blog.php
'raw' - returns the id and the title
'references' - like 'full', but urls are references to sections
'select' - like 'full', but urls are links to the article editor form - used at articles/edit.php
'tabs' - more compact than compact
'thumbnails' - to build a visual list

Built-in variants 'compact', 'full' or 'select' all return a list of $url => ($prefix, $label, $suffix, $type, $icon), but the content of these variables vary from one variant to another.

Variables returned when the variant equals 'full' or 'select':

$prefix = ( expired | new | updated ) ( private | restricted )
$label = <title>
$suffix = (n pages, n files, n links, n comments) \n <introduction>
$type = section
$icon = <thumbnail_url>

Variables returned when the variant equals 'compact':

$prefix = NULL
$label = <title>
$suffix = section_<id> (may be used to implement the 'you are here' feature in any template)
$type = basic
$icon = NULL

Voir aussi:

skins/boxesandarrows/template.php

lookup() - Get the id of one section knowing its nick name

function lookup($nick_name)

$nick_name - string the nick name looked for
returns string either 'section:<id>', or NULL

At the moment following section nick names are used throughout yacs:

'clicks' - to host external link that are embed into ordinary pages
'covers' - pages to be displayed as introductory articles at the front page
'forum' - the coffee machine, for those that are not drinking so much coffee
'extra_boxes' - page to be displayed as small boxes at the front page
'letters' - pages sent by e-mail to subscribers
'menus' - page to be displayed on all pages as the main site menu
'my_section' - sample section for demonstrattion purpose
'navigation_boxes' - pages to be displayed as small boxes on all pages
'partners' - pages dedicated to external partners
'queries' - pages sent by surfers to submit their queries to the webmaster

Voir aussi:

post() - Post a new section

function post($fields, $capability='?')

$fields - array an array of fields
$capability='?' - string to support editors -- see sections/edit.php
returns the id of the new article, or FALSE on error

On error this script updates $context['error'].

Voir aussi:

put() - Put an updated section in the database

function put($fields, $capability='?')

$fields - array an array of fields
$capability='?' - string to support editors -- see sections/edit.php
returns string either a null string, or some text describing an error to be inserted into the html response

Voir aussi:

sections/edit.php

put_template() - Change the template of a section

function put_template($id, $template, $directory=NULL)

$id - int the id of the target section
$template - string the new or updated template
$directory=NULL -
returns string either a null string, or some text describing an error to be inserted into the html response

This function saves the template as an attribute of the section.

Also, it attempts to translate it as a valid YACS skin made of template.php and skin.php. The skin name is section_<id>.

Lastly, it updates the options field to actually use the template for pages of this section.

Voir aussi:

search() - Search for some keywords in all sections

function &search($pattern, $offset=0, $count=10, $variant='full')

$pattern - the search string
$offset=0 - int the offset from the start of the list; usually, 0 or 1 - default is 0
$count=10 - int the number of items to display - default is 10
$variant='full' - string the list variant, if any - default is 'full'
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Only sections matching following criteria are returned:

section is visible (active='Y')
section is restricted (active='R'), but the surfer is an authenticated member,

or YACS is allowed to show restricted teasers

section is hidden (active='N'), but surfer is an associate
an expiry date has not been defined, or is not yet passed

Voir aussi:

search.php

increment_hits() - Set the hits counter - errors are not reported, if any

function increment_hits($id)

$id - the id of the section to update

Hits are aiming to track service usage of anonymous and of authenticated users. Normally this function is not called is the surfer is either an associates or an editor for this section.

Voir aussi:

sections/view.php

setup() - Create tables for sections

function setup()

Voir aussi:

control/populate.php

stat_for_anchor() - Get some statistics for some sections

function &stat_for_anchor($anchor = '', $capability='?')

$anchor = '' - the selected anchor (e.g., 'section:12')
$capability='?' -
returns the resulting ($count, $min_date, $max_date) array

Only sections matching following criteria are returned:

section is visible (active='Y')
section is restricted (active='R'), but surfer is a logged user
section is hidden (active='N'), but surfer is an associate

Non-activated and expired sections are counted as well.

Voir aussi: