Documentation

Light-weight, fast, simple and powerful!
 
Translations of this page?:

Providing a Settings page for your plugin

A number of plugins have defined various methods of saving and manipulating plugin specific settings. Here’s an overview of the current best practice according to the Wolf CMS development team. There are basically two things you will want to achieve:

  1. Allow Wolf CMS to automatically detect whether or not you have a settings page and link to it from the Administration section.
  2. Actually have a settings page which stores stuff in a database table.

This means you will have to:

  • Create a Controller (which turns into a tab in the Wolf CMS backend)
  • Add a settings() function
  • Add a settings view

Before we continue: the link to the settings page, the plugin’s tab and the settings page itself will only become available after you have enabled the plugin in Wolf’s Administration section. So remember to enable the plugin before testing all of this.

A little something about URLs in Wolf CMS

Wolf CMS is quite smart about URLs and uses those smarts to simplify calling particular functions in a plugin’s controller. A simple example for our hello_world plugin would be:

http://www.example.com/wolf/admin/plugin/hello_world

Any requests sent to this URL are interpreted by Wolf CMS to mean that you want to access the index() function of the hello_world plugin’s Controller.

What we are doing in this article is that we want to access the settings page. You could of course type in the URL manually each time you want to access that page, but we provide you with a link to it from the Administration screen and you (as the plugin’s developer) can add a link to it from the sidebar.

Just in case you were still wondering, the url to access for the settings() function would be:

http://www.example.com/wolf/admin/plugin/hello_world/settings

Creating the Controller

We are assuming that you haven’t already created a Controller, so we’ll help you create one now. The most basic controller you will likely want to create will display a tab in the Wolf CMS backend and will allow any user that is logged in to make use of the tab.

class HelloWorldController extends PluginController {
    function __construct() {
        AuthUser::load();
        if ( ! AuthUser::isLoggedIn()) {
            redirect(get_url('login'));
        }
 
        $this->setLayout('backend');
        $this->assignToLayout('sidebar', new View('../../plugins/hello_world/views/sidebar'));
    }
 
    function index() {
        $this->display('hello_world/views/index');
    }
}

The __construct() function checks if a user is logged in and forwards him or her to the login page when necessary. It then adds the controller to the “backend” layout. This produces the tab in the Wolf CMS backend. Lastly, it assigns the sidebar view to the layout.

Note: it is our recommendation that every plugin which provides a tab in the backend and a settings page or documentation page, also provides the sidebar.

The index() function simply forwards any request targeted at the plugin in general to the index view. You can of course do more than simply redirect. For more information about URLs in combination with plugins and Controllers, please read the section entitled: “A little something about URLs in Wolf CMS” at the top of this page.

Finally, you will need to let Wolf CMS know about the existence of your new Controller. To do so, add the following line to you plugin’s index.php file:

Plugin::addController('hello_world', 'Hello World');

This tells Wolf CMS that a tab should be created in the backend called “Hello World” as soon as you’ve enabled this new plugin.

Adding the settings function

Now we have to make certain Wolf CMS will automatically detect that you supply a settings page. Wolf CMS does this by verifying whether or not you have a settings() function in your Controller.

To provide it, for now simply add:

function settings() {
    $this->display('hello_world/views/settings');
}

This is the most basic use of the settings() function. It simply displays the settings view. In a real world example, you would probably want to read in the current settings before displaying the view. You can add variables to the view by doing something like the following example where $result could be the result from an SQL query for example.

$this->display('hello_world/views/settings', array(
        'myVarName' => $result->value
 
    ));

Adding the settings view

The settings() function we’ve added in the prior section displays a settings view. We will of course have to provide the plugin with this view. In your plugin directory, create a ‘views’ directory. In this ‘views’ directory create and edit a file called ‘settings.php’. Here’s an example of what you can put inside:

<h1><?php echo __('Hello World Plugin'); ?></h1>
 
<form action="<?php echo get_url('plugin/hello_world/save'); ?>" method="post">
</form>

As you can see, this form doesn’t actually do anything usefull.. It isn’t even a complete form, but you do have a settings page now. Please also notice that we have the form’s action set to get_url('plugin/hello_world/save'). This tells Wolf CMS to post the form information to the save() function of the hello_world controller.

To allow this form to actually save any settings that were changed through the form, you would have to create a save() function in the hello_world plugin’s controller which actually saves the information to a database table for instance and then redirects you back to the settings page.

For more information about URLs in combination with plugins and Controllers, please read the section entitled: ”A little something about URLs in Wolf CMS” at the top of this page.

That’s about it. Hopefully this document is clear enough, otherwise let us know in the forum.

 
tutorials/settings_page.txt · Last modified: 2011-09-12 00:46 (external edit)
 
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.2
Copyright 2010 wolfcms.org / design by yello studio / Wolf CMS Inside