Skip to content

Add format buttons

Jump to bottom
Jiuqing Song edited this page Feb 5, 2018 · 5 revisions

Go back to Quick Start

RoosterJs is a framework-independnt javascript HTML editor, so it doesn't have any UI component such as format buttons. But it does provide the ability to do format operations. So what you need to do is to build your format bar UI base on any existing UI framework you are using in your project, and call format APIs from roosterJs in the event handlers of your UI components.

Format API

RoosterJs provides more than 20 format APIs to help proceed the format actions. They are living in roosterjs-editor-api package. Here's a list of what we have currently:

clearFormat

Clear the format in current selection, after cleaning, the format will be changed to default format. The format that get cleaned include B/I/U/font name/ font size/text color/background color/align left/align right/align center/superscript/subscript.

createLink

Insert a hyperlink at cursor. When there is a selection, hyperlink will be applied to the selection, otherwise a hyperlink will be inserted to the cursor position.

insertImage

Insert an image to editor at current selection

insertTable

Insert table into editor at current selection

removeLink

Remove link at selection. If no links at selection, do nothing. If selection contains multiple links, all of the link styles will be removed. If only part of a link is selected, the whole link style will be removed.

setAlignment

Set content alignment to left, center or right.

setBackgroundColor

Set background color at current selection

setDirection

Change direction for the blocks/paragraph at selection to either from lef to right, or from right to left.

setFontName

Set font name at selection.

setFontSize

Set font size at selection.

setImageAltText

Set image alt text for all selected images at selection. If no images is contained in selection, do nothing. The alt attribute provides alternative information for an image if a user for some reason cannot view it (because of slow connection, an error in the src attribute, or if the user uses a screen reader).

setIndentation

Set indentation at selection. If selection contains bullet/numbering list, increase/decrease indentation will increase/decrease the list level by one.

setTextColor

Set text color at selection.

toggleBlockQuote

Toggle blockquote at selection, if selection already contains any blockquoted elements, the blockquoted elements will be unblockquoted and other elements will take no affect.

toggleBold

Toggle bold at selection. If selection is collapsed, it will only affect the following input after caret. If selection contains only bold text, the bold style will be removed. If selection contains only normal text, bold style will be added to the whole selected text. If selection contains both bold and normal text, bold stle will be added to the whole selected text.

toggleBullet

Toggle bullet at selection. If selection contains bullet in deep level, toggle bullet will decrease the bullet level by one. If selection contains number list, toggle bullet will convert the number list into bullet list. If selection contains both bullet/numbering and normal text, the behavior is decided by corresponding browser execCommand API.

toggleHeader

Toggle header at selection to be h1, h2, ... , h6 or not a header.

toggleItalic

Toggle italic at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only italic text, the italic style will be removed. If selection contains only normal text, italic style will be added to the whole selected text. If selection contains both italic and normal text, italic stlye will be added to the whole selected text.

toggleNumbering

Toggle numbering at selection. If selection contains numbering in deep level, toggle numbering will decrease the numbering level by one. If selection contains bullet list, toggle numbering will convert the bullet list into number list. If selection contains both bullet/numbering and normal text, the behavior is decided by corresponding realization of browser execCommand API.

toggleStrikethrough

Toggle strikethrough at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only strikethrough text, the strikethrough style will be removed. If selection contains only normal text, strikethrough style will be added to the whole selected text. If selection contains both strikethrough and normal text, strikethrough stlye will be added to the whole selected text.

toggleSubscript

Toggle subscript at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only subscript text, the subscript style will be removed. If selection contains only normal text, subscript style will be added to the whole selected text. If selection contains both subscript and normal text, the subscript style will be removed from whole selected text. If selection contains any superscript text, the behavior is determined by corresponding realization of browser.

toggleSuperscript

Toggle superscript at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only superscript text, the superscript style will be removed. If selection contains only normal text, superscript style will be added to the whole selected text. If selection contains both superscript and normal text, the superscript style will be removed from whole selected text. If selection contains any subscript text, the behavior is determined by corresponding realization of browser execCommand API.

toggleUnderline

Toggle underline at selection. If selection is collapsed, it will only affect the input after caret. If selection contains only underlined text, the underline style will be removed. If selection contains only normal text, underline style will be added to the whole selected text. If selection contains both underlined and normal text, the underline style will be added to the whole selected text.

Undo and Redo

Undo and Redo are very popular button in format bar. Their correlated APIs are not in roosterjs-editor-api package, but they are member function of Editor class directly. You can call editor.undo() and editor.redo() to perform these actions.

Current format state

It is very popular to show current format state on format bar when user is editing. For example, if current selected text is in bold state, the "bold" button will show a checked state. RoosterJs provides getFormatState() API in roosterjs-editor-api package to get current state. It returns a FormatState object which contains all available state of current format:

// The format state
interface FormatState {
    // Font name
    fontName?: string;

    // Font size
    fontSize?: string;

    // Whether the text is bolded
    isBold?: boolean;

    // Whether the text is italic
    isItalic?: boolean;

    // Whether the text has underline
    isUnderline?: boolean;

    // Background color
    backgroundColor?: string;

    // Text color
    textColor?: string;

    // Whether the text is in bullet mode
    isBullet?: boolean;

    // Whether the text is in numbering mode
    isNumbering?: boolean;

    // Whether the text has strike through line
    isStrikeThrough?: boolean;

    // Whether the text is in block quote
    isBlockQuote?: boolean;

    // Whether the text is in subscript mode
    isSubscript?: boolean;

    // Whether the text is in superscript mode
    isSuperscript?: boolean;

    // Whether unlink command can be called to the text
    canUnlink?: boolean;

    // Whether add image alt text command can be called to the text
    canAddImageAltText?: boolean;

    // Whether the content can be undone
    canUndo?: boolean;

    // Whether the content ca nbe redone
    canRedo?: boolean;

    // Header level (0-6, 0 means no header)
    headerLevel?: number;
}

To query format state after each edit event, you need to have a plugin to handle event such as MouseDown, KeyDown and ContentChanged. There is a sample Ribbon code in roosterjs-react project (see below).

Example

Suppose we have below HTML code to build the format bar with 3 basic buttons: bold, italic, underline:

<div>
    <button id="bold"><b>B</b></button>
    <button id="italic"><i>I</i></button>
    <button id="underline"><u>U</u></button>
</div>

Then use the following javascript code to handle click event of these buttons. (rooster.js file is directly used in this example. Please reference to the first example in Preparation)

document.getElementById('bold').addEventListener('click', function() {
    roosterjs.toggleBold(editor);
});
document.getElementById('italic').addEventListener('click', function() {
    roosterjs.toggleItalic(editor);
});
document.getElementById('underline').addEventListener('click', function() {
    roosterjs.toggleUnderline(editor);
});

To add more buttons, you need to render more UI buttons and call the format APIs above.

RoosterJs-react example

roosterjs-react repository contains a react based roosterjs wrapper and some UI components including a format bar (a.k.a Ribbon). You can check out source code, compile and run its sample site to see how a Ribbon and other UI components are created based on react and roosterjs.

Clone this wiki locally