# Froala Editor

With Froala (Editor) (opens new window) we are enhancing the User Experience for our Users, and what Feature Sets we want to deliver to them, in terms of what we think is best.

# Configuration

Most of the configuration for the Froala Editor is done inside the Showcase Core api/resources/js/editing-utils/froala/Config.js.

However, there are a few options which you can configure using the App Configuration: toolbarButtons, htmlAllowedTags, htmlDoNotWrapTags, paragraphFormat, lineHeights, fontSize.

For the list of available values please check Froala documentation (opens new window).

Here is the example on how to correctly configure one or more options using App Configuration, you can configure it for all or for some specific fields:

{
  "froala": [
    {
      "fields": [
        "element_text_1_content" // applies only to this field
      ],
      "config": {
        "toolbarButtons": [
          "bold",
          "italic",
          "underline"
        ],
        "htmlAllowedTags": [
          "h1",
          "p",
          "br"
        ],
        "htmlDoNotWrapTags": [
          "h1",
          "p"
        ],
        "paragraphFormat": {
          "N": "Normal",
          "H1": "Heading 1"
        },
        "lineHeights": {
          "Single": "100%",
          "150%": "150%"
        },
        "fontSize": [
          "10",
          "12",
          "14"
        ]
      }
    },
    {
      "fields": [], // applies to all fields
      "config": {}
    }
  ]
}

# Workflow

# Input Fields

# Image Uploads

# Commands

Within a Froala enabled field you do have different WYSIWYG commands, placed within the Froala Toolbar that shows on top of the Briefing when interacting with such a field.

Besides the option to reset the input made to any default that is defined within the App Configurations that match the current meta information, you can also use features like text alignment, text directions or the placement of predefined Veeva Tokens.

# Allowed HTML Tags

Out of our concerns and due to compatibility reasons in converting and using what Users input, we deliverately only accept certain HTML Tags.

h1
h2
h3
h4
p
br
i
em
strong
b
ul
ol
u
li
sub
sup
a
span
img
table
tbody
th
tr
td

# SCP Tokens

Next to the display of Veeva Tokens, we are also using our own Tokens to reflect a more dynamic approach with e.g. dates, like setting a year to the current one on the preview and renditioning.

To use SCP Tokens you need to wrap them inside a data-scp-token HTML Tag Attribute, so it can be correctly replaced by our JavaScript functionality.

For example:

<p>Some text <span data-scp-token="scp.token"></span> some text.</p>

does result in

Some text [token placement] some text.

Here [token placement] will be whatever the value of scp.token should be.

# Date Token

The SCP Date Tokens add specific date related context, according to local server time.

Token	Insert	Usage
`day`	The day of the current month	`scp.date.day`
`month`	The month of the current year	`scp.date.month`
`year`	The current year	`scp.date.year`

And when we take the SCP Token for year:

<p>© <span data-scp-token="scp.date.year"></span></p>

will result in

© 2021

# Events

We are currently using the following Events to interact with Froala or exchange interaction between the Front End, it's Fields (once known as Editors) and Froala:

Event	Usage
`sc2.briefing.contentSaved`	Signals that changes where saved
`sc2.briefing.disabled`	Signals that none of the different input fields are editable
`sc2.briefing.enabled`	Signals that all of the different input fields should be editable again
`sc2.briefing.updateContent`	Signals and Update with all current content as payload
`sc2.editor.${this.key}.initialized`	Signals that the Field was just initialized
`sc2.editor.${this.key}.mounted`	Signals that the Field was just mounted, allowing exporting to Back End
`sc2.editor.${this.key}.unmounted`	Signals that the Field was just unmounted, disallowing exporting to Back End
`sc2.editor.${this.key}.updated`	Signals that the Fields' value was just updated
`sc2.editor.deleted`	Signals that a Field was just deleted; its content is within the payload
`sc2.editor.updated`	Signals that a Field was just updated; its content is within the payload

# Handling on API side

briefing.js

This file handles the initialization of all the Briefings' JavaScript, on API side.

Everything related to it is available via the briefing object in your Content Apps' Briefing context.

content-apps/init-renditions.js

When starting a Rendition, based on a related Transition, a Screenshot will be made for any Material that allows it, so that a Thumbnail for its current state can be shown. This file helps with some workarounds for UrlBox, which we use for those.

editing-utils/Briefing.js

This file is also loaded when briefing.js is initialized, as that file depends on it.

It stores mainly all the current App Configurations, Fields, the Materials values, as well as External (Briefing) Services.

editing-utils/Briefing.js

This file is also loaded when briefing.js is initialized, as that file depends on it.

It stores mainly all the information about current App Configurations, Fields, the Materials values, as well as External (Briefing) Services

editing-utils/BriefingService.js

This one handles the initialization, any payload sending and authentication for External (Briefing) Services

editing-utils/constants.js

Simple as that: It handles constants.

editing-utils/DropboxField.js

Dropbox in name only, it manages dropzones, where files can be dragged'n'dropped into, uploaded, deleted, and basically be downloaded again.

This extends the functionality of Field.js.

editing-utils/Field.js

This file manages every different Field type within the Briefing.

It doesn't matter if it's a default Field, a Dropzone Field, a Material Picker Field or a Form Field , everything extends from it. So it's only to be expected that general definitions will be made here.

There are default definitions for setting or getting content, dispatching Change Events, and handling the related Field.

editing-utils/FormField.js

A FormField manages HTML form input types like input, select and textarea, and checks on Change Events

This extends the functionality of Field.js.

editing-utils/Material.js

It manages Material handling, as it fetches all new information and stores all the latest changes for a Material within the whole Briefing context.

editing-utils/MaterialPickerField.js

Field in name, it is not exactly like the other three, as it uses external input.

This one is for handling an External (Briefing) Service, the Material Picker, which is, like the ADAM Picker, another in house developed one.

It lets you select any matching Material Type, based on the given Filters, which you can then simply insert into your Briefing wherever any Material Picker Field can be placed.

For this there is a button to initialize the External (Briefing) Service on interaction and a room to store the payload necessary.

This extends the functionality of Field.js, though.

editing-utils/Showcase.js

This file handles all non GUI but SCP related interactions, like Briefing related UI Toast messages, marking a field as dirty and sending a state change about displaying the loader to the GUI, which encapsulates it as an iframe

editing-utils/Showcase.js

Checking the Users' Permissions, and Role is all done within the Briefings' context by this file.

editing-utils/utils.js

It currently just defines how and Event should be dispatched.

editing-utils/froala/Commands.js

The Froala Commands explained above can be found within this file, like the resetting its content back to the initial/App Config default.

editing-utils/froala/Config.js

It manages default drop down menus, action buttons, undo and forward buttons, and image upload buttons within the Froala (Editor) toolbar.

editing-utils/froala/Editor.js

This one is managing a Froala (Editor) field, as it manages and extends on its Change Events and handles it whole setup as well as its content.

As we currently still use Version 2.X of Field we have bound any functionality to it via the $jq object, where you can also access it's .froalaEditor(...) method, for using Froalas methods.

You can find a listing of all available methods in its V2 Docs (opens new window).

This extends the functionality of Field.js.

editing-utils/froala/Helpers.js

Like the name proposes it is but another file to help with content and command handling, within its Froala (Editor) context, like for its toolbar.

editing-utils/froala/Icons.js

There are but few icons we define ourselves or where we want to set a specific one under a specific name.

This is handled here.

# Use Cases

# Setting And Cleaning Fields

What if you would have an Field, that you want to clean after switching to another Brand Scheme? Like, how to set the Content within the Field correctly and how to clean up afterwards?

Sure, you could just hide the displayed Field's Content, but would that really clean up the resulting content.json?
The answer is No - also it might still show within the rendered Boilerplate, depending on your usage of keys/values.

When you create a Field on init or after some change, e.g. by using briefing._createEditor(key, [content], 'static') which creates a static Field for variable key, and you want to set Content to it, you would normally use something like briefing.setContent(key, content.outerHTML). When cleaning it up, you would then have to unmount the Field, by using briefing.getEditor(key).unmount(), as it then forcefully sets the Content of it to an empty string ''. That way the value is overwritten on changes made to the Briefing, which should already happen automatically if you set your Event Listeners correctly.

So you now know how to create, set and clean up a Field.

Do not forget, that you can also align your Fields with your App Configurations, so that you can use values defined within e.g. briefing._configuration or briefing._defaults.

← Briefing Forms Feature Configuring Content Apps →