Hey all,
This is the documentation post to be used with a TinyMCE plugin I’ve released (yep another rich text editor hits the plugin store!)
As with most of the plugins I create, I try to get as much configuration included as possible, and this one is no exception. All the documentation fields are fully written, the demo page is functional, if not a little colourful, and it includes a bunch of additional features, including annotations.
The demo page has been my testing ground, it’s not too bad but “making things look pretty” is definitely not one of my strong points!
I’ve spent a lot of time writing out all those little documentation links you see in the plugin options, so take the time to read these… they will help! There’s a number of posts I’ve come across throughout the forum relating to Tiny and rich text editors in general, so where anyone has previously asked for a feature, I’ve tried to make sure to include it.
I’m here to support this anyway, so if anyone spots a problem, has feature requests, questions, finds a bug or whatever, then please let me know and I’ll do my best to jump straight on it.
It’s a paid for plugin, simply because there’s a lot of effort gone into it, but it is cheap right now and I hope it will cater for everyone’s needs and grow.
That being said, he’s all the info you need to know…
DEMO
Demo
EDITOR
Editor
PLUGIN
Plugin
What it includes
- Can convert other Bubble elements into a rich text editors.
- Can handle multiple editors on the page.
- Includes styling to customize the editor.
- Includes themes.
- Contains a Latex interface allowing for mathematical and chemistry formulas to be written in various languages.
- Includes prism.js which is a code syntax highlighter/formatter supporting up to 10 code languages.
- Can extract HTML to be used elsewhere, includes creating HTML files.
- Will work inside repeating groups and if the editor resizes then so do the cells.
- Can automatically convert any image URL’s into a base64 content and update the image tags but for this feature to work, it will depend on the source of the image.
- Can configure any of the open-source plugins (over 25 available) and includes 3 additional plugins through an action like you’ve never seen before… trust me it’s massive!
- Has the ability to automatically upload images/videos to your Bubble storage, as they’re inserted into the editor.
- Tables can be inserted.
- Can add badges, callouts, page breaks, links, bullet lists, templates, character maps etc.
- Can modify the menu bar, add menu items (plus nested), create custom buttons etc.
- Includes events for most of the actions carried out.
- Can show alerts/notifications (and hide the API warning key message if not needed)
- Can resize the editor using a handle and modify the status bar it sits in.
- Can save current progress so content isn’t lost on page refreshes (uses browser storage).
- Supports 60 different languages.
- Configuration can be dynamically changed (not all of it though)
- Can import additional Google fonts.
- Various tool bar controls included that allow for draggable model dialogs.
- Content inside the editor can be set through means of running actions.
- Will handle image and videos resizing.
- Font families, colors, sizes, line indentations, letter spacing and other font styling options can be set.
- Can configure auto-correct fields whilst typing, pulling info from your database.
- Can configure and setup annotations allowing them to be modified and removed.
- Shortcuts can be configured.
Plus more…
Since this is the current cloud version of Tiny (v6.3) it does include an option (in the plugin settings) to provide an API key from them. It’s not a requirement though, 95% of all options in this plugin will work without a key. As far as I can tell, it will unlock their premium plugins, the ability to upload to your Tiny drive and give you some additional custom skins to use. I’m sure there’s more it grants access to, but I haven’t read up on all their additional features yet.
First thing, this plugin is very much data driven, mainly HTML and JSON.
Some of the configuration fields will require JSON objects as their input (these are the more advanced type of options) and if you need any help with the formatting then I’m here. Any field like this throughout the plugin will have some sort of example data in it. I’ve included a JSON formatter on the demo page, it’s just a link to another site which opens up in a popup that you can use if needed.
If there’s anything I’ve not covered in enough detail, then the official document for outlining all of the available options can be accessed here: https://www.tiny.cloud/docs/tinymce/6/
ELEMENTS
TinyMCE Advanced
This visual element shows the rich text editor.
-
All annotation (object state config item)
This should be set when you’re planning to use annotations. Select the option ‘All annotation (TinyMCE)’ from the dropdown list. This state (list of items) is populated every time an annotation is created/modified/removed and when the ‘Set content’ action runs which includes annotations within the HTML. See the ‘Configure annotations’ action to learn more. -
Current annotation (object state config item)
This should be set when you’re planning to use annotations. Select the option ‘Current annotation (TinyMCE)’ from the dropdown list. This state (single item) is populated when you click on an annotation or create one. See the ‘Configure annotations’ action to learn more.
Both of the above options are used when you run the “Configure annotations” action. They provide you with the relevant data when annotating words/paragraphs etc and making any selections, allowing for something like the below to be created.
General
Attribute ID
Use this option to provide an attribute ID (or a comma separated list of attribute ID’s as text) for other elements on your page, like a text element for example. These will be used to convert those elements into TinyMCE editors. Note: When doing so, this main plugin element will no longer show on your page, but all options will still apply to any targeted elements. This is best suited for converting other elements into inline editors. Note: If using the ‘Restore when empty’ option further down, you’ll also need to supply a single value here.
Placeholder
Adds placeholder content (when in classic mode) that will be shown when the editor is empty.
Initial content
HTML or text content to load into the editor on start-up. Note: When targeting other elements by using the attribute ID field above, any initial content set here will be used to replace the existing content that might already be present on targeted elements.
Replace line breaks
When using the initial content field above, this option allows you to replace all line feeds/carriage returns with
tags, which you may want to do when using text only to ensure new lines are formatted correctly. You probably don’t want to use this with HTML though.
Language (dropdown) and Language (dynamic)
Albanian, Arabic, Armenian, Azerbaijani, Basque, Bengali, Bulgarian, Catalan, Chinese Simplified, Croatian, Czech, Danish, Dhivehi, Dutch, Dutch (Belgium), English, Esperanto, Estonian, Finnish, French, Galician, German, Greek, Hebrew, Hindi, Hungarian, Icelandic, Indonesian, Irish, Italian, Japanese, Kabyle, Kazakh, Korean, Kurdish, Latvian, Lithuanian, Nepali, Norwegian Bokmal, Occitan, Persian, Polish, Portuguese (Brazilian), Romanian, Russian, Serbian (Cyrillic), Slovak, Slovenian, Spanish, Spanish (Mexican), Swedish, Tajik, Tamil, Thai, Turkish, Ukrainian, Uyghur, Vietnamese and Welsh.
Both these fields actually do the same thing, except one will give you a pre-defined list of 60 languages to choose from, and the other will allow you to dynamically set the language by name instead. The dynamic option overrides the static dropdown list and enables you to swap languages without having to reload the page etc.
Mode
Classic mode embeds an iframe on the page, which embeds the content and styles used in the content area. Inline mode does not use an iframe, instead the editor is run on the selected HTML element. Using Inline mode is better suited for targeting other elements, although if you wanted to use on the main plugin element, you can do. Note: Attempting to change this value dynamically within a conditional will not work.
Disable API warning
This option disables the API warning message which appears when having no API key specified through the plugin settings. The message is disabled by default, but this setting also has the unfortunate side effect of disabling all notifications from showing. The ‘Show notification’ action will not work when this setting is set to Yes. If you need to run that action, then set this to No and include a TinyMCE API key within the plugin settings area. It’s free to generate one. This setting applies a stylesheet so if you have multiple classic editors on your page, it’s important that this setting is the same for each of them.
Dynamic updates
By default, the nature of Tiny is that if a configuration item is to be changed dynamically, like we can do in Bubble through the use of conditionals, then the editor needs to be re-initialized again to pick up any new changes. When this option is set to Yes, it allows for this to happen. Performance is better when this is set to No, but if you need to set options dynamically then you can set this to Yes. Alternatively, you can run the ‘re-initialize editor’ action manually after any change which will do the same thing. Note: Not all options can be dynamically set in this way.
Fonts and Styling
Style formats
This option accepts an array of objects and it’s content affects what is shown under the Formats menu item. It allows you to define custom styles using references to existing formats. Formats can be changed through the ‘configure content formats’ action if needed. Modifying this is best done through a JSON editor. Note: This field contains a string representation of an array, and the syntax needs to be right for it to work. Make sure all values are contained in double quotes. For further information, refer to: Changing user formatting controls | TinyMCE Documentation
Block formats
This option defines the formats to be displayed in the ‘Blocks’ dropdown toolbar button and the blocks menu item. Each item in the string should be separated by semi-colons and specified using the form title=block.
Font family formats
This option defines the fonts to be displayed in the ‘Fonts’ dropdown toolbar button and the ‘Fonts’ menu item. Each item in the string should be separated by semi-colons and specified using the form of: title=font-family. For example, if you wanted to include a font menu item named ‘My Font’ and it be assigned to the ‘rubik burned’ font family, then you would include: My Font=rubik burned. Note: When adding new fonts, take them from the Google Fonts library and modify the ‘Content style’ field below.
To add a font into the Tiny Editor using the Google Fonts Library, you can do the following.
-
Navigate to: https://fonts.google.com/ and search for a font.
-
Select the font you want by clicking on it and then scroll down to a list of styles for that particular font. Select the style and open up the selected families side bar to see the details.
-
Select the @import radio button which will give you the styling code as shown.
-
There are 2 sections in the plugin options where this info must go. The styling section needs to be inserted into the content style setting. The rules section needs to be defined in the font family formats setting. Using the above example, these fields would look like this.
-
This example would give you the following font inside the editor.
Font size formats
This option allows you to override the font sizes displayed in the ‘Font size’ dropdown toolbar button and the ‘Font size’ menu item. Each item in the string should be space or comma-separated and include units.
Line height formats
This option allows you to override the line heights displayed in the ‘Line height’ dropdown toolbar button and the ‘Line height’ menu item. Each item in the string should be space separated.
Indentation
This option allows specification of the indentation level (in pixels) for indent/outdent buttons in the UI.
Letter spacing
This setting allows you to manually set the letter spacing within the editor. You can set this to something 2px if you wanted to increase it by 2 pixels. May require a little CSS knowledge!
Default font family
Supply a font family name and it will be loaded as the default font when the editor loads.
Default font size
Set the default font size here.
Default font color
Set the default color here.
Style formats merge
This option allows you to set whether the styles defined in the style formats option above, should be appended to or completely replaced.
Content style
This option allows for custom CSS styles to be added and applied to the editable area. The default value here contains an import rule which is used to import three additional fonts from Google (Lato, Roboto and Rubik Distressed). If you plan on adding new fonts into the ‘Font family formats’ option above, then you will need to add them here too.
Container Styles
Community skins
Oxide, Oxide-Dark, Tinymce-5, Tinymce-5-dark, Match System Preferences
These are the free community skins which control the overall appearance of the editor. Designed to work in classic mode only. Note: If you have more than one classic editor on the page, this option will affect all of them, however the ‘editable area styles’ options further down will be set for each editor on the page.
Premium skins
Bootstrap, Borderless, Fabric, Fluent, Jam, Material-classic, Material-outline, Naked, Outside, Small, Snow
These are the premium skins which can only be used when your API key allows them. Selecting one of these skins will override the community options above. Designed to work in classic mode only. When setting up a new account in Tiny, you get access to these for 2 weeks. Requires the API key to be set through the plugin settings.
Border roundness, Border width
Should be a value in pixels for which you want to set the editor’s container border roundness and the border width to.
Border color
Choose a color to apply to the editor’s container border.
Min height, Max height, Min width, Max width
These settings allow the various minimum and maximum dimensions of which the editor can stretch to.
Editable Area Styles
CSS (community)
Default, Dark, Document, Writer, TinyMCE-5, TinyMCE-5-Dark, Match System Preferences
These are the free community CSS options that change the styling within the editable area. Designed to work in classic mode only.
CSS (premium)
Fabric, Fluent, Material-classic, Material-outline
These are the premium CSS styling options which can only be used when your API key allows them. Selecting one of these styles will override the community options above. Designed to work in classic mode only. When setting up a new account in Tiny, you get access to these for 2 weeks. Requires the API key to be set through the plugin settings.
Background color
Sets the background color of the editable area.
Inner padding
This setting allows you to manually set the padding around the body within the editor. This becomes apparent when you select the ‘Document’ option from the CSS dropdown above, it has quite a large padding area set. You can set this to something like 2rem which will give you a relatively decent padding area. May require a little CSS knowledge!
Tool bars
Enable tool bar
Enables or disables the tool bar. When disabled, all tool bar options below will be ignored.
Tool bar 1
To specify the buttons that should appear on the editor’s toolbar, provide a space separated list of button names. To create groups within this list, you can add the pipe character (|) between the groups of buttons that you want to create. For further information, refer to: Toolbar Buttons Available for TinyMCE | TinyMCE Documentation
Tool bar 2
Same as the tool bar option above but will add a secondary toolbar underneath the first when in use.
Tool bar mode
The tool bar mode option is used to extend the tool bar to accommodate the overflowing toolbar buttons. This option is useful for small screens or small editor frames. Available options are: Floating, Sliding, Scrolling and Wrap.
Tool bar location
Auto, Top, Bottom
Tool bar’s location.
Tool bar sticky
When enabled, the tool bar will dock to the top of the editor.
Tool bar sticky (offset)
This option allows the toolbar to stick or dock at the specified offset from the top or bottom of the viewport depending on the toolbar location. This can be useful if using a floating group pinned to the top of the page, allowing the toolbar to stick below this area. The value should be a number in pixels.
Toolbar persist
This option is only supported when using Inline mode. It disables the automatic show and hide behaviour of the toolbar and menu bar for inline editors. Enable this option to always show the toolbar and menu bar, and not hide them whenever focus is lost. Use this option to make the toolbar and menu bar persistent for inline editors.
Tool bar draggable
This option is only supported when using Inline mode. Allows the toolbar and menu bar area to become draggable.
Fixed toolbar element
This option is only supported when using Inline mode. Use to render the inline toolbar into a fixed positioned by specifying an attribute ID for an existing element. Acts in a similar way to how Bubble’s group focus element works.
Behaviours
Keep styles
This option will keep the editor’s current text style after pressing enter/return.
Remove table margins
Within tables, text is wrapped into paragraphs which by default, have a top and bottom margin. This can make the cells appear to have way too much white space around it. Setting this option to Yes, will remove the paragraph margins.
Improve line
The horizontal rule (
element), is a single pixel grey hair line, which can be hard to select. Setting this option to Yes, will add a slightly larger click area just underneath the line that should make it easier to select.
Newline behaviour
Default, Linebreak
This option enables you to adjust what happens when Enter or Return is pressed.
Auto focus
Automatically set the focus to the editor. This can also help with making sure content isn’t automatically in a selected state upon loading through the initial content field at the top.
Read only
Puts the editor into read only mode.
Read only font color
Sets the font color when the editor is in read only mode.
Browser spellcheck
This will utilize the browser’s native spell check functionality inside the editor.
Directionality
This option allows you to set the base direction of text within the editor. Accepted values are ‘ltr’ (left to right) and ‘rtl’ (right to left).
Object resizing
This option allows you to turn on/off the resizing handles on images, tables or media objects. It’s a string value which accepts either true, false or img. Setting the value to ‘img’ will just allow for images to be resized.
Resize proportionally
When an image is resized in the editor, this option controls whether the image is resized proportionally or freely. When set to Yes, images can be resized proportionally. When set to No, images can be resized freely. Holding SHIFT whilst resizing, will reverse the behaviour.
Disable paste
When set to Yes, the ability to paste anything into the editor will be disabled. When pasting is allowed, the ‘paste content’ state will also be populated. Depending on the ‘Paste as text’ option found in the Edit menu, it could affect the data held within this state.
Paste as text
This allows you to set the default option in the Edit menu for the ‘paste as text’ feature. Anything pasted into the editor will be just plain text when this is enabled. No images, tables or any other styling will be preserved.
Paste images
When set to Yes, images will be allowed to be pasted into the editor. Note: If you’re wanting to disable any images to be inserted, you should not include the ‘images’ plugin.
Draggable model
This option allows for model dialogs which appear, to be draggable, such as the image/file/table insert dialogs.
User Interface
Menu bar
Enable, disable or set the options on the menu bar. Accepted values are: true, false or a space separated string of menu bar items, for example: file edit insert view format table tools help. Note: When the editor is in ‘inline’ mode, this value automatically gets set to false. This option can’t be set dynamically through the conditionals tab, you must use the ‘Set menu bar’ action.
Status bar
Disable the status bar which is the grey bar aligned to the bottom of the editor’s editable area. The status bar contains the path information and the resize handle.
Resize
This option controls the behaviour of the resize handle. You can disable it, allow vertical resizing only or have both horizontal and vertical resizing. You may also need to adjust the Bubble layout settings accordingly for this to function correctly. For example, putting the editor into a fixed group will not allow the outer group to expand with the editor. The ‘dynamic updates’ option at the top may have an effect on this setting.
Branding
Setting this option to No, removes the Tiny logo from the status bar.
Context menu
The context menu is a configurable component that appears when you right click inside the editable area. By default it does not disable the operating system’s native context menu, if there are no items to display at the cursor position the native context menu will be shown. This option allows you to specify which items should appear on the menu. The format of this option is a space separated list of items in a string. To disable the context menu, leave this field empty.
Never use native
This option allows you to prevent the browser context menu from appearing within the editor. Using this may result in unexpected behaviour when right-clicking in text areas, be cautious when using this.
Plugins
There is an associated action that you can run to configure any of the open-source plugins in more detail. There isn’t one for the premium ones yet although they can be enabled.
Plugins (open source)
TinyMCE comes with two sets of plugins, open-source and premium. Some of the open-source plugins are listed here but not all of them are enabled by default. There’s at least 25 free plugins that can enabled and a single action which can configure all them. To enable/disable/modify any of these plugins, run the ‘configure open-source plugins’ action. For further information on these, refer to: Plugins for TinyMCE | TinyMCE Documentation
Plugins (premium)
These are the premium plugins which require an API key to use. Some of these require a corresponding open-source plugin since they extend functionality. They’re free to try for the first 2 weeks after the initial sign up with Tiny, then will only continue to function once a price plan is in place. For further information, refer to: Plugins for TinyMCE | TinyMCE Documentation.
External plugins
This option allows you to insert custom plugins into the editor by supplying an object of items that include a name and location. An example of how this might look would be {“plugin1”: “https://www.example/plugin1.min.js”, “plugin2”: “https://www.example/plugin2.min.js”}. For further information, refer to: Key editor options for adding TinyMCE to an application | TinyMCE Documentation.
Restore when empty
This option is part of the ‘autosave’ plugin. When set to Yes, that plugin will automatically be enabled (regardless of the list options set above). It enables you to specify if the editor should automatically restore the content stored in local storage when the editor is empty on initialization. This can be useful for users who don’t know that they could restore lost work if the browser crashed by selecting Restore last draft from the File menu. Note: For this to work correctly, the ‘Initial content’ field at the top must be empty, the attribute Id field must be set with a single value and the mode be set to Classic. To configure this option further, see the ‘Configure open-source plugins’ action where you can specify the autosave frequency or retention options. Default value for autosaving is every 30 seconds.
Files
These options require the Image and Media plugins to be installed. All other plugin configuration is contained in the ‘Configure open-source plugins’ action.
File picker types
This option enables you to specify what types of file pickers you need by a space or comma separated list of type names. There are currently three valid types: file, image and media. When inserting an image for example, you will see the file picker icon allowing the user to open a file dialog to choose a new image file. When ‘image’ is removed from this field, the file picker will no longer show.
Image file types
This field allows you to define the image file types allowed when the file picker appears. If you want to restrict this, then it should contain a comma separated list of file extensions, for example: jpg, jpeg, webp. When left empty or set to image/*, then all image types will be allowed.
Video file types
This field allows you to define the video file types allowed when the file picker appears. If you want to restrict this, then it should contain a comma separated list of file extensions, for example: mp4, ogg, webm. When left empty, or set to video/*, all video types will be allowed.
Unsupported drops
When this option is set to Yes, the editor blocks unsupported images and files from being dropped into the editor. If set to No, dropping an unsupported file into the editor will cause the browser to navigate away from the page containing the editor. Really sorry, but videos are not supported with this feature!
Save to S3
When set to Yes, inserted files will automatically be uploaded to S3.
Media live embeds
Setting this value to Yes, enables a live preview of the embedded video content within the editable area. When set to No, will show a placeholder image instead. This enables you to play a video clip, such as YouTube, within the editor.
Media dimensions
This option allows you disable the Dimensions input fields in the media dialog.
Media poster
Enables the Poster input field in the media dialog.
Media alt source
This option allows you enable the Alternative source input field in the media dialog.
Image caption
This option allows for enabling captions for images. When this option is enabled the image dialog will have an extra checkbox called “Caption”. When the checkbox is checked, the image will get wrapped in an HTML5 figure element with a caption inside it. You’ll then be able to type caption content inside the editor.
Image advanced tab
This option adds an ‘Advanced’ tab to the image dialog allowing you to add custom styles, spacing and borders to images.
Image title
This options allows you enable the image title input field in the image dialog.
Image description
This option allows you disable the image description input field in the image dialog.
Image dimensions
This option allows you disable the dimensions input fields in the image dialog.
Image roundness
This is the border roundness for images that are inserted into the editor, in pixels.
Image border color
This is the border color for images (not selected).
Image border width
This is the border width for images (not selected).
Image select color
This is the border color for images that are selected.
Image select width
This is the border width for images that are selected, in pixels.
Annotation Styles
These color fields are used when annotations are created by running the ‘Configure annotations’ action. They’re set here because of the way the CSS is passed into the editor. These control the text background and font colors which affect annotated content within the editor.
Annotate 1 (backgrnd) and Annotate 1 (font)
For annotation SET 1 - Background color and font color after the annotation has been applied.
Annotate 2 (backgrnd) and Annotate 2 (font)
For annotation SET 2 - Background color and font color after the annotation has been applied.
Annotate 3 (backgrnd) and Annotate 3 (font)
For annotation SET 3 - Background color and font color after the annotation has been applied.
Continued on next post…
Testing it now.
