CONTENTS OF THIS FILE
---------------------

 * Introduction
 * Requirements
 * Installation
 * Configuration
 * Maintainers


INTRODUCTION
------------

The htmLawed module uses the htmLawed PHP library to restrict and purify HTML
for compliance with site administrator policy and standards and for security.
Use of the htmLawed library allows for highly customizable control of HTML
markup. For more, visit the module's and htmLawed library's websites at
https://www.drupal.org/project/htmlawed and
http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed.


REQUIREMENTS
------------

This module requires no modules outside of Drupal core.


INSTALLATION
------------

Install the htmLawed module as you would normally install a contributed Drupal module.
Visit https://www.drupal.org/node/1897420 for further information.

Note: If the htmLawed PHP library has been installed through the Libraries
Drupal module, then the htmLawed module will use that library, and not the
library in the htmLawed module's htmLawed sub-directory.


CONFIGURATION
-------------

To enable and/or configure the htmLawed filter, such as for a text format, visit
the text formats section of your Drupal website and configure the text format
that will use or uses the filter. More than one text format can use the filter,
each configured with its own settings for the filter.

The htmLawed filter is configured by providing values in the form for its settings.

The Config. form-field is filled with comma-separated, quoted, key-value pairs that
are interpreted as PHP array elements. The default Config. value for the filter is:

```
'safe'=>1, 'elements'=>'a, em, strong, cite, code, ol, ul, li, dl, dt, dd, br, p',
'deny_attribute'=>'data-hx-*, id, style', 'any_custom_element'=>0
```

With this default setting, htmLawed allows the use of the a, em, strong, cite, code,
ol, ul, li, dl, dt, dd, br and p HTML tags, and denies the data-hx-*, id, and style
HTML attributes and potentially unsafe markup such as the scriptable event attributes
like onclick and onmouseover, HTML CDATA or comment sections, and certain types of
URLs.

The Spec. form-field is an optional string of unquoted text. See the htmLawed
library documentation for more on how Config. and Spec. can be set, for instance,
to permit all HTML, or restrict links to only certain domains. Content in the Short
tip and Long tip form-fields are used to inform users about the filter, such as
about the tags that are allowed.

To allow HTML comments such as the one used for the Drupal teaser-break indicator
(<!--break-->), add 'comment' => 2 to the Config. value of the htmLawed settings.
To allow PHP codes (flanked by <?php and ?>) add 'save_php' => 1 to the Config. value
of the htmLawed settings.

Depending on the types of filters that are also used, you may need to re-arrange the
processing order of filters. The htmLawed filter would usually be the last filter to
be run. If a filter generates HTML markup and is run before htmLawed, then htmLawed
should be configured appropriately to permit such markup.

Any in-built Drupal actions/filters to restrict HTML, correct broken HTML, or balance
or properly nest HTML tags can be disabled since htmLawed performs these tasks. The
htmLawed filter can also be used to restrict HTML attributes, limit URL protocols, etc.
Note that htmLawed does not convert URLs into links nor does it convert line breaks
into HTML br or p tags.

It is important to understand the security implications of the htmLawed settings in
use and the limitations of htmLawed. Security vulnerabilities may arise if htmLawed
Config. parameters such as elements and deny_attribute are set inappropriately even
if the safe parameter is enabled. Recent versions of Drupal (11.2+) use scriptable
custom data attributes (data-hx-*) and you may want to have them filtered out from
input text by ensuring that the deny_attribute parameter value includes data-hx-*
(e.g., 'deny_attribute'=>'data-hx-*, id, style'). To keep the htmLawed script included
with the module updated, replace the htmLawed.php and htmLawed_README.htm files inside
the htmLawed sub-directory of the module directory with newer versions downloaded from
the htmLawed library website.


MAINTAINERS
-----------

 * alpha2zee - https://www.drupal.org/u/alpha2zee
