tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Extended docs for shortcode handling and doctypes (fixes #1700)

Browse Source
This commit is contained in:
Ingo Schommer 2013-04-16 14:01:04 +02:00
parent 08bf2aa91e
commit 67ce9e08cc
2 changed files with 40 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
docs/en/topics/data-types.md
View File

@ -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

32
docs/en/topics/rich-text-editing.md
View File

@ -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 `<br/>` instead of `<br>`.
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 `<article>` or `<figure>`.
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