Skip to content

Latest commit

 

History

History
195 lines (152 loc) · 6.84 KB

fHTML.wiki

File metadata and controls

195 lines (152 loc) · 6.84 KB

Table of Contents

fHTML

<<css mode="next" class="sidebar"></css>> (((

Class Resources <<toc></toc>>

 - '''<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.

Escaping Content (Security)

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.

Disallowing HTML

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.

Allowing HTML

`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.

Formatting

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:

Select Options and Checkboxes

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:
would produce the following HTML:

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()`:
would produce the following output:

Sending the Content Type Header

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.