rupertlssmith / rte-toolkit-patch / RichText.Editor

This is the main module for an editor, and contains functions for initializing, updating, and rendering an editor.

Model


type alias Editor =
RichText.Internal.Editor.Editor

Editor represents the entire state of the editor, and is what you store in your model.

init : RichText.Model.State.State -> Editor

Initializes an editor

docNode : Block
docNode =
    block
        (Element.element doc [])
        (blockChildren <|
            Array.fromList
                [ block
                    (Element.element paragraph [])
                    (inlineChildren <| Array.fromList [ plainText "Hello world" ])
                ]
        )

init <| State.state docNode Nothing

state : Editor -> RichText.Model.State.State

Retrieves the current state from the editor

shortKey : Editor -> String

The editor shortKey is a platform dependent key for command map bindings. It is initialized to either "Control" or "Meta" depending on if the editor webcomponent detects if the platform is mac/iOS or something else. Note that this gets updated after the editor has been rendered, and defaults to "Meta".

history : Editor -> RichText.Model.History.History

Retrieves the current history from the editor

withHistory : RichText.Model.History.History -> Editor -> Editor

Sets the history on the editor.

editor
    |> withHistory newHistory

changeCount : Editor -> Basics.Int

Change count is a counter that gets incremented any time the editor's state gets updated. You may want to use this as a quick way to see if the editor has changed via a command after the update function. Note: this is a stop gap until a good story for how programmers can react to editor state changes has been thought out.

Config


type Config msg

This type represents your Editor configuration, e.g. the non-comparable things that define the behavior of the editor. This includes the document specification, key and input event command bindings, decorative functions, and tagger function.

config : { decorations : RichText.Config.Decorations.Decorations msg, spec : RichText.Config.Spec.Spec, commandMap : RichText.Config.Command.CommandMap, toMsg : Message -> msg } -> Config msg

Create the config for your view and update functions.

import RichText.Commands exposing (defaultCommandMap)
import RichText.Config.Decorations exposing (emptyDecorations)
import RichText.Definitions exposing (markdown)

type MyMsg
    = InternalMsg Message | ...

myConfig : Config
myConfig =
    config
        { decorations = emptyDecorations
        , commandMap = defaultCommandMap
        , spec = markdown
        , toMsg = InternalMsg
        }

commandMap : Config msg -> RichText.Config.Command.CommandMap

The commandMap from the config object.

decorations : Config msg -> RichText.Config.Decorations.Decorations msg

The decorations from the config object.

spec : Config msg -> RichText.Config.Spec.Spec

The spec from the config object.

Update


type alias Message =
RichText.Internal.Editor.Message

The internal events that an editor has to respond to.

update : Config msg -> Message -> Editor -> Editor

The editor's internal update function. It's important that the editor process all Message events with the update function so it doesn't go out of sync with the virtual DOM.

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        EditorMsg editorMsg ->
            ( { model | editor = RichText.Editor.update config editorMsg model.editor }, Cmd.none )

apply : RichText.Config.Command.NamedCommand -> RichText.Config.Spec.Spec -> Editor -> Result String Editor

Apply a named command to the editor. If the command was successful, the resulting editor will be returned, otherwise a String describing the command's error is returned.

Note that after the command is executed, it is validated against the spec. If it is not valid, then an error is returned. If the command is successful and validated, the resulting editor state is reduced (via RichText.State.reduce) and the history is updated.

wrapBlockNode : Spec -> Model -> Model
wrapBlockNode spec model =
    { model
        | editor =
            Result.withDefault model.editor
                (apply
                    ( "wrapBlockquote"
                    , transform <|
                        wrap
                            identity
                            (element blockquote [])
                    )
                    spec
                    model.editor
                )
    }

applyList : RichText.Config.Command.NamedCommandList -> RichText.Config.Spec.Spec -> Editor -> Result String Editor

Apply a list of named commands to the editor to try in order, returning the updated editor after the first command has been successful. If no command was successful, a String describing the last command's error is returned.

This method stops execution of the commands after the first success. Its intent is to allow you to group your commands for different contexts, like lift, join, split, into one chained command. If you want multiple commands to be executed, you may want to compose the respective transform functions or call apply for each command.

As with the apply command, each command is validated after it is applied, and if successful, the editor state is reduced and the history is updated.

liftBlock : Spec -> Model -> Model
liftBlock spec model =
    { model
        | editor =
            Result.withDefault model.editor
                (applyList
                    [ ( "liftList"
                      , transform <| RichText.List.lift defaultListDefinition
                      )
                    , ( "lift"
                      , transform <| lift
                      )
                    ]
                    spec
                    model.editor
                )
    }

applyNoForceSelection : RichText.Config.Command.NamedCommand -> RichText.Config.Spec.Spec -> Editor -> Result String Editor

Same as apply, but the selection state is not forced to update if it hasn't changed. This normally should not be used, but can be useful for situations like if you have an embedded input element in a "contentediable=false" wrapper that requires focus or independent selection.

View

view : Config msg -> Editor -> Html msg

Take an editor model and config and render it in the DOM.

readOnlyView : Config msg -> Editor -> Html msg

Renders the contents of the editor with contenteditable set to false and the event listeners removed.