www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/htmlawed/readme.txt

   1 CONTENTS OF THIS FILE
   2 ---------------------
   3
   4  * Introduction
   5  * Requirements
   6  * Installation
   7  * Configuration
   8  * Maintainers
   9
  10
  11 INTRODUCTION
  12 ------------
  13
  14 The htmLawed module uses the htmLawed PHP library to restrict and purify HTML
  15 for compliance with site administrator policy and standards and for security.
  16 Use of the htmLawed library allows for highly customizable control of HTML
  17 markup.
  18
  19  * For a full description of the module, visit the project page:
  20    https://www.drupal.org/project/htmlawed
  21    or https://www.drupal.org/node/255886
  22
  23  * To submit bug reports and feature suggestions, or to track changes:
  24    https://www.drupal.org/project/issues/htmlawed
  25
  26
  27 REQUIREMENTS
  28 ------------
  29
  30 This module requires no modules outside of Drupal core.
  31
  32
  33 INSTALLATION
  34 ------------
  35
  36  * Install the htmLawed module as you would normally install a contributed
  37    Drupal module. Visit https://www.drupal.org/node/1897420 for further
  38    information.
  39
  40 Note: If the htmLawed PHP library has been installed through the Libraries
  41 Drupal module, then the htmLawed module will use that library, and not the
  42 library in the htmLawed module's 'htmLawed' sub-directory.
  43
  44
  45 CONFIGURATION
  46 -------------
  47
  48 To enable and/or configure the htmLawed filter, such as for a text format, visit
  49 the text formats section of your Drupal website and configure the text format
  50 that will use or uses the filter.
  51
  52 More than one text format can use the filter, each configured with its own
  53 settings for the filter. The htmLawed filter is configured by providing values
  54 in the form for its settings. The 'Config.' form-field is filled with
  55 comma-separated, quoted, key-value pairs like:
  56
  57 ```
  58 'safe'=>1, 'element'=>'a, em, strong'
  59 ```
  60
  61 (These are interpreted as PHP array elements).
  62
  63 The 'Spec.' form-field is an optional string of unquoted text. Visit the
  64 htmLawed documentation for more on how 'Config.' and 'Spec.' can be set, for
  65 instance, to permit all HTML, or restrict links to only certain domains. The
  66 default htmLawed filter settings allow the use of the a, em, strong, cite,
  67 code, ol, ul, li, dl, dt, dd, br and p HTML tags, and deny the id and style
  68 HTML attributes, and any unsafe markup (such as the scriptable onclick
  69 attribute).
  70
  71 Content in the 'Short tip' and 'Long tip' form-fields are used to inform users
  72 about the filter, such as about the tags that are allowed.
  73
  74 To allow HTML comments such as the one used for the Drupal teaser-break
  75 indicator (<!--break-->), add "'comment' => 2" to the 'Config.' value of the
  76 htmLawed settings. To allow PHP codes (flanked by '<?php' and '?>') add
  77 "'save_php' => 1" to the 'Config.' value of the htmLawed settings.
  78
  79 Depending on the types of other filters in use, you may need to re-arrange the
  80 processing order of filters. The htmLawed filter would usually be the last
  81 filter to be run. If a filter generates HTML markup and is run before htmLawed,
  82 then htmLawed should be configured appropriately to permit such markup.
  83
  84 Any in-built Drupal actions/filters to restrict HTML, correct broken HTML, or
  85 balance or properly nest HTML tags can be disabled since htmLawed performs
  86 these tasks. The htmLawed filter can also be used to restrict HTML attributes,
  87 limit URL protocols, etc. Note that htmLawed does not convert URLs into links
  88 nor does it convert line breaks into HTML.
  89
  90 It is important to understand the security implications of the htmLawed settings
  91 in use and the limitations of htmLawed. To keep the htmLawed library included
  92 with the module updated, replace the 'htmLawed.php' and 'htmLawed_README.htm'
  93 files inside the 'htmLawed' sub-directory of the htmLawed module directory
  94 ('htmlawed') with newer versions downloaded from the htmLawed website
  95 (www.bioinformatics.org/phplabware/internal_utilities/htmLawed). If the htmLawed
  96 library is being used through the Libraries Drupal module, use that module to
  97 update the library.
  98
  99
 100 MAINTAINERS
 101 -----------
 102
 103  * alpha2zee - https://www.drupal.org/u/alpha2zee