Hotaru Docs

 [həʊdɒks]

Adding User Settings

About User Settings

Hotaru CMS allows users to choose their own settings rather than using site-wide settings. One example of a plugin that adds such an option is the Admin Email plugin. This plugin gives users the choice of opting out of emails from site administrators.

This setting, along with those provided by other plugins appear on an individual user's settings page accessible from their profile, and also in the User Manager "Edit Default Permissions" page.

This guide shows the steps necessary to add settings from your own plugin, using the Admin Email and SB Base plugins as examples.

Necessary Hooks

Before you start, you'll need four plugin hooks in your hooks list at the top of your plugin:

install_plugin, user_settings_pre_save, user_settings_fill_form, user_settings_extra_settings

Register the default setting(s)

Example 1: The Admin Email install_plugin function:

// Add "admin notify" option to the default user settings
$base_settings = $h->getDefaultSettings('base'); // originals from plugins
$site_settings = $h->getDefaultSettings('site'); // site defaults updated by admin
if (!isset($base_settings['admin_notify'])) { 
    $base_settings['admin_notify'] = "checked";
    $site_settings['admin_notify'] = "checked";
    $h->updateDefaultSettings($base_settings, 'base');
    $h->updateDefaultSettings($site_settings, 'site');
}

Example 2: The SB Base plugin adds two settings, "new tab" and "link action":

$base_settings = $h->getDefaultSettings('base'); // originals from plugins
$site_settings = $h->getDefaultSettings('site'); // site defaults updated by admin
 
// Add "open in new tab" option to the default user settings
if (!isset($base_settings['new_tab'])) { 
    $base_settings['new_tab'] = ""; 
    $site_settings['new_tab'] = "";
    $h->updateDefaultSettings($base_settings, 'base'); 
    $h->updateDefaultSettings($site_settings, 'site');
}
 
// Let users choose whether links open the source post or post on the Hotaru site
if (!isset($base_settings['link_action'])) { 
    $base_settings['link_action'] = ""; 
    $site_settings['link_action'] = "";
    $h->updateDefaultSettings($base_settings, 'base'); 
    $h->updateDefaultSettings($site_settings, 'site');
}

Notice that user settings use radio buttons so the options are "checked" or "".

Fill the form

Next, we need to fill the user settings form with our new settings, checked according to the defaults or custom settings. Fortunately, the Users plugin does the hard work for you, so all you have to do is this:

/**
 * User Settings - fill the form
 */
public function user_settings_fill_form($h)
{
    if (!isset($h->vars['settings']) || !$h->vars['settings']) { return false; }
 
    if ($h->vars['settings']['admin_notify']) { 
        $h->vars['admin_notify_yes'] = "checked"; 
        $h->vars['admin_notify_no'] = ""; 
    } else { 
        $h->vars['admin_notify_yes'] = ""; 
        $h->vars['admin_notify_no'] = "checked"; 
    }
}

Display the choices on the form

Now we've got the values of each radio button, we can display the buttons:

/**
 * User Settings - html for form
 */
public function user_settings_extra_settings($h)
{
    if (!isset($h->vars['settings']) || !$h->vars['settings']) { return false; }
 
    echo "<tr>\n";
        // ACCEPT EMAIL FROM ADMINS?
        echo "<td>" . $h->lang['users_settings_email_from_admin'] . "</td>\n";
        echo "<td><input type='radio' name='admin_notify' value='yes' " . $h->vars['admin_notify_yes'] . "> " . $h->lang['users_settings_yes'] . " &nbsp;&nbsp;\n";
        echo "<input type='radio' name='admin_notify' value='no' " . $h->vars['admin_notify_no'] . "> " . $h->lang['users_settings_no'] . "</td>\n";
    echo "</tr>\n";
}

Get the user's choices and save

The Users plugin will do the saving for you, but before it does, you need to find out what the user selected and update the global $h->vars['settings'] array so the Users plugin knows what to save.

/**
 * User Settings - before saving
 */
public function user_settings_pre_save($h)
{
    // Emails from Admins:
    if ($h->cage->post->getAlpha('admin_notify') == 'yes') { 
        $h->vars['settings']['admin_notify'] = "checked"; 
    } else { 
        $h->vars['settings']['admin_notify'] = "";
    }
}

Finished!

Getting StartedDesign and LayoutPlugin DevelopmentAdvanced TopicsFunction ReferenceTroubleshooting