Skip to content

Commit

Permalink
update tinymce docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@vangheem
vangheem committed Sep 19, 2015
1 parent b8867bf commit 29ecd81
Showing 1 changed file with 29 additions and 284 deletions.
313 changes: 29 additions & 284 deletions develop/plone/forms/wysiwyg.rst
View file
Expand Up @@ -117,22 +117,8 @@ Customizing TinyMCE options
----------------------------

In your add-on code, all TinyMCE options in the control panel can be exported and imported
:doc:`using GenericSetup, portal_setup and tinymce.xml </develop/addons/components/genericsetup>`.
:doc:`using GenericSetup, portal_setup and registy.xml </develop/addons/components/genericsetup>`.

Custom field-specific style list for TinyMCE
-----------------------------------------------

Dexterity
===========

Oho.

Archetypes
===========

For Archetypes see

* https://plone.org/products/tinymce/documentation/how-to/how-to-customize-tinymce-for-an-archetypes-richwidget

Rich text transformations
---------------------------
Expand All @@ -145,307 +131,66 @@ Rich text transformations
Hacking TinyMCE Javascript
---------------------------

Plone ships with pre-compressed TinyMCE source code enabled by default.

If you want to toy around with TinyMCE source code itself, you might
want to first enable the usage of debug version of TinyMCE source.
All JavaScript is built and compiled with Plone 5's new Resource Registry.

In ``Products.TinyMCE.skins`` open tiny_mce_src.js and
copy-paste its content into tiny_mce.js.

.. note ::
Replacing tiny_mce.js with tiny_mce_src.js in portal_javascripts
doesn't seem to work as it breaks TinyMCE plug-in loading.

TinyMCE plug-ins
------------------

TinyMCE consists of plug-ins. Existing plug-ins can be overlaid with your
custom version by loading Javascript after core TinyMCE load.
The TinyMCE control panel has the ability to provide custom plugins. Custom plugins
map to the http://www.tinymce.com/wiki.php/Configuration:external_plugins setting.

* Default TinyMCE plug-in Javascript files can be found under Products.TinyMCE/skins/tinymce/plugins
A value is in the format of "plugin name|path/to/javascript.js".

* Usually TinyMCE plug-ins dialogs load in <iframe> and HTML code loads separate CSS and JS
files from the main site
TinyMCE 3 plugins should still work as Plone ships with the TinyMCE backward
compatibility layer for TinyMCE 3.


Adding a new plug-in
------------------------------------

Here are instructions how to add new buttons to TinyMCE

Some rules

* Plug-in id goes to ``tinymce.xml``

* Your plug-in must be in a file called ``editor_plugin.js`` in skins layer

* You must have a skins layer folder named after your plug-in id

* You don't register plug-in Javascript *portal_javascripts*

* TinyMCE button row is in the main document. However, the edit area itself is in <iframe>.
Also, many of TinyMCE dialogs are launched in <iframe> and they load a hardcoded
set of Javascript files (they don't use any kind of Plone master template or <head> section).

So in the end you'll have a file::

yourcompany.app./yourcompany/app/skins/tinymce_plugin_flowplayer/flowplayer/editor_plugin.js

Why all this? I don't know. And honestly, in this point, I don't care.

Register your specially named skin layer in ``skins.xml``::

<?xml version="1.0"?>
<object name="portal_skins" meta_type="Plone Skins Tool">


<object name="tinymce_plugin_flowplayer"
meta_type="Filesystem Directory View"
directory="your.app:skins/tinymce_plugin_flowplayer"/>

<skin-path name="*">
<layer name="tinymce_plugin_flowplayer"
insert-after="custom"/>
</skin-path>

</object>

Register your plugin in ``tinymce.xml`` GenericSetup install profile

.. code-block:: xml
<?xml version="1.0"?>
<object>
<toolbar>
<customtoolbarbuttons purge="False">
<element value="flowplayer"/>
</customtoolbarbuttons>
</toolbar>
<resourcetypes>
<customplugins purge="False">
<element value="flowplayer"/>
</customplugins>
Then finally drop a ``editor_plugin.js`` to your plug-in folder

.. code-block:: javascript
/**
* a TinyMCE plug-in for opening a dialog asking a video link and creating Flowplayer code out of it
*
*/
(function() {
tinymce.create('tinymce.plugins.FlowplayerPlugin', {
init : function (ed, url) {
var t = this;
t.url = url;
t.editor = ed;
t.docs = false;
ed.addButton('flowplayer', {
title : 'Video',
cmd : 'flowplayer',
image : url + '/img/flowplayer.gif'
});
ed.addCommand('flowplayer', function (val, page) {
var url = prompt("Copy-paste URL to MP4 video file", "");
// note: flowplayer link must not have text inside
html = '<a class="flow-player tinymce-flow-player" href="' + url + '" />';
ed.execCommand('mceInsertContent', false, html);
});
//ed.onPostRender.add(t._setupTOC, t);
},
getInfo : function () {
return {
longname : 'collective.flowplayer video insert plug-in ',
author : 'Mikko Ohtamaa',
authorurl : 'http://webandmobile.mfabrik.com',
infourl : 'http://webandmobile.mfabrik.com',
version : "1.0"
};
}
});
tinymce.PluginManager.add('flowplayer', tinymce.plugins.FlowplayerPlugin);
})();
Media resources
==================

TinyMCE exposes URL to your plug-in base folder, where editor_plugin.js is, as plug-in ``init()`` parameter.

You can construct relative URLs to set media resources in ``init()``.

.. code-block:: javascript
Here are instructions how to add new plugins to TinyMCE

ed.addButton('flowplayer', {
title : 'Video',
cmd : 'video',
image : url + '/img/placegallery.gif'
});
Language resources
=======================

TinyMCE does not directly accept strings as labels, but uses its own internal translation mechanism which is not gettext.

* Create folder ``langs`` under plug-in base folder

* There create file ``en.js``

Sample content

.. code-block:: javascript
tinyMCE.addI18n('en.placegallery',{
desc : 'Placegallery button'
});
Plug-in configuration goes to ``registry.xml`` GS profile with the record::
<record name="plone.custom_plugins"
interface="Products.CMFPlone.interfaces.controlpanel.ITinyMCESchema"
field="custom_plugins">
<field type="plone.registry.field.List">
<value_type type="plone.registry.field.TextLine" />
</field>
<value>
<element>myplugin|some/path/to/script.js</element>
</value>
</record>


Customizing existing plug-in
------------------------------------

The recommended way is to customize TinyMCE

* Re-register plug-in by simply including a plug-in JS code
in a separate Javascript file loaded after tinymce.js

* override existing individual TinyMCE files using
:doc:`jbot </adapt-and-extend/theming/templates_css/skin_layers>`.

Overriding plug-in
===================================

Create a duplicate of plug-in JS file (table.js),
register it as a custom Javascript from your add-on resource folder.
* Go to the Resource Registry control panel

TinyMCE overrides previous plug-in registrations with new ones
and you can just re-register your own plug-in version to override the existing version.
* Click the ``Overrides`` tab

* Refer it in portal_javascripts
* Use the search to find the plugin code you want to override

.. code-block:: xml
* Save your changes

<!-- TinyMCE customizations -->
<javascript
id="++resource++your.app/tiny_mce_special.js"
authenticated="True"
cacheable="True" compression="safe" cookable="True" insert-after="tinymce.js"
enabled="True" expression=""
inline="False"
/>
* Click the ``Registry`` tab

* Click the ``build`` button next to the ``plone-logged-in`` bundle


Overriding plug-in resources
===================================

Yoiu can also override CSS, HTML (.htm.pt templates) with ``z3c.jbot``
You can also override CSS, HTML (.htm.pt templates) with ``z3c.jbot``
as instructed above.

Example::

jbot/Products.TinyMCE.skins.tinymce.plugins.table.js.table.js
jbot/Products.CMFPlone.static.components.tinymce-builded.js.tinymce.plugins.autosave.plugin.js

.. warning ::
Since there resources are loaded in <iframe> the normal browser refresh
does not trigger reload for them. Right click <iframe>, choose Refresh
from context menu.
Ploneboard and anonymous editor
-------------------------------

Problems with TinyMCE and Ploneboard.

For more information, see

* http://www.llakomy.com/articles/enable-kupu-for-anonymous-in-ploneboard


TinyMCE shortcuts
-------------------

``Products.TinyMCE`` versions 1.3+ provide a shortcut view in
link and image dialogs. You can add your own site specific shortcuts here.

The most common use case is a shortcut link a folder which acts
as a site image bank. On multilingual sites this folder is

* Below natural language folders in the site root

* Language neutral

These make navigating to the folder using normal means very difficult.

New TinyMCE shortcuts can be registered as global utility via
`Products.TinyMCE.interfaces.IShortcut interface <https://github.com/plone/Products.TinyMCE/blob/master/Products/TinyMCE/interfaces/shortcut.py>`_.

.. image :: tinymce_images.png
We'll register our image bank as a shortcut into TinyMCE image dialog.

The view is registered at ``configure.zcml`` in your :doc:`add-on </develop/plone/getstarted/index>`::

<configure
xmlns="http://namespaces.zope.org/zope"
xmlns:browser="http://namespaces.zope.org/browser"
xmlns:five="http://namespaces.zope.org/five"
xmlns:genericsetup="http://namespaces.zope.org/genericsetup"
xmlns:i18n="http://namespaces.zope.org/i18n"
i18n_domain="example.dexterityforms">

...

<utility
name="imagebank"
factory=".shortcut.ImageBankShortcut"
provides="Products.TinyMCE.interfaces.shortcut.ITinyMCEShortcut" />

</configure>


Then add the following to the ``shortcut.py`` file::

class ImageBankShortcut(object):
"""Provides shortcut to the language neutral image bank below language folders """

# This time we don't bother with i18n and assume
# the whole world understands Finnish
title = u'Kuvapankki'

# Portal root relative path
link = "/kuvapankki"

def render(self, context):

portal_state = context.restrictedTraverse('@@plone_portal_state')

return ["""
<img src="img/folder_current.png" />
<a id="currentfolder" href="%s">%s</a>
""" % (portal_state.portal_url() + self.link, self.title)]

After this you still need to go to TinyMCE control panel
(``http://localhost:8080/Plone/@@tinymce-controlpanel``)
and enable the link button in the settings for *Image Shortcuts*.

.. note ::
You might also want to disable TinyMCE inline image uploads through CSS
and disable image creation in arbitrary folders on your site. Currently
the only way is to override TinyMCE internal CSS files using z3c.bot.
Since there resources are loaded in built into one JavaScript file,
Any change this way will require you to re-build the JavaScript.

0 comments on commit 29ecd81

Please sign in to comment.