CommaJS - Documentation

Quickstart

Configuration

Styling

Plugins

Utilities

Custom Plugins

APIs

Styling

CommaJS gives you full control over a document's look and feel. Most importantly, you won't need to learn the "CommaJS way" of styling. Simply define which CSS classes or style properties you want to manage and let CommaJS do the work.

Styles are managed by these three configuration options:

styles

defaultStyle

defaultLineStyle

Here we will focus on the styles option. DefaultStyle and defaultLineStyle simply tell CommaJS which defaults to use. For more information, see defaultStyle.

A simple example

To illustrate how simple this process is, let's assume for a moment that CommaJS does not support italic text out of the box. All you need to do to add italic to your documents is to define a style and pass it in the options object to CommaJS. We called this style 'italix':

options.styles = {
    ...
    italix: {
        applyAs: "style",
        name: "fontStyle",
        on: "italic",
        off: "normal"
    },
    ...        
}

let commajsInstance = new CommaJS('id-container', options);

To apply italix at the cursor position or to selected text, simply call:

commajsInstance.ToggleStyleOnSelection("italix");

.styles

The styles configuration property is a key-value object that defines which styles are supported in your document:

options.styles = {
    bold: { ... },
    italic: { ... },
    mainParagraph: { ... }        
}

Each style is defined as an object that supports the following properties:

applyAs

possible values: 'style', 'class'

required

Defines how a style should be applied on the dom element: inline using the style attribute or using the class attribute

if applyAs == 'class'

classes

Array of user defined classes to be applied.

if applyAs == 'style'

name

The name of the style (e.g., margin, fontWeight, fontSize, fontFamily, etc.). Note that, following Javascript standards, the property names are in camel-case.

off

A string representing the 'off' value for the style.

A string representing the 'on' value for the style. If the 'on' value is unknown or passed at runtime, set 'on' equal to 'set#by#user'. For example, fontFamily is a property whose value can be picked at runtime by the user. Setting on equal to "set#by#user" you can change the font family as follow:

commajsInstance.ToggleStyleOnSelection("fontFamily", "Verdana");

preserve

Boolean property used for those CSS properties defined by multiple values. For example, text-decoration. Text-decoration can be used to manage multiple text properties, such as 'text-decoration: underline line-through;'. To control 'underline' and 'line-through' indipendently you can set preserve equal to true and CommaJS will change only the specified property. For example:

...
underlined: {
    applyAs: "style",
    name: "textDecorationLine", 
    on: "underline",
    off: "none",
    preserve: true
},
strike: {
    applyAs: "style",
    name: "textDecorationLine", 
    on: "line-through",
    off: "none",
    preserve: true
},
...

isColor

Boolean property. Indicates whether the on/off values contain colors (all color formats supported).

calculated

Boolean property. The use for this option is best explained with an example: indent. Every time a user presses Tab, we want to add 40px as padding to the left. We can define it as follows:

...
indent: {
    applyAs: "style",
    name: "paddingLeft",
    calculated: true,
    step: 40,
    unit: "px",
    on: 0, //starting value,
    off: 0, //min value
},

Note that you need to specify two additional properties: step and unit. Now, when the user presses Tab, we can add or subtract 'step' as:

commajsInstance.ToggleStyleOnSelection("indent", "add"); //or subtract

Default Styles

Of course, CommaJS comes with the most common styles already configured. As a reference, the following is our default configuration. Whatever you decide to specify in .style will be merged with our default configuration. Feel free to add or overwrite your own styles as described in the previous section.

const AllStyles = {	

    bold: {
        applyAs: "style",
        name: "fontWeight",
        on: "bold",
        off: "normal"
    },

    italic: {
        applyAs: "style",
        name: "fontStyle",
        on: "italic",
        off: "normal"
    },

    underlined: {
        applyAs: "style",
        name: "textDecorationLine", 
        on: "underline",
        off: "none",
        preserve: true
    },

    strike: {
        applyAs: "style",
        name: "textDecorationLine", 
        on: "line-through",
        off: "none",
        preserve: true
    },
    
    fontSize: {
        applyAs: "style",
        name: "fontSize",
        on: "set#by#user",
        off: "initial" 
    },

    fontFamily: {
        applyAs: "style",
        name: "fontFamily",
        on: "set#by#user", 
        off: "initial"
    },

    fontColor: {
        applyAs: "style",
        name: "color",
        on: "set#by#user", 
        off: "initial",
        isColor: true 
    },

    backgroundColor: {
        applyAs: "style",
        name: "backgroundColor",
        on: "set#by#user", 
        off: "initial",
        isColor: true
    },

    align: {
        applyAs: "style",
        name: "textAlign",
        on: "set#by#user", 
        off: "left"
    },

    indent: {
        applyAs: "style",
        name: "paddingLeft",
        step: 40,
        preserve: false,
        calculated: true, 
        unit: "px",
        on: 0, 
        off:0, 
    },

    lineSpacing: {
        applyAs: "style",
        name: "lineHeight",
        on: "set#by#user", 
        off: "normal"
    },

    horizontalRule: {
        applyAs: "style",
        name: "borderBottom",
        on: "1px solid #8c8c8c", 
        off: "none"
    },

    headerOne: {
        applyAs: "class",
        classes: ["headerOne"]
    },

    headerTwo: {
        applyAs: "class",
        classes: ["headerTwo"]
    },

    headerThree: {
        applyAs: "class",
        classes: ["headerThree"]
    },

    superscript: {
        applyAs: "class",
        classes: ["scplSup"],
        isToggle: true
    },

    subscript: {
        applyAs: "class",
        classes: ["scplSub"],
        isToggle: true
    },

    splitSelection: {
        applyAs: "class",
        classes: ["splitSelectionDummy"]
    }
}