Configure the PHP Theme

Once you have installed the PHP Theme it's time to configure the template to suit your website or project and add customizations.

Basic Page

All pages must include, at a minimum, the drawHeader() and drawFooter() methods in order to render the theme template.

<?php
require '/mysite/autoload.php';
$theme = new Site\Theme('Page title');
$theme->drawHeader();
?>

<!-- Page content goes here -->
<p>Hello world!</p>

<?php
$theme->drawFooter();

Instantiate the theme class using the page title and an optional array of configuration options.

<?php
$theme = new Site\Theme('Page title', [
    'site_title' => 'Department title',
]);

Configuration Methods

You can configure the theme in two ways; global and/or local.

Global

Global configurations are applied to all pages using the theme. Global configurations are placed in the Site\Theme::init() method in your site's configuration file /mysite/src/IastateTheme/Site.php.

<?php
namespace Site;

class Theme extends \IastateTheme\Theme {
    public function init() {
        $this->setOptions([
            'theme_asset_path' => '/iastate',
            'site_title' => 'Department of Lorem Ipsum',
        ]);
    }
}

All pages using this theme will now have these options.

Local

Local configurations are applied to a single page using the theme. Configure each individual page by calling the setOption() method.

<?php
$theme = new Site\Theme('Page title');
$theme->setOption('site_title', 'Change site title just for this page');

Adding Assets (CSS/JS)

The theme provides the following two methods to add additional CSS and JS assets to your site.

addStyle
IastateTheme\Theme addStyle(string|array $spec [, string $mode = 'link'])

Use this method to add <link> and <style> items to the document <head>.

See the head_link and head_style options on how to format $spec.

$mode can be either 'link' or 'style'.

<?php
// This will output a <link> item inside <head>
$page->addStyle('{{asset_path}}/css/base.css');

// This will output a <style> item inside <head>
$style = <<<CSS
body {
    font-size: 12px;
}
CSS;
$page->addStyle($style, 'style');
addScript
IastateTheme\Theme addScript(string|array $spec [, string $mode = 'file' [, string $pos = 'inline']])

Use this method to add <script> items to the document <head> or at the end of <body>.

See the head_script and inline_script options on how to format $spec.

$mode can be either 'file' or 'script'.

$pos can be either 'inline' or 'head'.

<?php
// This will output a <script> tag at the end of <body>
$page->addScript('{{asset_path}}/js/jquery-1.9.1.min.js');

// This will output a <script> tag inside <head>
$script = <<<JS
$(document).ready(function()
{
    console.log('Hello world!');
});
JS;
$page->addScript($script, 'script', 'head');

Remember to call these methods before you perform drawHeader().

Navigation items are configured using simple arrays. The array represents a list of pages which is then rendered into a nested unordered html list.

Each page represents a navigation item and can be either a link or a heading. The following keys are supported:

label (string) page label (required)
escape (boolean) will not escape label if set to false (default: true)
translate (boolean) will not translate label if set to false (default: true)
uri (string) page link. will display a heading item if the uri (or route) is not provided.
route (string|array) complex page route generated using route_callback. will display a heading item if the route (or uri) is not provided.
attributes (array) an array of html element attributes to be applied to the link.
order (integer) the order in which the item shows up in the list (lower number means higher in the list)
pages (array) array of sub navigation items
show_children (boolean) whether to display sub-pages when parent is not active
pattern (regexp) will mark item as selected if requested url matches this pattern
nopattern (regexp) will mark item as not selected if requested url matches this pattern
noselect (boolean) will mark item as not selected regardless of requested url
allowed_roles (string[]) item is shown only if authorization_callback returns true for any of the given roles
allowed_permissions (string[]) item is shown only if authorization_callback returns true for any of the given permissions
denied_roles (string[]) item is not shown if authorization_callback returns true for any of the given roles
denied_permissions (string[]) item is not shown if authorization_callback returns true for any of the given permissions

Example

This is for demonstration purposes. Keep in mind that setting navbar_menu will result in the automatic rendering of the navbar in $theme->drawHeader().

Let's use the theme object to set and then render the sidebar items.

<?php
$theme->setOption('navbar_menu', [
    [
        'label' => 'Home',
        'uri' => '/',
    ],
    [
        'label' => 'Section',
    ],
    [
        'label' => 'Sample',
        'uri' => '/sample/',
        'pages' => [
            [
                'label' => 'Foobar',
                'uri' => '/sample/foobar/',
            ],
        ],
    ],
]);
echo $theme->renderNav($theme->getOption('navbar_menu'));

The sample code will output the following html:

<nav class="navbar navbar-menu navbar-default navbar-static-top no-border navbar-caps navbar-menu-affix" role="navigation">
    <div class="container">
        <div class="collapse navbar-collapse" id="navbar-menu-collapse">
            <ul class="nav navbar-nav" >
                <li class="">
                    <a class="" href="/" tabindex="0">Home</a>
                </li>
                <li class="">
                    <a class="" href="" tabindex="0">Section</a>
                </li>
                <li class="dropdown dropdown-hover is-activeTrail">
                    <a class="dropdown-toggle" href="/sample/" role="button" data-toggle="" aria-haspopup="true" aria-expanded="false" data-submenu="" tabindex="0">Sample</a>
                    <a class="dropdown-toggle-mobile" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false"></a>
                    <ul class="dropdown-menu" role="menu">
                        <li class="">
                            <a class="" href="/sample/foobar/" tabindex="0">Foobar</a>
                        </li>
                    </ul>
                </li>
            </ul>
        </div>
    </div>
</nav>

Options

The theme provides the following methods to get and set options:

hasOption
bool hasOption(string $name)

Return: true/false based on whether the theme has an option by the given name.

getOption
mixed getOption(string $name [, mixed $default = null])
Return:

Value of option by the given name.

If the option value is null and a $default is provided, that will be returned instead.

setOption
IastateTheme\Theme setOption(string $name [, mixed $value [, bool $reset = false]])

Set the value of option by the given name.

If the option currently has an array value and the incoming $value is an array as well the two will be merged.

You can overwrite the current option completely by setting $reset to true.

getOptions
array getOptions()

Return: An array of all options within the theme object.

setOptions
IastateTheme\Theme setOptions(array $options)

Set multiple options at once. The keys in $options are used as the option names with the corresponding values as option values.

Available Options

Please refer to the configuration options page.