Documentation : articles/articles.php

Class Articles - The database abstraction layer for articles

The several versions of article content are now saved for history, and may be restored at any time.

How to lock an article?

An article can be locked to prevent modification. This feature only concerns regular members of the community, as associates and editors are always allowed to add, change of remove any page.

How to manage options for articles?

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

This means that some options are used within the context of one article (eg, no_links), while others can be used with related items as well.

Specific options to be processed by advanced overlays are not described hereafter. One example of this is the optional keyword 'home_with_results' for the rendering of polls. Please check documentation pages for any overlay you use, like overlays/poll.php.

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

files_by_title - When viewing articles, order attached files by alphabetical order instead of using edition time information. This option may prove useful to structure a list of files. For example, on a page describing a complex project, you would like to offer an introduction to the project ('1.introduction.doc'), then a report on initial issue ('2.the issue.ppt'), and a business case for the solution ('3.profit_and_loss.xls'). By adjusting file names and titles as shown, and by setting the option files_by_title, you would achieve a nice and logical thing.

formatted - The YACS rendering engine is disabled, since the description contains formatting tags. Use this option if you copy the source of a HTML or of a XHTML page, and paste it into an article at your server. Note that this keyword is also accepted if it is formatted as a YACS code ('[formatted]') at the very beginning of the description field.

hardcoded - The YACS rendering engine is disabled, except that new lines are changed to (X)HTML breaks. Use this option if you copy some raw text file (including a mail message) and make a page out of it. Note that this keyword is also accepted if it is formatted as a YACS code ('[hardcoded]') at the very beginning of the description field.

links_by_title - When wiewing articles, order attached links by alphabetical order instead of using edition time information. This options works like files_by_title, except that it applies to link. Use it to create nice and ordered bookmarks.

no_comments - New comments cannot be posted on this page.

no_files - New files cannot be attached to this page.

no_links - New links cannot be posted to this article.

skin_<xxxx> - Select one skin explicitly. Use this option to apply a specific skin to a page. This setting is the most straightforward way of introducing some skin to web surfers.

variant_<xxxx> - Select one skin variant explicitly. Usually only the variant 'articles' is used throughout articles. 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.

Also, a specific option is available to handle the article at the front page:

none - Don't mention this published article at the site front page. Use this option to avoid that special pages add noise to the front page. For example, while building the on-line manual of YACS this option has been set to intermediate pages, that are only featuring lists of following pages.

How to order articles and to manage sticky pages?

Usually articles 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 articles created by YACS are ranked equally.

Less than 10000 - Useful to create sticky and ordered pages. 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 pages.

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

This script is a reference file of this system.

Voir aussi :

versions/versions.php

Licence : GNU Lesser General Public License

Auteurs :

Bernard Paques bernard.paques@bigfoot.com
Florent
GnapZ
Christophe Battarel christophe.battarel@altairis.fr

Testeurs :

Mark
Fernand Le Chien
NickR

Reste à faire

add a field to count words in a post
add new monitoring layout http://www.socialtext.com/products/tour/recentchanges
add a read-only ticket for protected pages
place in bin on deletion

are_allowed() - Check if new articles can be added

function are_allowed($anchor=NULL, $item=NULL)

$anchor=NULL - object an instance of the Anchor interface, if any
$item=NULL - array a set of item attributes, if any
returns TRUE or FALSE

This function returns TRUE if articles can be added to some place, and FALSE otherwise.

The function prevents the creation of new articles when:

the global parameter 'users_without_submission' has been set to 'Y'
provided item has been locked --but not its parent anchor!
item has some option 'no_articles' that prevents new articles
the anchor has some option 'no_articles' that prevents new articles

Then the function allows for new articles when:

surfer has been authenticated as a valid member
or parameter 'users_without_teasers' has not been set to 'Y'

Then, ultimately, the default is not allow for the creation of new articles.

count_for_anchor() - Count records for one anchor

function count_for_anchor($anchor, $without_sticky=FALSE)

$anchor - string the selected anchor (e.g., 'section:12')
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns int the resulting count, or NULL on error

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous or the variant is 'boxes', and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

delete() - Delete one article

function delete($id)

$id - int the id of the article to delete
returns boolean TRUE on success, FALSE otherwise

Voir aussi :

delete_for_anchor() - Delete all articles for a given anchor

function delete_for_anchor($anchor)

$anchor - string the anchor to check (e.g., 'section:123')
returns void

Voir aussi :

delete_for_nick_name() - Delete articles by nick name

function delete_for_nick_name($nick_name)

$nick_name - the nick name of the article(s) to delete
returns an error message, if any

duplicate_for_anchor() - Duplicate all articles for a given anchor

function duplicate_for_anchor($anchor_from, $anchor_to)

$anchor_from - string the source anchor
$anchor_to - string the target anchor
returns int the number of duplicated records

This function duplicates records in the database, and changes anchors to attach new records as per second parameter.

Voir aussi :

shared/anchors.php

get() - Get one article by id, nick name or by handle

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

$id - int the id of the article
$mutable=FALSE - boolean TRUE to always fetch a fresh instance, FALSE to enable cache
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

get_attributes() - Get only some attributes

function &get_attributes($id, $attributes, $mutable=FALSE)

$id - int the id of the article
$attributes - mixed names of the attributes to return
$mutable=FALSE - boolean TRUE to always fetch a fresh instance, FALSE to enable cache
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

get_newest_for_anchor() - Get the newest article for one anchor

function &get_newest_for_anchor($anchor, $without_sticky=FALSE)

$anchor - int the id of the anchor
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns the resulting $item array, with at least keys: 'id', 'title', 'description', etc.

This function is to be used while listing articles for one anchor. It provides the last edited article for this anchor.

Only articles matching following criteria are returned:

article is visible (active='Y')
article is restricted (active='R'), but surfer is a logged user
article is protected (active='N'), but surfer is an associate
article has been officially published
an expiry date has not been defined, or is not yet passed
(if 2nd parameter is TRUE) article is not sticky (rank >= 10000)

Voir aussi :

index.php

get_next_url() - Get url of next article

function get_next_url(&$item, $anchor, $order='date')

&$item - array the current item
$anchor - string reference to the current anchor (e.g., 'section:123')
$order='date' - string the order, either 'date' or 'title' or 'rank'
returns an array ($url, $title)

This function is used to build navigation bars.

Voir aussi :

sections/section.php

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

function &get_options()

returns the HTML to insert in the page

Only articles matching following criteria are returned:

article is visible (active='Y')
article is restricted (active='R'), but surfer is a logged user
article is protected (active='N'), but surfer is an associate, and we are not feeding someone
article has been officially published
an expiry date has not been defined, or is not yet passed

Voir aussi :

comments/edit.php

get_previous_url() - Get url of previous article

function get_previous_url(&$item, $anchor, $order='date')

&$item - array the current item
$anchor - string reference to the anchor (e.g., 'section:123')
$order='date' - string the order, either 'date' or 'title'
returns an array($url, $title)

This function is used to build navigation bars.

Voir aussi :

sections/section.php

get_url() - Build a reference to an article

function get_url($id, $action='view', $name=NULL, $nick_name=NULL)

$id - int the id of the article to handle
$action='view' - string the expected action ('view', 'print', 'edit', 'delete', ...)
$name=NULL - string additional data, such as page name, if any
$nick_name=NULL - string nick name, if any, to take over on previous parameter
returns string a normalized reference

Depending on parameter 'with_friendly_urls' and on action, following results can be observed:

view - articles/view.php?id=123 or articles/view.php/123 or article-123

other - articles/edit.php?id=123 or articles/edit.php/123 or article-edit/123

If a third parameter is provided, it may be used to achieve a nice link, such as the following:

Articles::get_url(123, 'view', 'A very nice page');

will result to

http://server/article-123-a-very-nice-page

If a fourth parameter is provided, it will take over the third one. This is used to leverage nick names in YACS, as per the following invocation:

Articles::get_url($item['id'], 'view', $item['title'], $item['nick_name']);

Voir aussi :

control/configure.php

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

function increment_hits($id)

$id - the id of the article to update

is_assigned() - Has the surfer been assigned to this article?

function is_assigned($id, $surfer_id=NULL)

$id - int the id of the target article
$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_() - List most recent articles

function &list_($offset=0, $count=10, $layout='full', $since=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
$layout='full' - mixed the list variant, if any
$since=NULL - string stamp of the minimum publication date to be considered
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Items order is provided by the layout.

list_assigned_by_date() - List articles assigned to one surfer

function &list_assigned_by_date($surfer_id, $offset=0, $count=20, $variant='full', $shared_page = FALSE)

$surfer_id - int surfer id
$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
$shared_page = FALSE -
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Only articles matching following criteria are returned:

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

list_assigned_by_date_for_anchor() - List articles assigned to one surfer in one anchor

function &list_assigned_by_date_for_anchor($anchor, $surfer_id, $offset=0, $count=20, $variant='full', $shared_page = FALSE)

$anchor - mixed, either a string the target anchor, or an array of anchors
$surfer_id - int surfer id
$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
$shared_page = FALSE -
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Only articles matching following criteria are returned:

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

Voir aussi :

users/view.php

list_by() - List articles

function &list_by($order=NULL, $offset=0, $count=10, $layout='full', $since=NULL)

$order=NULL - string order of resulting set
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='full' - mixed the list variant, if any
$since=NULL - string stamp of the minimum publication date to be considered
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The ordering method is provided as first parameter:

'draft' - order by reverse date of modification, but only draft pages
'edition' - order by reverse date of modification
'expiry' - order by reverse expiry date, and consider only expired articles
'future' - order by reverse date of publication, and consider only future publication dates
'hits' - order by reverse count of hits
'publication' - order by reverse date of publication
'random' - use random order
'rating' - order by reverse number of points
'review' - order by MAX(date of last modification, date of last review)
'unread' - order by count of hits

list_by_date() - List most recent articles

function &list_by_date($offset=0, $count=10, $layout='full', $since=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
$layout='full' - mixed the layout, if any
$since=NULL - string stamp of the minimum publication date to be considered
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Actually list articles by publishing date, then by title.

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

$items = Articles::list_by_date(0, 10);
$context['text'] .= Skin::build_list($items, 'decorated');

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

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
article has been officially published
an expiry date has not been defined, or is not yet passed
related section is regularly displayed at the front page

Voir aussi :

list_by_date_for_anchor() - List most recent publications for one anchor

function &list_by_date_for_anchor($anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$anchor - mixed, either a string the target anchor, or an array of anchors
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_anchor' - mixed the layout, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

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

Example:

$items = Articles::list_by_date_for_anchor('section:12');
$context['text'] .= Skin::build_list($items, 'decorated');

Use the variant 'boxes' to fetch articles within boxes. This is the standard way of displaying navigation, gadgets and extra boxes in yacs.

// load the navigation boxes, if any
$anchor = Sections::lookup('navigation_boxes');
if($items = Articles::list_by_date_for_anchor($anchor, 0, 5, 'boxes')) {
 foreach($items as $title => $content)
   echo "<p></p>n".Skin::build_box($title, $content, 'navigation')."n";
}

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous, and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

Voir aussi :

list_by_date_for_author() - List most recent articles for one author

function &list_by_date_for_author($author_id, $offset=0, $count=10, $layout='no_author')

$author_id - int the id of the author of the article
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_author' - mixed the layout, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Articles are sorted by edition dates, to let updated articles appear at the top of lists in user pages.

Example:

$items = Articles::list_by_date_for_author(12, 0, 10);
$context['text'] .= Skin::build_list($items, 'decorated');

Only articles matching following criteria are returned:

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

Voir aussi :

users/view.php

list_by_edition_date_for_anchor() - List most recent updates for one anchor

function &list_by_edition_date_for_anchor($anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$anchor - mixed, either a string the target anchor, or an array of anchors
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_anchor' - mixed the layout, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

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

Using edition dates enables updated articles to appear at the top of list in sections.

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous, and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

Voir aussi :

list_by_hits() - List most read articles

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

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

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

$items = Articles::list_by_hits(0, COMPACT_LIST_SIZE);
$context['text'] .= Skin::build_list($items, 'compact');

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

Only articles matching following criteria are returned:

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

Voir aussi :

list_by_hits_for_anchor() - List most read articles for one anchor

function &list_by_hits_for_anchor($anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$anchor - mixed, either a string the target anchor, or an array of anchors
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_anchor' - mixed the layout, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous, and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

Voir aussi :

codes/codes.php

list_by_hits_for_author() - List most read articles for one author

function &list_by_hits_for_author($author_id, $offset=0, $count=10, $layout='no_author')

$author_id - int the id of the author of the article
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_author' - mixed the layout, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

To build a simple box of the most read articles on the author page, just use:

$items = Articles::list_by_hits_for_author(12, 0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

Only articles matching following criteria are returned:

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

Voir aussi :

users/view.php

list_by_title_for_anchor() - List articles by title for one anchor

function &list_by_title_for_anchor($anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$anchor - string the target 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
$layout='no_anchor' - mixed the layout, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

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

Example:

$items = Articles::list_by_title_for_anchor('section:12');
$context['text'] .= Skin::build_list($items, 'decorated');

Use the variant 'boxes' to fetch articles within boxes. This is the standard way of displaying navigation and extra boxes in yacs.

// load the navigation boxes, if any
$anchor = Sections::lookup('navigation_boxes');
if($items = Articles::list_by_title_for_anchor($anchor, 0, 5, 'boxes')) {
 foreach($items as $title => $content)
   echo "<p></p>n".Skin::build_box($title, $content, 'navigation')."n";
}

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous or the variant is 'boxes', and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

Voir aussi :

list_by_title_for_ids() - List these articles

function &list_by_title_for_ids($ids, $layout='select')

$ids - mixed a list of ids or nick names
$layout='select' - mixed the layout to apply
returns string to be inserted into the resulting page

The first parameter can be either a string containing several ids or nick names separated by commas, or it can be an array of ids or nick names.

The second parameter can be either a string accepted by Articles::list_selected(), or an instance of the Layout interface.

list_for_anchor() - List articles attached to one anchor

function &list_for_anchor($anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$anchor - mixed, either a string the target anchor, or an array of anchors
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_anchor' - string the list variant, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The ordering method is provided by layout.

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous, and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

list_for_anchor_by() - List articles attached to one anchor

function &list_for_anchor_by($order, $anchor, $offset=0, $count=10, $layout='no_anchor', $without_sticky=FALSE)

$order - string order of resulting set
$anchor - mixed, either a string the target anchor, or an array of anchors
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$layout='no_anchor' - mixed the layout, if any
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

The ordering method is provided as first parameter:

'draft' - order by reverse date of modification, but only draft pages
'edition' - order by rank, then by reverse date of modification
'hits' - order by reverse number of hits, then by reverse date of publication
'overlay' - order by overlay_id
'publication' - order by rank, then by reverse date of publication
'rating' - order by rank, then by reverse number of points
'title' - order by rank, then by titles

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous, and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

list_for_name() - List named articles

function &list_for_name($name, $exception=NULL, $layout='compact')

$name - string the nick name
$exception=NULL - int the id of the current page, which will not be listed
$layout='compact' - mixed the layout, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

This function lists all articles with the same nick name.

This is used by the page locator to offer alternatives when several pages have the same nick names. It is also used to link a page to twins, these being, most of the time, translations.

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate or an editor
article has been officially published, or surfer is an associate or an editor
an expiry date has not been defined, or is not yet passed

list_selected() - List selected articles

function &list_selected(&$result, $variant='compact')

&$result - resource result of database query
$variant='compact' - mixed string e.g., 'full', or an instance of Layout_Interface
returns NULL on error, else the outcome of the selected layout

Accept following layouts:

'boxes' - a special variant to build boxes on index pages
'compact' - to build short lists in boxes and sidebars (this is the default)
'contents' - an array of $url => array($time, $label, $author, $section, $icon, $introduction, $content, $trackback) for feeds and search
'daily' - for blogs
'digest' - for newsletters
'feeds' - an array of $url => array($time, $label, $author, $section, $icon, $introduction, $content, $trackback) for feeds and search
'freemind' - to create Freemind maps
'news' - to build a list of news or of featured pages
'raw'
'review'
'rpc'
'select' - to select an article among several templates
'simple' - to build line-based lists
'thumbnails'

Options can be provided to the selected layout by adding them after a space character. For example: 'simple no_anchor' when listing private conversations.

Voir aussi :

lock() - Lock/unlock an article

function lock($id, $status='Y')

$id - int the id of the article to update
$status='Y' - string the previous locking state
returns TRUE on success toggle, FALSE otherwise

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

function lookup($nick_name)

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

move() - Move articles from one anchor to another

function move($from_anchor, $to_anchor)

$from_anchor - string reference of the source anchor
$to_anchor - string reference of the target anchor
returns int number of moved articles, of FALSE

Voir aussi :

sections/bulk.php

post() - Post a new article

function post(&$fields)

&$fields - array an array of fields
returns the id of the new article, or FALSE on error

This function populates the error context, where applicable.

Voir aussi :

articles/edit.php

purge_for_anchor() - Limit the number of articles for one anchor

function purge_for_anchor($anchor, $limit=1000)

$anchor - int the maximum number of pages to keep in the database
$limit=1000 -
returns void

This function deletes oldest pages going beyond the given threshold.

put() - Put an updated article in the database

function put(&$fields)

&$fields - array an array of fields
returns TRUE on success, or FALSE on error

Voir aussi :

put_attributes() - Change only some attributes

function put_attributes(&$fields)

&$fields - array an array of fields
returns TRUE on success, or FALSE on error

rate() - Rate a page

function rate($id, $rating)

$id - int the id of the article to rate
$rating - int the rate

Errors are not reported, if any

search() - Search for some keywords in all articles

function &search($pattern, $offset=0, $count=50, $layout='full')

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

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is restricted (active='N'), but surfer is an associate
article has been officially published, or the surfer is a logged user
an expiry date has not been defined, or is not yet passed

Voir aussi :

search_in_section() - Search for some keywords articles anchored to one precise section

function &search_in_section($section_id, $pattern, $offset=0, $count=10, $layout='full')

$section_id - the id of the section to look in
$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
$layout='full' - mixed the layout, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

This function also searches in sub-sections, with up to three levels of depth.

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is restricted (active='N'), but surfer is an associate
article has been officially published, or the surfer is a logged user
an expiry date has not been defined, or is not yet passed

Voir aussi :

search.php

setup() - Create tables for articles

function setup()

stamp() - Stamp an article

function stamp($id, $publication=NULL, $expiry=NULL, $publisher=NULL)

$id - int the id of the item to publish
$publication=NULL - string the target publication date, if any
$expiry=NULL - string the target expiration date, if any
$publisher=NULL - array attributes of the publisher, if any
returns string either a null string, or some text describing an error to be inserted into the html response

This function is used to change various dates for one article.

If a publication date is provided, it is saved along the article. An optional expiry date will be saved as well.

If only an expiry date is provided, it is saved along the article.

If no date is provided, the review field is updated to the current date and time.

Dates are supposed to be in UTC time zone.

The name of the surfer is registered as the official publisher. As an alternative, publisher attributes ('name', 'id' and 'address') can be provided in parameters.

Voir aussi :

stat() - Get some statistics

function &stat()

returns the resulting ($count, $min_date, $max_date) array

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
article has been officially published
an expiry date has not been defined, or is not yet passed
related section is regularly displayed at the front page
article is allowed to be displayed at the front page of the server (home_panel != 'none')

Voir aussi :

articles/index.php

stat_for_anchor() - Get some statistics for one anchor

function &stat_for_anchor($anchor, $without_sticky=FALSE)

$anchor - the selected anchor (e.g., 'section:12')
$without_sticky=FALSE - boolean FALSE to include sticky pages, TRUE otherwise
returns the resulting ($count, $min_date, $max_date) array

Only articles matching following criteria are returned:

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

or YACS is allowed to show restricted teasers

article is protected (active='N'), but surfer is an associate, and we are not feeding someone
surfer is anonymous or the variant is 'boxes', and article has been officially published
logged surfers are restricted to their own articles, plus published articles
an expiry date has not been defined, or is not yet passed

Voir aussi :

sections/view.php

stat_for_author() - Get some statistics for one author

function &stat_for_author($author_id)

$author_id - the selected author (e.g., '12')
returns the resulting ($count, $min_date, $max_date) array

Only articles matching following criteria are returned:

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

Voir aussi :

users/view.php

unpublish() - Unpublish an article

function unpublish($id)

$id - int the id of the item to unpublish
returns string either a null string, or some text describing an error to be inserted into the html response

Clear all publishing information

Voir aussi :

articles/unpublish.php

Visualiser ce script · Logiciel serveur