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 strings
$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, $dateFormat = "")
Return page meta data as language specific date

$yellow->page->getDateHtml($key, $dateFormat = "")
Return page meta data as language specific 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->getFiles($showInvisible = false)
Return page collection with media files for current page

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

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

$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->getDateHtml("modified") ?></p>
</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->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 list($name, $pages) = $yellow->getSnippetArgs() ?>
<?php if(!$pages) $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 pages with draft status:

<?php list($name, $pages) = $yellow->getSnippetArgs() ?>
<?php if(!$pages) $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, $multiLang = 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>

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, 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 media files of a specific type:

<?php $files = $yellow->files->index(true, 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 ?>

Yellow themes

Yellow themes gives access to themes:

$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("blogsite")): ?>
<p>Blogsite theme installed.</p>
<?php else: ?>
<?php $yellow->page->error(500, "Snippet requires 'blogsite' theme!") ?>
<?php endif ?>

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>

Yellow text

Yellow text gives access to text strings:

$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->getDateFormatted($timestamp, $format)
Return human readable date, custom date format

$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 showing languages:

<ul>
<?php foreach($yellow->text->getLanguages() as $language): ?>
<li>
<?php echo $yellow->text->getTextHtml("languageDescription", $language) ?> - 
<?php echo $yellow->text->getTextHtml("languageTranslator", $language) ?>
</li>
<?php endforeach ?>
</ul>

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->readFile($fileName, $sizeMax = 0)
Read file, empty string if not found

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

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

$yellow->toolbox->renameFile($fileNameSource, $fileNameDest, $mkdir = false)
Rename 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->getFileExtension($fileName)
Return file extension

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

$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 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>

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 format:

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 text is displayed on a page 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>

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 onUserAccount($email, $password, $action, $users)
Handle user account changes

function onUserRestrictions($email, $location, $fileName, $users)
Handle user restrictions to change page

function onCommand($args)
Handle command

function onCommandHelp()
Handle command help

function onShutdown()
Handle shutdown

Here's an example plugin, a very basic one:

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

Here's an example plugin for including an [example] shortcut:

<?php
class YellowExample
{
    const VERSION = "0.1.2";
    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.3";
    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);
?>

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-plugin/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.28, Apache/2.4.23 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
YellowCore::startup

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

Datenstrom Yellow 0.7.1, PHP 5.6.28, Apache/2.4.23 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 builds and code analysis. Have a look at our tests.

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 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.

Next: Support →