Jump to content

Developer Documentation

Using settings in plugins

Much like full applications, plugins can have system settings that allow administrators to configure it. For example, you might have a setting that toggles some part of your functionality on and off, or fields that can accept some authentication values used by some other system. If your plugin requires some data or preferences to be set by the administrator, settings are the ideal way do implement it.


Allocating space in IPS\Settings

\IPS\Settings is a repository for scalar key/value data pairs - it is shared amongst all applications and plugins and is accessible from anywhere as a Singleton, there are also shortcuts to access it's contents within templates. Its primary intention is for storing settings the administrator provides in the Admin CP.

In order to use this, you must enter the keys you want to be allocated to your plugin and the default values in the Plugin Developer Center. The keys are not namespaced, so it is recommended that you choose keys that are unlikely to be used by other applications or plugins.

Creating a settings page

Your plugin is allowed to have one settings page which will be displayed with the administrator clicks the "edit" button next to your plugin. In most cases, this will be just a regular form using the form helper, however, though the form helper is very flexible (it can handle tabs, sidebars and a wide variety of input types), you are not restricted to this and can display your settings however you like.

In the /plugins/<your plugin> directory, you'll find a file called "settings.rename.php" - rename this to "settings.php" and this will be the code that runs when the user accesses your settings page. The example file is written with the form helper in mind, and to use that, all you need to do is add additional input fields. If you want to use a custom interface though, you just need to return either a string (with the content to display) or TRUE to dismiss the settings page. Your code will be eval'd and so you should not include an opening <?php tag - one is included in the example file so that syntax highlighting will work in most code editors, however it is commented out and should remain so.

  Report Document

  • Create New...