ember-froala-editor

Bring the Froala WYSIWYG Editor into an ember-cli project with this
addon. Besides importing the required Froala Editor files, the main part of
this addon is the <FroalaEditor ></FroalaEditor> component, which adds the editor in your
ember app. Other functionality is also included to help interact with the
editor and content, see the Usage section below.

Compatibility

• Ember.js v3.20 or above
• Ember CLI v3.20 or above
• Node.js v18 and above
• ember-auto-import v2 or above

Note on ember-auto-import version requirement

This addon (and Ember v4+) uses ember-auto-import v2, which implies that
consuming projects also use ember-auto-import v2. Outside of
npm install --save-dev ember-auto-import@^2.0.0 webpack, take a look at the
upgrade guide
for further details when upgrading from ember-auto-import v1.

Upgrading from 3.x

The only change is with the configuration options in ember-cli-build.js. All
option types (languages, plugins, themes) must now be arrays with specific
assets listed. Boolean and string values are no longer supported. Ex:

From

let app = new EmberApp(defaults, {
  'ember-froala-editor': {
    languages: 'es',
    plugins  : ['align','char_counter'],
    themes   : true
  }
});

To

let app = new EmberApp(defaults, {
  'ember-froala-editor': {
    languages: ['es'],
    plugins  : ['align','char_counter'],
    themes   : ['dark','gray','royal']
  }
});

No other changes needed from an ember perspective. Installation and usage is
still the same, but editor configuration options might have changed. See the
Froala Editor docs
for those details.

Installation

ember install ember-froala-editor

Configuration

This addon will import files from the froala-editor package into the build-tree
to be included in the final app output. This covers the Download details
on the Froala Editor docs to get the main editor files into your project. You
can additionally include languages, plugins, and themes by
adding configuration details in your ember-cli-build.js file.

Within the ember-cli-build.js file, add a ember-froala-editor object and
list which additional assets to include in an array. For plugins, you can use
either the plugin name as shown in the Froala Editor docs or file name (without
the extension). Ex:

// ember-cli-build.js
// ... (snip)
let app = new EmberApp(defaults, {
  'ember-froala-editor': {
    languages: ['es','fr','de'],
    plugins  : ['align','charCounter','paragraph_format'],
    themes   : ['royal']
  }
});
// ... (snip)

Usage

This addon includes a couple components, several template helpers, and a couple
test helpers.

<FroalaEditor> Component

The <FroalaEditor> component exposes many aspects of the Froala Editor in
“Ember ways” and uses the <div contenteditable> version of the editor (not
<textarea>). And with the Froala Editor being a third-party program, this
component will handle proper setup and teardown.

<FroalaEditor ></FroalaEditor>

Pass-in existing HTML/content via the @content argument and capture changes
from the @update argument (which should be a setter, including {{mut}}).
However, when using {{mut}} it must be wrapped in {{fn}} to retain the
function (setter) aspect. The @content must be a SafeString from
@ember%2Ftemplate/htmlSafe">htmlSafe and @update will also return a SafeString.

<FroalaEditor
  @content={{this.content}}
  @update={{fn (mut this.content)}}
></FroalaEditor>

The @update setter will be called on the contentChanged editor event
by default. There is a slight debounce effect with that event, which may or
may not be desirable. To change which event is used, pass in the event name
through the @updateEvent argument.

<FroalaEditor
  @content={{this.content}}
  @update={{fn (mut this.content)}}
  @updateEvent="input"
></FroalaEditor>

Options can be passed in through the @options argument or individually
using the option name as the @argument name. Note: If the same option is
passed within the @options argument and individual argument, the individual
argument will “win”. In the example below, the theme would be “dark”.

<FroalaEditor
  @options={{hash theme="gray"}}
  @theme="dark"
></FroalaEditor>

Event callbacks can be passed into the component using the @on-* argument
format, where the event name is prefixed with @on-. Also, when an event has a
period in the name, replace it with a dash. The callback will be given the editor
instance as the first argument, with the other event params (if any) following.

<FroalaEditor
  @on-focus={{this.focusCallback}}
  @on-paste-afterCleanup={{this.pasteCallback}}
  @on-commands-after={{this.commandsCallback}}
></FroalaEditor>

The callback signatures should look like;

function(editor, ...params) {}
// Or for the examples above
function focusCallback(editor) {}
function pasteCallback(editor, clipboard_html) {}
function commandsCallback(editor, cmd, param1, param2) {}

The <FroalaEditor> also watches the @disabled state and will appropriately
enable/disable the editing abilities when this argument changes. It basically
is the equivalent to the <textarea disabled> attribute.

<FroalaEditor
  @disabled={{this.disabled}}
  @on-edit-on={{this.editorEnabledCallback}}
  @on-edit-off={{this.editorDisabledCallback}}
></FroalaEditor>

<FroalaContent> Component

According to the Froala Editor documentation, content created from the
editor should be contained within an element with the .fr-view class. This
is simply a component that applies the class. It can be used in either inline
(with the @content argument) or block form, but either should be SafeString
from the @ember%2Ftemplate/htmlSafe">htmlSafe().

{{!-- this.content = htmlSafe('<p>Content here</p>') --}}
<FroalaContent @content={{this.content}} ></FroalaContent>
<FroalaContent>{{this.content}}</FroalaContent>

Either will render:

<div class="fr-view"><p>Content here</p></div>

{{froala-arg}} Template Helper

This helper creates a closure that will capture the editor instance and pass it
into the event callback as the first argument, with the other event args
following. The Froala Editor binds callbacks to the editor instance, so this
is the editor and not the original context (even with the @action decorator).

Note: All @on-* arguments on the <FroalaEditor> already have this applied
automatically. This is mainly useful when passing callbacks through the
events option.

<FroalaEditor
  @options={{hash events=(hash click=(froala-arg this.callback))}}
  @on-click={{this.callback}}
></FroalaEditor>

The callback signature should look like;

function(editor, ...args) {}
// Or for the example above with the click event
function(editor, clickEvent) {}

{{froala-html}} Template Helper

This helper creates a closure that will pass the editors current HTML/content
as the first argument to the callback function. This is very useful when
combined with setters or the {{mut}} helper.
Ex: {{froala-html (fn (mut this.content))}}

Note: The @update argument on <FroalaEditor> already has this applied
automatically. This is mainly useful when needing HTML on other callbacks
but can also be done by calling editor.html.get() from within your callback.

<FroalaEditor
  @options={{hash events=(hash input=(froala-html this.callback))}}
  @on-input={{froala-html this.callback}}
></FroalaEditor>

The callback signature should look like;

function(html, editor, ...args) {}
// Or for the example above with the input event
function(html, editor, inputEvent) {}

{{froala-method}} Template Helper

This helper creates a closure that will call an editor method when
called. It is meant to replace an event callback on the
<FroalaEditor> component. Simply specify the method name as the
first parameter of the helper.

<FroalaEditor
  @on-paste-after={{froala-method "commands.undo"}}
></FroalaEditor>

The helpers first parameter will be used as the editor method to be called, and
the remaining parameters will be used for method arguments. So you can pass in
the proper arguments as documented, and they will be spread out when called. Ex:

{{froala-method "align.apply" "right"}}

In addition, you can use values from the event callback and “proxy” them to the
method. First, define a parameter in the position which the argument should be
passed in (to). Then define a hash with the same name and an integer of the
position (1 indexed) which the argument would have been received (from). Ex:

<FroalaEditor
  @on-save-error={{froala-method "html.insert" "message" message=2}}
></FroalaEditor>

In the above example, the “on-save-error” event callback would have received
(editor, error). In the {{froala-method}} helper we defined a “message”
and told it to use the second argument, which is error.

{{html-safe}} Template Helper

Since the <FroalaEditor> requires that @content be a SafeString from
@ember%2Ftemplate/htmlSafe">htmlSafe(), this helper can provide a way to convert a content string
when passing to the editor component. However, you should also sanitize the
content going in to guard against XSS exploits.

Note: This helper is NOT automatically imported into the app. Rather,
you must create your own helper to re-export the helper from this addon.

1. ember generate helper html-safe
2. Change app/helpers/html-safe.js to export { default } from 'ember-froala-editor/helpers/html-safe';
3. Use {{html-safe}} in your app templates

<FroalaEditor
  @content={{html-safe this.content}}
></FroalaEditor>

{{to-string}} Template Helper

Since the <FroalaEditor> requires that @content to be a SafeString, it will
also return a SafeString from the @update callback (and any callbacks that
use the {{froala-html}} helper). This helper will convert that SafeString
back to a normal string. However, you should also sanitize the content coming
back to guard against XSS exploits.

Note: This helper is NOT automatically imported into the app. Rather,
you must create your own helper to re-export the helper from this addon.

1. ember generate helper to-string
2. Change app/helpers/to-string.js to export { default } from 'ember-froala-editor/helpers/to-string';
3. Use {{to-string}} in your app templates

<FroalaEditor
  @content={{html-safe this.content}}
  @update={{to-string (fn (mut this.content))}}
></FroalaEditor>

{{merged-hash}} Template Helper

This helper is a little out-of-scope for this addon, but can be very useful
when you need to use a combination of options. It allows you to use an
object / hash property but also add others or override options. Ex:

<FroalaEditor
  @options={{merged-hash this.parentOptions heightMin=400}}
></FroalaEditor>

The helper assumes all parameters are objects, and then uses assign() to
merge everything together. Each parameter takes priority on the previous, with
the “hash” (named parameters) being the final. So you can merge multiple
“levels” of options. Ex:

{{merged-hash
  this.applicationOptions
  this.routeOptions
  pastePlain=true
  placeholderText="Only plain text can go here..."}}

Note: This helper is NOT automatically imported into the app. Rather,
you must create your own helper to re-export the helper from this addon.

1. ember generate helper merged-hash
2. Change app/helpers/merged-hash.js to export { default } from 'ember-froala-editor/helpers/merged-hash';
3. Use {{merged-hash}} in your app templates

fillInFroalaEditor() Test Helper

Test helper to best simulate content within the editor changing. It uses the
fillIn() helper provided by ember-test-helpers but just ensures the
correct DOM element is targeted. It requires a selector (string) as the first
argument and HTML (string or @ember%2Ftemplate/htmlSafe">SafeString) as the second argument. As an
async function, you should await the results before continuing with your test.

import { fillInFroalaEditor } from 'ember-froala-editor/test-support';
await fillInFroalaEditor('#editorId', '<p>HTML</p>');

getInFroalaEditor() Test Helper

Test helper that grabs the innerHTML of the editor content, simple as that.
It returns the HTML as a string and not a SafeString, unlike {{froala-html}}.

import { getInFroalaEditor } from 'ember-froala-editor/test-support';
let content = getInFroalaEditor('#editorId');

So putting both of these test helpers together, an Acceptance Test might
look something like this;

import { module, test } from 'qunit';
import { visit } from '@ember/test-helpers';
import { setupApplicationTest } from 'ember-qunit';
import { fillInFroalaEditor, getInFroalaEditor } from 'ember-froala-editor/test-support';
module('Acceptance | FroalaEditor', function(hooks) {
  setupApplicationTest(hooks);
  test('<FroalaEditor> properly updates when content is filled in', async function(assert) {
    assert.expect(2);
    await visit('/');
    assert.strictEqual(getInFroalaEditor('#editor'), '<p>Foobar</p>');
    await fillInFroalaEditor('#editor', '<p>Foobaz</p>');
    assert.strictEqual(getInFroalaEditor('#editor'), '<p>Foobaz</p>');
  });
});

Defaults for <FroalaEditor> component

Most likely you will have customizations/options that are common across many/all
of your <FroalaEditor> instances. Instead of passing around a shared options
object, there are a few ways to apply “default” options at once. And both ways
can be applied at the same time (ex: environment.js for the key and extending
for options/callbacks).

environment.js config

The <FroalaEditor> first looks to your config/environment.js file for a
ember-froala-editor object to use as the options. This is a great
place for your key after purchasing the Froala Editor.

'use strict';
module.exports = function(environment) {
  var ENV = {
    // (other default code snipped...)
    'ember-froala-editor': {
      key: '_YOUR_KEY_HERE_'
    }
  };
  // ... (other default code snipped...)
  return ENV;
};

Extending <FroalaEditor> component

The <FroalaEditor> was created with extending and applying defaults in mind.
Simply generate a new component within your app, extending from the addons
component and apply options and event callbacks, similar to invoking
the editor in a template by passing arguments, but instead make them class
properties and methods.

1. ember generate component-class froala-editor
2. Change app/components/froala-editor.js to the example show below, where the editor is extended
3. Add options to the options = {} object or individually
4. Add event callbacks with the on-eventName naming strategy
   • Note: Use the @action decorator to retain the component context

// app/components/froala-editor.js
import FroalaEditorComponent from 'ember-froala-editor/components/froala-editor';
export default class FroalaEditor extends FroalaEditorComponent {
  options = {
    theme: "gray"
  };
  // OR
  theme = "gray";
  'on-eventName'(editor, ...args) {/* this = editor */}
  @action 'on-eventName'(editor, ...args) {/* this = component */}
}

Custom Elements

The Froala Editor allows the creation of custom elements to use within
the editor, such as custom buttons, dropdowns, popups, icons, and plugins.
These should be created from within an application initializer so they
are created/setup just once. Then you can use them within the editor as shown
in the Froala Editor docs.

1. ember generate initializer froala-editor-elements — Or name(s) of your choosing
2. import FroalaEditor from 'froala-editor';
3. FroalaEditor.DefineIcon(), FroalaEditor.RegisterCommand(), etc.

import FroalaEditor from 'froala-editor';
export function initialize(/* application */) {
  FroalaEditor.RegisterCommand('myButton', {});
}
export default {
  initialize
};

FAQ

Why can’t I use the {{on}} modifier for Froala Editor events?

Starting with Froala Editor v3, it no longer triggers custom events on the DOM.
Instead, the new way is to pass callbacks into the options.events object,
or use the editor.events.on() method. This is done for you with the
<FroalaEditor ></FroalaEditor> component by taking all @on-* args and adding them
to the editor using the editor.events.on() method.

Why can’t I customize the editor tagName?

With the move to Glimmer Components, the tagName is no longer customized
through the component class. Rather, the forthcoming(?) (element) helper
will fill this need but it is not released in Ember.js proper yet. Once it is,
you’ll be able to customize the emitted DOM Element using the @tagName argument.
Just to note, the Froala Editor itself modifies the DOM quite a bit, so the
emitted element might change anyway.

Why can’t content be passed into <FroalaEditor> in block form?

Content changes must be captured by the component to properly update the editor
using editor.html.set() instead of through the Glimmer template. When content
is passed in via block form (<FroalaEditor>{{this.content}}</FroalaEditor>)
there is no way for the Glimmer component class to capture updates.

Is there a way to enable two-way binding of @content?

As of this writing, no. Ember Octane with Glimmer Components do not allow
two-way bound @arguments whatsoever. However, there has been discussion
on how to explicitly enable two-way binding in some manor, possibly by
a “boxing” a value with a setter. The <FroalaEditor> was designed with
this in mind, where the @update argument could look for a setter on
@content, without needing to pass in the setter explicitly/separately.

Why can’t @content be a regular string anymore?

There has been some debate on if the <FroalaEditor> itself should automatically
display @content unescaped by applying @ember%2Ftemplate/htmlSafe">htmlSafe(). Rather, the user
of the component should indicate that the @content is Ok to display in its’
current form. Additionally, by requiring a SafeString, the addon was able to
allow greater backwards compatibility without resorting to computeds. We can
always go back on this decision but it was a good change to make at v3.

Why is my build output size larger with v4?

With the move to ember-auto-import, all possible dynamic import() assets
are included in the build. Therefore, all language files, plugins, and themes
will be included in the project build output. However, only those listed in
your ember-cli-build.js ember-froala-editor options will actually be
requested by your browser.

Why is it recommended to depend upon a minor version and not major?

Ex: ~4.0.0 instead of ^4.0.0. Froala would like this addon (and other
official integrations) to match versions of the main editor package.
While we try to withold breaking changes to a major release, there are times
where changes in the Ember ecosystem require changes to the addon, before the
next major release of the Froala Editor (we note these in the release notes).

Contributing

See the Contributing guide for details.

License

The ember-froala-editor project is under MIT License. However, in
order to use Froala WYSIWYG HTML Editor plugin you must purchase a license for it.

Froala Editor has 3 different licenses for commercial use.
For details please see License Agreement.