Reactive Froala WYSIWYG Editor
Meteor JS Plugin
Meteor JS plugin for the Froala WYSIWYG HTML Editor is also available.
Breaking Change to v2
Version 2.0.0 of this package onwards uses the upgraded Froala Editor V2. You will need to update and revise all Froala Editor API usage in your code (e.g. events, additional Froala Editor method calls, options) as described in the V2 migration guide. Please contact Froala directly for help, unless you really think there is an issue in the reactive wrapper code in this package(!)
Installation
You can install Froala-Reactive using Meteor's package management system The Froala-Reactive package automatically includes the separate froala:editor package which provides the actual Froala Editor javascript library:
meteor add froala:editor-reactive
Basic Usage
Froala-Reactive provides a Template inclusion tag which wraps the underlying Froala-Editor jQuery plugin. In it's simplest form, add it to your template like this:
<template name="myTemplate"> <div> {{> froalaReactive getFEContext}} </div> </template>
Template.myTemplate.helpers({ getFEContext: function () { var self = this; return { // Set html content _value: self.myDoc.myHTMLField, // Preserving cursor markers _keepMarkers: true, // Override wrapper class _className: "froala-reactive-meteorized-override", // Set some FE options toolbarInline: true, initOnClick: false, tabSpaces: false, // FE save.before event handler function: "_onsave.before": function ( editor) { // Get edited HTML from Froala-Editor var newHTML = editor.html.get(true /* keep_markers */); // Do something to update the edited value provided by the Froala-Editor plugin, if it has changed: if (!_.isEqual(newHTML, self.myDoc.myHTMLField)) { console.log("onSave HTML is :"+newHTML); myCollection.update({_id: self.myDoc._id}, { $set: {myHTMLField: newHTML} }); } return false; // Stop Froala Editor from POSTing to the Save URL }, } }, })
Where:
- The "myTemplate" template has a data context that contains a 'myDoc' property, which itself contains '_id' and 'myHTMLField' properties.
- We use a helper to build the data context object to pass to the froalalReactive template.
- We set some Froala Editor options
- The
"_onsave.before"
property provides a callback function to handle the Froala-Editor save.before event. - The
_value
argument provides the HTML string that you want to display and edit
Here, we are triggering the update of the underlying 'myDoc' document record in the 'myCollection' collection when the Froala Editor 'beforeSave' event triggers. We could easily have used the 'blur' or 'contentChanged' events instead.
The final line in the callback stops Froala Editor from generating its own AJAX call to post the updated HTML contents, because we have used the awesomeness of Meteor to do that for us instead.
Note that Froala-Reactive does not automatically update the edited _value
, you
have to provide your own Froala-Editor event handler(s) to do that.
However, Froala-Reactive will reactively update the displayed _value
HTML immediately if you have assigned it to a data context property or template helper function which changes its value any time after the template has rendered (e.g. if the underlying collection document is updated from the server, or another action on the client).
Events
You can provide callbacks for any of the Froala-Editor events by specifying _on<event name>
arguments in the {{> froalaReactive}}
inclusion tag with name of template helper functions that must return a function with the expected Froala-Editor event function signature.
For example, to set up a callback for the image.beforeUpload event:
{{> froalaReactive ... _onimage.beforeUpload=imagePasted ...}}
Template.myTemplate.helpers({ imagePasted: function () { var self = this; return function (editor, img) { // Do something }; } });
Note that the event name used in the _on<event name>
argument name must be exactly the same as used in the Froala Editor on('froalaEditor.<event name>', function ....)
callback declaration.
Options
Similarly, you can pass any of the Froala-Editor options to the underlying Froala-Editor plugin object, by simply declaring them as arguments to the froalaReactive
inclusion tag. Also, if any of these option argument values are set to values on your template's data context, or from return vaues from template helpers, Froala-Reactive will call the Froala Editor option
setter method to change them if any of them change values once your template has been rendered.
{{> froalaReactive ... language=getLanguage ...}}
Template.myTemplate.helpers({ getlanguage: function () { return Session.get('language'); } })
Note that option values cannot be changed after initialisation (e.g. inlineMode) ... please refer to the Meteor-Editor documentation.
_className wrapper div class name override
If you have multiple instances of {{froalaReactive}}
in the same template, and you need to target the underlying FroalaEditor instance in each, override the wrapping div
class name in each instance to be a unique value, by specifying the _className=fooClass
context property.
_keepMarkers
If you preserve the current cursor position marker when saving the FroalaEditor contents (using html.get
keepmarkers method flag), then also set `keepMarkers=true` context property. This ensures that FroalaReactive's comparison between current and new contents takes the market html into account.
Methods
You can invoke any of the Froala Editor methods directly on the editor
object in your Froala Editor event callback functions. See above for an example of calling editor.html.get()
.
Gotchas
- Remember that you must provide one or more
_on
callbacks to handle changing the froalaEditor contents, if you want use the Meteor Framework to do so. - If two or more users are actively editing the same underlying state (e.g. the same property of the same document in a collection), and you have set up a contentChanged event handler, or an autosaving Froala Editor, then the content will keep changing. Their local caret cursor will keep resetting and jumping around. To avoid this, you may want to implement some kind of locking mechanism, to only one user can initiate an edit session at a time. To do this properly requires implementing something like Operational Transform!
- The Froala Editor V2 API has renamed some methods with dotted notation (e.g. save.before. This means you cannot set their values directly in a blaze template (it throws an error in the blaze compiler if you try something like
{{froalaReactive onsave.before=doSave}}
). Instead, you will have to create a template helper function that builds the complete context JSON object ... see the example given in the Basic section above.
Acknowledgements
This package is based on the implementation of the x-editable-reactive-template package.