From 8d9b00a4fd82b59ea0c6e9d0942a3ecec4d33d7a Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 14 Feb 2012 00:49:34 +0100 Subject: [PATCH] MINOR Docs about HtmlEditorField and rich text editing --- docs/en/howto/extend-cms-interface.md | 3 +- docs/en/reference/cms-architecture.md | 3 +- docs/en/reference/form-field-types.md | 3 +- docs/en/topics/rich-text-editing.md | 129 ++++++++++++++++++++++++++ 4 files changed, 135 insertions(+), 3 deletions(-) create mode 100644 docs/en/topics/rich-text-editing.md diff --git a/docs/en/howto/extend-cms-interface.md b/docs/en/howto/extend-cms-interface.md index bc3339646..f5021d373 100644 --- a/docs/en/howto/extend-cms-interface.md +++ b/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) \ No newline at end of file + * [CMS Architecture](../reference/cms-architecture) + * [Topics: Rich Text Editing](../topics/rich-text-editing) \ No newline at end of file diff --git a/docs/en/reference/cms-architecture.md b/docs/en/reference/cms-architecture.md index 94f61e84f..305b33156 100644 --- a/docs/en/reference/cms-architecture.md +++ b/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) \ No newline at end of file + * [Reference: ModelAdmin](../reference/modeladmin) + * [Topics: Rich Text Editing](../topics/rich-text-editing) \ No newline at end of file diff --git a/docs/en/reference/form-field-types.md b/docs/en/reference/form-field-types.md index 23db760fb..ff4ee484c 100644 --- a/docs/en/reference/form-field-types.md +++ b/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) diff --git a/docs/en/topics/rich-text-editing.md b/docs/en/topics/rich-text-editing.md new file mode 100644 index 000000000..731fd43f4 --- /dev/null +++ b/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) \ No newline at end of file