# roadiejs-import
##### A plugin for [RoadieJS](https://github.com/wmfs/roadiejs)

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

## Contents
* [API](#api)
  * [renderTemplate](#renderTemplate)
  * [renderActivity](#renderActivity)
* [Elements](#elements)
  * [ui](#ui)
  * [widget](#widget)
* [Activities](#activities)
  * [showUi](#showUi)
  * [populateWizard](#populateWizard)
* [Widgets](#widgets)
  * [Layout/structure](#layoutStructure)
    * [container](#container)
    * [row](#row)
    * [jumbotron](#jumbotron)
    * [wizard](#wizard)
    * [table](#table)
    * [modal](#modal)
  * [Boilerplate](#boilerplate)
    * [heading](#heading)
    * [paragraph](#paragraph)
  * [Inputs](#inputs)
    * [text](#text)
    * [number](#number)
    * [email](#email)
    * [date](#date)
    * [freeText](#freeText)
    * [lookup](#lookup)
    * [select](#select)
  * [Activity](#activity)
    * [submitData](#submitData)
* [License](#license)

## <a name="api"></a>API

### <a name="renderTemplate"></a>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](http://getbootstrap.com/) 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
<code><strong>GET</strong></code> <code>/ui/[:ns](https://github.com/wmfs/roadiejs#ns)/[:bp](https://github.com/wmfs/roadiejs#bp)/[:bv](https://github.com/wmfs/roadiejs#bv)/[:lv](https://github.com/wmfs/roadiejs#lv)/:uiId</code>

| 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.

---

### <a name="renderActivity"></a>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

<code><strong>GET</strong></code> <code>/ui/:flowId/:activityId</code>

| 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`).


## <a name="elements"></a>Elements

### <a name="ui"></a>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
```json
{
  "element": "ui",
  "id": "newTeacherUi",
  "config": {
    "title": "Teacher form"
  }
}
```
###### Config

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

---


### <a name="widget"></a>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
```json
{
  "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](#widgets) section for widget-specific config and rules.

## <a name="activities"></a>Activities

### <a name="showUi"></a>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
```json
{
  "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.

---

### <a name="populateWizard"></a>populateWizard
Calculates and sets all the necessary metadata to support the operation of a `wizard` element.
###### Example
```json
{
  "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`.


## <a name="widgets"></a>Widgets

### <a name="layoutStructure"></a>Layout/structure

#### <a name="container"></a>container

Adds a [Bootstrap container](http://getbootstrap.com/css/#overview-container), onto which most elements can be added.

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

---

#### <a name="row"></a>row

Adds a [Bootstrap row](http://getbootstrap.com/css/#grid), 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.

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

---

#### <a name="jumbotron"></a>jumbotron

Adds a [Bootstrap Jumbotron](http://getbootstrap.com/components/#jumbotron), onto which boilerplate widgets are typically added.

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

---

#### <a name="wizard"></a>wizard

Adds a wizard-style interface into the UI.

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

---

#### <a name="table"></a>table

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

```json
{
  "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"
      }
    ]
  }
}
```

---

#### <a name="modal"></a>modal

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

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

### <a name="boilerplate"></a>Boilerplate

#### <a name="heading"></a>heading

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

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

---

#### <a name="paragraph"></a>paragraph

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

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

### <a name="inputs"></a>Inputs

#### <a name="text"></a>text

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

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

---
#### <a name="number"></a>number

Adds an HTML `input`, configured to collecting numeric data.

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

---

#### <a name="email"></a>email

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

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

---

#### <a name="date"></a>date

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

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

---

#### <a name="freeText"></a>freeText

Adds an HTML editing UI component.

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

---

#### <a name="lookup"></a>lookup

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

```json
{
  "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"
  }
}
```

---

#### <a name="select"></a>select

Adds an HTML `select` element.

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

### <a name="activity"></a>Activity

#### <a name="submitData"></a>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`)

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


## <a name="license"></a>License
[MIT](https://github.com/wmfs/roadiejs-ui/blob/master/LICENSE.md)