ratatoeskr/frontend.php

All the stuff for the frontend (i.e. what the visitor of the website sees).

License

This file is part of Ratatöskr.  Ratatöskr is licensed unter the MIT / X11 License.  See “ratatoeskr/licenses/ratatoeskr” for more information.

Summary
ratatoeskr/frontend.phpAll the stuff for the frontend (i.e.
Functions
section_transform_steTransforms an Section object to an array, so it can be accessed via a STE template.
tag_transform_steTransforms an Tag object to an array, so it can be accessed via a STE template.
article_transform_steTransforms an Article object to an array, so it can be accessed via a STE template.
comment_transform_steTransforms an Comment object to an array, so it can be accessed via a STE template.
STE Tags
articles_getGet articles by custom criterias.
section_listIterate over all sections.
article_comments_countGet the number of comments for an article.
article_commentsList all comments for an article.
comment_formGenerates a HTML form tag that allows the visitor to write a comment.
Page controlThese tags can create links to the previous/next page.
languagesList all languages available in the current context.
styles_loadLoad all current styles.
titleGenerate a HTML title tag for your site.
on_articleExecute tag content, if currently an article is requested.
on_tagExecute tag content, if currently a tag is requested.
on_sectionExecute tag content, if currently a section is requested.
STE Variables
$currentHolds information about the current page in the frontend (the part of the webpage, the visitor sees).
$languageThe short form (e.g.
Functions
frontend_url_handler
CommentRejectedAn Exeption a comment validator can throw, if the validation failed.

Functions

section_transform_ste

function section_transform_ste($section,
$lang)

Transforms an Section object to an array, so it can be accessed via a STE template.

Parameters

$sectionSection object.
$langThe current language.

Returns

Array with these fields:

  • id - The ID of the section.
  • name - The name of the section.
  • title - The title of the section in the current language
  • __obj - The Section object.  Useful for plugins, so they do not need to fetch the object from the database again.

tag_transform_ste

function tag_transform_ste($tag,
$lang)

Transforms an Tag object to an array, so it can be accessed via a STE template.

Parameters

$sectionTag object.
$langThe current language.

Returns

Array with these fields:

  • id - The ID of the tag.
  • name - The name of the tag.
  • title - The title in the current language.
  • __obj - The Tag object.  Useful for plugins, so they do not need to fetch the object from the database again.

article_transform_ste

function article_transform_ste($article,
$lang)

Transforms an Article object to an array, so it can be accessed via a STE template.

Parameters

$articleArticle object.
$langThe current language.

Returns

Array with these fields:

  • id
  • urlname
  • fullurl
  • title
  • text
  • excerpt
  • custom (array: name=>value)
  • status (numeric)
  • section (sub-fields: section_transform_ste)
  • timestamp
  • tags (array(sub-fields: tag_transform_ste))
  • languages (array: language name=>url)
  • comments_allowed
  • __obj - Useful for plugins, so they do not need to fetch the object from the database again.

comment_transform_ste

function comment_transform_ste($comment)

Transforms an Comment object to an array, so it can be accessed via a STE template.

Parameters

$commentComment object.

Returns

Array with these fields:

  • id
  • text
  • author
  • timestamp

STE Tags

articles_get

Get articles by custom criterias.  Will only get articles, that are available in the current language ($language).  The fields of an article can be looked up at article_transform_ste.

Parameters

var(mandatory) The name of the variable, where the current article should be stored at.
id(optional) Filter by ID.
urlname(optional) Filter by urlname.
section(optional) Filter by section (section name).
sectionvar(optional) Filter by section (Name of variable that contains a section).
status(optional) Filter by status (numeric, ARTICLE_STATUS_).
tag(optional) Filter by tag (tag name).
tagvar(optional) Filter by tag (Name of variable that contains a tag).
sort(optional) How to sort.  Format: “fieldname direction” where fieldname is one of [id, urlname, title, timestamp] and direction is one of [asc, desc].
perpage(optional) How many articles should be shown per page (default unlimited).
page(optional) On which page are we (starting with 1).  Useful in combination with $current[page], page_prev and page_next.  (Default: 1)
maxpage(optional) (variable name) If given, the number of pages are stored in this variable.
skip(optional) How many articles should be skipped?  (Default: none)
count(optional) How many articles to output.  (Default unlimited)

Tag Content

The tag’s content will be executed for every article.  The current article will be written to the variable specified by the var parameter before.

Returns

All results from the tag content.

section_list

Iterate over all sections.  The fields of a section can be looked up at section_transform_ste.

Parameters

var(mandatory) The name of the variable, where the current section should be stored at.
exclude(optional) Sections to exclude
include_default(optional) Should the default section be included (default: No).

Tag Content

The tag’s content will be executed for every section.  The current section will be written to the variable specified by the var parameter before.

Returns

All results from the tag content.

article_comments_count

Get the number of comments for an article.

Parameters

article(mandatory) The name of the variable, where the article is stored at.

Returns

The number of comments.

article_comments

List all comments for an article.  The fields of a comment can be looked up at comment_transform_ste.

Parameters

var(mandatory) The name of the variable, where the current comment should be stored at.
article(mandatory) The name of the variable, where the article is stored at.
sort(optional) Should the comments be sorted chronologically (asc) or inverse (desc)?  Default: asc

Tag Content

The tag’s content will be executed for every comment.  The current comment will be written to the variable specified by the var parameter before.

Returns

All results from the tag content.

comment_form

Generates a HTML form tag that allows the visitor to write a comment.

Parameters

article(mandatory) The name of the variable, where the article is stored at.
default(optional) If not empty, a default formular with the mandatory fields will be generated.
previewbtn(optional) If not empty and default form is choosen, a preview button will also be generated.

Tag Content

The tag’s content will be written into the HTML form tag.  You have at least to define these fields:

  • <input type=”text” name=”author_name” /> - The Name of the author.
  • <input type=”text” name=”author_mail” /> - The E-Mailaddress of the author.
  • <textarea name=”comment_text”></textarea> - The Text of the comment.
  • <input type=”submit” name=”post_comment” /> - Submit button.

You might also want to define this

  • <input type=”submit” name=”preview_comment” /> - For a preview of the comment.

If the parameter default is not empty, the tag’s content will be thrown away.

Returns

The finished HTML form.

See Also

The “prevcomment” field in $current.

Page control

These tags can create links to the previous/next page.

page_prevLink to the previous page (if available).
page_nextLink to the next page (if available).

Parameters

current(mandatory) The current page number.
maxpage(mandatory) How many pages in total?
default(optional) If not empty, a default localized link text will be used.

Tag Content

The tag’s content will be used as the link text.

Returns

A Link to the previous / next page.

languages

List all languages available in the current context.

Parameters

var(mandatory) The name of the variable, where the current language information should be stored at.

Sub-fields of var

short2 letter code of language
fullnameThe full name of the language
urlURL to the current page in this language

Tag Content

The tag’s content will be executed for every language.  The current language will be written to the variable specified by the var parameter before.

Returns

All results from the tag content.

styles_load

Load all current styles.

Parameters

mode(optional) Either “embed” or “link”.  Default: link

Returns

The current styles (either linked or embedded)

title

Generate a HTML title tag for your site.

Tag Content

The name of your site.

Returns

A HTML title tag that describes the current (sub)page.

on_article

Execute tag content, if currently an article is requested.

Parameters

var(optional) If set, the article will be stored in the variable with that name (see article_transform_ste for sub-fields).

Returns

The executed tag content, if an article was requested.

on_tag

Execute tag content, if currently a tag is requested.

Parameters

var(optional) If set, the tag will be stored in the variable with that name (see tag_transform_ste for sub-fields).

Returns

The executed tag content, if a tag was requested.

on_section

Execute tag content, if currently a section is requested.

Parameters

var(optional) If set, the section will be stored in the variable with that name (see section_transform_ste for sub-fields).

Returns

The executed tag content, if a section was requested.

STE Variables

$current

Holds information about the current page in the frontend (the part of the webpage, the visitor sees).

$current has these fields

  • article - Only set if a single article is shown.  Holds information about an article.  (sub-fields are described at article_transform_ste).
  • section - Only set if a whole section is shown.  Holds information about an section.  (sub-fields are described at section_transform_ste).
  • tag - Only set if all articles with the same tag should be shown (pseudo section _tags).  Holds information about a tag.  (sub-fields are described at tag_transform_ste).
  • page - Which subpage is shown?  Useful with page_prev, page_next and the page parameter of articles_get.  Default: 1
  • commented - True, if the visitor has successfully written a comment.
  • comment_fail - If the user tried to comment, but the system rejected the comment, this will be set and will contain the error message.
  • comment_prev - If the user wanted to preview the article, this will be set and contain the HTML code of the comment.
  • styles - The styles, that should be loaded.  You can also just use styles_load.
  • url_fragments - Array of URL parts.  Mainly used internally, so you really should not modify this one...
  • oldcomment - The data of the previously sent formular (subfields: name, mail, text).  Only set inside the comment_form tag.

Plugins might insert their own $current fields.

$language

The short form (e.g.  “en” for English, “de” for German, ...) of the current language.

Functions

frontend_url_handler

function frontend_url_handler(&$data,
$url_now,
&$url_next)

CommentRejected

An Exeption a comment validator can throw, if the validation failed.

See Also

<register_comment_validator>

function section_transform_ste($section,
$lang)
Transforms an Section object to an array, so it can be accessed via a STE template.
Representing a section
function tag_transform_ste($tag,
$lang)
Transforms an Tag object to an array, so it can be accessed via a STE template.
Representation of a tag
function article_transform_ste($article,
$lang)
Transforms an Article object to an array, so it can be accessed via a STE template.
Representation of an article
function comment_transform_ste($comment)
Transforms an Comment object to an array, so it can be accessed via a STE template.
Representing a user comment
function frontend_url_handler(&$data,
$url_now,
&$url_next)
Possible Article::$status values.
Link to the previous page (if available).
Link to the next page (if available).
Holds information about the current page in the frontend (the part of the webpage, the visitor sees).
Get articles by custom criterias.
Load all current styles.
Generates a HTML form tag that allows the visitor to write a comment.
Close