diff --git a/README.txt b/README.txt index ea3bff6..ed231e9 100644 --- a/README.txt +++ b/README.txt @@ -118,12 +118,17 @@ Accepted attributes, the same as a 'textfield' plus: The defaults are preset for the CSS attribute 'opacity' but can be overriden. ##### A selectable measurement unit (e.g. px, em, %) ##### -To have a select widget after a number field : +To have a unit select widget after a number field : - Put both in a fieldset with the class 'container-inline'. - Make sure the number field has NO '#field_suffix'. - The unit '#type' => 'select' should be '#required' => TRUE. - In the form submit handler concatenate the value and unit vars in one new var. +##### Image URL #### +'#type' => 'style_settings_imgurl', +- Accepts an absolute or relative (from base) URL. +- If not empty, validates the URL syntax, if it is an image and exists (no 404). + #### More info #### For more information on custom theme settings, read: @@ -136,6 +141,9 @@ For more information on custom module settings, read: A simple but complete example of module settings is Drupal core's '/modules/update/update.settings.inc'. +Examples how to provide different types of +Style Settings can be found in the 'code snippets' section below. + ### Code snippet examples ### @@ -149,30 +157,45 @@ Put the following comment at the top of CSS files that contain style variables: An example for FOO.admin.inc: +Replace FOO with your module's machine name. + // START OF CODE /** * Implements hook_settings(). */ function FOO_admin_settings() { + // Declare a submit handler. $form['#submit'][] = 'FOO_admin_settings_submit'; + + // Put CSS variables together in a fieldset. Remove if only one is given. + $form['css_variables'] = array( + '#type' => 'fieldset', + '#title' => t('CSS variables'), + '#collapsible' => TRUE, + '#collapsed' => FALSE, + ); + if (module_exists('style_settings')) { + // When we have a list of CSS variables it is better to collapse it. + $form['css_variables']['#collapsed'] = TRUE; - // Any form API element can be used - // A normal textfield. It does not offer any validation by itself. - $form['FOO_caption_align'] = array( + // Any normal form API type can be used + // A normal TEXTFIELD. It does not offer any validation by itself. + $form['css_variables']['FOO_caption_align'] = array( '#type' => 'textfield', '#title' => t('Caption text align'), '#default_value' => variable_get('FOO_caption_align', 'center'), '#size' => 12, ); - // Style Settings offers several form API elements to help developers build - // the settings page. Cool UI widgets and built-in validation of user input. + // The Style Settings module offers several form API elements to help + // developers build the settings page. Cool UI widgets and built-in + // validation of user input specially designed for CSS attributes. - // Number example in this case with an appended measurement unit (optional). + // NUMBER example in this case with an appended measurement unit (optional). // E.g. user input: '2', field_suffix: 'px' => stored variable: '2px'. - $form['FOO_borderwidth'] = array( + $form['css_variables']['FOO_borderwidth'] = array( '#type' => 'style_settings_number', '#title' => t('Border width'), '#step' => 1, // In this case if forces an integer as input. @@ -185,17 +208,20 @@ function FOO_admin_settings() { '#field_suffix' => 'px', // Uncomment the line below to NOT align the field input on the right. // '#attributes' => NULL, + // Uncomment the line below to NOT show min, max and step values as help. +// '#input_help' => NULL, ); - // Color picker example. - $form['FOO_bordercolor'] = array( + // COLOR PICKER example. + $form['css_variables']['FOO_bordercolor'] = array( '#type' => 'style_settings_colorpicker', '#title' => t('Border color'), + // Besides hex color value also color names are accepted. '#default_value' => variable_get('FOO_bordercolor', 'IndianRed'), ); - // Slider widget example. - $form['FOO_magnifier_icon_opacity'] = array( + // SLIDER WIDGET example. + $form['css_variables']['FOO_magnifier_icon_opacity'] = array( '#type' => 'style_settings_slider', '#title' => t('Magnifier icon opacity'), '#description' => t('0 = transparent. 1 = opaque.'), @@ -206,25 +232,26 @@ function FOO_admin_settings() { '#step' => 0.01, '#min' => 0, '#max' => 1, - // Added for demonstration purpose. // The suffix gets added to the input on submit if valid measurement unit. + // Added for demonstration purpose only. 'field_suffix' => NULL, ); - // A selectable measurement unit (e.g. px, em, %) example. - $form['FOO_fontsize'] = array( + // A SELECTABLE MEASUREMENT UNIT (e.g. px, em, %) example. It goes together + // with a submit handler inside the function FOO_admin_settings_submit(). + $form['css_variables']['FOO_fontsize'] = array( '#type' => 'fieldset', '#title' => t('Caption font-size'), // Make containing fields align horizontally. '#attributes' => array('class' => array('container-inline')), ); // Number field without a '#field_suffix'. - $form['FOO_borderwidth']['FOO_fontsize_value'] = array( + $form['css_variables']['FOO_borderwidth']['FOO_fontsize_value'] = array( '#type' => 'style_settings_number', '#max' => 200, // Defaults to 1 if omitted. '#default_value' => variable_get('FOO_fontsize_value', '85'), ); - $form['FOO_borderwidth']['FOO_fontsize_unit'] = array( + $form['css_variables']['FOO_borderwidth']['FOO_fontsize_unit'] = array( '#type' => 'select', '#options' => array( 'px' => t('px'), @@ -234,7 +261,17 @@ function FOO_admin_settings() { '#default_value' => variable_get('FOO_fontsize_unit', '%'), '#required' => TRUE, ); + $form['css_variables']['FOO_bgimage'] = array( + '#type' => 'style_settings_imgurl', + '#title' => t('Background image'), + // If you use this for a 'theme', replace 'module' below. + '#default_value' => variable_get('FOO_bgimage', '/' . drupal_get_path('module', 'FOO') . '/image/bg-default.jpg'), + // To not accept empty images (valid in CSS), uncomment the line below. +// '#required' => TRUE, + // ..or reset an empty field to a default image, see submit handler below. + ); } + // If the Style Settings module is not enabled, provide some instructions. else { $style_settings_module = l(t('Style (CSS) Settings module'), 'https://drupal.org/project/style_settings', array( 'attributes' => array( @@ -242,9 +279,9 @@ function FOO_admin_settings() { 'target' => '_blank', ), )); - $form['FOO_note'] = array( + $form['css_variables']['FOO_note'] = array( '#markup' => t("Enable the !style_settings_module to get style options exposed here. They consist of:", array('!style_settings_module' => $style_settings_module)), @@ -257,8 +294,19 @@ function FOO_admin_settings() { */ function FOO_admin_settings_submit($form, &$form_state) { if (module_exists('style_settings')) { - // Concatenate the value and unit in a new variable (the one that will be used in the CSS). + // SELECTABLE MEASUREMENT UNIT: concatenate the value and unit in a new + // variable (the one that will be used in the CSS). variable_set('FOO_fontsize', variable_get('FOO_fontsize_value', '85') . variable_get('FOO_fontsize_unit', '%')); + // IMAGE URL: Optionally strip whitespace and reset to default URL if empty. + $url = trim($form_state['values']['FOO_bgimage']); + if (empty($url)) { + variable_set('FOO_bgimage', '/' . drupal_get_path('module', 'flickr') . '/images/bg-default.jpg'); + drupal_set_message(t('An empty image URL has been replaced with the default image.'), 'warning'); + } + else{ + variable_set('FOO_bgimage', $url); + } + // Make sure changes are visible right after saving the settings. _drupal_flush_css_js(); } } diff --git a/style_settings.module b/style_settings.module index d23ef42..90ba617 100644 --- a/style_settings.module +++ b/style_settings.module @@ -233,18 +233,18 @@ function style_settings_element_info() { ), )); $types['style_settings_colorpicker'] = array( - '#default_value' => '', '#input' => TRUE, + '#type' => 'textfield', '#theme' => array('textfield'), '#theme_wrappers' => array('form_element'), '#autocomplete_path' => FALSE, '#element_validate' => array('style_settings_color_validate'), - '#type' => 'textfield', '#size' => 12, '#maxlength' => 20, '#description' => t('Also shorthand (like #fff) and !colornames are accepted.', array('!colornames' => $colornames)), '#prefix' => '
', '#suffix' => '
', + '#default_value' => '', '#attributes' => array('class' => array('style_settings-colorpicker')), '#attached' => array( 'library' => array(array('system', 'farbtastic')), @@ -253,7 +253,6 @@ function style_settings_element_info() { ); $types['style_settings_number'] = array( '#input' => TRUE, - '#type' => 'textfield', '#min' => 0, '#size' => 4, '#process' => array('ajax_process_form'), @@ -275,6 +274,17 @@ function style_settings_element_info() { '#theme' => 'style_settings_slider', '#theme_wrappers' => array('form_element'), ); + $types['style_settings_imgurl'] = array( + '#input' => TRUE, + '#type' => 'textfield', + '#description' => t("An absolute (external) or relative (local) image URL. A relative URL must be given from the base URL, for example /sites/default/files/images/some-image.png. Note the leading slash!"), + '#theme' => array('textfield'), + '#theme_wrappers' => array('form_element'), + '#autocomplete_path' => FALSE, + '#element_validate' => array('style_settings_imgurl_validate'), + '#size' => 80, + '#maxlength' => 160, + ); return $types; } @@ -290,12 +300,13 @@ function style_settings_color_validate($element, &$form_state) { } } -/* Validates hex color. Checks for a Color Name first to prevent error if a name +/* + * Validates hex color. Checks for a Color Name first to prevent error if a name * was entered (optional). + * * $color: the color hex value stirng to Validates $named: (optional), set to * 1 or TRUE to first test if a Named color was passed instead of a Hex value. */ - function style_settings_validate_html_color($color, $named = TRUE) { if ($named) { $named = array('aliceblue', 'antiquewhite', 'aqua', 'aquamarine', 'azure', 'beige', 'bisque', 'black', 'blanchedalmond', 'blue', 'blueviolet', 'brown', 'burlywood', 'cadetblue', 'chartreuse', 'chocolate', 'coral', 'cornflowerblue', 'cornsilk', 'crimson', 'cyan', 'darkblue', 'darkcyan', 'darkgoldenrod', 'darkgray', 'darkgreen', 'darkkhaki', 'darkmagenta', 'darkolivegreen', 'darkorange', 'darkorchid', 'darkred', 'darksalmon', 'darkseagreen', 'darkslateblue', 'darkslategray', 'darkturquoise', 'darkviolet', 'deeppink', 'deepskyblue', 'dimgray', 'dodgerblue', 'firebrick', 'floralwhite', 'forestgreen', 'fuchsia', 'gainsboro', 'ghostwhite', 'gold', 'goldenrod', 'gray', 'green', 'greenyellow', 'honeydew', 'hotpink', 'indianred', 'indigo', 'ivory', 'khaki', 'lavender', 'lavenderblush', 'lawngreen', 'lemonchiffon', 'lightblue', 'lightcoral', 'lightcyan', 'lightgoldenrodyellow', 'lightgreen', 'lightgrey', 'lightpink', 'lightsalmon', 'lightseagreen', 'lightskyblue', 'lightslategray', 'lightsteelblue', 'lightyellow', 'lime', 'limegreen', 'linen', 'magenta', 'maroon', 'mediumaquamarine', 'mediumblue', 'mediumorchid', 'mediumpurple', 'mediumseagreen', 'mediumslateblue', 'mediumspringgreen', 'mediumturquoise', 'mediumvioletred', 'midnightblue', 'mintcream', 'mistyrose', 'moccasin', 'navajowhite', 'navy', 'oldlace', 'olive', 'olivedrab', 'orange', 'orangered', 'orchid', 'palegoldenrod', 'palegreen', 'paleturquoise', 'palevioletred', 'papayawhip', 'peachpuff', 'peru', 'pink', 'plum', 'powderblue', 'purple', 'red', 'rosybrown', 'royalblue', 'saddlebrown', 'salmon', 'sandybrown', 'seagreen', 'seashell', 'sienna', 'silver', 'skyblue', 'slateblue', 'slategray', 'snow', 'springgreen', 'steelblue', 'tan', 'teal', 'thistle', 'tomato', 'turquoise', 'violet', 'wheat', 'white', 'whitesmoke', 'yellow', 'yellowgreen'); @@ -396,6 +407,36 @@ function style_settings_valid_number_step($value, $step, $offset = 0.0) { return $computed_acceptable_error >= $remainder || $remainder >= ($step - $computed_acceptable_error); } +/* + * Validates an image URL if not empty. + * Checks syntax, existence and being an image. + */ +function style_settings_imgurl_validate(&$element, &$form_state) { + // An image URL with leading or trailing whitespace is still valid in CSS. + $url = trim($element['#value']); + $name = empty($element['#title']) ? $element['#parents'][0] : $element['#title']; + // An empty image URL resulting in url('') is still valid in CSS. + if (!empty($url)) { + // Get the base URL. + global $base_url; + // For a relative URL append the base URL. + if (parse_url($url, PHP_URL_SCHEME) == '') { + $url = $base_url . $url; + } + $headers = @get_headers($url, 1); + if (isset($headers['Content-Type'])) { + // Generate an error if the URL isn't an image or returns a 404. + if (strpos($headers['Content-Type'], 'image/') === FALSE) { + form_set_error($element['#parents'][0], t('%name is not an image, does not exist or something else is wrong with it.', array('%name' => $name))); + } + } + else { + // No 'Content-Type' returned. + form_set_error($element['#parents'][0], t('%name is not a valid URL.', array('%name' => $name))); + } + } +} + /** * Form element input handler for #type 'style_settings_number'. */