From 1346916c49209f766b13d588e307101205fb7c61 Mon Sep 17 00:00:00 2001 From: GeLo Date: Sun, 21 Feb 2016 11:58:39 +0100 Subject: [PATCH] Rewrite doc using RestructuredText --- .travis.yml | 1 + LICENSE | 2 +- README.md | 7 +- Resources/doc/configuration.md | 115 ------- Resources/doc/file_browse_upload.md | 123 -------- Resources/doc/index.rst | 51 ++++ Resources/doc/installation.md | 27 -- Resources/doc/installation.rst | 40 +++ Resources/doc/usage.md | 339 --------------------- Resources/doc/usage/autoinline.rst | 22 ++ Resources/doc/usage/config.rst | 61 ++++ Resources/doc/usage/file-browse-upload.rst | 103 +++++++ Resources/doc/usage/index.rst | 24 ++ Resources/doc/usage/index.rst.inc | 14 + Resources/doc/usage/inline.rst | 20 ++ Resources/doc/usage/jquery.rst | 46 +++ Resources/doc/usage/loading.rst | 24 ++ Resources/doc/usage/plugin.rst | 48 +++ Resources/doc/usage/skin.rst | 32 ++ Resources/doc/usage/style.rst | 36 +++ Resources/doc/usage/template.rst | 50 +++ Resources/doc/usage/textarea-fallback.rst | 18 ++ Resources/doc/usage/textarea-sync.rst | 18 ++ Resources/doc/usage/toolbar.rst | 83 +++++ Resources/doc/usage/version.rst | 40 +++ 25 files changed, 734 insertions(+), 610 deletions(-) delete mode 100644 Resources/doc/configuration.md delete mode 100644 Resources/doc/file_browse_upload.md create mode 100644 Resources/doc/index.rst delete mode 100644 Resources/doc/installation.md create mode 100644 Resources/doc/installation.rst delete mode 100644 Resources/doc/usage.md create mode 100644 Resources/doc/usage/autoinline.rst create mode 100644 Resources/doc/usage/config.rst create mode 100644 Resources/doc/usage/file-browse-upload.rst create mode 100644 Resources/doc/usage/index.rst create mode 100644 Resources/doc/usage/index.rst.inc create mode 100644 Resources/doc/usage/inline.rst create mode 100644 Resources/doc/usage/jquery.rst create mode 100644 Resources/doc/usage/loading.rst create mode 100644 Resources/doc/usage/plugin.rst create mode 100644 Resources/doc/usage/skin.rst create mode 100644 Resources/doc/usage/style.rst create mode 100644 Resources/doc/usage/template.rst create mode 100644 Resources/doc/usage/textarea-fallback.rst create mode 100644 Resources/doc/usage/textarea-sync.rst create mode 100644 Resources/doc/usage/toolbar.rst create mode 100644 Resources/doc/usage/version.rst diff --git a/.travis.yml b/.travis.yml index 3c05c78e..14db8ca0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,6 +18,7 @@ env: install: - composer self-update + - if [[ "$TRAVIS_PHP_VERSION" == "5.3.3" ]]; then composer config disable-tls true; fi - composer require --no-update symfony/framework-bundle:${SYMFONY_VERSION} - composer require --no-update symfony/form:${SYMFONY_VERSION} - composer require --dev --no-update symfony/phpunit-bridge:${SYMFONY_PHPUNIT_BRIDGE_VERSION} diff --git a/LICENSE b/LICENSE index b80f290a..77c443ae 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2011-2015 Eric GELOEN +Copyright (c) 2011-2016 Eric GELOEN Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the diff --git a/README.md b/README.md index c8e09d38..d05195b8 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,11 @@ [![License](https://poser.pugx.org/egeloen/ckeditor-bundle/license.svg)](https://packagist.org/packages/egeloen/ckeditor-bundle) The bundle provides a [CKEditor](http://ckeditor.com/) integration for your Symfony2 Project. It automatically registers -the new `ckeditor` form type which can be easily configured. +the new `ckeditor` form type which can be easily as well as highly configured. ## Documentation - 1. [Installation](/Resources/doc/installation.md) - 2. [Usage](/Resources/doc/usage.md) - 3. [Configuration](/Resources/doc/configuration.md) (Optional) - 4. [File Browse/Upload](/Resources/doc/file_browse_upload.md) (Optional) +Please, read the [official documentation](/Resources/doc/index.rst). ## Testing diff --git a/Resources/doc/configuration.md b/Resources/doc/configuration.md deleted file mode 100644 index 50985d6d..00000000 --- a/Resources/doc/configuration.md +++ /dev/null @@ -1,115 +0,0 @@ -# Configuration - -The CKEditor provides an advanced configuration which can be reused on multiple CKEditor instance. Instead of duplicate -the configuration on each form builder, you can directly configure it once & then reuse it all the time. - -## Basic configuration - -The bundle allows you to define as many configs you want. The list of all config options are available -[here](http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html). - -``` yaml -ivory_ck_editor: - configs: - my_config: - toolbar: [ [ "Source", "-", "Save" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] - uiColor: "#000000" - filebrowserUploadRoute: "my_route" - extraPlugins: "wordcount" - # ... -``` - -When you have defined a config, you can use it with the `config_name` option: - -``` php -$builder->add('field', 'ckeditor', array( - 'config_name' => 'my_config', -)); -``` - -If you want to override some parts of the defined config, you can still use the `config` option: - -``` php -$builder->add('field', 'ckeditor', array( - 'config_name' => 'my_config', - 'config' => array('uiColor' => '#ffffff'), -)); -``` - -If you want to define globally your configuration, you can use the `default_config` node: - -``` yaml -ivory_ck_editor: - default_config: my_config - configs: - my_config: - # ... -``` - -## Toolbar configuration - -### Built-in - -CKEditor provides 3 different packages with their own configurations (full, standard & basic). The bundle is shipped -with the full edition but you can easily switch the toolbar configuration by using the `full`, `standard` or `basic` -keywork as toolbar. - -``` yaml -ivory_ck_editor: - configs: - my_config: - toolbar: standard -``` - -Here, the toolbar will be rendered as it is defined in the standard edition. If you want to define your own toolbar, -you should use the custom way :) - -### Custom - -Build a toolbar in the configuration or on the form builder is really a pain... Each time, you want a custom one, you -need to redefine all the structure... To avoid this duplication, the bundle allows you to define your toolbars in a -separate node & reuse them: - -``` yaml -ivory_ck_editor: - configs: - my_config_1: - toolbar: "my_toolbar_1" - uiColor: "#000000" - # ... - my_config_2: - toolbar: "my_toolbar_2" - uiColor: "#ffffff" - # ... - my_config_2: - toolbar: "my_toolbar_1" - uiColor: "#cccccc" - toolbars: - configs: - my_toolbar_1: [ [ "Source", "-", "Save" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] - my_toolbar_2: [ [ "Source" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] -``` - -The config is still not perfect as you still have code duplications in the toolbar items. To avoid this part, you can -define a group of items in a separate node & then, inject them in your toolbar by prefixing them with a `@`. - -``` yaml -ivory_ck_editor: - configs: - my_config_1: - toolbar: "my_toolbar_1" - uiColor: "#000000" - # ... - my_config_2: - toolbar: "my_toolbar_2" - uiColor: "#ffffff" - # ... - toolbars: - configs: - my_toolbar_1: [ "@document", "/", "@link" , "/", "@tool" ] - my_toolbar_2: [ "@document", "/", "@tool" ] - items: - document: [ "Source", "-", "Save" ] - link: [ "Anchor" ] - tool: [ "Maximize" ] -``` diff --git a/Resources/doc/file_browse_upload.md b/Resources/doc/file_browse_upload.md deleted file mode 100644 index b34432d7..00000000 --- a/Resources/doc/file_browse_upload.md +++ /dev/null @@ -1,123 +0,0 @@ -# File Browse/Upload - -To ease the CKEditor file handling, the bundle adds options which are not in CKEditor by default. These options are -related to URLs which allows to manage file browse/upload. As explain -[here](http://symfony.com/doc/current/book/routing.html), Symfony provides a powerfull routing component allowing you -to generate URLs. These concepts are directly managed by the bundle by adding three new options for each "*Url" option: - -For example, the filebrowserBrowseUrl option can be generated with these three new options: - - * filebrowserBrowseRoute - * filebrowserBrowseRouteParameters - * filebrowserBrowseRouteAbsolute - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'filebrowserBrowseRoute' => 'my_route', - 'filebrowserBrowseRouteParameters' => array('slug' => 'my-slug'), - 'filebrowserBrowseRouteAbsolute' => true, - ), -)); -``` - -If this process does not fit your needs, you can use the `filebrowser*Handler` option allowing you to build your own -url with a simple closure: - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'filebrowserBrowseHandler' => function (RouterInterface $router) { - return $router->generate('my_route', array('slug' => 'my-slug', true); - }, - ), -)); -``` - -A closure will allow you to use the `use` keyword in order to make it aware of your own dependencies :) - -These features are about the following options: - - * filebrowserBrowseUrl - * filebrowserFlashBrowseUrl - * filebrowserImageBrowseUrl - * filebrowserImageBrowseLinkUrl - * filebrowserUploadUrl - * filebrowserFlashUploadUrl - * filebrowserImageUploadUrl - -## Integration - -If you want to simplify your life, you can directly use other bundles which provides an easy integration. - -### [FMElfinderBundle](https://github.com/helios-ag/FMElfinderBundle) - -The FMElfinderBundle provides a [elfinder](http://elfinder.org/) integration for your Symfony2 project and at the same -time provides an integration with the IvoryCKEditorBundle. - -To use it, just read this [documentation](https://github.com/helios-ag/FMElfinderBundle#using-elfinder-with-ckeditorbundle). - -### [CoopTilleulsCKEditorSonataMediaBundle](https://github.com/coopTilleuls/CoopTilleulsCKEditorSonataMediaBundle/) - -The CoopTilleulsCKEditorSonataMediaBundle provides [SonataMedia](http://sonata-project.org/bundles/media) integration with CKEditor and IvoryCKEditorBundle. - -Read [installation instructions](https://github.com/coopTilleuls/CoopTilleulsCKEditorSonataMediaBundle/blob/master/Resources/doc/install.md). - -The working example: - -Install and configure [SonataMediaBundle](http://sonata-project.org/bundles/media/master/doc/index.html). - -Add CoopTilleulsCKEditorSonataMediaBundle in your `composer.json` file: - -``` json -{ - "require": { - "tilleuls/ckeditor-sonata-media-bundle": "~1.0", - } -} -``` - -Register the bundle in your AppKernel: - -``` php -// app/AppKernel.php - -public function registerBundles() -{ - return array( - // ... - new CoopTilleuls\Bundle\CKEditorSonataMediaBundle\CoopTilleulsCKEditorSonataMediaBundle(), - // ... - ); -} -``` - -Install bundles: - -``` -$ composer update -``` - -Configure IvoryCKEditorBundle to use the bundle as file browser: - -``` yaml -# app/config/config.yml - -ivory_ck_editor: - default_config: default - configs: - default: - filebrowserBrowseRoute: admin_sonata_media_media_browser - filebrowserImageBrowseRoute: admin_sonata_media_media_browser - # Display images by default when clicking the image dialog browse button - filebrowserImageBrowseRouteParameters: - provider: sonata.media.provider.image - filebrowserUploadRoute: admin_sonata_media_media_upload - filebrowserUploadRouteParameters: - provider: sonata.media.provider.file - # Upload file as image when sending a file from the image dialog - filebrowserImageUploadRoute: admin_sonata_media_media_upload - filebrowserImageUploadRouteParameters: - provider: sonata.media.provider.image - context: my-context # Optional, to upload in a custom context -``` diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst new file mode 100644 index 00000000..4ace6653 --- /dev/null +++ b/Resources/doc/index.rst @@ -0,0 +1,51 @@ +Getting started with IvoryCKEditorBundle +======================================== + +.. toctree:: + :hidden: + + installation + usage/index + +Overview +-------- + +The bundle integrates `CKEditor`_ into `Symfony`_ via the `Form Component`_. It automatically registers a new type +called ``ckeditor`` which can be easily as well as highly configured. This type extends the `textarea`_ one, meaning +all textarea options are available. + +Here, an example where we customize the `CKEditor config`_: + +.. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'uiColor' => '#ffffff', + //... + ), + )); + +.. note:: + + As of Symfony 2.8, the second argument of ``$builder->add()`` accepts the fully qualified class name of the + form type and it becomes mandatory to use it in Symfony 3.0. Depending on your Symfony versions, you should replace + the ``ckeditor`` parameter by ``Ivory\CKEditorBundle\Form\Type\CKEditorType`` or by ``CKEditorType::class`` if your + project relies on PHP 5.5+. + +Installation +------------ + +To install the bundle, please, read the :doc:`Installation documentation`. + +Usage +----- + +If you want to learn more, this documentation covers the following use cases: + +.. include:: usage/index.rst.inc + +.. _`CKEditor`: http://ckeditor.com/ +.. _`Symfony`: http://symfony.com/ +.. _`Form Component`: http://symfony.com/doc/current/book/forms.html +.. _`textarea`: http://symfony.com/doc/current/reference/forms/types/textarea.html +.. _`CKEditor config`: http://docs.ckeditor.com/#!/api/CKEDITOR.config diff --git a/Resources/doc/installation.md b/Resources/doc/installation.md deleted file mode 100644 index c0258a3d..00000000 --- a/Resources/doc/installation.md +++ /dev/null @@ -1,27 +0,0 @@ -# Installation - -Require the bundle in your composer.json file: - -``` -$ composer require egeloen/ckeditor-bundle --no-update -``` - -Register the bundle: - -``` php -// app/AppKernel.php - -public function registerBundles() -{ - return array( - new Ivory\CKEditorBundle\IvoryCKEditorBundle(), - // ... - ); -} -``` - -Install the bundle: - -``` -$ composer update egeloen/ckeditor-bundle -``` diff --git a/Resources/doc/installation.rst b/Resources/doc/installation.rst new file mode 100644 index 00000000..15a398dc --- /dev/null +++ b/Resources/doc/installation.rst @@ -0,0 +1,40 @@ +Installation +============ + +Download the Bundle +------------------- + +Require the bundle in your ``composer.json`` file: + +.. code-block:: bash + + $ composer require egeloen/ckeditor-bundle + +Register the Bundle +------------------- + +Then, update your ``app/AppKernel.php``: + +.. code-block:: php + + class AppKernel extends Kernel + { + public function registerBundles() + { + $bundles = array( + new Ivory\CKEditorBundle\IvoryCKEditorBundle(), + // ... + ); + + // ... + } + } + +Install the Assets +------------------ + +Once, you have registered the bundle, you need to install the assets in the web directory: + +.. code-block:: bash + + $ php app/console assets:install web diff --git a/Resources/doc/usage.md b/Resources/doc/usage.md deleted file mode 100644 index 1e60e777..00000000 --- a/Resources/doc/usage.md +++ /dev/null @@ -1,339 +0,0 @@ -# Usage - -Before starting, you should read the Symfony2 Form documentation which is available -[here](http://symfony.com/doc/current/book/forms.html). It will give you a better understanding for the next parts. - -To resume, the bundle simply registers a new form field type called ``ckeditor``. This type extends the -[textarea](http://symfony.com/doc/current/reference/forms/types/textarea.html) one. - -## Config - -The config option is the equivalent of the -[CKEditor config option](http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html). A simple example: - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'toolbar' => array( - array( - 'name' => 'document', - 'items' => array('Source', '-', 'Save', 'NewPage', 'DocProps', 'Preview', 'Print', '-', 'Templates'), - ), - '/', - array( - 'name' => 'basicstyles', - 'items' => array('Bold', 'Italic', 'Underline', 'Strike', 'Subscript', 'Superscript', '-', 'RemoveFormat'), - ), - ), - 'uiColor' => '#ffffff', - //... - ), -)); -``` - -**NOTE** As of Symfony 2.8, the second parameter for ``$builder->add()`` accepts the fully qualified class name of the -form type and is required in Symfony 3.0. In these Symfony versions, you should replace the ``ckeditor`` parameter value -with ``Ivory\CKEditorBundle\Form\Type\CKEditorType`` or its constant ``CKEditorType::class`` if your on PHP 5.5 or -upper. - -A toolbar is an array of toolbars (strips), each one being also an array, containing a list of UI items. To do a -carriage return, you just have to add the char ``/`` between strips. - -## Plugins support - -The bundle offers you the ability to manage extra plugins. To understand how it works, you will enable the -[wordcount](http://ckeditor.com/addon/wordcount) plugin for our CKEditor widget. - -### Install - -First, you need to download & extract it in the web directory. For that, you have 2 possibilities: - - - Directly put the plugin in the web directory (`/web/ckeditor/plugins/` for example). - - Put the plugin in the `/Resources/public/` directory of any of your bundles. - -### Register - -In order to load it, you need to specify his location to the bundle. For that, you can pass it as option to the widget: - -``` php -$builder->add('field', 'ckeditor', array( - 'plugins' => array( - 'wordcount' => array( - 'path' => '/bundles/mybundle/wordcount/', - 'filename' => 'plugin.js', - ), - ), -)); -``` - -The plugin can now be used but if you do that, the plugin will only be usable for this form. If you prefer enable -plugins for all CKEditor widget, you should register them in your configuration file: - -``` -ivory_ck_editor: - plugins: - wordcount: - path: "/bundles/mybundle/wordcount/" - filename: "plugin.js" -``` - -### Use it - -To use it, simply add it as `extraPlugins` in the ckeditor widget config: - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'extraPlugins' => 'wordcount', - ), -)); -``` - -## Skin support - -Download a skin from [CKEditor](http://ckeditor.com/addons/skins/all) & extract it in the web or bundle resource directory: - -ex: `/web/ckeditor/skins/` - -### Register - -Place the following code on your config.yml and change the skin name - -``` -ivory_ck_editor: - configs: - my_config: - skin: "skin_name,/absolute/web/skin/path/" # ex: ckeditor/skins/skin_name/ if you placed in the web directory -``` - -## StylesSet support - -The bundle allows you to define your own styles. Like plugins, you can define them at the form level or in your -configuration file: - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'stylesSet' => 'my_styles', - ), - 'styles' => array( - 'my_styles' => array( - array('name' => 'Blue Title', 'element' => 'h2', 'styles' => array('color' => 'Blue')), - array('name' => 'CSS Style', 'element' => 'span', 'attributes' => array('class' => 'my_style')), - array('name' => 'Multiple Element Style', 'element' => array('h2', 'span'), 'attributes' => array('class' => 'my_class')), - array('name' => 'Widget Style', 'type' => 'widget' => 'widget' => 'my_widget', 'attributes' => array('class' => 'my_widget_style')), - ), - ), -)); -``` - -``` yaml -# app/config/config.yml -ivory_ck_editor: - default_config: my_config - configs: - my_config: - stylesSet: "my_styles" - styles: - my_styles: - - { name: "Blue Title", element: "h2", styles: { color: "Blue" }} - - { name: "CSS Style", element: "span", attributes: { class: "my_style" }} - - { name: "Widget Style", type: widget, widget: "my_widget", attributes: { class: "my_widget_style" }} -``` - -## Templates support - -The bundle offers you the ability to manage extra templates. To use this feature, you need to enable the `templates` -plugins shipped with the bundle and configure your templates. Like plugins, you can define them at the form level or in -your configuration file: - -``` php -$builder->add('field', 'ckeditor', array( - 'config' => array( - 'extraPlugins' => 'templates', - 'templates' => 'my_template', - ), - 'templates' => array( - 'my_template' => array( - 'imagesPath' => '/bundles/mybundle/templates/images', - 'templates' => array( - array( - 'title' => 'My Template', - 'image' => 'images.jpg', - 'description' => 'My awesome template', - 'html' => '

Crazy template :)

', - ), - // ... - ), - ), - ), -)); -``` - -``` yaml -# app/config/config.yml -ivory_ck_editor: - default_config: my_config - configs: - my_config: - extraPlugins: "templates" - templates: "my_templates" - templates: - my_templates: - imagesPath: "/bundles/mybundle/templates/images" - templates: - - - title: "My Template" - image: "image.jpg" - description: "My awesome template" - html: "

Crazy template :)

" -``` - -## Load manually the library - -By default, all fields loads the CKEditor library. It means if you have multiple CKEditor fields, there will be -multiple CKEditor library loading (as much as you have fields). If you want to control it, you can configure the -bundle to not load the library at all and let you the control of it. To disable the CKEditor libary loading, you can -do it globally: - -``` yaml -ivory_ck_editor: - autoload: false -``` - -Or, if you just want to disable it for a specific field, you can use: - -``` php -$builder->add('field', 'ckeditor', array('autoload' => false)); -``` - -Be aware, the library must be loaded before any field have been rendered. - -## Inline support - -By default, the bundle uses a [classic editing](http://docs.ckeditor.com/#!/guide/dev_framed) which relies on -`CKEDITOR.replace`. If you want to use the [inline editing](http://docs.ckeditor.com/#!/guide/dev_inline) which relies -on `CKEDITOR.inline`, you can configure it globally: - -``` yaml -ivory_ck_editor: - inline: true -``` - -Or, if you just want to enable it for a specific field, you can use: - -``` php -$builder->add('field', 'ckeditor', array('inline' => true)); -``` - -## Disable auto inline - -By default, CKEditor enables the auto inline feature meaning that any `contenteditable` attribute sets to `true` will -be converted to ckeditor instance automatically. If you want to disable it, you can do it globally: - -``` yaml -ivory_ck_editor: - auto_inline: false -``` - -Or, if you just want to disable it at runtime, you can use: - -``` php -$builder->add('field', 'ckeditor', array('auto_inline' => false)); -``` - -Be aware this option will only disable the CKEditor auto inline feature not the browser one if it supports it. - -## JQuery adapter - -The CKEditor JQuery adapter is by default not loaded even if the `autoload` option is enabled. In order to load it, -the `autoload` flag must be enabled and you must explicitly enable the jquery adapter. You can do it globally: - -``` yaml -ivory_ck_editor: - jquery: true -``` - -Or, if you just want to enable it for a specific field, you can use: - -``` php -$builder->add('field', 'ckeditor', array('jquery' => true)); -``` - -We recommend to use JQuery adapter if your app relies on JQuery. -It allows to wrap CKEditor code in `$(document).ready()` - -Additionally, by default, the JQuery adapter used is the [one](/Resources/public/adapters/jquery.js) shipped with the -bundle. If you want to use your own, you can configure it globally: - -``` yaml -ivory_ck_editor: - jquery_path: your/own/jquery.js -``` - -Or, you can configure it just for a specific field: - -``` php -$builder->add('field', 'ckeditor', array('jquery_path' => 'your/own/jquery.js')); -``` - -## Synchronize the textarea - -When the textarea is transformed into a CKEditor widget, the textarea value is no more populated except for form -submission. Then, it leads to issues when you try to serialize form in javascript or you try to rely on the textare -value. To automatically synchronize the textarea value, you can do it globally: - -``` yaml -ivory_ck_editor: - input_sync: true -``` - -Or, you can do it locally: - -``` php -$builder->add('field', 'ckeditor', array('input_sync' => true)); -``` - -## Fallback to textarea for testing purpose - -Sometime you don't want to use the CKEditor widget but a simple textarea (e.g testing purpose). As CKEditor uses an -iframe to render the widget, it can be difficult to automate something on it. To disable CKEditor and fallback on the -parent widget (textarea), simply disable it in your configuration file or in your widget: - -``` -# app/config/config_test.yml -ivory_ck_editor: - enable: false -``` - -``` php -$builder->add('field', 'ckeditor', array('enable' => false)); -``` - -## Use your own CKEditor version - -The bundle is shipped with the latest CKEditor 4 full release. If you don't want to use it, the bundle allows you to -use your own by defining it in your configuration file or in your widget. - -First of all, you need to download & extract your version in the web directory. For that, you have 2 possibilities: - - - Directly put it in the web directory (`/web/ckeditor/` for example). - - Put it in the `/Resources/public/` directory of any of your bundles. - -Then, register it: - -``` -# app/config/config.yml -ivory_ck_editor: - base_path: "ckeditor" - js_path: "ckeditor/ckeditor.js" -``` - -``` php -$builder->add('field', 'ckeditor', array( - 'base_path' => 'ckeditor', - 'js_path' => 'ckeditor/ckeditor.js', -)); -``` - -**Each path is relative to the web directory** diff --git a/Resources/doc/usage/autoinline.rst b/Resources/doc/usage/autoinline.rst new file mode 100644 index 00000000..38f21d10 --- /dev/null +++ b/Resources/doc/usage/autoinline.rst @@ -0,0 +1,22 @@ +Disable auto inline +=================== + +By default, CKEditor enables the auto inline feature meaning that any ``contenteditable`` attribute sets to ``true`` +will be converted to CKEditor instance automatically. If you want to disable it, you can do it in your configuration or +in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + auto_inline: false + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('auto_inline' => false)); + +.. note:: + + This option will only disable the CKEditor auto inline feature not the browser one if it supports it. diff --git a/Resources/doc/usage/config.rst b/Resources/doc/usage/config.rst new file mode 100644 index 00000000..951e7ce7 --- /dev/null +++ b/Resources/doc/usage/config.rst @@ -0,0 +1,61 @@ +Define reusable configuration +============================= + +The CKEditor bundle provides an advanced configuration which can be reused on multiple CKEditor instance. Instead of +duplicate the configuration on each form builder, you can directly configure it once & reuse it all the time. The +bundle allows you to define as many configurations as you want. + +All CKEditor configuration options are available here: http://docs.ckeditor.com/#!/api/CKEDITOR.config + +Define a configuration +---------------------- + +.. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + configs: + my_config: + toolbar: [ [ "Source", "-", "Save" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] + uiColor: "#000000" + filebrowserUploadRoute: "my_route" + extraPlugins: "wordcount" + # ... + +Use a configuration +------------------- + +When you have defined a config, you can use it with the ``config_name`` option: + +.. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config_name' => 'my_config', + )); + +Override a configuration +------------------------ + +If you want to override some parts of the defined config, you can still use the ``config`` option: + +.. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config_name' => 'my_config', + 'config' => array('uiColor' => '#ffffff'), + )); + +Define default configuration +---------------------------- + +If you want to define globally your configuration in order to make it used by default without having to use the +``config_name`` option, you can use the ``default_config`` node: + +.. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + configs: + my_config: + # ... diff --git a/Resources/doc/usage/file-browse-upload.rst b/Resources/doc/usage/file-browse-upload.rst new file mode 100644 index 00000000..4d81202d --- /dev/null +++ b/Resources/doc/usage/file-browse-upload.rst @@ -0,0 +1,103 @@ +How to handle file browse/upload +================================ + +Before starting, be aware there is nothing which will automatically handle file browse/upload for you in this bundle +(it's out of scope). So, you will need to implement it by yourself and then configure your browse/upload URIs or routes +in the CKEditor configuration or in the widget. + +Supported Options +----------------- + +CKEditor natively supports different options according to what you want to browse or upload. This options should be +URIs which point to your controllers. The available options are: + + * filebrowserBrowseUrl + * filebrowserFlashBrowseUrl + * filebrowserImageBrowseUrl + * filebrowserImageBrowseLinkUrl + * filebrowserUploadUrl + * filebrowserFlashUploadUrl + * filebrowserImageUploadUrl + +Routing Options +--------------- + +To ease the CKEditor file handling, the bundle adds options which are not in CKEditor by default. These options are +related to the Symfony `Routing Component`_ and allow you to configure routes instead of URIs. For each ``*Url`` +option, three new options are available. + +For example, the ``filebrowserBrowseUrl`` option can be generated with these three new options: + + * filebrowserBrowseRoute + * filebrowserBrowseRouteParameters + * filebrowserBrowseRouteAbsolute + +Static Routing +~~~~~~~~~~~~~~ + +If you're routing is static, you can configure these options in your configuration or in your widget this way: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + config: + my_config: + filebrowserBrowseRoute: "my_route" + filebrowserBrowseRouteParameters: { slug: "my-slug" } + filebrowserBrowseRouteAbsolute: true + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'filebrowserBrowseRoute' => 'my_route', + 'filebrowserBrowseRouteParameters' => array('slug' => 'my-slug'), + 'filebrowserBrowseRouteAbsolute' => true, + ), + )); + +Dynamic Routing +~~~~~~~~~~~~~~~ + +If the static routing does not fit your needs, you can use the `filebrowser*Handler` option allowing you to build your +own url with a simple but much more powerful closure and so make it aware of your dependencies: + +.. code-block:: php + + // A blog post... + $post = $manager->find($id); + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'filebrowserBrowseHandler' => function (RouterInterface $router) use ($post) { + return $router->generate('my_route', array('slug' => $post->getSlug(), true); + }, + ), + )); + + +Integration +----------- + +If you want to simplify your life, you can directly use other bundles which have already integrated the concept explain +in the previous chapter. + +CoopTilleulsCKEditorSonataMediaBundle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `CoopTilleulsCKEditorSonataMediaBundle`_ provides a `SonataMedia`_ integration with this bundle. + +FMElfinderBundle +~~~~~~~~~~~~~~~~ + +The `FMElfinderBundle`_ provides a `ELFinder`_ integration with this bundle. + +.. _`Routing Component`: http://symfony.com/doc/current/book/routing.html +.. _`CoopTilleulsCKEditorSonataMediaBundle`: https://github.com/coopTilleuls/CoopTilleulsCKEditorSonataMediaBundle +.. _`SonataMedia`: http://sonata-project.org/bundles/media +.. _`FMElfinderBundle`: https://github.com/helios-ag/FMElfinderBundle +.. _`ELFinder`: http://elfinder.org diff --git a/Resources/doc/usage/index.rst b/Resources/doc/usage/index.rst new file mode 100644 index 00000000..675c7ca6 --- /dev/null +++ b/Resources/doc/usage/index.rst @@ -0,0 +1,24 @@ +Usage +===== + +If you ever wonder something about this bundle, you are at the good place. Here, you can find all bundle features: + +.. toctree:: + :hidden: + + config + toolbar + loading + file-browse-upload + jquery + textarea-sync + textarea-fallback + autoinline + inline + plugin + skin + style + template + version + +.. include:: index.rst.inc diff --git a/Resources/doc/usage/index.rst.inc b/Resources/doc/usage/index.rst.inc new file mode 100644 index 00000000..14f32ea8 --- /dev/null +++ b/Resources/doc/usage/index.rst.inc @@ -0,0 +1,14 @@ +- :doc:`/usage/config` +- :doc:`/usage/toolbar` +- :doc:`/usage/loading` +- :doc:`/usage/file-browse-upload` +- :doc:`/usage/jquery` +- :doc:`/usage/textarea-sync` +- :doc:`/usage/textarea-fallback` +- :doc:`/usage/autoinline` +- :doc:`/usage/inline` +- :doc:`/usage/plugin` +- :doc:`/usage/skin` +- :doc:`/usage/style` +- :doc:`/usage/template` +- :doc:`/usage/version` diff --git a/Resources/doc/usage/inline.rst b/Resources/doc/usage/inline.rst new file mode 100644 index 00000000..4dcb8305 --- /dev/null +++ b/Resources/doc/usage/inline.rst @@ -0,0 +1,20 @@ +Use inline editing +================== + +By default, the bundle uses a `Classic Editing`_ which relies on ``CKEDITOR.replace``. If you want to use the +`Inline Editing`_ which relies on ``CKEDITOR.inline``, you can configure it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + inline: true + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('inline' => true)); + +.. _`Classic Editing`: http://docs.ckeditor.com/#!/guide/dev_framed +.. _`Inline Editing`: http://docs.ckeditor.com/#!/guide/dev_inline diff --git a/Resources/doc/usage/jquery.rst b/Resources/doc/usage/jquery.rst new file mode 100644 index 00000000..47988efc --- /dev/null +++ b/Resources/doc/usage/jquery.rst @@ -0,0 +1,46 @@ +jQuery adapter +============== + +If your application relies on jQuery, we recommend you to use the jQuery adapter. The bundle will automatically wrap +the CKEditor instantiation into a ``jQuery(document).ready()`` block making the code more reliable. + +Enable the Adapter +------------------ + +The CKEditor jQuery adapter is by default not loaded even if the ``autoload`` option is enabled. In order to load it, +the ``autoload`` flag must be enabled and you must explicitly enable the jquery adapter. You can do it your +configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + jquery: true + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('jquery' => true)); + +Use your Adapter +---------------- + +Additionally, the jQuery adapter used by default is the [one](/Resources/public/adapters/jquery.js) shipped with the +bundle. If you want to use your own, you can configure it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + jquery_path: your/own/jquery.js + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('jquery_path' => 'your/own/jquery.js')); + +.. note:: + + Each path must be relative to the web directory. diff --git a/Resources/doc/usage/loading.rst b/Resources/doc/usage/loading.rst new file mode 100644 index 00000000..04666799 --- /dev/null +++ b/Resources/doc/usage/loading.rst @@ -0,0 +1,24 @@ +Load manually CKEditor +====================== + +By default, all fields loads the CKEditor library. It means if you have multiple CKEditor fields, there will be +multiple CKEditor library loading (as much as you have fields). If you want to control it, you can configure the +bundle to not load the library at all and let you the control of it. To disable the CKEditor library loading, you can +do it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + autoload: false + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('autoload' => false)); + +.. note:: + + CKEditor must be loaded before any fields have been rendered, so we recommend you to register it in the ``head`` + of your page. diff --git a/Resources/doc/usage/plugin.rst b/Resources/doc/usage/plugin.rst new file mode 100644 index 00000000..5b183982 --- /dev/null +++ b/Resources/doc/usage/plugin.rst @@ -0,0 +1,48 @@ +Plugin support +============== + +The bundle offers you the ability to manage extra plugins. To understand how it works, you will enable the `Wordcount`_ +plugin for our CKEditor widget. + +Install the Plugin +------------------ + +First, you need to download & extract it in the web directory. For that, you have 2 possibilities: + + - Directly put the plugin in the web directory (``/web/ckeditor/plugins/`` for example). + - Put the plugin in the ``/Resources/public/`` directory of any of your bundles. + +Register the Plugin +------------------- + +In order to load it, you need to specify its location. For that, you can do it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + config: + extraPlugins: "wordcount" + plugins: + wordcount: + path: "/bundles/mybundle/wordcount/" + filename: "plugin.js" + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'extraPlugins' => 'wordcount', + ), + 'plugins' => array( + 'wordcount' => array( + 'path' => '/bundles/mybundle/wordcount/', + 'filename' => 'plugin.js', + ), + ), + )); + +.. _`Wordcount`: http://ckeditor.com/addon/wordcount diff --git a/Resources/doc/usage/skin.rst b/Resources/doc/usage/skin.rst new file mode 100644 index 00000000..195627d9 --- /dev/null +++ b/Resources/doc/usage/skin.rst @@ -0,0 +1,32 @@ +Skin support +============ + +Install your Skin +----------------- + +First of all, you need to download & extract your skin in the web directory. For that, you have 2 possibilities: + + - Directly put it in the web directory (``/web/ckeditor/`` for example). + - Put it in the ``/Resources/public/`` directory of any of your bundles and install the assets. + +Register your Skin +------------------ + +Then, to use your skin, just need to register it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + configs: + my_config: + skin: "skin_name,ckeditor/skins/skin_name/" + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array('skin' => 'skin_name,ckeditor/skins/skin_name/'), + )); diff --git a/Resources/doc/usage/style.rst b/Resources/doc/usage/style.rst new file mode 100644 index 00000000..01805462 --- /dev/null +++ b/Resources/doc/usage/style.rst @@ -0,0 +1,36 @@ +Style support +============= + +The bundle allows you to define your own styles. Like plugins, you can define them in your configuration or your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + configs: + my_config: + stylesSet: "my_styles" + styles: + my_styles: + - { name: "Blue Title", element: "h2", styles: { color: "Blue" }} + - { name: "CSS Style", element: "span", attributes: { class: "my_style" }} + - { name: "Widget Style", type: widget, widget: "my_widget", attributes: { class: "my_widget_style" }} + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'stylesSet' => 'my_styles', + ), + 'styles' => array( + 'my_styles' => array( + array('name' => 'Blue Title', 'element' => 'h2', 'styles' => array('color' => 'Blue')), + array('name' => 'CSS Style', 'element' => 'span', 'attributes' => array('class' => 'my_style')), + array('name' => 'Multiple Element Style', 'element' => array('h2', 'span'), 'attributes' => array('class' => 'my_class')), + array('name' => 'Widget Style', 'type' => 'widget' => 'widget' => 'my_widget', 'attributes' => array('class' => 'my_widget_style')), + ), + ), + )); diff --git a/Resources/doc/usage/template.rst b/Resources/doc/usage/template.rst new file mode 100644 index 00000000..71469553 --- /dev/null +++ b/Resources/doc/usage/template.rst @@ -0,0 +1,50 @@ +Template support +================ + +The bundle offers you the ability to manage extra templates. To use this feature, you need to enable the ``templates`` +plugins shipped with the bundle and configure your templates. Like plugins, you can define them in your configuration +or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + default_config: my_config + configs: + my_config: + extraPlugins: "templates" + templates: "my_templates" + templates: + my_templates: + imagesPath: "/bundles/mybundle/templates/images" + templates: + - + title: "My Template" + image: "image.jpg" + description: "My awesome template" + html: "

Crazy template :)

" + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array( + 'extraPlugins' => 'templates', + 'templates' => 'my_template', + ), + 'templates' => array( + 'my_template' => array( + 'imagesPath' => '/bundles/mybundle/templates/images', + 'templates' => array( + array( + 'title' => 'My Template', + 'image' => 'images.jpg', + 'description' => 'My awesome template', + 'html' => '

Crazy template :)

', + ), + // ... + ), + ), + ), + )); diff --git a/Resources/doc/usage/textarea-fallback.rst b/Resources/doc/usage/textarea-fallback.rst new file mode 100644 index 00000000..93bb28ea --- /dev/null +++ b/Resources/doc/usage/textarea-fallback.rst @@ -0,0 +1,18 @@ +Fallback to textarea +==================== + +Sometime, you don't want to use the CKEditor widget but a simple textarea (e.g testing purpose). As CKEditor uses an +iFrame to render the widget, it can be difficult to automate something on it. To disable CKEditor and fallback on the +parent widget (textarea), simply disable it in your configuration file or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config_test.yml + ivory_ck_editor: + enable: false + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('enable' => false)); diff --git a/Resources/doc/usage/textarea-sync.rst b/Resources/doc/usage/textarea-sync.rst new file mode 100644 index 00000000..fd95744a --- /dev/null +++ b/Resources/doc/usage/textarea-sync.rst @@ -0,0 +1,18 @@ +Synchronize the textarea +======================== + +When the textarea is transformed into a CKEditor widget, the textarea value is no more populated except when the form +is submitted. Then, it leads to issues when you try to serialize form or you try to rely on the textarea value in +javascript. To automatically synchronize the textarea value, you can do it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + input_sync: true + + .. code-block:: php + + $builder->add('field', 'ckeditor', array('input_sync' => true)); diff --git a/Resources/doc/usage/toolbar.rst b/Resources/doc/usage/toolbar.rst new file mode 100644 index 00000000..6bff1286 --- /dev/null +++ b/Resources/doc/usage/toolbar.rst @@ -0,0 +1,83 @@ +Customize the toolbar +===================== + +Built-in Toolbars +----------------- + +CKEditor provides 3 different packages with their own configurations (full, standard & basic). The bundle is shipped +with the full edition but you can easily switch the toolbar configuration by using the ``full``, ``standard`` or +``basic`` keyword as toolbar. You can configure it in your configuration or in your widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + configs: + my_config: + toolbar: full + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'config' => array('toolbar' => 'full'), + )); + + +Custom Toolbar +-------------- + +Build a toolbar in the configuration or especially in the widget is really a pain... Each time, you want a custom one, +you need to redefine all the structure... To avoid this duplication, the bundle allows you to define your toolbars in +a separate node & reuse them. This feature is only available in your configuration. + +.. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + configs: + my_config_1: + toolbar: "my_toolbar_1" + uiColor: "#000000" + # ... + my_config_2: + toolbar: "my_toolbar_2" + uiColor: "#ffffff" + # ... + my_config_2: + toolbar: "my_toolbar_1" + uiColor: "#cccccc" + toolbars: + configs: + my_toolbar_1: [ [ "Source", "-", "Save" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] + my_toolbar_2: [ [ "Source" ], "/", [ "Anchor" ], "/", [ "Maximize" ] ] + +Here, we see how is structured a toolbar. A toolbar is an array of toolbars (strips), each one being also an array, +containing a list of UI items. To do a carriage return, you just have to add the char ``/`` between strips. It relies +on the exact same structure than CKEditor itself. + +Using the toolbars node is better but the config is still not perfect as you still have code duplications in the toolbar +items. To avoid this part, you can define a group of items in a separate node & then, inject them in your toolbar by +prefixing them with a `@`. + +.. code-block:: yaml + + ivory_ck_editor: + configs: + my_config_1: + toolbar: "my_toolbar_1" + uiColor: "#000000" + # ... + my_config_2: + toolbar: "my_toolbar_2" + uiColor: "#ffffff" + # ... + toolbars: + configs: + my_toolbar_1: [ "@document", "/", "@link" , "/", "@tool" ] + my_toolbar_2: [ "@document", "/", "@tool" ] + items: + document: [ "Source", "-", "Save" ] + link: [ "Anchor" ] + tool: [ "Maximize" ] diff --git a/Resources/doc/usage/version.rst b/Resources/doc/usage/version.rst new file mode 100644 index 00000000..7d9d9c91 --- /dev/null +++ b/Resources/doc/usage/version.rst @@ -0,0 +1,40 @@ +Use your own CKEditor +===================== + +The bundle is shipped with the latest CKEditor 4 full release. If you don't want to use it, the bundle allows you to +use your own by defining it in your configuration file or in your widget. + +Install your CKEditor +--------------------- + +First of all, you need to download & extract your own CKEditor version in the web directory. For that, you have +2 possibilities: + + - Directly put it in the web directory (``/web/ckeditor/`` for example). + - Put it in the ``/Resources/public/`` directory of any of your bundles and install the assets. + +Register your CKEditor +---------------------- + +Then, to use your own CKEditor instead of the built-in, just need to register it in your configuration or in your +widget: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + ivory_ck_editor: + base_path: "ckeditor" + js_path: "ckeditor/ckeditor.js" + + .. code-block:: php + + $builder->add('field', 'ckeditor', array( + 'base_path' => 'ckeditor', + 'js_path' => 'ckeditor/ckeditor.js', + )); + +.. note:: + + Each path must be relative to the web directory.