Add a conditional

Settings can be added to your settings page the usual way. If you declare the Style (CSS) Settings module only as a soft-dependency (thus not required), it makes sense to show settings only if the Style Settings module is enabled by wrapping all Style Settings specific form elements inside a conditional:

  if (module_exists('style_settings')) { ... }
  // If the Style Settings module is not enabled, provide some instructions.
  else { ... }

 

Add form fields

Developers can use any Drupal core form API element on their settings page to capture a theme setting or variable. The Style Settings module offers also some custom form API elements to make building CSS settings easier. Cool UI widgets, for example a color picker or a slider, and built-in validation of user input.

For project maintainers adding a Style Setting field to their configuration form is easy, adding only a few lines of code. Validation is taken care of by the Style Settings module. Examples how to provide different types of Style Settings can be found in the 'code snippets' section on the next page or looking at the demo code included in the module itself (recommended). There is also a #2548427: Demo for theme settings.
 

Number

'#type' => 'style_settings_number',

  • Takes care of the validation rules just by providing a '#min', '#max' and '#step' $form attribute.
  • Adds a unit if valid. Input: '2', field_suffix: 'px' => stored variable: '2px'
  • Aligns field input to the right to stay close to the unit (field_suffix).

Accepted form element attributes are the same as a 'textfield' plus:

  • '#min' => [minimum, defaults to 0],
  • '#max' => [maximum, optional],
  • '#step' => [multiple of .. , optional, if set to 1 accept only integers],
  • '#input_help' => [show above mentioned values as field help text, defaults to TRUE],

 

Color picker

A lot of CSS attributes contain a color value. Although a simple text field could hold a color hex value, having a color picker is more convenient.

Colorpicker provided by the Style (CSS) Settings module

'#type' => 'style_settings_colorpicker',

  • Uses Drupal core's Farbtastic ColorPicker plugin.
  • Makes the current chosen color visible in the settings field itself.
  • Only accepts a valid color, a hex value but also a color name.
  • Does not depend on any contrib or the Color module.
  • Does not need an additional jQuery library.
  • Stores the variable as a hex value or color name that is valid in CSS files.

 

Slider (HTML5 range input)

HTML5 slider (range) API form field

'#type' => 'style_settings_slider',

  • Exposes a slider widget (a range) in HTML5 capable browsers (all but <= IE9).
  • Shows the numeric value that corresponds with the handle position.
  • Validation just by providing a '#min', '#max' and '#step' value.
  • Adds a unit if valid. Input: '1', field_suffix: 'em' => stored variable: '1em'

Accepted form element attributes are the same as a 'textfield' plus:
'#min' => [minimum, defaults to 0],
'#max' => [maximum, defaults to 1],
'#step' => [multiple of .. , defaults to 0.01],
The defaults are preset for the CSS attribute 'opacity' but can be overridden.
 

Image URL

'#type' => 'style_settings_imgurl',

  • Accepts an absolute or relative (/sites/..) URL.
  • Validates (if not empty):
    • the URL syntax
    • if it is an image and exists (no 404).

 

More info

For more information on custom theme settings, read:
https://www.drupal.org/node/177868
A simple example of theme settings is Drupal core's
'/themes/garland/theme-settings.php' and '/themes/garland/garland.info'.

For more information on custom module settings, read:
https://www.drupal.org/node/1111260
A simple but complete example of module settings is Drupal core's '/modules/update/update.settings.inc'.

A selectable measurement unit (e.g. px, em, %)

To have a unit select widget after a number field :

  • Put both in a fieldset with the class 'container-inline'.
    '#attributes' => array('class' => array('container-inline')),
  • Make sure the number field has NO '#field_suffix' declared.
  • The unit '#type' => 'select', should be '#required' => TRUE,.
  • In the form submit handler concatenate the value and unit variables in a new one.

 
Examples how to provide different types of Style Settings can be found in the 'code snippets' on the next page. Alternatively you can take a look at how things are done in the module's demo at 'sites/all/modules/style_settings/demo', which includes also an example of a 'preview area' to make style changes visible in the settings form itself. There is also a #2548427: Demo for theme settings.