├── .gitignore ├── LICENSE ├── README.md ├── _config.yml ├── froala-reactive.html ├── froala-reactive.js ├── package.js └── versions.json /.gitignore: -------------------------------------------------------------------------------- 1 | .build* 2 | .DS_Store 3 | .versions 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 RSBA Technology Ltd & Froala Labs 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Froala Reactive WYSIWYG HTML Editor 2 | 3 | >Froala-Reactive provides a template-based, reactive wrapper around the [Froala WYSIWYG HTML Editor](https://froala.com/wysiwyg-editor/pricing), designed to play nicely with [Meteor Framework](https://www.meteor.com/) client-side templates. 4 | 5 | >Note that Froala Editor requires a [license for commercial use](https://froala.com/wysiwyg-editor/pricing). 6 | 7 | ## Breaking Change to v2 8 | 9 | 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](https://www.froala.com/wysiwyg-editor/docs/migrate-from-v1). Please contact Froala directly for help, unless you really think there is an issue in the reactive wrapper code in this package(!) 10 | 11 | ## Installation 12 | 13 | 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: 14 | 15 | ```bash 16 | meteor add froala:editor-reactive 17 | ``` 18 | 19 | ## Basic Usage 20 | 21 | Froala-Reactive provides a [Template inclusion tag](https://github.com/meteor/meteor/blob/devel/packages/spacebars/README.md#inclusion-tags) which wraps the underlying Froala-Editor jQuery plugin. In it's simplest form, add it to your template like this: 22 | 23 | ```html 24 | 29 | ``` 30 | 31 | ```javascript 32 | Template.myTemplate.helpers({ 33 | getFEContext: function () { 34 | var self = this; 35 | self.myDoc.myHTMLField = 'Hello World !'; 36 | return { 37 | // Set html content 38 | _value: self.myDoc.myHTMLField, 39 | // Preserving cursor markers 40 | _keepMarkers: true, 41 | // Override wrapper class 42 | _className: "froala-reactive-meteorized-override", 43 | 44 | // Set some FE options 45 | // toolbarInline: true, 46 | initOnClick: false, 47 | tabSpaces: false, 48 | 49 | // FE save.before event handler function: 50 | "_onsave.before": function ( editor) { 51 | // Get edited HTML from Froala-Editor 52 | var newHTML = editor.html.get(true /* keep_markers */); 53 | // Do something to update the edited value provided by the Froala-Editor plugin, if it has changed: 54 | if (!_.isEqual(newHTML, self.myDoc.myHTMLField)) { 55 | console.log("onSave HTML is :"+newHTML); 56 | myCollection.update({_id: self.myDoc._id}, { 57 | $set: {myHTMLField: newHTML} 58 | }); 59 | } 60 | return false; // Stop Froala Editor from POSTing to the Save URL 61 | }, 62 | } 63 | }, 64 | }) 65 | ``` 66 | 67 | Where: 68 | 69 | * The "myTemplate" template has a data context that contains a 'myDoc' property, which itself contains '_id' and 'myHTMLField' properties. 70 | * We use a helper to build the data context object to pass to the froalalReactive template. 71 | * We set some [Froala Editor options](https://www.froala.com/wysiwyg-editor/docs/options) 72 | * The `"_onsave.before"` property provides a callback function to handle the Froala-Editor [save.before](https://www.froala.com/wysiwyg-editor/docs/events#save.before) event. 73 | * The `_value` argument provides the HTML string that you want to display and edit 74 | 75 | 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. 76 | 77 | 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. 78 | 79 | Note that Froala-Reactive *does not* automatically update the edited `_value`, you 80 | have to provide your own Froala-Editor event handler(s) to do that. 81 | 82 | 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). 83 | 84 | 85 | ## Events 86 | 87 | You can provide callbacks for any of the Froala-Editor [events](https://froala.com/wysiwyg-editor/docs/events) by specifying `_on` 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. 88 | 89 | For example, to set up a callback for the [image.beforeUpload](https://froala.com/wysiwyg-editor/docs/events#image.beforeUpload) event: 90 | 91 | ```html 92 | {{> froalaReactive ... _onimage.beforeUpload=imagePasted ...}} 93 | ``` 94 | 95 | ```javascript 96 | Template.myTemplate.helpers({ 97 | imagePasted: function () { 98 | var self = this; 99 | return function (editor, img) { 100 | // Do something 101 | }; 102 | } 103 | }); 104 | ``` 105 | 106 | Note that the event name used in the `_on` argument name must be exactly the same as used in the Froala Editor `on('', function ....)` callback declaration. 107 | ## Options 108 | 109 | Similarly, you can pass any of the Froala-Editor [options](https://froala.com/wysiwyg-editor/docs/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. 110 | 111 | ```html 112 | {{> froalaReactive ... language=getLanguage ...}} 113 | ``` 114 | 115 | ```javascript 116 | Template.myTemplate.helpers({ 117 | getlanguage: function () { 118 | return Session.get('language'); 119 | } 120 | }) 121 | ``` 122 | 123 | Note that option values cannot be changed after initialisation (e.g. [inlineMode](https://froala.com/wysiwyg-editor/docs/options#toolbarInline)) ... please refer to the Meteor-Editor documentation. 124 | 125 | #### _className wrapper div class name override 126 | 127 | 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. 128 | 129 | #### _keepMarkers 130 | 131 | If you preserve the current cursor position marker when saving the FroalaEditor contents (using `html.get` keep_markers 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. 132 | 133 | ## Methods 134 | 135 | You can invoke any of the Froala Editor [methods](https://froala.com/wysiwyg-editor/docs/methods) directly on the `editor` object in your Froala Editor event callback functions. See above for an example of calling `editor.html.get()`. 136 | 137 | 138 | ## Gotchas 139 | 140 | 1. 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. 141 | 2. 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! 142 | 3. The Froala Editor V2 API has renamed some methods with dotted notation (e.g. [save.before](https://www.froala.com/wysiwyg-editor/docs/events#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. 143 | 144 | ## Acknowledgements 145 | 146 | This package is based on the implementation of the [x-editable-reactive-template](https://github.com/davidworkman9/x-editable-reactive-template) package. 147 | 148 | ## License 149 | 150 | This package is released under the MIT License (see LICENSE). However, in order to use Froala WYSIWYG HTML Editor plugin you should purchase a license for it. 151 | 152 | Froala Editor has [3 different licenses](https://froala.com/wysiwyg-editor/pricing) for commercial use. 153 | For details please see [License Agreement](https://froala.com/wysiwyg-editor/terms). 154 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-minimal -------------------------------------------------------------------------------- /froala-reactive.html: -------------------------------------------------------------------------------- 1 | 4 | -------------------------------------------------------------------------------- /froala-reactive.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Froala-Reactive 3 | * =============== 4 | * 5 | * (c) 2014-2015 RSBA Technology Ltd 6 | * 7 | * Wraps Froala Editor jQuery plugin into a reactive Meteor template object 8 | * 9 | * Implementation heavily based on 'x-editable-reactive-template' Meteor package 10 | * see: https://github.com/davidworkman9/x-editable-reactive-template 11 | * 12 | * Example Usage: 13 | * 14 | * {{> froalaEditor toolbarInline=true initOnClick=false saveInterval=2000 15 | * _value=requirementParameter.text}} 16 | * 17 | * Set Froala Editor options as