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 Frog development team. There are basically two things you will want to achieve:
- Allow Frog to automatically detect whether or not you have a settings page and link to it from the Administration section.
- 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 Frog 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 Frog’s Administration section. So remember to enable the plugin before testing all of this.
A little something about URLs in Frog
Frog 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/frog/admin/plugin/hello_world
Any requests sent to this URL are interpreted by Frog 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/frog/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 Frog 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 Frog 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 Frog’ at the top of this page.
Finally, you will need to let Frog 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 Frog 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 Frog will automatically detect that you supply a settings page. Frog 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 Frog 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 Frog’ at the top of this page.
That’s about it. Hopefully this document is clear enough, otherwise let us know in the forum.
