ItemManager is ideally suited for creating, saving and managing configuration options. This guide will provide you a quick overview of the basic principles of using ItemManager to create a template configuration handler. The template configuration contains template meta data (template name, author), defines page layouts, navigation areas, and anything else you want.

What you need:

1. ConfigHandler - A Class that would take control and manage the configuration options/parameters.

These files are in use:

1. index.php - Your entry point
2. ConfigHandler.php - ConfigHandler class

Let's start with ConfigHandler class.

ConfigHandler.php

<?php   
/**
 * Class ConfigHandler
 *
 * Can be used to create, retrieve and save various
 * configurations options/parameters.
 *
 */
class ConfigHandler extends \Imanager\Mapper
{
    /**
     * @var \Imanager\Category|null
     */
    public $config = null;

    /**
     * ConfigHandler constructor.
     *
     * @param null $name - Configuration name
     */
    public function __construct($name = null)
    {
        parent::___init();
        if($name) {
            $this->config = $this->imanager->getCategory("name=$name");
        }
    }

    /**
     * Utilizes data from real category
     *
     * @param string $name
     */
    public function __get($name)
    {
        if(array_key_exists($name, get_object_vars($this->config))) {
            return $this->config->$name;
        } else if($name == 'items') {
            return $this->config->items;
        } else if($name == 'fields') {
            return $this->config->fields;
        } else {
            return @$this->config->getItem("name=$name")->data;
        }
    }

    /**
     * Creates new fields in configuration category
     *
     * @param string $name
     * @param string $type
     */
    public function createField($name, $type)
    {
        if(!$this->config->id) { die('Category id does not exist'); }

        $field = new \Imanager\Field($this->config->id);
        $field->set('name', $name);
        $field->set('type', $type);
        $field->save();
    }

    /**
     * Set config option
     *
     * @param $key
     * @param $value
     * @param bool $sanitize
     */
    public function set($key, $value, $sanitize = true)
    {
        $item = $this->config->getItem("name=$key");
        if(!$item) {
            $item = $this->addItem($key);
        }
        $item->set('data', $value, $sanitize);
        $item->save();
    }

    /**
     * Remove config option
     *
     * @param $key
     */
    public function remove($key)
    {
        $item = $this->config->getItem("name=$key");
        if($item) {
            $this->config->remove($item);
        }
    }

    /**
     * Create new config option
     *
     * @param $name
     *
     * @return \Imanager\Item
     */
    protected function addItem($name)
    {
        $item = new \Imanager\Item($this->config->id);
        $item->set('name', $name);
        return $item;
    }
}

The work is done. Now all that's needed is to create your category, which will include the entire configuration settings.

The code below is only needed once and can be deleted as soon as you create the category.

index.php

<?php   
// NOTE: Fit the path to your environment
include 'framework/imanager.php';
include 'ConfigHandler.php';

/**
 * Create TemplateConfig
 */
// 1. Step: Create ConfigHandler
$configHandler = new \Imanager\Category();
// Set name of the handler category
$configHandler->set('name', 'TemplateConfig');
$configHandler->save();

// 2. Step: Build field(s) of the Config
$config = new ConfigHandler('TemplateConfig');
if($config) {
    // Create our config data field
    $config->createField('data', 'text');
}

Yep, that was easy. Now delete or comment out the code above. You can see whether the category is created when you call this code:

$config = new ConfigHandler('TemplateConfig');
echo "<pre>Category: $config->name</pre>";
\Imanager\Util::preformat($config->fields);

How can you use ConfigHandler class to create the options? It's really simple. But, to set/update the config parameters, you should normally use an end-user friendly form, however, I prefer not to use it in this tutorial for reasons of time:

index.php

// NOTE: Fit the path to your environment
include 'framework/imanager.php';
include 'ConfigHandler.php';

$config = new ConfigHandler('TemplateConfig');

$config->set('template_name', 'My responsive template');
$config->set('author', 'J. Ehret');
$config->set('meta_description', 'Template Configuration Presentation');
$config->set('home_navi', '
<nav>
  <a href="html">HTML</a> |
  <a href="css">CSS</a> |
  <a href="js">JavaScript</a> |
  <a href="jquery">jQuery</a>
</nav>
', $sanitize = false);

Note that the parameter sanitize is set to false in the last function call, so we enforce ItemManager not to sanitize the HTML code. This also will override the default 255 character length restriction for the text field.

The options can of course also be deleted if they are no longer needed. Just use the remove function like shown below:

$config = new ConfigHandler('TemplateConfig');
$config->remove('option_name');

In order to access the stored configuration parameters in your template, you can reference them directly from the $config variable:

index.php

<?php
// NOTE: Fit the path to your environment
include 'framework/imanager.php';
include 'ConfigHandler.php';

$config = new ConfigHandler('TemplateConfig');
?>
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title><?php echo $config->template_name; ?></title>
    <meta name="description" content="<?php echo $config->meta_description; ?>">
    <!-- Mobile-friendly viewport -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="author" content="<?php echo $config->author; ?>" />
</head>
<body><?php echo $config->home_navi; ?>   
<main role="main">
    <h1>ItemManager</h1>
    <p><i>ItemManager is a simple flat-file PHP framework, its extremely lightweight and easy to use.</i></p>
    <p>If you're seeing the date format here <strong style="color:red"><?php echo $imanager->config->systemDateFormat; ?></strong>,
        it says ItemManager has been properly included.</p>
</main>
<footer role="contentinfo">
    <small>Copyright &copy;
        <time datetime="<?php echo date('Y'); ?>"><?php echo date('Y'); ?></time> Ehret Studio</small>
</footer>
</body>
</html>

Of course, you can define any number of different configurations and combine them in your template:

$templateConfig = new ConfigHandler('TemplateConfig');
$siteConfig = new ConfigHandler('SiteConfig');
// display site name
echo $siteConfig->siteName;
// display navigation ...
echo $templateConfig->mainNavi;
...

Have fun!