roadiejs-import

A plugin for RoadieJS

A toolbox of widgets, elements and API endpoints from which to build user interfaces.

Contents

• API
  • renderTemplate
  • renderActivity
• Elements
  • ui
  • widget
• Activities
  • showUi
  • populateWizard
• Widgets
  • Layout/structure
    • container
    • row
    • jumbotron
    • wizard
    • table
    • modal
  • Boilerplate
    • heading
    • paragraph
  • Inputs
    • text
    • number
    • email
    • date
    • freeText
    • lookup
    • select
  • Activity
    • submitData
• License

API

renderTemplate

Returns HTML representing an for a specific ui element.

• May contain HTML5 attributes.
• To work as intended, the returned HTML requires at least Bootstrap CSS.
• A future enhancement will be to support a format parameter to so a JSON representation can be requested instead of HTML (for use with mobile apps)

Request

GET /ui/:ns/:bp/:bv/:lv/:uiId

| Name | Notes | ---- | ---- | uiId | The id of a ui element defined in the blueprint.

Response

Status 200

• The body of the response will be HTML representing the ui element identified in the request.

renderActivity

Much the same as renderTemplate, except here the uiId is inferred from a flow/activity instead of being explicitly provided.

• Designed to work in-conjunction with immediatePendingActivityId from roadiejs-flow.

Request

GET /ui/:flowId/:activityId

| Parameter | Notes | --------- | ---- | flowId | A system-generated id that uniquely identifies a flow (e.g. flowId returned from createFlowFromRequest). | activityId | The id of an activity within the specified flow. This activity needs to be of type showId (so that a uiId can be inferred, and subsequently rendered).

Response

Status 200

• The body of the response will be HTML representing a ui element (the id of which will be inferred via a showUi).

Elements

ui

Declares a new user interface, onto which child widget elements can be added. The structure of widgets under a ui widget is typically tree-like.

Example

{
  "element": "ui",
  "id": "newTeacherUi",
  "config": {
    "title": "Teacher form"
  }
}

Config

| Name | Type | Notes | ----------- | -------| ----------- | title | string | A brief description that summarises what the user interface does.

widget

A component used to build-up user interfaces. Can be a child of a ui element, or another widget element... the precise rules involved are specific to the widgets involved.

Example

{
  "element": "widget",
  "path": "newTeacherUi.jumbotron",
  "config": {
    "widgetType": "heading",
    "size": 1,
    "text": "Teacher"
  }
}

Config

| Name | Type | Notes | ------------ | -------- | ----------- | widgetType | string | Identifies the type of widget. Must be a supported widget name.

• Only widgetType is a mandatory value across all widgets... all other values, and permitted child/parent elements, are specific to the widget's type.
• Please see the Widgets section for widget-specific config and rules.

Activities

showUi

Once flow reaches an activity of this type, user-facing apps can derive a ui element to display. It's the responsibility (e.g. via setDataAndProgress and similar) of the app to update things so that the flow subsequently resumes.

Example

{
  "element": "activity",
  "id": "showTeacherUi",
  "path": "newTeacher",
  "config": {
    "activityType": "showUi",
    "config": {
      "uiId": "newTeacherUi"
    }
  }
}

Config

| Name | Type | Notes | ------------ | -------| ----------- | uiId | string | The id of a ui element that should be displayed to the user.

populateWizard

Calculates and sets all the necessary metadata to support the operation of a wizard element.

Example

{
  "element": "activity",
  "id": "populateWizard",
  "path": "newPupil",
  "config": {
  "activityType": "populateWizard",
    "config": {
      "targetActivityId": "showPupilUi"
    }
  }
}

Config

| Name | Type | Notes | ------------ | -------| ----------- | targetActivityId | string | The id of an activity in the current flow, with a type of ui.

Widgets

Layout/structure

container

Adds a Bootstrap container, onto which most elements can be added.

{
  "element": "widget",
  "id": "container",
  "path": "newTeacherUi",
  "config": {
    "widgetType": "container"
  }
}

row

Adds a Bootstrap row, onto which most elements can be added. Rows need not be explicitly defined, and will be added automatically if a widgets parent isn't a suitable container.

{
  "element": "widget",
  "path": "newTeacherUi.container",
  "config": {
    "widgetType": "row"
  }
}

jumbotron

Adds a Bootstrap Jumbotron, onto which boilerplate widgets are typically added.

{
  "element": "widget",
  "id": "jumbotron",
  "path": "newTeacherUi",
  "config": {
    "widgetType": "jumbotron",
    "fullWidth": true
  }
}

wizard

Adds a wizard-style interface into the UI.

{
  "element": "widget",
  "id": "wizard",
  "path": "newPupilWizard",
  "config": {
    "widgetType": "wizard"
  }
}

table

Adds a configurable table for applying CRUD operations to sub-documents.

{
  "element": "widget",
  "id": "qualifications",
  "path": "maintainTeacherUi.container",
  "config": {
    "widgetType": "table",
    "heading": "Qualifications",
    "singular": "qualification",
    "plural": "qualifications",
    "dataPath": "qualifications",
    "uiId": "qualificationUi",
    "createAllowed": true,
    "deleteAllowed": true,
    "cols": [
      {
        "label": "Code",
        "field": "code",
        "action": "update"
      },
      {
        "label": "Title",
        "field": "title",
        "action": "update"
      },
      {
        "label": "Issued",
        "field": "issued",
        "filter": "date",
        "action": "update"
      }
    ]
  }
}

modal

Defines a modal dialog for use with table widgets and similar.

{
  "element": "widget",
  "id": "modal",
  "path": "qualificationUi",
  "config": {
    "widgetType": "modal",
    "heading": "Qualification",
    "controlScheme": "simple"
  }
}

Boilerplate

heading

Adds a HTML <h1>, <h2>, <h3> etc. elements.

{
  "element": "widget",
  "path": "newTeacherUi.jumbotron",
  "config": {
    "widgetType": "heading",
    "size": 1,
    "text": "Teacher"
  }
}

paragraph

Adds a <p>...</p> HTML element.

{
  "element": "widget",
  "path": "newTeacherUi.jumbotron",
  "config": {
    "widgetType": "paragraph",
    "text": "Create teacher..."
  }
}

Inputs

text

Adds an HTML input, configured to collecting string/text data.

{
  "element": "widget",
  "id": "firstName",
  "path": "newTeacherUi.container",
  "config": {
    "widgetType": "text",
    "dataPath": "firstName",
    "prompt": {
      "text": "First name"
    }
  }
}

number

Adds an HTML input, configured to collecting numeric data.

{
  "element": "widget",
  "id": "version",
  "path": "showStreetCreateUi.container",
  "config": {
    "widgetType": "number",
    "dataPath": "version",
    "prompt": {
      "text": "Version"
    }
  }
}

email

Adds an HTML input, configured to collecting an e-mail address.

{
  "element": "widget",
  "id": "email",
  "path": "departmentUi.container",
  "config": {
    "widgetType": "email",
    "dataPath": "email",
    "prompt": {
      "text": "Email"
    }
  }
}

date

Adds a UI component (with calendar tool) for collecting a date.

{
  "element": "widget",
  "id": "dob",
  "path": "newTeacherUi.container",
  "config": {
    "widgetType": "date",
    "dataPath": "dateOfBirth",
    "prompt": {
      "text": "Date of birth"
    }
  }
}

freeText

Adds an HTML editing UI component.

{
  "element": "widget",
  "id": "mission",
  "path": "departmentUi.container",
  "config": {
    "widgetType": "freeText",
    "dataPath": "mission",
    "prompt": {
      "text": "Front page"
    }
  }
}

lookup

Adds a UI component for picking a single value from a list via Elasticsearch. Supports typeahead and other functionality.

{
  "element": "widget",
  "id": "department",
  "path": "newTeacherUi.container",
  "config": {
    "widgetType": "lookup",
    "widgetSubType": "single",
    "singular": "department",
    "placeholder": "Search departments",
    "field": "department",
    "schema": "departments",
    "required": true,
    "prompt": {
      "text": "Department"
    },
    "placeholder": "Search departments",
    "dataPath": "department"
  }
}

select

Adds an HTML select element.

{
  "element": "widget",
  "id": "title",
  "path": "newTeacherUi.container",
  "config": {
    "widgetType": "select",
    "dataPath": "title",
    "prompt": {
      "text": "Title"
    },
    "options": {
      "sourceType": "enum",
      "config": {
        "schema": "teachers",
        "path": "title"
      }
    }
  }
}

Activity

submitData

Adds Cancel and OK buttons.

• Pressing OK will update the activity with form data, and attempts to continue (via setDataAndProgress)
• Pressing Cancel will terminate the flow (via stopFlowFromRequest)

{
  "element": "widget",
  "id": "submit",
  "path": "maintainTeacherUi.container",
  "config": {
    "widgetType": "submitData"
  }
}

License

MIT