Merge pull request #694 from swierczek/feature/channel-settings

Add Typography > HTML Formatting options

Author: intoeetive

AUTHORS.md

@@ -17,6 +17,7 @@ If an entry is incorrect or duplicated, add or correct the entry in `.mailmap` i
 - Derek Jones <derek.jones@ellislab.com>
 - Doug Black Jr <dougblackjr@gmail.com>
 - Douglas Black <dougblackjr@gmail.com>
+- Eric Swierczek <2423727+swierczek@users.noreply.github.com>
 - Erwin Romkes <hello@stoneandstorm.com>
 - Gareth Davies <hello@garethtdavies.com>
 - Gavin * JCOGS <gavin@jcogs.net>
@@ -54,7 +55,7 @@ If an entry is incorrect or duplicated, add or correct the entry in `.mailmap` i
 - Simon Job <simon@job.id.au>
 - Stefan Rechsteiner <info@stefanrechsteiner.com>
 - Stephen G <45797159+stephengalbraith@users.noreply.github.com>
-- Stephen G <45797159+zdravvy@users.noreply.github.com>
+- zdravvy <45797159+zdravvy@users.noreply.github.com>
 - Terry Leigh Britton <terrybritton@users.noreply.github.com>
 - Tom Jaeger <Tom@PacketTide.com>
 - TomJaeger <Tom@PacketTide.com>

README.md

@@ -8,7 +8,7 @@ The ExpressionEngine user guide is written in human-readable Markdown and uses a
 
 ### Prerequisites
 
-Building the docs requires Node and npm.
+Building the docs requires Node and npm (latest stable version).
 
 In the root of the repository, install all the dependencies:
 
@@ -30,6 +30,10 @@ The documentation css and js files are located under `theme/assets-src`.
 
 To build the theme assets, run `npm run buildAssets`. You can also dynamically rebuild the assets when a file changes: `npm run watchAssets`.
 
+### Viewing local changes
+
+Manually load `/build/index.html` in your browser to view your local build. For example, `file:///Users/<username>/Documents/ExpressionEngine-User-Guide/build/index.html`. You can use the side navigation to navigate to different local files, but the search functionality always takes you to the live version at docs.expressionengine.com.
+
 ## Contributing
 
 See something that needs fixing? Want to improve the user guide or make it more helpful? Great! Check out [CONTRIBUTING.md](CONTRIBUTING.md) for details.

docs/control-panel/channels.md

@@ -121,8 +121,11 @@ NOTE: **Note:** We recommend using the default base URL variable `{base_url}` de
 - **Maximum characters allowed?** -- You may set a maximum number of characters allowed in any comment. Setting this preference to 0 (zero) will not place a restriction on the number of characters allowed.
 - **Comment time limit** -- This is the optional number of seconds that must lapse after a comment is posted before that same user can post another comment. This setting can help reduce comment "spam". The preference can be left blank or set to 0 (zero) if you do not want to impose a limit.
 - **Comment expiration** -- The number of days after an entry is posted in which to allow comments. After that period has expired, the entry will be closed to commenting and the comment form will no longer appear. Existing comments will still be displayed. Enter 0 (zero) for no expiration. Note that this preference sets the _default_ setting for the channel. The setting can be overridden and changed on a per-entry basis. You may override this setting in the [Comment Module Control Panel](comment/control-panel.md) section of the Comment Module so that comments are set to be moderated rather than closed once the expiration period is passed. If you also select the checkbox accompanying this setting, then all existing entries in this channel will be updated to reflect the new setting when you submit.
-- **Text formatting** -- This setting determines how comments are formatted by the system. There are three possible choices:
+- **Text formatting** -- This setting determines how comments are formatted by the system. There are three possible choices: `Auto line break`, `None`, and `XHTML`
 - **HTML formatting** -- Like the channel setting, this preference determines how raw HTML code within comments is handled. There are three options:
+1. Convert to HTML entities -- This will convert any HTML tags to their encoded versions and output the HTML tag as text without rendering the HTML in the DOM. For example: `<h1>` would become `&lt;h1&gt;`.
+2. Allow only safe HTML -- This will remove any unsafe HTML tags as defined in the [Typography library](development/legacy/libraries/typography.md#html_format).
+3. Allow all HTML (not recommended) -- This will allow any HTML to be saved and output as-is. For example: `<h1>test</h1>` would actually render an `h1` in the DOM.
 - **Allow image URLs?** -- You can determine whether or not you want people to be able to display images within comments by using the URL for the image.
 - **Render URLs and Email addresses as links?** -- When this option is set to "Yes", any full URLs or email addresses in comments will be automatically formatted as a valid HTML link to the address. If the option is "No" then the URL or email address in comment body will be treated and displayed as plain text.
 

docs/development/legacy/libraries/typography.md

@@ -98,6 +98,10 @@ The Typography class has a number of class properties that you may wish to set b
 
 (`string`) \[ **safe** / all / none \] — Controls how HTML is handled in text.
 
+- `"safe"` -- Allows the following HTML tags to be rendered in the DOM: `h2`, `h3`, `h4`, `h5`, `h6`, `abbr`, `b`, `blockquote`, `cite`, `code`, `del`, `em`, `i`, `ins`, `mark`, `pre`, `span`, `strong`, `sub`, `sup`. All other HTML tags are removed from the content.
+- `"all"` -- Allows all HTML tags to be rendered in the DOM. This is not recommended because it may allow users (who may not otherwise have access to edit templates) to inject HTML in unexpected places. For example, if the template is defined as `<p>{content}</p>`, but `{content}` itself is `<form><input></form>`, that will be rendered in the DOM as `<p><form><input></form></p>` which would essentially allow a user to add a form to a page via a `content` field that was probably not intended to be used in this way.
+- `"none"` -- Converts all HTML tags to their encoded values (e.g. `<h1>` becomes `&lt;h1&gt;`) and will output it as text. This is the safest option because it prevents any unexpected HTML from being rendered in the DOM.
+
 ### `$parse_images`
 
 (`bool`) \[ **TRUE** / FALSE \] — Whether or not `{file:XX:url}` and `{filedir_#}` variables are to be parsed.
@@ -203,7 +207,7 @@ This method encodes email addresses with Javascript, to assist in prevention of
 
 If you want to return a human readable "encoded" email address instead, you can also set the `Typography::$encode_type` class property to `"noscript"`.
 
-## Auto (XTHML) Typography
+## Auto (XHTML) Typography
 
 ### `auto_typography($str[, $reduce_linebreaks = FALSE])`