diff --git a/docs/en/topics/data-types.md b/docs/en/topics/data-types.md index 099832ff6..23f86656b 100644 --- a/docs/en/topics/data-types.md +++ b/docs/en/topics/data-types.md @@ -13,12 +13,12 @@ sentence in a longer piece of text. * `[api:Date]`: A date field * `[api:Decimal]`: A decimal number. * `[api:Enum]`: An enumeration of a set of strings -* `[api:HTMLText]`: A variable-length string of up to 2 megabytes, designed to store HTML +* `[api:HTMLText]`: A variable-length string of up to 2MB, designed to store HTML * `[api:HTMLVarchar]`: A variable-length string of up to 255 characters, designed to store HTML * `[api:Int]`: An integer field. * `[api:Percentage]`: A decimal number between 0 and 1 that represents a percentage. * `[api:SS_Datetime]`: A date / time field -* `[api:Text]`: A variable-length string of up to 2 megabytes, designed to store raw text +* `[api:Text]`: A variable-length string of up to 2MB, designed to store raw text * `[api:Time]`: A time field * `[api:Varchar]`: A variable-length string of up to 255 characters, designed to store raw text @@ -83,12 +83,15 @@ Example: Flagging an object of type `MyObject` (see above) if it's date is in th ## Casting HTML Text -The database field types `[api:HTMLVarchar]` and `[api:Varchar]` are exactly the same in the database. However, the -templating engine knows to escape the `[api:Varchar]` field and not the `[api:HTMLVarchar]` field. So, it's important you -use the right field if you don't want to be putting $FieldType.XML everywhere. +The database field types `[api:HTMLVarchar]`/`[api:HTMLText]` and `[api:Varchar]`/`[api:Text]` +are exactly the same in the database. However, the templating engine knows to escape +fields without the `HTML` prefix automatically in templates, +to prevent them from rendering HTML interpreted by browsers. +This escaping prevents attacks like CSRF or XSS (see "[security](/topics/security)"), +which is important if these fields store user-provided data. -If you're going to put HTML content into the field, please use the field type with the HTML prefix. Otherwise, you're -going to risk double-escaping your data, forgetting to escape your data, and generally creating a confusing situation. +You can disable this auto-escaping by using the `$MyField.RAW` escaping hints, +or explicitly request escaping of HTML content via `$MyHtmlField.XML`. ## Related diff --git a/docs/en/topics/rich-text-editing.md b/docs/en/topics/rich-text-editing.md index cc9ed7ccb..1e4f5a0b1 100644 --- a/docs/en/topics/rich-text-editing.md +++ b/docs/en/topics/rich-text-editing.md @@ -5,7 +5,9 @@ Editing and formatting content is the bread and butter of every content management system, which is why SilverStripe has a tight integration with our preferred editor library, [TinyMCE](http://tinymce.com). On top of the base functionality, we use our own insertion dialogs to ensure -you can effectively select and upload files. +you can effectively select and upload files. In addition to the markup managed by TinyMCE, +we use [shortcodes](/reference/shortcodes) to store information about inserted +images or media elements. ## Usage @@ -151,7 +153,12 @@ documentation, or browse through plugins that come with the Framework at `thirdp The `[api:HtmlEditorField]` API also handles inserting images and media files into the managed HTML content. It can be used both for referencing files on the webserver filesystem (through the `[api:File]` and `[api:Image]` APIs), -as well as hotlinking files from the web. +as well as hotlinking files from the web. + +We use [shortcodes](/reference/shortcodes) to store information about inserted images or media elements. +The `[api:ShortcodeParser]` API post-processes the HTML content on rendering, +and replaces the shortcodes accordingly. It also takes care of care of placing the +shortcode replacements relative to its surrounding markup (e.g. left/right alignment). ## oEmbed: Embedding media through external services @@ -168,6 +175,27 @@ a cache, append `?flush=1` to a URL. To disable oEmbed usage, set the `Oembed.enabled` configuration property to "false". +### Doctypes + +Since TinyMCE generates markup, it needs to know which doctype your documents +will be rendered in. You can set this through the [element_format](http://www.tinymce.com/wiki.php/Configuration:element_format) configuration variable. It defaults to the stricter 'xhtml' +setting, for example rendering self closing tags like `
` instead of `
`. +In case you want to adhere to HTML4 instead, use the following configuration: + + :::php + HtmlEditorConfig::get('cms')->setOption('element_format', 'html'); + +By default, TinyMCE and SilverStripe will generate valid HTML5 markup, +but it will strip out HTML5 tags like `
` or `
`. +If you plan to use those, add them to the [valid_elements](http://www.tinymce.com/wiki.php/Configuration:valid_elements) +configuration setting. + +Also, the `[api:SS_HTMLValue]` API underpinning the HTML processing parses the markup +into a temporary object tree which can be traversed and modified before saving. +The built-in parser only supports HTML4 and XHTML syntax. In order to successfully +process HTML5 tags, please use the +['silverstripe/html5' module](https://github.com/silverstripe/silverstripe-html5). + ## Recipes ### Customizing the "Insert" panels