Documentation: categories/categories.php

Class Categories - The database abstraction layer for categories

How to manage options for categories?

The options field is a convenient place to save attributes for any category without extending the database schema.

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

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

* categories_by_title - Order sub-categories 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.

* layout_as_inline - A special layout to list the content of sub-categories. Each sub-category, with related pages, is a section bow in the main panel.

* layout_as_yahoo - A 2-column and decorated layout, with up to 3 entries per category.

* links_by_title - Order links by alphabetical order instead of using edition time information.

* skin_<xxxx> - Select one skin explicitly. Use this option to apply a specific skin to a category page.

* variant_<xxxx> - Select one skin variant explicitly. Usually the variant 'categories' is used throughout categories. 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 categories of your site, if the skin allows it.

* with_comments - This category can be commented. By default YACS does not allow comments in categories. However, in some situations you may ned to capture surfers feed-back directly at some particular category. Set the option with_comments to activate the commenting system. Please note that threads based on categories differ from threads based on articles. For example, they are not listed at the front page.

* with_files - Files can be attached to this category. By default within YACS libraries of files are supposed to be based on articles and attached files. But you may have to create a special set of files out of a category. If this is the case, add the option with_files manually and upload shared files.

* no_links - Links cannot be posted to this category. You can also create lists of bookmarks based on articles and attached links. But you may have to create a special set of bookmarks out of a category.

Where to display categories?

Each category can be embedded, or displayed, into one other page. Use this feature to display categories as sidebars throughout your site.

Each sidebar will feature:

the category title (this is the box title)
a limited and compact list of top pages in the category
if there is no page, a limited and compact list of top links in the category
a follow-up link to the category page ('more pages')

This is achieved through the field 'display', which is actually an anchor to the target page. Following anchors are recognized for categories:

'site:all' - build one navigation box for the category, in skins/your_skin/template.php
'home:extra' - build one extra box for the category at the front page, in index.php
'home:gadget' - build one gadget box in the middle of the front page, in index.php
'article:index' - a sidebar at articles/index.php
'file:index' - a sidebar at files/index.php
'link:index' - a sidebar at links/index.php
'section:index' - a sidebar at sections/index.php
'user:index' - a sidebar at users/index.php

How to order sub-categories?

Usually sub-categories are ranked by edition date, with the most recent page 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 categories created by YACS are ranked equally.

* Less than 10000 - Useful to create sticky and ordered subcategories. Sticky, since these pages will always come first. 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. This lets you arrange precisely the order of sticky categories.

* More than 10000 - To reject categories at the end of lists.

This script is a reference file of this system.

Voir aussi:

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com
GnapZ

build_path() - Build the path from top-level category

function build_path($reference)

$reference - string reference to an anchor (i.e., 'category:423')
returns a string to be used in <option>

delete() - Delete one category

function delete($id)

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

get() - Get one category by id

function &get($id)

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

get_by_keyword() - Get one category by keyword

function &get_by_keyword($keyword)

$keyword - string the keyword of the category
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

get_by_title() - Get one category by title

function &get_by_title($title)

$title - string the title of the category
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

get_most_read() - Get the most read category

function &get_most_read()

returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

Only categories matching following criteria are returned:

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

get_newest() - Get the newest category

function &get_newest()

returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

Only categories matching following criteria are returned:

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

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

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

$to_avoid=NULL - array a list of categories ($reference => $attributes) currently assigned to the item, or a category reference (i.e., 'category:234')
$to_select=NULL - string the anchor currently selected, if any
returns the HTML to insert in the page

This function is used to assign sub-categories to categories, or articles to categories.

For the assignment of articles, the argument is an array of categories already used, that won't be listed at all.

For the assignment of sub-categories, the current anchor has to be highlighted in the list. But the subcategory itself should not appear in the list (self-anchoring is forbidden).

Only categories matching following criteria are returned:

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

Voir aussi:

get_url() - Get the url to view a category

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

$id - int the id of the category 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. 'categories/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. 'categories/view.php/512').

Voir aussi:

control/configure.php

list_by_date() - List most recent categories

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

$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)

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

To build a simple box of the newest categories in your main index page, just use:

include_once 'categories/categories.php';
$items = Categories::list_by_date(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

You can also display the newest category separately, using Categories::get_newest() In this case, skip the very first category in the list by using Categories::list_by_date(1, 10)

Only categories matching following criteria are returned:

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

list_by_date_for_anchor() - List categories by date for a given anchor

function &list_by_date_for_anchor($anchor, $offset=0, $count=10, $variant='full')

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

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

Only categories matching following criteria are returned:

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

list_by_date_for_display() - List categories by date for a given anchor

function &list_by_date_for_display($display='site:index', $offset=0, $count=10, $variant='references')

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

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

Only categories matching following criteria are returned:

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

list_by_date_for_keywords() - List most recent categories

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

$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)

include_once 'categories/categories.php';
$items = Categories::list_by_date(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

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

list_by_hits() - List most read categories

function &list_by_hits($offset=0, $count=10, $variant='hits')

$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='hits' - string the list variant, if any - default is 'hits'
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

To build a simple box of the most read categories in your main index page, just use:

include_once 'categories/categories.php';
$items = Categories::list_by_hits(0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

You can also display the most read category separately, using Categories::get_most_read() In this case, skip the very first category in the list by using Categories::list_by_hits(1, 10)

Only categories matching following criteria are returned:

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

list_by_path() - List categories by path

function &list_by_path($offset=0, $count=10, $variant='full', $capability=NULL)

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='full' - string the list variant, if any
$capability=NULL - string to impersonate the actual user through services/blog.php
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

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

Only categories matching following criteria are returned:

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

Voir aussi:

services/blog.php

list_by_title_for_anchor() - List categories by title at a given level in the categories tree

function &list_by_title_for_anchor($anchor, $offset=0, $count=10, $variant='full')

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

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

To build a simple box of the root level categories in your main index page, just use:

include 'categories/categories.php';
if($items = Categories::list_by_title_for_anchor(NULL))
 $context['text'] .= Skin::build_list($items, '2-columns');

Only categories matching following criteria are returned:

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

list_inactive_by_title() - List inactive categories by title

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

$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)

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

To be used by associates to access special categories (featured, etc.)

Only categories matching following criteria are returned:

category is not visible (active='N')
an expiry date has been defined, and the category is now dead

list_selected() - List selected categories

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

&$result - resource result of database query
$layout='compact' - 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 variants:

'compact' - to build short lists in boxes and sidebars (this is the default)
'full' - include anchor information
'index' - to display sub categories as well
'raw' - to build lists with item ids
'search' - to build result lists

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

function lookup($nick_name)

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

post() - Post a new category

function post($fields)

$fields - array an array of fields
returns string either a null string, or some text describing an error to be inserted into the html response

put() - Put an updated category in the database

function put($fields)

$fields - array an array of fields
returns string either a null string, or some text describing an error to be inserted into the html response

remember() - Remember publications

function remember($reference, $stamp=NULL, $categories=NULL)

$reference - string a reference to the published material (e.g., 'article:12')
$stamp=NULL - string the publication date and time
$categories=NULL -

This function is used to classify published material according to publication time.

search() - Search for some keywords in all categories

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

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

Only categories matching following criteria are returned:

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

Voir aussi:

[script=for $variant description]#list_selected[/script]

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

function increment_hits($id)

$id - the id of the category to update

setup() - Create tables for categories

function setup()

stat_for_anchor() - Get some statistics for some categories

function &stat_for_anchor($anchor)

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

Only categories matching following criteria are returned:

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