Documentation

Top

Audience

This extension is intended for developers who are building ExpressionEngine extensions for web sites which use ExpressionEngine's Multiple Site Manager. You may be interested in this extension if you are reasonably familiar with extension development in EE.

Top

Installation

The jam_ext_settings extension and language file are packaged as a tgz along with the example extension jam_iframe_tab.

To install the extensions unpackage the tgz then place the extension files (beginning ext.) into the extensions folder of your ExpressionEngine intsallation, and the language files (beginning lang.) into the language/english folder.

Enable the extensions under Admin > Utilities using the EE control panel.  Enable the Jam Ext Settings extension before the Jam IFrame Tab extension.

But you're an extension developer right, so you know this stuff already.

Top

Motivation

We use a variety of plugins, modules and extensions - some of them third party, some that we develop ourselves.

Recently we've been using Multiple Site Manager quite a lot and we've become slightly frustrated at how tricky it is to develop extensions which play nicely with MSM. We want to talk about what we found tricky and we're going to describe an extension we developed which made things easier for us. If you think you would find the extension useful you're welcome to download it. We have also provided an example extension to get you started. We're interested in finding out how you get on!

But We Found it Hard to Handle Extension Settings When Using MSM

The problem we've had is with extension settings. We wanted a nice simple way to read and write our extension's settings on each site, but found that the tools provided in EE aren't as simple as we would like. The Abstracted Settings and Form Processing API from the developer documentation just wouldn't work for us when we were using Multiple Site Manager. We took a look at some third party extensions and saw that they were using the slightly more complex Built In Settings Form and Processing API, with a few added tricks to make sure each site's settings were kept separate. This works fine but we felt there must be a way to make things simpler.

So we created an extension to make it easier!

Top

Usage

Getting Started

The extension is called jam_ext_settings and once you've installed and enabled the extension you start to use it like this:

require_once(PATH_EXT . 'ext.jam_ext_settings.php');

class Jam_iframe_tab {

        //var $settings = array(); // UNUSED!
        var $jam_ext_settings = null;
        var $name = 'Jam IFrame Tab';
        var $version = JAM_IFRAME_TAB_VERSION;
        var $description = 'An example extension to show how to use settings with jam_ext_settings.';
        var $settings_exist = 'y';
        var $docs_url = 'http://jamdigital.co.nz/';


        function Jam_iframe_tab( $settings="" )
        {
                $this->__construct($settings);
        }

        function __construct( $settings="" )
        {
                $this->jam_ext_settings = new Jam_ext_settings(
                        'Jam_iframe_tab'
                        , $this->get_default_settings()
                        );
        }
}

The first thing to do is to require_once the ext.jam_ext_settings.php source file, so that you have access to the class Jam_ext_settings. Then in your class constructor create and store an instance of the Jam_ext_settings class, passing it your extension name (in this case Jam_iframe_tab) and the default settings for your extension. The newly created object will handle all the settings for this extension for all your MSM sites, arranging to offer your default settings initially.

Notice that in the class variables for the Jam_iframe_tab class we do not use the $settings variable.

The get_default_settings() function returns your extension defaults as an array:

        function get_default_settings()
        {
                $default_settings = array(
                        'weblogs'               => '0'
                        , 'iframe_target'       => 'http://jamdigital.co.nz'
                );
                return $default_settings;
        }

If you want to label your settings when they are displayed on the Settings Form simply add an entry for each label in your language file, in this case lang.jam_iframe_tab.php.

 $L = array(     
  'weblogs'=>'Enable Extension On The Following Weblogs',
  'iframe_target'=>'Web Page to Display in IFrame',
  // END          
  ''=>''                  
);              

For $settings use $jam_ext_settings

With the jam_ext_settings object created and arrangements made for default setting values you're all set to start using your settings. Here's how:

         function get_settings()
        {
                global $PREFS;
                $result = $this->jam_ext_settings->get_settings(
                                'Jam_iframe_tab'
                                , $PREFS->ini('site_id')
                );
                return $result;
        }

Getting your settings involves calling the get_settings() function in your jam_ext_settings object, passing it your extension name and site id. We find it most convenient to bundle this up into a member function. Using settings in your extension is then a matter of replacing reference to the member variable $settings with a call to $this->get_settings().

        function publish_form_new_tabs( $publish_tabs, $weblog_id, $entry_id, $hidden )
        {
                $settings = $this->get_settings();

                // your code here
        }

Handling Your Settings Form

As we mentioned at that start of this article, we found that when using Multiple Site Manager we needed to use the functions settings_form() and save_settings() to handle editing for our settings. To make things simpler for extension developers, Jam_ext_settings provides an implementation of each of these functions, allowing simple settings editing forms to be created with minimal effort. The most basic settings form provides a text field in which administrators can edit each setting. It's used like this:

        function settings_form($ignored)
        {
                global $LANG;
                $settings = $this->get_settings();
                $this->jam_ext_settings->jam_settings_form(
                        'Jam_iframe_tab',
                        $LANG->line('Jam_iframe_tab'),
                        $settings
                );
        }

        function save_settings()
        {
                $this->jam_ext_settings->save_settings();
        }

The function which provides a settings form is called jam_settings_form. Its parameters are the extension name, a label for the extension (used in the Breadcrumbs show on the form) followed by the settings to display on the form. Using the save_settings() function could not be easier, simply pass the call on to the identically named function in the jam_ext_settings object.

The jam_settings_form() function also takes an optional fourth parameter, an array of options controlling the way in which settings are displayed. The Jam_iframe_tab class contains an example of the way this can be used to offer a multiselect for the weblog setting.