Nobody Prefers Margarine

    roadiejs-ui

    0.0.10 • Public • Published

    roadiejs-import

    A plugin for RoadieJS

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

    Contents

    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

    Keywords

    Install

    npm i roadiejs-ui

    DownloadsWeekly Downloads

    1

    Version

    0.0.10

    License

    MIT

    Last publish

    Collaborators

    • timneedham