Roles of a Plugin

• Inform the system about what roles the plugin handles
  • tags
  • generated media types
  • deployment targets
  • import and export types
• Specify the syntax of the tag’s content
• Specify what elements are allowed in a tag
• Expose a manifest
  • name
  • description
  • usage
  • help
  • elements, media types, deployment targets, import/export types
• Tap into lifecycle hooks
• Register specialized callbacks
• Validate content
• Provide configuration

Installing Plugins

Plugins are installed using the configuration object that is passed into the createWordscriptEngine function.

createWordscriptEngine({
    plugins: standardPlugins(),
})

Most plugins are functions that accept configuration options and return a WordscriptPlugin.

createWordscriptEngine({
    plugins: [ somePlugin({doThis:true, doThat:false}) ],
})

Adding Additional Plugins

createWordscriptEngine({
    plugins: [
        ...standardPlugins()
        speechPlugin(),
        slidePlugin(),
        htmlTranscriptPlugin(),
    ]
})

Configuring A Standard Plugin

To configure a standard plugin, first exclude it from the other standard plugins. Then re-add it using an options object.

const plugins = standardPlugins().filter(it => it.id !== 'heading')
createWordscriptEngine({
    plugins: [
        ...plugins,
        HeadingPlugin({maxHeading:12})
    ]
})

Creating A Plugin

A plugin is simply an object that exposes manifest and an install method.

const plugin = {
    manifest: {
        name: 'PDF viewer',
        description: 'Converts contents into an interactive PDF'
        tags: ['pdf']
    },
    install(context) {
    }
}

Most plugins are set up as functions that accept an options object and return a plugin.

const plugin = (options) => ({
    install(context) {
    },
    manifest: {
        name: 'Some Plugin',
        tags: ['xyz']
    }
})

It is common practice to destructure the context parameter.

const plugin = {
    install({hooks}) {
      hooks.speech.willSpeak.tap( () => {
      })
    }

There are two ways a plugin can interact with the runtime; Tapping into a hook, or registering a callback.

Taps

const plugin = {
    install({hooks}) {
      hooks.speech.willSpeak.tap( () => {
      })
    }

Callbacks

const plugin = {
    install({register}) {
      register.speech('testing',  () => {
      })
    }

Standard Plugins

The following plugins are installed automatically by default.

Tag

• Text Plugin
• Heading Plugin
• Style Plugin
• Anchor Plugin
• Bullet Item Plugin
• HTML Plugin
• Internal Plugin

Generate

System

• Log Speech Plugin
• Log Print Plugin
• Media Plugin
• Speech Plugin
• Export Plugin
• Publish Plugin
• Ignore Plugin
• Keyword Plugin
• Include Plugin
• Import Plugin
• Pause Plugin
• Play Plugin
• Prompt Plugin

Deploy

• Local Storage
• Local File

Plugin Types

• Speech
• Print
• Export
• Media Export
• Transcript
• Resource
• Interact
• Publish
• Deploy
• Lookup

Generated Media Types

• Speech
• Interactive Speech
• Website
• Webpage
• Slides
• Podcast
• Email
• Message
• Robocall
• Command Line
• Robotic
• Transcript
• Chat
• Help Desk

Plugin Usage

Heading Plugin

The heading plugin allows for creating headings. Headings can indicate static and dynamic levels. Headings are used for script organization, and can be printed, spoken, displayed, and linked.

Tags

h

Content

{ static_level | dynamic_level } { content }

{ static_level} The static_level is an integer greater than 0.

{ dynamic_level } The dynamic_level is =, +, -, or multiple ++ or --. Dynamic levels adjust the last level up to that point. = uses the same level, while the other variants adjust it.

{content} Elements that evaluate to text.

The content can be omitted. In this case the element will set the reference level for all dynamic levels that follow, without contributing any text.

Media

[todo]

Examples

[[h 2 Heading 2]]
[[h = Still heading 2]]
[[h + Heading 3]]
[[h -- Back to heading 1]]

[[# Sets the current level for all following dynamic levels, without contributing any text ]]
[[h 4 ]]
[[h = I am heading 4]]

Style Plugin

Add common styles to dialogue.

Tag	Description
i	italic
b	bold
u	underline
em	emphasis
strong	strong

Tags

i b u em strong

Content

unscoped text and elements that evaluate to text.

Examples

[[b I am bold ]]

[[b [[i  I am bold and italic ]] ]]

[[b,i  I am also bold and italic ]]

[[u [[include some_wordscript.ws ]] ]]

HTML Plugin

Embed HTML directly in your Wordscript

Tags

html

Content

HTML only

Examples

[[html
<h1>Hello</h1>
<div>This is <em>HTML</em></div>
]]

Lookup Plugin

Resolve scope level attributes and computed values.

Tags

$

Content

Space separated names. Names may have a namespace prefix.

Examples

[[@ title:Welcome To Wordscript.]]

The title is [[$ @title ]].

Prompt Plugin

Prompt the recipient for a response, and take action on responses.

Tags

prompt response action

Content

prompt element

[text element] Prompt message
[response element]

response element

[text element] Command
[any element] Action

action element

exit Exit the Wordscript
go target = Go to the specified target

Examples

[[prompt Would you like to continue?
[[response yes [[ OK ]] ]]
[[response no [[ Goodbye ]] ]]
]]

Internal Plugin

Manages internal system-level elements.

Tags

! section @ #

Content

location

! Declares a location element

section

section Declares a section element

attribute

@ Declares an attribute element

comment

# Declares a comment element

A comment element always contains text.
]] characters must be escaped.

Examples