<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fHTML">Class Documentation</a>''' - <a href="/api/fHTML">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fHTML.php" target="_blank">Source Code</a>
<<toc></toc>> )))
The fHTML class helps to manipulate text so that it can be reliably converted for HTML display.
When developing websites that allow for user-generated content, it can be challenging to ensure that all content entered is displayed as it was intended to be displayed. Certain content may allow HTML, while other may not. The fHTML class provides two static methods for escaping data to be displayed, ::encode() and ::prepare(). Both methods treat all content as UTF-8.
If there is a need to escape content that does not allow HTML, the static method ::encode() should be used. This method will encode special characters, including the < and > characters used for HTML tags. Because of this, all HTML tags will be displayed as plain text, and will not function as HTML.
It is very important that all untrusted user input be escaped using this method to prevent cross-site scripting attacks. See the security page for more information.
`encode()` also properly escapes characters for display inside of HTML `input`, `textarea` and `select` tags.
`prepare()` will ensure that all special characters in the provided content will be properly displayed, while allowing HTML tags and entities. This method should only be used for content coming from trusted sources otherwise the code will be vulnerable to cross-site scripting attacks.
In addition to preparing content for valid display by encoding content, often times content needs to have some basic HTML formatting applied to it. The fHTML class provides two methods, ::convertNewlines() and ::makeLinks(), to help with common formatting tasks.
`convertNewlines()` will look at content as a mixture of plain text and HTML. If neither the `
` or any block-level HTML tags are found, the content will have all newline characters converted to `
`. If the converse is true, the content will be returned as is.
Below is an example of the conversion happening:
The output from above would be:
Here is an example of newlines being left as-is due to block-level HTML:
The output from above would be:
The ::makeLinks() method will parse through a string and create HTML links out of anything that resembles a URL or email address, as long as it is not already part of an `` tag.
Here is an example of it in action:
The output would be:
When displaying `select` and `checkbox` inputs it is necessary to print specific attributes to specify the current state of the inputs. The fHTML class provides two helper methods to simply this process: ::printOption() and ::showChecked().
- printOption() will display a `select` input `option` tag while marking it with `selected="selected"` if the option’s value equals the currently selected value. The following PHP:
- showChecked() provides similar functionality for checkboxes, however since checkboxes can include many different attributes, `showChecked()` only handles printing the `checked="checked"` part. Here is an example of using `showChecked()`:
If you default content is HTML, the method ::sendHeader() should be called ensure that the `Content-Type` header is set to the correct value of `text/html; charset=utf-8`. The `utf-8` character set encoding is specified since all of Flourish is built to work with UTF-8.