1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Adding User Settings

Discussion in 'Developing Plugins' started by Nick, Jan 16, 2010.

  1. Nick

    Nick Well-Known Member

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

    Code:
    install_plugin, user_settings_pre_save, user_settings_fill_form, user_settings_extra_settings
    Register the default setting(s):

    Admin Email install_plugin function:

    PHP:
            // 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');
            }
    The SB Base plugin adds two settings, "new tab" and "link action":

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

    PHP:
        /**
         * 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:

    PHP:
        /**
         * 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.

    PHP:
        /**
         * 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!
     

Share This Page