Home « Server software «

Documentation: links/links.php

Content

Class Links - The database abstraction layer for links

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com
Florent

click() - Increment one click link

function click($url)

$url - string the external url that is targeted

Voir aussi:

links/click.php

delete() - Delete one link

function delete($id)

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

Voir aussi:

links/delete.php

delete_for_anchor() - Delete all links for a given anchor

function delete_for_anchor($anchor)

$anchor - the anchor to check
returns an error message, if any

Voir aussi:

shared/global.php

get() - Get one link by id or by url

function &get($id)

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

Voir aussi:

have() - Check for link existence

function have($url, $anchor=NULL)

$url - string the external url that is targeted
$anchor=NULL - string an internal anchor, if any
returns either TRUE or FALSE

This function can be used either to see if a link exists in the database, or to check if one link has been attached to a particular anchor.

To query the whole database, use:

if(Links::have($that_beautiful_url))
   ...

To check that an article has a link attached, use:

$anchor = 'article:'.$article['id'];
if(Links::have($that_beautiful_url, $anchor))
   ...

Voir aussi:

list_by_date() - List newest links

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

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

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

// side bar with the list of most recent links
include_once 'links/links.php';
$local['title_en'] = 'Most recent Links';
$local['title_fr'] = 'liens r&eacute;cents';
$title = i18n::user('title');
$items = Links::list_by_date(0, 10);
$text = Skin::build_list($items, 'compact');
$context['text'] .= Skin::build_box($title, $text, 'navigation');

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

This function masks links fetched from external feeds, by ensuring the action code is not 'link:feed'.

Voir aussi:

list_by_date_for_anchor() - List newest links for one anchor

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

$anchor - int the id of the anchor
$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='no_anchor' - string the list variant, if any
$capability='?' - string actual surfer capability ('?', 'M', or 'A')
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Example:

include_once 'links/links.php';
$items = Links::list_by_date_for_anchor('section:12', 0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

Voir aussi:

list_by_date_for_author() - List newest links for one author

function &list_by_date_for_author($author_id, $offset=0, $count=20, $variant='no_author')

$author_id - int the id of the author of the link
$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='no_author' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Example:

include_once 'links/links.php';
$items = Links::list_by_date_for_author(12, 0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

list_by_hits() - List most read links

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
$count=10 - int the number of items to display
$variant='hits' - string the list variant, 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 links in your main index page, just use Links::list_by_hits(0, 10)

Example:

include_once '../links/links.php';
$context['text'] .= Skin::build_list(Links::list_by_hits(), 'compact');

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

Voir aussi:

index.php

list_by_hits_for_author() - List most popular links for one author

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

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

Example:

include_once 'links/links.php';
$items = Links::list_by_hits_for_author(12, 0, 10);
$context['text'] .= Skin::build_list($items, 'compact');

list_by_title_for_anchor() - List links by title for one anchor

function &list_by_title_for_anchor($anchor, $offset=0, $count=10, $variant='no_anchor', $capability='?')

$anchor - int the id of the 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='no_anchor' - string the list variant, if any
$capability='?' - string actual surfer capability ('?', 'M', or 'A')
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Example:

include_once '../links/links.php';
$items = Links::list_by_title_for_anchor('article:12');
$context['text'] .= Skin::build_list($items, 'decorated');

Voir aussi:

list_news() - List links received from newsfeeders

function &list_news($offset=0, $count=10, $variant='dates')

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

This function is used to show most recent news received from the net. It restricts the lookup to links that have the action code 'link:feed'.

Voir aussi:

feeds/feeds.php

list_selected() - List selected links

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 an array of $url => ($prefix, $label, $suffix, $icon)

Accept following variants:

'compact' - to build short lists in boxes and sidebars (this is the default)
'dates' - short lists with stamps
'hits' - short lists with hits information
'no_anchor' - to build detailed lists in an anchor page
'no_author' - to build detailed lists in an author page
'full' - include anchor information
'search' - include anchor information
'review' - like 'full', but provide the actual link

ping() - Ping back links referenced in some text

function ping($text, $anchor)

$text - string the referencing text that has to be scanned
$anchor - string the local anchor of the referencing text (e.g., 'article:124')
returns array list($links, $created, $advertised, $skipped)

This is the client implementation of trackback and pingback specifications.

This function is triggered by publishing scripts, either articles/publish.php, services/blog.php, agents/messages.php or agents/uploads.php.

It is used to efficiently link pages across a set of web sites according to the following mechanism:

The list of external links is built for this page
Only the 7 first links are kept from the list; others are stripped
If links do not exist, create additional records in the table used for links
Each link (actually, only the 7 most recent) is checked, to see if it's trackback- or pingback-enabled or not
Each trackback-/pingback-enabled link is activated, providing the full URL of the anchor page

We are claiming to support most of the trackback client interface here, as described in the trackback specification. A foreign page is considered as being trackback-enabled if it has a special RDF section linking its reference (i.e., URL) to a Trackback Ping URL.

Note that YACS also implements the server part of the trackback specification in links/trackback.php, which supports POST REST calls.

We are claiming to fully support the pingback client interface here, as described in the pingback specification. A foreign page is considered to be pingback-enabled if it has a meta link to a Pingback Ping URL.

Note that YACS also implements the server part of the pingback specification in services/ping.php, which supports XML-RPC calls.

This function transforms every YACS codes into HTML before extracting links, and before submitting the excerpt to remote site.

Voir aussi:

ping_as_pingback() - Attempt to use the pingback interface

function ping_as_pingback($text, $source, $target)

$text - string - some text, extracted from the target site, to extract the broker URL, if any
$source - string - the source address
$target - string - the target address from which the text has been extracted
returns TRUE if the target site has been pinged back, FALSE otherwise

Voir aussi:

Pingback specification

ping_as_trackback() - Attempt to use the trackback interface

function ping_as_trackback($text, $source, $target, $title='', $excerpt='', $blog_name='')

$text - string some text, extracted from the target site, to extract the broker URL, if any
$source - string the source address
$target - string the target address from which the text has been extracted
$title='' - string title of the source page
$excerpt='' - string excerpt of the source page
$blog_name='' - string blog name of the source page
returns TRUE if the target site has been pinged back, FALSE otherwise

Voir aussi:

TrackBack Technical Specification

post() - Post a new link or an updated link

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

Voir aussi:

purge_old_news() - Cap the number of news in the database

function purge_old_news($limit=1000)

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

This function deletes oldest entries going beyond the given threshold. Links coming from feeders are located by the special value 'link:feed' in the field edit action.

Note that if a link is collected from a feeder, and if it is modified afterwards, then the edit-action field is changed to 'link:update', meaning it is not condidered as some news anymore. This link won't appear at the front page anymore, and won't be purged either. Any change to a news link makes it become an ordinary and permanent link.

Voir aussi:

search() - Search for some keywords in all links

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)

Voir aussi:

search.php

setup() - Create tables for links

function setup()

Voir aussi:

control/setup.php

stat() - Get some statistics

function &stat()

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

Voir aussi:

links/index.php

stat_for_anchor() - Get some statistics for one anchor

function &stat_for_anchor($anchor)

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

Voir aussi:

transform_reference() - Reference another page at this site

function transform_reference($text)

$text - string any string, maybe with a local reference in it
returns an array($url, $title, $description) or NULL

The function transforms a local reference (e.g;, [user=2]) to an actual link relative to the YACS directory (e.g., users/view.php/2), adds a title and, sometimes, set a description as well.

Voir aussi: