The following use case leads you through the creation of a plugin that creates a configuration form (using the Config Form hook), and saves data from that configuration form (using the Config hook).
The "Configure This!" plugin has no actual function other than to demonstrate how a configuration form. If you're interested in seeing its use in other use cases, see the Plugin_Use_Cases/Writing_Your_First_Omeka_Plugin "Hello World" example.
Files You'll Create in this Use Case
- ConfigureThis/ (folder)
- config_form.php
- plugin.ini
- plugin.php
Use Case Steps
1. Create a plugin.php file that is empty, and a plugin.ini file with the following text:
[info] name="Configure This!" author="Plugin Developer" description="Creates a configuration form and saves and option to the database." omeka_minimum_version="1.0" omeka_tested_up_to="1.1" version="1.0" tags="configuration"
You now have a plugin that can be installed and uninstalled properly, but it does nothing yet.
2. Create a new php file called config_form.php that will store the HTML for our configuration form. We'll include this file in plugin
<?php // create a form inputs to collect the user's configuration text echo '<div id="configure_this_config_form">'; echo '<label for="configure_this_configuration">Your Configuration Text:</label>'; echo text(array('name'=>'configuration_this_configuration'), get_option('configuration_this_configuration'), null); echo '</div>'; ?>
3. Use the Config Form and Config hooks to know what to do with the form, displaying a button beside a plugin's title on the administrative panel's configuration page, and save any data from that form. When you install and activate a plugin, the configuration button will appear if this hook is used. We'll add a reference to the hooks, as well as the functions it uses:
<?php // add plugin hooks add_plugin_hook('config_form', 'configure_this_config_form'); add_plugin_hook('config', 'configure_this_config'); // show plugin configuration page function configure_this_config_form() { include('config_form.php'); } // save plugin configurations in the database function configure_this_config() { set_option('configure_this_configuration', trim($_POST['configure_this_configuration'])); }
To dissect this code, the config_form hook is responsible for outputting HTML on the configuration page. In this use case, we included the config_form.php file, however you can echo text within that function. The config hook runs after the form on a configuration page is saved. The data that's POSTed is there in $_POST as you'd expect. If there is any processing to do, you can do that here. To store the data, Omeka provides the set_option function, which takes two parameters, a name and a value, and stores the data in the database.
This basic architecture of plugin configuration pages is useful to offer plugin settings without having to create a separate administrative view to manage them. It also creates a consistent experience for users while they install and uninstall plugins.