API

API for developers. We developers.

Objects

The following objects are available in Datenstrom Yellow:

$yellow->page gives access to current page
$yellow->pages gives access to pages from file system
$yellow->files gives access to files from file system
$yellow->plugins gives access to plugins
$yellow->themes gives access to themes
$yellow->config gives access to configuration
$yellow->text gives access to text
$yellow->toolbox gives access to toolbox with helpers

Yellow page

Yellow page gives access to current page:

$yellow->page->get($key)
Return page meta data

$yellow->page->getHtml($key)
Return page meta data, HTML encoded

$yellow->page->getDate($key, $format = "")
Return page meta data as language specific date

$yellow->page->getDateHtml($key, $format = "")
Return page meta data as language specific date, HTML encoded

$yellow->page->getDateFormatted($key, $format)
Return page meta data as custom date

$yellow->page->getDateFormattedHtml($key, $format)
Return page meta data as custom date, HTML encoded

$yellow->page->getContent($rawFormat = false, $sizeMax = 0)
Return page content, HTML encoded or raw format

$yellow->page->getParent()
Return parent page of current page, null if none

$yellow->page->getParentTop($homeFailback = true)
Return top-level page for current page, null if none

$yellow->page->getSiblings($showInvisible = false)
Return page collection with pages on the same level as current page

$yellow->page->getChildren($showInvisible = false)
Return page collection with child pages of current page

$yellow->page->getPages()
Return page collection with additional pages for current page

$yellow->page->getPage($key)
Return related page

$yellow->page->getBase($multiLanguage = false)
Return page base

$yellow->page->getLocation($absoluteLocation = false)
Return page location

$yellow->page->getUrl()
Return page URL

$yellow->page->getExtra($name)
Return page extra HTML data

$yellow->page->getHeader($key)
Return page response header

$yellow->page->getModified($httpFormat = false)
Return page modification date, Unix time or HTTP format

$yellow->page->getLastModified($httpFormat = false)
Return last modification date, Unix time or HTTP format

$yellow->page->getStatusCode($httpFormat = false)
Return page status code, number or HTTP format

$yellow->page->error($statusCode, $pageError = "")
Respond with error page

$yellow->page->clean($statusCode, location = "")
Respond with status code, no page content

$yellow->page->isAvailable()
Check if page is available

$yellow->page->isVisible()
Check if page is visible

$yellow->page->isActive()
Check if page is within current request

$yellow->page->isCacheable()
Check if page is cacheable

$yellow->page->isError()
Check if page with error

$yellow->page->isHeader($key)
Check if response header exists

$yellow->page->isExisting($key)
Check if page meta data exists

$yellow->page->isPage($key)
Check if related page exists

Here's an example snippet for showing page content:

<div class="content">
<div class="main">
<h1><?php echo $yellow->page->getHtml("titleContent") ?></h1>
<?php echo $yellow->page->getContent() ?>
</div>
</div>

Here's an example snippet for showing page content with additional meta data:

<div class="content">
<div class="main">
<h1><?php echo $yellow->page->getHtml("titleContent") ?></h1>
<?php echo $yellow->page->getContent() ?>
<p><?php echo $yellow->page->getHtml("author") ?></p>
</div>
</div>

Here's an example snippet for showing page content with additional tags:

<div class="content">
<div class="main">
<h1><?php echo $yellow->page->getHtml("titleContent") ?></h1>
<?php echo $yellow->page->getContent() ?>
<?php if($yellow->page->isExisting("tag")): ?>
<p>
<?php foreach(preg_split("/\s*,\s*/", $yellow->page->get("tag")) as $tag): ?>
<?php if(++$tagCounter>1) echo ", "; echo htmlspecialchars($tag) ?>
<?php endforeach ?>
</p>
<?php endif ?>
</div>
</div>

Yellow page collection

Yellow page collection gives access to these functions:

$pages->filter($key, $value, $exactMatch = true)
Filter page collection by meta data

$pages->match($regex = "/.*/")
Filter page collection by file name

$pages->sort($key, $ascendingOrder = true)
Sort page collection by meta data

$pages->similar($page, $ascendingOrder = false)
Sort page collection by meta data similarity

$pages->merge($input)
Merge page collection

$pages->append($page)
Append to end of page collection

$pages->prepend($page)
Prepend to start of page collection

$pages->limit($pagesMax)
Limit the number of pages in page collection

$pages->reverse()
Reverse page collection

$pages->shuffle()
Randomize page collection

$pages->pagination($limit, $reverse = true)
Paginate page collection

$pages->getPaginationNumber()
Return current page number in pagination

$pages->getPaginationCount()
Return highest page number in pagination

$pages->getPaginationLocation($absoluteLocation = true, $pageNumber = 1)
Return location for a page in pagination

$pages->getPaginationPrevious($absoluteLocation = true)
Return location for previous page in pagination

$pages->getPaginationNext($absoluteLocation = true)
Return location for next page in pagination

$pages->getPagePrevious($page)
Return previous page in collection, null if none

$pages->getPageNext($page)
Return next page in collection, null if none

$pages->getFilter()
Return current page filter

$pages->getModified($httpFormat = false)
Return page collection modification date, Unix time or HTTP format

$pages->isPagination()
Check if there is a pagination

Here's an example snippet for showing three random pages:

<?php $pages = $yellow->pages->index() ?>
<ul>
<?php foreach($pages->shuffle()->limit(3) as $page): ?>
<li><?php echo $page->getHtml("title") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing latest pages:

<?php $pages = $yellow->pages->index() ?>
<ul>
<?php foreach($pages->sort("modified", false) as $page): ?>
<li><?php echo $page->getHtml("title") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing all pages with draft status:

<?php $pages = $yellow->pages->index(true, true) ?>
<ul>
<?php foreach($pages->filter("status", "draft") as $page): ?>
<li><?php echo $page->getHtml("title") ?></li>
<?php endforeach ?>
</ul>

Yellow pages

Yellow pages gives access to pages from file system:

$yellow->pages->find($location, $absoluteLocation = false)
Return page from file system, null if not found

$yellow->pages->index($showInvisible = false, $multiLanguage = false, $levelMax = 0)
Return page collection with all pages

$yellow->pages->top($showInvisible = false)
Return page collection with top-level navigation

$yellow->pages->path($location, $absoluteLocation = false)
Return page collection with path ancestry

$yellow->pages->multi($location, $absoluteLocation = false, $showInvisible = false)
Return page collection with multiple languages

$yellow->pages->clean()
Return page collection that is empty

Here's an example snippet for showing all pages:

<?php $pages = $yellow->pages->index(true, true) ?>
<?php $yellow->page->setLastModified($pages->getModified()) ?>
<ul>
<?php foreach($pages as $page): ?>
<li><?php echo $page->getHtml("title") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing pages below a specific location:

<?php $pages = $yellow->pages->find("/help/")->getChildren(true) ?>
<?php $yellow->page->setLastModified($pages->getModified()) ?>
<ul>
<?php foreach($pages as $page): ?>
<li><?php echo $page->getHtml("title") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing top-level navigation pages:

<?php $pages = $yellow->pages->top() ?>
<?php $yellow->page->setLastModified($pages->getModified()) ?>
<ul>
<?php foreach($pages as $page): ?>
<li><?php echo $page->getHtml("titleNavigation") ?></li>
<?php endforeach ?>
</ul>

Yellow files

Yellow files gives access to files from file system:

$yellow->files->find($location, $absoluteLocation = false)
Return page with media file information, null if not found

$yellow->files->index($showInvisible = false, $multiPass = false, $levelMax = 0)
Return page collection with all media files

$yellow->files->clean()
Return page collection that is empty

Here's an example snippet for showing all media files:

<?php $files = $yellow->files->index(true) ?>
<?php $yellow->page->setLastModified($files->getModified()) ?>
<ul>
<?php foreach($files as $file): ?>
<li><?php echo $file->getLocation(true) ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing latest media files:

<?php $files = $yellow->files->index(true)->sort("modified", false) ?>
<?php $yellow->page->setLastModified($files->getModified()) ?>
<ul>
<?php foreach($files as $file): ?>
<li><?php echo $file->getLocation(true) ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for showing media files of a specific type:

<?php $files = $yellow->files->index(true)->filter("type", "pdf") ?>
<?php $yellow->page->setLastModified($files->getModified()) ?>
<ul>
<?php foreach($files as $file): ?>
<li><?php echo $file->getLocation(true) ?></li>
<?php endforeach ?>
</ul>

Yellow plugins

Yellow plugins gives access to plugins:

$yellow->plugins->get($name)
Return plugin

$yellow->plugins->getData()
Return plugin version

$yellow->plugins->getModified($httpFormat = false)
Return plugin modification date, Unix time or HTTP format

$yellow->plugins->register($name, $plugin, $version, $priority = 0)
Register plugin

$yellow->plugins->isExisting($name)
Check if plugin exists

Here's an example snippet for showing information about plugins:

<ul>
<?php foreach($yellow->plugins->getData() as $key=>$value): ?>
<li><?php echo htmlspecialchars("$key $value") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for checking if plugin exists:

<?php if($yellow->plugins->isExisting("fontawesome")): ?>
<a href="https://twitter.com/username"><i class="fa fa-twitter"></i></a>
<?php else: ?>
<?php $yellow->page->error(500, "Snippet requires 'fontawesome' plugin!") ?>
<?php endif ?>

Here's an example for registering a plugin, see also more example plugins:

<?php
class YellowExample
{
    const VERSION = "0.1.0";
}
$yellow->plugins->register("example", "YellowExample", YellowExample::VERSION);
?>

Yellow themes

Yellow themes gives access to themes:

$yellow->themes->get($name)
Return theme

$yellow->themes->getData()
Return theme version

$yellow->themes->getModified($httpFormat = false)
Return theme modification date, Unix time or HTTP format

$yellow->themes->register($name, $theme, $version, $priority = 0)
Register theme

$yellow->themes->isExisting($name)
Check if theme exists

Here's an example snippet for showing information about themes:

<ul>
<?php foreach($yellow->themes->getData() as $key=>$value): ?>
<li><?php echo htmlspecialchars("$key $value") ?></li>
<?php endforeach ?>
</ul>

Here's an example snippet for checking if theme exists:

<?php if($yellow->themes->isExisting("flatsite")): ?>
<p>Flatsite theme installed.</p>
<?php else: ?>
<?php $yellow->page->error(500, "Snippet requires 'flatsite' theme!") ?>
<?php endif ?>

Here's an example for registering a theme:

class YellowThemeExample
{
    const VERSION = "0.1.0";    
}
$yellow->themes->register("example", "YellowThemeExample", YellowThemeExample::VERSION);
?>

Yellow config

Yellow config gives access to configuration:

$yellow->config->get($key)
Return configuration

$yellow->config->getHtml($key)
Return configuration, HTML encoded

$yellow->config->getData($filterStart = "", $filterEnd = "")
Return configuration strings

$yellow->config->getModified($httpFormat = false)
Return configuration modification date, Unix time or HTTP format

$yellow->config->isExisting($key)
Check if configuration exists

Here's an example snippet for showing static website settings:

<div class="config">
<?php foreach($yellow->config->getData("static") as $key=>$value): ?>
<?php echo htmlspecialchars("$key: $value") ?><br />
<?php endforeach ?>
</div>

Here's an example snippet for showing webmaster settings:

<div class="config">
<?php $author = $yellow->config->get("author") ?>
<?php $email = $yellow->config->get("email") ?>
<?php echo htmlspecialchars("$author - $email") ?>
</div>

Here's an example snippet for checking safe mode:

<div class="config">
<?php $parserSafeMode = $yellow->config->get("parserSafeMode") ?>
Safe mode is <?php echo htmlspecialchars($parserSafeMode ? "on" : "off") ?>.
</div>

Yellow text

Yellow text gives access to text:

$yellow->text->get($key)
Return text string

$yellow->text->getHtml($key)
Return text string, HTML encoded

$yellow->text->getText($key, $language )
Return text string for specific language

$yellow->text->getTextHtml($key, $language )
Return text string for specific language, HTML encoded

$yellow->text->getData($filterStart = "", $language = "")
Return text strings

$yellow->text->getLanguages()
Return languages

$yellow->text->getModified($httpFormat = false)
Return text modification date, Unix time or HTTP format

$yellow->text->isLanguage($language)
Check if language exists

$yellow->text->isExisting($key, $language = "")
Check if text string exists

Here's an example snippet for showing contact text strings:

<div class="text">
<?php foreach($yellow->text->getData("contact") as $key=>$value): ?>
<?php echo htmlspecialchars("$key: $value") ?><br />
<?php endforeach ?>
</div>

Here's an example snippet for checking if language exists:

<div class="text">
<?php $swedish = $yellow->text->isLanguage("sv") ?>
Swedish language <?php echo htmlspecialchars($swedish ? "" : "not") ?> found.
</div>

Here's an example snippet for showing languages and translators:

<div class="text">
<?php foreach($yellow->text->getLanguages() as $language): ?>
<?php echo $yellow->text->getTextHtml("languageDescription", $language) ?> - 
<?php echo $yellow->text->getTextHtml("languageTranslator", $language) ?><br />
<?php endforeach ?>
</div>

Yellow toolbox

Yellow toolbox gives access to toolbox with helpers:

$yellow->toolbox->getLocation($filterStrict = true)
Return location from current HTTP request

$yellow->toolbox->getLocationArgs()
Return location arguments from current HTTP request

$yellow->toolbox->isLocationArgs($location = "")
Check if there are location arguments in current HTTP request

$yellow->toolbox->normaliseArgs($text, $appendSlash = true, $filterStrict = true)
Normalise location arguments

$yellow->toolbox->getDirectoryEntries($path, $regex = "/.*/", $sort = true, $directories = true, $includePath = true)
Return files and directories

$yellow->toolbox->readFile($fileName, $sizeMax = 0)
Read file, empty string if not found

$yellow->toolbox->createFile($fileName, $fileData, $mkdir = false)
Create file

$yellow->toolbox->copyFile($fileNameSource, $fileNameDestination, $mkdir = false)
Copy file

$yellow->toolbox->renameFile($fileNameSource, $fileNameDestination, $mkdir = false)
Rename file

$yellow->toolbox->mergeFile($fileNameSource, $fileNameDestination)
Merge file

$yellow->toolbox->deleteFile($fileName, $pathTrash = "")
Delete file

$yellow->toolbox->deleteDirectory($path, $pathTrash = "")
Delete directory

$yellow->toolbox->modifyFile($fileName, $modified)
Set file modification date, Unix time

$yellow->toolbox->getFileModified($fileName)
Return file modification date, Unix time

$yellow->toolbox->getTextLines($text)
Return lines from text string, including newline

$yellow->toolbox->getTextArgs($text, $optional = "-")
Return arguments from text string, space separated

Here's an example snippet for showing location and arguments of HTTP request:

<div class="toolbox">
<?php echo htmlspecialchars($yellow->toolbox->getLocation()) ?><br />
<?php foreach($_REQUEST as $key=>$value): ?>
<?php echo htmlspecialchars("$key: $value") ?><br />
<?php endforeach ?>
</div>

Here's an example snippet for showing files in a directory:

<div class="toolbox">
<?php $path = $yellow->config->get("configDir") ?>
<?php foreach($yellow->toolbox->getDirectoryEntries($path, "/.*/", true, false) as $entry): ?>
<?php echo htmlspecialchars($entry) ?><br />
<?php endforeach ?>
</div>

Here's an example snippet for reading text lines from file:

<div class="toolbox">
<?php $fileName = $yellow->config->get("configDir").$yellow->config->get("robotsFile") ?>
<?php $fileData = $this->yellow->toolbox->readFile($fileName) ?>
<?php foreach($this->yellow->toolbox->getTextLines($fileData) as $line): ?>
<?php echo htmlspecialchars($line) ?><br />
<?php endforeach ?>
</div>

Events

The following events are available:

function onLoad($yellow)
Handle initialisation

function onStartup($update)
Handle startup

function onRequest($scheme, $address, $base, $location, $fileName)
Handle request

function onParseMeta($page)
Handle page meta data parsing

function onParseContentRaw($page, $text)
Handle page content parsing of raw format

function onParseContentBlock($page, $name, $text, $shortcut)
Handle page content parsing of custom block

function onParseContentText($page, $text)
Handle page content parsing

function onParsePage()
Handle page parsing

function onExtra($name)
Handle page extra HTML data

function onEditUserRestrictions($email, $location, $fileName, $users)
Handle user restrictions

function onEditUserAccount($email, $password, $action, $users)
Handle user account changes

function onEditContentFile($page, $action)
Handle content file editing

function onCommand($args)
Handle command

function onCommandHelp()
Handle command help

function onShutdown()
Handle shutdown

Here's the normal sequence of events:

onLoad -----▶ onStartup -----▶ onRequest
                  |                |
                  |                |---------------------
                  |                |                    |
                  ▼                ▼                    ▼
              onCommand        onParseMeta          onEditUserRestrictions
              onCommandHelp    onParseContentRaw    onEditUserAccount
                  |            onParseContentBlock  onEditContentFile
                  |            onParseContentText       |
                  |            onParsePage              |
                  |            onExtra                  |
                  ▼                |                    |
exit ◀------- onShutDown ◀-------------------------------

When a page is displayed, the plugins are loaded and onLoad will be called. As soon as all plugins are loaded onStartup will be called. After that the core informs with onRequest that there's a request. Then pages can be analysed with various onParse-events. If an error occurs, an error page will be generated. Finally the page is output and onShutdown will be called.

Here's an example plugin for generating HTML with an [example] shortcut:

<?php
class YellowExample
{
    const VERSION = "0.1.1";
    var $yellow;
 
    // Handle initialisation
    function onLoad($yellow)
    {
        $this->yellow = $yellow;
    }
 
    // Handle page content parsing of custom block
    function onParseContentBlock($page, $name, $text, $shortcut)
    {
        $output = null;
        if($name=="example" && $shortcut)
        {
            $output = "<div class=\"".htmlspecialchars($name)."\">";
            $output .= "Add more HTML code here";
            $output .= "</div>";
        }
        return $output;
    }
}
$yellow->plugins->register("example", "YellowExample", YellowExample::VERSION);
?>

Here's an example plugin for including files example.css and example.js:

<?php
class YellowExample
{
    const VERSION = "0.1.2";
    var $yellow;
 
    // Handle initialisation
    function onLoad($yellow)
    {
        $this->yellow = $yellow;
    }
 
    // Handle page extra HTML data
    function onExtra($name)
    {
        $output = null;
        if($name=="header")
        {
            $pluginLocation = $this->yellow->config->get("serverBase").
            $pluginLocation .= $this->yellow->config->get("pluginLocation");
            $output = "<link rel=\"stylesheet\" type=\"text/css\" media=\"all\" href=\"{$pluginLocation}example.css\" />\n";
            $output .= "<script type=\"text/javascript\" src=\"{$pluginLocation}example.js\"></script>\n";
        }
        return $output;
    }
}
$yellow->plugins->register("example", "YellowExample", YellowExample::VERSION);
?>

Here's an example plugin for restricting write access for certain users:

<?php
class YellowExample
{
    const VERSION = "0.1.3";
    var $yellow;
 
    // Handle initialisation
    function onLoad($yellow)
    {
        $this->yellow = $yellow;
    }
 
    // Handle user restrictions
    function onEditUserRestrictions($email, $location, $fileName, $users)
    {
        return $users->getHome($email)=="/guests/";
    }
}
$yellow->plugins->register("example", "YellowExample", YellowExample::VERSION);
?>

Formats

The following date formats are available:

YYYY-MM-DD = date starting with the year, e.g. 2013-04-07
YYYY-MM-DD HH:MM:SS = date and time, e.g. 2013-04-07 11:30:00

When dates are displayed on a page they are converted to a language specific date:

dateFormatShort = short date, e.g. April 2013
dateFormatMedium = medium date, e.g. 2013-04-07
dateFormatLong = long date, e.g. 2013-04-07 11:30

When times are displayed on a page they are converted to a language specific time:

timeFormatShort = short time, e.g. 11:30
timeFormatMedium = medium time, e.g. 11:30:01
timeFormatLong = long time, e.g. 11:30:01 GMT+1

When text is displayed you can use one of these encoding functions:

htmlspecialchars($string) = encode text string into HTML format
rawurlencode($string) = encode URL, e.g. hyperlink arguments
strencode($string) = encode string, e.g. JavaScript arguments

Here's an example snippet for encoding HTML arguments:

<?php list($name, $class) = $yellow->getSnippetArgs() ?>
<?php if(empty($class)) $class = "regular" ?>
<img src="https://unsplash.it/210/140/?random" class="<?php echo htmlspecialchars($class) ?>" />

Here's an example snippet for encoding hyperlink arguments:

<?php list($name, $id) = $yellow->getSnippetArgs() ?>
<?php if(empty($id)) $id = "821" ?>
<img src="https://unsplash.it/210/140/?image=<?php echo rawurlencode($id) ?>" />

Here's an example snippet for encoding JavaScript arguments:

<?php list($name, $message) = $yellow->getSnippetArgs() ?>
<?php if(empty($message)) $message = "Hello world" ?>
<script type="text/javascript">
console.log("<?php echo strencode($message) ?>");
</script>

Debugging

Open the file system/plugins/core.php, change first line to <?php define("DEBUG", 1);

YellowCore::sendPage Content-Type: text/html; charset=UTF-8
YellowCore::sendPage Page-Modified: Fri, 30 Jan 2015 09:30:12 GMT
YellowCore::sendPage Last-Modified: Mon, 02 Feb 2015 13:19:03 GMT
YellowCore::sendPage theme:flatsite template:blogpages parser:markdown
YellowCore::processRequest file:content/2-plugins/1-blog/page.txt
YellowCore::request status:200 handler:core time:19 ms

Get file system information by increasing debug level to <?php define("DEBUG", 2);

Datenstrom Yellow 0.7.1, PHP 5.6.30, Apache/2.4.25 Darwin
YellowConfig::load file:system/config/config.ini
YellowText::load file:system/plugins/language-de.txt
YellowText::load file:system/plugins/language-en.txt
YellowText::load file:system/plugins/language-fr.txt
YellowUsers::load file:system/config/user.ini
YellowText::load file:system/config/text.ini

Get maximum information by increasing debug level to <?php define("DEBUG", 3);

Datenstrom Yellow 0.7.1, PHP 5.6.30, Apache/2.4.25 Darwin
YellowConfig::load file:system/config/config.ini
YellowConfig::load Sitename:Datenstrom developers
YellowConfig::load Author:Datenstrom
YellowConfig::load Email:webmaster
YellowConfig::load Language:en
YellowConfig::load Timezone:Europe/Stockholm
YellowConfig::load Theme:flatsite

We run automatic tests and code analysis.

Tips and tricks

Some tips for developers:

  1. Install the developer kit. The developer kit for Datenstrom Yellow includes plugins, themes and examples. You can try out how to make small web pages, blogs and wikis. It's a great place to get started.

  2. Learn the web basics. Make yourself familiar with HTML, CSS and JavaScript. These are the most important things you need to know to make websites. You don't need to learn any complex frameworks or libraries.

  3. Put your code on GitHub. Create a repository for each new plugin/theme. The name of your repository should be yellow-plugin-xyz or yellow-theme-xyz. Your code doesn't have to be perfect, but it should be working in the developer kit.