Sitelib Documentation
Sitelib is a library that encapsulates code that is often used in siteseed interfaces. This includes mainly database queries in order to achieve a higher level of abstraction and to be more independent of possible database changes in the future. This article explains all library functions and provides examples for their proper usage.
It is not yet part of one of the official releases, but is already available in the CVS snapshot on http://www.sourceforge.org. Here's an overview of the current library functions written in PHP. The library itself has to be included in an interface with
<?php include("include/sitelib.php"); ?>
- section
section -- returns information of a given section.
Description
array section ( int section_id )
section() returns an array with information related to the section provided by section_id. That information is needed in order to create a navigation and to label your section pages.
Result array:
$result['id'] -- same section ID as given by section_id
$result['parent'] -- parent ID of current section. May be used for back navigation
$result['name'] -- name of section given by section_id with htmlentities() already applied to
$result['path'] -- Static path of section (if available, otherwise empty string)
$result['visible'] -- (bool) is current section visible? Only used by Sitlib functions
Examples
<?php
$info = section(5);
/* print name of section #5 */
echo '<h1>' . $info['name'] . '</h1>';
?>
<?php
/* get information for current and parent section */
$current_section = section($id);
$parent_section = section($current_section['parent']);
/* back navigation to parent section */
echo "<a href=\"/?id=$parent_section['id']\">back to $parent_section['name']</a>';
?>
- sectionlevel
sectionlevel -- returns depth of section (relative to section tree) provided by id.
Description
int sectionlevel ( int id )
sectionlevel() returns '0' for the default section (homepage). Sections that are a level deeper (all sections with parent ID equal to '0') will return '1', etc... This can also be used to create a navigation or layout depending on the current section level. See also parentsection() example #1.
Examples
<?php
/* check section level */
if( sectionlevel($id) == 2 )
{
/* print layout for level 2 */
echo $layout;
}
?>
- parentsection
parentsection -- returns a parent id of the section provided by id.
Description
int parentsection ( int id [, int levelsup ])
parentsection() returns a parent section of the section given by id. The optional parameter levelsup defines the distance between id and levelsup. Parameter levelsup defaults to '1'. In this case it's equivalent to section(). Also compare section() example #2 with example #2 below.
Example
<?php
/* check section level */
if( sectionlevel($id) >= 2 )
{
/* print back navigation 2 levels up */
echo "<a href=\"/?id=" . parentsection($id, 2) . "\">two levels up</a>';
}
?>
<?php
/* back navigation to parent section */
echo "<a href=\"/?id=" . parentsection($id) . "\">back to parent section</a>';
?>
- subsections
subsections -- returns the subsections of the section provided by parent_id.
Description
array subsections ( int parent_id [, string link_prefix [, string link_postfix [, bool use_static_paths_if_available [, bool only_consider_visible_sections ]]]])
subsections() returns the subsection information of the current section provided by parent_id. The returned result is an array that both keeps the prepared data suitable to be processed by a loop and the original db query. Optional parameters are link_prefix, link_postfix, use_static_paths_if_available, and only_consider_visible_sections. If use_static_paths_if_available equals to true, the static path, if available, is used to create the link to the subsection, in all other cases link_prefix and link_postfix are used to generate links to the subsections. only_consider_visible_sections allows to only consider sections set to visible using Siteseed's Section Editor. link_prefix defaults to '?id=', link_postfix to an empty string, use_static_paths_if_available and only_consider_visible_sections to true. If you want to create a navigation based on your section structure, subsections() is your way to go.
Result array:
$result[$index]['id'] -- same section ID as given by section_id
$result[$index]['parent_id'] -- parent ID of current section. May be used for back navigation
$result[$index]['name'] -- name of section given by section_id with htmlentities already applied to.
$result[$index]['path'] -- static path of section (if available, otherwise empty string)
$result[$index]['link'] -- link to subsection
$result['query'] -- complete MySQL result query.
$result['number_of_sections'] -- number of sections. May be used for loops.
$result[$index]['link'] (given that no static path is used) is equivalent to "<a href=\"$link_prefix14link_postfix\">" . $result[$index]['name'] . "</a>";
Example
<?php
/* print menu for subsections */
$current_subsections = subsections($id, '/?id=');
for($index = 1; $index <= $current_subsections['number_of_sections']; $index++)
{
echo $current_subsections[$index]['link'];
echo '<br>\n';
}
?>
- function sectionname($section_id='')
sectionname -- returns the section name
Description
string sectionname ( [ int section_id ])
sectionname() returns the section name given by section_id with htmlentities already applied to. Optional parameter section_id defaults to empty string. sectionname() is almost identical with area_name(). If section_id is not of type integer, the current section provided by global $id is assumed. Also compare section() example #1 with example below.
Example
<?php
/* print current section name */
echo sectionname();
?>
- breadcrumbs
breadcrumbs -- outputs the html code for a back-navigation bar (also known as breadcrumbs)
Description
string breadcrumbs ( [ string link_prefix [, string link_postfix [, string separator [, int offset [, bool use_static_paths_if_available ]]]]])
breadcrumbs() outputs the html code for a back-navigation bar also known as breadcrumbs (derived from the Grimm Brothers' tale Hansel and Gretel.) E.g. Sports / Basketball / Players / Michael Jordan / ...
All parameters are optional. link_prefix defaults to '?id=', link_postfix to an empty string, separator to '/', offset to '0', and use_static_paths_if_available to true. link_prefix and link_postfix (see subsections()) are used to generate breadcrumb links, as long as no static path is available or use_static_paths_if_available is set to false. separator defines the section separator. If there is an offset, the breadcrumb is assembled starting from position 'offset +1'. E.g. offset=1 would result in ignoring the homepage (default section).
Example
<?php
/* generate breadcrumbs */
$backnavi = breadcrumbs();
if($backnavi != "")
{
echo $backnavi;
}
else
{
/* in case of default section, print non breaking space */
/* e.g. to preserve layout. */
echo ' ';
}
?>
- sectionbutton
sectionbutton -- outputs the html code for a button
Description
string sectionbutton ( string image_1, string image_2, int section_id [, string link_prefix [, string link_postfix [, string alt='' ]]]])
sectionbutton() outputs the html code for a button with image_1, if section_id is the current section given by global $id. Otherwise it outputs a button with $image_2. Optional parameters are link_prefix, link_postfix, separator, and alt. link_prefix defaults to '?id=', all other optional parameters to an empty string. link_prefix and link_postfix are used to generate links, alt is used as value for the alt parameter of the <img> tag.
sectionbutton() allowes to generate links with images depending on $id. This allows e.g to adjust link buttons to different layouts.
Example
<?php
/* print section button depending on section #1 */
echo sectionname("image1.gif", "image2.gif", 1);
?>
<?php
/* same problem like above, but solved with different approach */
if($id == 1)
{
echo "<a href=\"?id=$id\"><img src=\"image_1.gif\" border=0 alt=\"\"></a>";
}
else
{
echo "<a href=\"?id=$id\"><img src=\"image_2.gif\" border=0 alt=\"\"></a>";
}
?>
- subjectid
subjectid -- returns the first subject id of a given article
Description
int subjectid ( int article )
subjectid() returns the first subject id of an article given by article. Additional subjects are ignored, if more than one subjects are assigned to the given article.
This allows to set the section ID depending on the subject assigned to an article. Why is this needed? A section is usually called by an URL that keeps the reqested section id in its query string e.g. http://www.siteseed.de/?id=4. In this case id (section id) is used to generate layout depending on the current section. But if an article like http://www.siteseed.de/$article=14&visual=1 is called without an id, siteseed doesn't know what layout to generate to use. One could of course hard code the id, but it's more elegant and flexible, if one may derive the section from the subject name. But keep in mind, if you don't provide a section id, the default interface is taken.
Example
<?php /* place this at the very top of your interface */
/* init mode variables, can be used for layout */
$section_mode = true;
$article_mode = false;
/* check for article mode */
if($article > 0)
{
$section_mode = false;
$article_mode = true;
}
/* get section id by article subject id */
if($article_mode == true)
{
$subjectid = subjectid($article);
switch($subjectid)
{
case 1: /* subject #1 */
$id = 11;
break;
case 2: /* subject #2 */
$id = 13;
break;
}
}
?>
- allsubjectids
allsubjectids -- returns a string containing all subject ids
Description
string allsubjectids ( int article [, string separator ])
subjectid() returns all subject ids of an article given by article that are assigned to it. The subject ids are separated by the optional parameter separator. Default value of separator is ','. See also subjectid().
Example
<?php
/* get all subject ids of article and store */
/* them in an array */
$subjectids = explode(",", allsubjectids($article) );
?>
- subjectname
subjectname -- returns the first subject name of an article
Description
string subjectname ( int article )
subjectname() returns the first subject name of the article defined by article. Additional subjects are ignored. This allows to label an article with its subject name. The output is exactely like what's stored in the database, so it's a good idea to apply htmlentities() on the it. Compare with subjectnamebyid().
Example
<?php
/* get subject name of article and output it */
echo htmlentities( subjectname($article) );
?>
- allsubjectnames
allsubjectnames -- returns a string containing all subject names an article.
Description
string allsubjectnames ( int article [, string separator ])
allsubjectnames() returns a string containing all subject names of article defined by article. Subject names are separated by the content of optional parameter separator. Default value of separator is ','. This can be used to display all subjects assigned to an article.
Example
<?php
/* output all article subjects */
echo allsubjectnames($article, "<br>");
?>
- subjectnamebyid
subjectnamebyid -- returns the subject name of a subject id
Description
string subjectnamebyid ( int subjectid )
subjectnamebyid() returns the subject name related to subjectid. This allows to label an article with its subject name (given that you know at least one subject that is assigned to it). Compare with subjectname().
Example
<?php
/* get subject name of article and output it */
echo subjectnamebyid( subjectid($article) );
?>
- more to come...
|
