Hotaru Docs


How to Make a Theme Settings Page

Theme designers can include settings for their themes which users can adjust from Admin -> Theme Settings -> theme name.

The settings page itself is very simple, but it does show a few details about the theme, including a link to the author's own website. This tutorial explains how to create a settings page with options to enable or disable sidebars, as used by the Bars theme.

Error creating thumbnail: File missing
Error creating thumbnail: File missing
Error creating thumbnail: File missing

Editing the index.php file

First, the theme details added to the top of the settings page are drawn from the comment block at the top of the theme's index.php file:

 * name: Bars
 * description: Flexible two or three column theme
 * version: 0.1
 * author: Nick Ramsay
 * authorurl:
 * etc...

To hide or display sidebars, the index.php file does these things:

1. It gets the current settings:

// get settings:
$bars = $h->getThemeSettings();

2. It sets up some variables to determine the width of each enabled block, and the number for each widget block.

3. It includes a few conditions around each sidebar to determine whether to show it or not.

Those last two go beyond the scope of this tutorial, which intended for creating a theme settings page.

Creating a settings.php file

The settings page needs a new template file called settings.php. Here is the full code that generates the page in the first screen shot above:

// If the form has been submitted, save the data...
if ($h->cage->post->getAlpha('submitted') == 'true')
    $bars['left'] = ($h->cage->post->keyExists('left_bar')) ? 'checked' : '';
    $bars['right'] = ($h->cage->post->keyExists('right_bar')) ? 'checked' : '';
    $h->updateThemeSettings($bars, 'bars');
    $h->showMessage('Settings updated', 'green');
// If the user wants to revert to the defaults...
if ($h->cage->get->getAlpha('reset') == 'true')
    $bars = $h->getThemeSettings('bars', 'default');
    $h->updateThemeSettings($bars, 'bars', 'value');
    $h->showMessage('Reverted to default settings', 'green');
// Default settings:
$defaults['left'] = '';
$defaults['right'] = 'checked';
// Get settings from database if they exist...
$bars = $h->getThemeSettings('bars');
if (!$bars) { 
    $h->updateThemeSettings($defaults, 'bars', 'both');     // inserts settings for the first time
    $bars = $defaults;                                      // use the defaults
<form name='theme_settings_form' action='<?php echo BASEURL; ?>admin_index.php?page=theme_settings&amp;theme=bars' method='post'>
<p><input type='checkbox' name='left_bar' value='left_bar' <?php echo $bars['left']; ?>>&nbsp;&nbsp;Enable left sidebar</p>
<p><input type='checkbox' name='right_bar' value='right_bar' <?php echo $bars['right']; ?>>&nbsp;&nbsp;Enable right sidebar</p>
<br />
<input type='hidden' name='submitted' value='true' />
<input type='submit' value='<?php echo $h->lang["main_form_save"]; ?>' />
<input type='hidden' name='csrf' value='<?php echo $h->csrfToken; ?>' />
<br />
<a href="<?php echo BASEURL; ?>admin_index.php?page=theme_settings&amp;theme=bars&amp;reset=true"><?php echo $h->lang["admin_theme_theme_revert_settings"]; ?></a>
Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting