Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

MINOR Docs about HtmlEditorField and rich text editing

  • Loading branch information...
commit 8d9b00a4fd82b59ea0c6e9d0942a3ecec4d33d7a 1 parent 5220a46
@chillu chillu authored
View
3  docs/en/howto/extend-cms-interface.md
@@ -143,4 +143,5 @@ blocks and concepts for more complex extensions as well.
## Related
- * [CMS Architecture](../reference/cms-architecture)
+ * [CMS Architecture](../reference/cms-architecture)
+ * [Topics: Rich Text Editing](../topics/rich-text-editing)
View
3  docs/en/reference/cms-architecture.md
@@ -180,4 +180,5 @@ and `[api:CMSMenu::remove_menu_item()]`.
## Related
* [Howto: Extend the CMS Interface](../howto/extend-cms-interface)
- * [Reference: ModelAdmin](../reference/modeladmin)
+ * [Reference: ModelAdmin](../reference/modeladmin)
+ * [Topics: Rich Text Editing](../topics/rich-text-editing)
View
3  docs/en/reference/form-field-types.md
@@ -79,4 +79,5 @@ save it to the database
## CMS Field Editor
-Please see `[api:HTMLEditorField]` for in-depth documentation about custom forms created through a GUI in the CMS.
+Please see `[api:HTMLEditorField]` for in-depth documentation about custom forms created through a GUI in the CMS,
+as well as the topic documentation about [Rich Text Editing](/topics/rich-text-editing)
View
129 docs/en/topics/rich-text-editing.md
@@ -0,0 +1,129 @@
+# Rich-Text Editing (WYSIWYG)
+
+## Introduction
+
+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.
+
+## Usage
+
+The framework comes with a `[api:HTMLEditorField]` form field class which encapsulates most of the required functionality.
+It is usually added through the `[api:DataObject->getCMSFields()]` method:
+
+ :::php
+ class MyObject extends DataObject {
+ static $db = array('Content' => 'HTMLText');
+
+ public function getCMSFields() {
+ return new FieldSet(new HTMLEditorField('Content'));
+ }
+ }
+
+## Configuration
+
+To keep the JavaScript editor configuration manageable and extensible,
+we've wrapped it in a PHP class called `[api:HtmlEditorConfig]`.
+The class comes with its own defaults, which are extended through the `_config.php`
+files in the framework (and the `cms` module in case you've got that installed).
+There can be multiple configs, which should always be created / accessed using `[api:HtmlEditorConfig::get].
+You can then set the currently active config using `set_active()`.
+By default, a config named 'cms' is used in any field created throughout the CMS interface.
+
+Example: Enable the "media" plugin:
+
+ :::php
+ // File: mysite/_config.php
+ HtmlEditorConfig::get('cms')->enablePlugins('media');
+
+Example: Remove some buttons for more advanced formatting
+
+ :::php
+ // File: mysite/_config.php
+ HtmlEditorConfig::get('cms')->removeButtons('tablecontrols', 'blockquote', 'hr');
+
+## Recipes
+
+### Customizing the "Insert" panels
+
+In the standard installation, you can insert links (internal/external/anchor/email),
+images as well as flash media files. The forms used for preparing the new content element
+are rendered by SilverStripe, but there's some JavaScript involved to transfer
+back and forth between a content representation the editor can understand, present and save.
+
+Example: Remove field for "image captions"
+
+ :::php
+ // File: mysite/code/MyToolbarExtension.php
+ class MyToolbarExtension extends Extension {
+ public function updateFieldsForImage(&$fields, $url, $file) {
+ $fields->removeByName('Caption');
+ }
+ }
+
+ :::php
+ // File: mysite/_config.php
+ Object::add_extension('HtmlEditorField', 'MyToolbarExtension');
+
+Adding functionality is a bit more advanced, you'll most likely
+need to add some fields to the PHP forms, as well as write some
+JavaScript to ensure the values from those fields make it into the content
+elements (and back out in case an existing element gets edited).
+There's lots of extension points in the `[api:HtmlEditorField_Toolbar]` class
+to get you started.
+
+### Security groups with their own editor configuration
+
+Different groups of authors can be assigned their own config,
+e.g. a more restricted rule set for content reviewers (see the "Security" )
+The config is available on each user record through `[api:Member->getHtmlEditorConfigForCMS()]`.
+The group assignment is done through the "Security" interface for each `[api:Group]` record.
+Note: The dropdown is only available if more than one config exists.
+
+### Using the editor outside of the CMS
+
+Each interface can have multiple fields of this type, each with their own toolbar to set formatting
+and insert HTML elements. They do share one common set of dialogs for inserting links and other media though,
+encapsulated in the `[api:HtmlEditorField_Toolbar]` class.
+In the CMS, those dialogs are automatically instanciated, but in your own interfaces outside
+of the CMS you have to take care of instanciation yourself:
+
+ :::php
+ // File: mysite/code/MyController.php
+ class MyObjectController extends Controller {
+ public function EditorToolbar() {
+ return Object::create('HtmlEditorField_Toolbar', $this, "EditorToolbar");
+ }
+ }
+
+ :::ss
+ // File: mysite/templates/MyController.ss
+ $Form
+ <% control EditorToolbar %>
+ $MediaForm
+ $LinkForm
+ <% end_control %>
+
+Note: The dialogs rely on CMS-access, e.g. for uploading and browsing files,
+so this is considered advanced usage of the field.
+
+ :::php
+ // File: mysite/_config.php
+ HtmlEditorConfig::get('cms')->disablePlugins('ssbuttons');
+ HtmlEditorConfig::get('cms')->removeButtons('sslink', 'ssimage');
+ HtmlEditorConfig::get('cms')->addButtonsToLine(2, 'link', 'image');
+
+### Developing a wrapper to use a different WYSIWYG editors with HTMLEditorField
+
+WYSIWYG editors are complex beasts, so replacing it completely is a difficult task.
+The framework provides a wrapper implementation for the basic required functionality,
+mainly around selecting and inserting content into the editor view.
+Have a look in `HtmlEditorField.js` and the `ss.editorWrapper` object to get you started
+on your own editor wrapper. Note that the `[api:HtmlEditorConfig]` is currently hardwired to support TinyMCE,
+so its up to you to either convert existing configuration as applicable,
+or start your own configuration.
+
+## Related
+
+ * [Howto: Extend the CMS Interface](../howto/extend-cms-interface)
Please sign in to comment.
Something went wrong with that request. Please try again.