Setup

Setup

After installing SYP-Editor you need to configure and setup the editor-instance.

Basic Setup

The basic-setup includes all features, SypEditor has to offer out of the box. It consists of following tools:

• undo/redo
• linking
• heading
• lists
• blockquote
• codeblock
• textaligns (justify, center, left, right)
• bold
• italic
• underline
• strikethrough

To offer those toolings following packages from tiptap must be installed:

• @tiptap/core
• @tiptap/extension-document
• @tiptap/extension-blockquote
• @tiptap/extension-list
• @tiptap/extension-paragraph
• @tiptap/extension-text
• @tiptap/extension-text-align
• @tiptap/extension-heading
• @tiptap/extensions
• @tiptap/extension-bold
• @tiptap/extension-italic
• @tiptap/extension-strike
• @tiptap/extension-underline
• @tiptap/extension-code-block-lowlight
• @tiptap/extension-link

Based on those an editor can be created:

import { Editor } from '@tiptap/core'
import Document from '@tiptap/extension-document'
import Blockquote from '@tiptap/extension-blockquote'
import { BulletList, ListItem, TaskList, TaskItem, OrderedList } from '@tiptap/extension-list'
import Paragraph from '@tiptap/extension-paragraph'
import Text from '@tiptap/extension-text'
import TextAlign from '@tiptap/extension-text-align'
import Heading from '@tiptap/extension-heading'
import { UndoRedo} from '@tiptap/extensions'
import Bold from '@tiptap/extension-bold'
import Italic from '@tiptap/extension-italic'
import Strike from '@tiptap/extension-strike'
import Underline from '@tiptap/extension-underline'
import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight'
import Link from '@tiptap/extension-link'
import { SypEditor, SypEditorLinkExtension } from '@syntaxphoenix/syp-editor';

const element = document.querySelector('#editor');

// TODO: Configure lowlight according to your needs, see tiptap-documentation for more info

const tiptapEditor = new Editor({
    element: element,
    extensions: [
        Document,
        Paragraph,
        Text,
        Heading,
        TextAlign.configure({
            types: ['heading', 'paragraph'],
        }),
        UndoRedo,
        Bold,
        Italic,
        Underline,
        Strike,
        Blockquote,
        CodeBlockLowlight.configure({
            lowlight,
        }),
        BulletList,
        ListItem,
        TaskList,
        TaskItem,
        OrderedList,
        Link
    ],
    content: '',
});

const sypEditor = new SypEditor(
    element,
    tiptapEditor,
    {
        configuration: [
            {
                type: 'preset',
                name: 'fontawesome5_redo_undo_group'
            },
            {
                type: 'separator'
            },
            {
                type: 'group',
                elements: [
                    {
                        type: 'preset',
                        name: 'fontawesome5_heading_dropdown'
                    },
                    {
                        type: 'preset',
                        name: 'fontawesome5_list_dropdown'
                    },
                    {
                        type: 'button',
                        icon: 'code',
                        iconProvider: 'fontawesome5',
                        name: 'code block',
                        command: 'toggleCodeBlock'
                    },
                    {
                        type: 'button',
                        icon: 'quote-right',
                        iconProvider: 'fontawesome5',
                        name: 'blockquote',
                        command: 'toggleBlockquote'
                    },
                    {
                        type: 'preset',
                        name: 'fontawesome5_link'
                    }
                ]
            },
            {
                type: 'separator'
            },
            {
                type: 'preset',
                name: 'fontawesome5_textalign_group'
            },
            {
                type: 'separator'
            },
            {
                type: 'preset',
                name: 'fontawesome5_fontstyle_group'
            }
        ],
        settings: {
            presetsEnabled: true
        },
        elementExtensions: [
            new SypEditorLinkExtension()
        ]
    }
);

For styling you also need to include the css/scss-files.

For scss:

  @import '~@syntaxphoenix/syp-editor/scss/editor.scss';

For css:

  import '~@syntaxphoenix/syp-editor/dist/editor.min.css';

Setup

The setup of SypEditor consists of three parameters:

Parameter	Type	Description
element	HTMLElement	This is the editor-element. As tiptap does not work on textareas it should in most cases be a div-container
editor	Editor	This is the tiptap-editor instance
configuration	Partial	The configuration of syp-editor, consisting of settings, the toolbar-configuration and extensions

Most important is the configuration-parameter. It is used to configure settings of the SypEditor-instance, adding ElementExtensions, Icon-Providers, and Preset-Providers and for the toolbar-configuration.

SypEditor-Settings

The settings-section is used for general editor-settings, and has following options:

presetsEnabled : boolean
Default: false
Enables the preset-functionallity of SypEditor, only enable it, when its used for performance reasons

iconAttributes : Object
Default: {}
Global attributes for icons, a parameter could be class when used with the Fontawesome 5 icon-provider

presetAttributes : Object
Default: {}
Global attributes for presets

Icon-Providers

Consists of a list of additional icon-providers. For more information look at icon-providers

Preset-Providers

Consists of a list of additional preset-providers. For more information look at preset-providers

Element-Extensions

Consists of a list of additional element-extensions. SypEditor already delivers the SypEditorLinkExtension, which can be added to the list, if links should be used. For more information look at element-extensions

Toolbar-Configuration

The section configuration holds the toolbar-configuration and is the main-section of the configuration.
It consists of an array of ConfigurationEntrys, some of those even having subelements, like the group or dropdown-element. They get rendered to ToolbarItems when loaded

In general the configuration looks like follows:

configuration: [
  {
    type: 'preset',
    name: 'fontawesome5_redo_undo_group'
  },
  {
    type: 'separator'
  },
  {
    type: 'group',
    elements: [
      {
        type: 'preset',
        name: 'fontawesome5_heading_dropdown'
      },
      {
        type: 'preset',
        name: 'fontawesome5_list_dropdown'
      }
    ]
  },
]

A list of all ToolbarItems can be found here.

The configuration can be then combined of multiple ToolbarItems, with ToolbarItems like the dropdown and group multiple sub-elements can be placed in "sub-menus". With the preset-functionallity created sections can get reused. This might be helpful if you want to create a editor for e-mails and a wysiswyg-editor for a blog and want to reuse the toolbar-items. In addition the readymade presets offer a good start and helps reducing the development-time of adding SypEditor to your project.

Important Note: Presets can not be a preset of another preset, as this would add additional performance-impact onto the loading-time. Therefore configurations should be reused within the preset-providers.