Index of /Vanilla/extensions/SetList

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory   -  
[TXT]COPYING.txt 2015-11-12 11:52 202  
[TXT]default.php 2015-11-12 11:52 15K 
[TXT]settings_setlist_for..>2015-11-12 11:52 1.2K 
SetList - Vanilla Extension

SetList

SetList is a Vanilla extension that helps extension authors to quickly and easily create a form for their extension's settings. By writing a simple INI file, any extension developer can have clean and correct form on the Vanilla settings page without a single extra line of PHP code.

Table of Contents

What SetList Does

By itself, SetList does nothing. Installing SetList on a clean copy of Vanilla with no other extensions will have absolutely no noticable effect.

SetList will only take action when it finds a "SetList.ini" file inside another extension's directory. SetList will read the INI file and use it to build a settings form for that extension. The form will be accessible in the Panel of the Settings page, under the header "Extension Settings" with the extension's name as the link. When the form is submitted, SetList will save the settings to Vanilla's global configuration.

Extension writers can customize the form even further by adding Init and Process delegates to SetList with extra form logic. All text on the form is registered as definitions in the Context to make life easier for translators. Theme writers can override the form template to ensure than extension settings forms don't break their themes.

Extensions do not require SetList! Even if SetList is uninstalled - or never installed at all - forum admins can still use a SetList-aware extension normally, specifying setting values by changing the Vanilla settings file directly.

Installing and Enabling SetList

In order for Vanilla to recognize an extension, it must be contained within its own directory within the extensions directory. So, once you have downloaded and unzipped the SetList files, you can then place the folder containing the default.php file into your installation of Vanilla. The path to SetList's default.php file should look like this:

/path/to/vanilla/extensions/SetList/default.php

Once this is complete, you can enable SetList through the "Manage Extensions" form on the settings tab in Vanilla.

How Extension Writers Use SetList

Starting Quickly

Using SetList to create a settings form can be as easy as writing a SetList.ini file in your extension's directory:

elements.MyHeader.type = "header"
elements.MyHeader.label = "This is a Header"
elements.MyHeader.description = "This is text describing the stuff here."

elements.MyCheckbox.type = "checkbox"
elements.MyCheckbox.label = "Check this box"
elements.MyCheckbox.description = "If you check this box, it will be checked."

elements.MyText.type = "text"
elements.MyText.label = "Some text here"
elements.MyText.description = "This is a single line text input."

elements.MyTextarea.type = "textarea"
elements.MyTextarea.label = "Lots of text here"
elements.MyTextarea.description = "This is a 15-line text box."

elements.MySelect.type = "select"
elements.MySelect.label = "Select something"
elements.MySelect.description = "This is a select box."
elements.MySelect.options.First.label = "First"
elements.MySelect.options.First.value = "1"
elements.MySelect.options.Second.label = "Second"
elements.MySelect.options.Second.value = "2"
elements.MySelect.options.Third.label = "Third"
elements.MySelect.options.Third.value = "3"

elements.MyHidden.type = "hidden"
elements.MyHidden.value = "Something sneaky"

Go ahead, copy and paste that into a file named SetList.ini in your extension's directory. It will work, and it will explain the process much better than I could.

If you think this INI looks a lot like how you would create a form in Zend Framework, gold star for you. SetList does not use ZF but it does use a very simplified version of ZF's config format.

Note that you don't have to specify an element's description, it's optional. However, if you don't specify an element's label you will get a default label of that element's key name, such as MyText.

More Advanced

Right now the values on this form will only load from and save to the global Vanilla configuration. You may want to add some extra logic via delegate functions in your extension's default.php file:

function SetList_Init_MyExt(&$SetList)
{
   $form = &$SetList->DelegateParameters['Form'];

   $SetList->Context->SetDefinition('MyExt.IP', 'Your IP address');

   $form['elements']['MyText']['label'] =
      $SetList->Context->GetDefinition('MyExt.IP');
   $form['elements']['MyText']['value'] = GetRemoteIp();
}
$Context->AddToDelegate('SetList', 'Init_MyExt', 'SetList_Init_MyExt');

function SetList_Process_MyExt(&$SetList)
{
   $form = &$SetList->DelegateParameters['Form'];

   $SetList->Context->SetDefinition('MyExt.ErrorThird',
      'You must choose the third option because I say so.');

   if ( 3 != $form['elements']['MySelect']['value'] ) {
      $SetList->Context->WarningCollector->Add(
         $SetList->Context->GetDefinition('MyExt.ErrorThird'));
      $form['elements']['MySelect']['value'] = 3;
	}
}
$Context->AddToDelegate('SetList', 'Process_MyExt', 'SetList_Process_MyExt');

Try adding this to your extension's default.php, but replace the text MyExt with your extension's key. The key is the name of your extension with only alphanumeric and underscore characters. For example, an extension named "Me and My_Monk3y" would have the key MeandMy_Monk3y. Go ahead, try it. I'll wait.

Note that if your Init_ or Process_ function adds a message to the Context's WarningCollector, the settings will not be saved. This is a good easy way to invalidate the entire form. If you want to send a non-error message, add to the global $NoticeCollector object instead.

Saving Settings

Anything typed into a form will be saved by SetList. Type in stuff and save it, then open Vanilla's conf/settings.php file. You should see some lines at the end like this:

$Configuration['MyExt.MyCheckbox'] = '1';
$Configuration['MyExt.MyText'] = 'I wrote some text.';
$Configuration['MyExt.MyTextarea'] = 'I wrote more text.';
$Configuration['MyExt.MySelect'] = '3';
$Configuration['MyExt.MyHidden'] = 'Something%2Bsneaky';

The config key for each value is YourExtensionKey.MySetting (or something similar). This can be changed by specifying a configkey attribute for an element:

; In an INI file:
elements.MyText.configkey = "MYEXTENSION_MYTEXT"

-OR-

// In code:
$form['elements']['MyText']['configkey'] = 'MYEXTENSION_MYTEXT';

-RESULTS IN-

$Configuration['MYEXTENSION_MYTEXT'] = 'I wrote some text';

Order of Operation

The actual value of an element can come from one of several different steps. A value specified in a later step will destroy any value from a previous step:

1. Value may be specified in the INI:
elements.MyText.value = "some text"
2. Value is read from Vanilla's configuration (if the config key already exists)
3. Value may be assigned in your extension's Init_ function:
$form['elements']['MyText']['value'] = 'other text';
4. Settings form is displayed to the user
5. Settings form is submitted by the user
6. Value is read from the submitted settings form
7. Value may be changed in your extension's Process_ function:
$form['elements']['MyText']['value'] = 'another text';
8. Value is saved to Vanilla's settings file

Keep in mind that steps 6 through 8 don't happen until a user submits a form. Until that happens, SetList will not put your settings in the global settings file. If you want default values added when your extension first installs, you will have to handle that yourself.

Other Tricks

To prevent an element from saving to config, use the nosave attribute:

; In an INI file:
elements.MyText.nosave = 1

-OR-

// In code:
$form['elements']['MyText']['nosave'] = 1;

To prevent an element from rendering AND saving, use the norender attribute:

; In an INI file:
elements.MyText.norender = 1

-OR-

// In code:
$form['elements']['MyText']['norender'] = 1;

How Translators Use SetList

Translating the example form above is as easy as translating any other text in Vanilla. To translate the above form into Spanish, just add the following lines to Vanilla's languages/Spanish/definitions.php file:

$Context->Dictionary['MyExt.MyHeader.label'] = 'Esta es una de cabecera';
$Context->Dictionary['MyExt.MyHeader.description'] = 'Este es el texto de la descripción de las cosas aquí.';
$Context->Dictionary['MyExt.MyCheckbox.label'] = 'Marque esta casilla';
$Context->Dictionary['MyExt.MyCheckbox.description'] = 'Si marca esta casilla, que serán revisados.';
$Context->Dictionary['MyExt.MyText.label'] = 'Algunos texto aquí';
$Context->Dictionary['MyExt.MyText.description'] = 'Se trata de una única línea de entrada de texto.';
$Context->Dictionary['MyExt.MyTextarea.label'] = 'Una gran cantidad de texto aquí';
$Context->Dictionary['MyExt.MyTextarea.description'] = 'Se trata de una línea de 15-cuadro de texto.';
$Context->Dictionary['MyExt.MySelect.label'] = 'Seleccione algo';
$Context->Dictionary['MyExt.MySelect.description'] = 'Se trata de una caja de selección.';
$Context->Dictionary['MyExt.MySelect.First.label'] = 'Primera';
$Context->Dictionary['MyExt.MySelect.Second.label'] = 'Segunda';
$Context->Dictionary['MyExt.MySelect.Third.label'] = 'Tercera';

Keep in mind that if the extension specifies error messages or other text in the code, you should translate those too:

$Context->Dictionary['MyExt.ErrorThird'] = 'Usted debe elegir la tercera opción, porque lo digo.';

How Theme Writers Use SetList

Theming the SetList form is just as easy as theming any other Vanilla settings form. The template file is named settings_setlist_form.php and should go in your theme's directory with all of the other template files.

The easiest way to understand the template is to open it up and take a look (it's not very complicated). The most important part is the loop that renders the form elements:

$elementKeys = array_keys($this->formData['elements']);
foreach ($elementKeys as $element) {
   if ( $this->shouldRender($element) ) {
      echo '
         <li>
            ' . $this->renderLabel($element) . '
            ' . $this->renderElementHtml($element) . '
            ' . $this->renderDescription($element) . '
         <li>
   }
}

To render an HTML element, call renderElementHtml() and pass in that element's key, likewise for the label and the description. The label will come wrapped in <label></label> tags. The description will come wrapped in <p></p> tags with the attribute class="Description".

The element, the label, and the description are all rendered seperately and you can render them in any order you want. There are two exceptions: First, for any checkbox element the label will be rendered by renderElementHtml() along with the checkbox element itself. This is to keep consistency with the look of Vanilla's own settings forms. Calling renderLabel() for a checkbox element will return an empty string. Second, a "header" is not strictly an HTML element, so it has no value. The text of a header's "label" is used as the header text. Calling renderLabel() for a header element will return an empty string.

Uninstalling SetList

Had enough? Just disable the SetList extension in Vanilla and delete the SetList directory from the extensions directory. That's all.

Development

SetList was written by squirrel. Updates are available at the Vanilla add-ons site. Part of the Vanilla Friends project.