Guide to Loris React components

Under construction

Note: this guide assumes a basic understanding of React concepts and lifecycle.
For React documentation click here.

You can find a set of reusable components under jsx/ directory of your Loris installation. The list is continuously expanding, so watch out for updates.

---

Table of Contents

1. StaticDataTable.js
2. DynamicDataTable.js
3. Form.js
   • FormElement
   • SelectElement
   • TextboxElement
   • TextareaElement
   • DateElement
   • NumericElement
   • FileElement
   • StaticElement
   • ButtonElement
   • LorisElement
4. FilterForm.js 🆕
5. Tabs.js 🆕
6. Panel.js 🆕
7. Breadcrumbs.js
8. PaginationLinks.js
9. Markdown.js
10. MultiSelectDropdown.js (Currently only used by DQT, ask Jordan for details)

---

StaticDataTable

Static Data Table displays a set of data that is receives via props.
Optional props are in [] brackets.

API

Props	Type	Description
Headers	array	Headers of the given table
Data	array	Data to be shown in the table
[RowNumLabel]	string	Header of the first column of every table (Default: 'No.')
[getFormattedCell]	function	Signature: function formatColumn(column, cell, rowData, rowHeaders){} Return: JSX element for a table cell
[freezeColumn]	string	Name of the column that stays in place when table is scrolled horizontally
[RowNameMap]	???	???
[Filter]	object	Object used to filter displayed data

Usage

<StaticDataTable
    Headers={['ID', 'First Name', 'Last Name']}
    Data=[[1, 'Ted', 'Mosby'], [2, 'Barney', 'Stinson'], [3, 'Robin', 'Scherbatsky']]
    getFormattedCell={formatColumn}
    freezeColumn="ID"
/>

Note: formatColumn() is usually declared in a separate file, typically named columnFormatter.js

---

DynamicDataTable

DynamicDataTable is a wrapper around StaticDataTable

Instead of raw Data and Headers, it expects a URL pointing to JSON data which it retrieves and passes down to StaticDataTable. All other properties are the same as in StaticDataTable as they are passed down to it.

Usage

<DynamicDataTable
  DataURL="https://loris.ca/media/?format=json",
  getFormattedCell={formatColumn},
  freezeColumn="File Name"
/>

---

Form

Form.js contains a collection of components commonly used to built interactive forms.

FormElement

FormElement is a React wrapper around HTML <form> element, adding dynamic functionality, such as:

API

Props	Type	Description
name	string	Form name
[id]	string	Form unique id
[method]	string	GET or POST
[class]	string	CSS class applied on <form> element
[columns]	number	Number of columns in the form. Determines the layout of children elements.
[formElements]	object	React elements rendered inside the <form>
[onSubmit]	function	Callback function triggered on form submission
[onUserInput]	function	Callback function triggered on input change in one of the form elements

SelectElement

SelectElement is a react wrapper around HTML <select>, adding dynamic functionality, such as:

API

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
options	object	Options displayed in the <select> dropdown
[label]	string	User friendly text describing <select> purpose. Default: ""
[value]	string or array	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[class]	string	CSS class applied on <form> element. Default: ""
[multiple]	bool	When set to true the element replicates native HTML5 behaviour allowing user to select multiple elements in the dropdown. Default: false
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[emptyOption]	bool	By default adds an empty option to every <select> dropdown. Default: true
[hasError]	bool	When set to true adds displays errorMessage and applies error styles to the element. Default: false
[errorMessage]	string	The error message, displayed only if hasError is set to true. Default: "The field is required!"
[onUserInput]	function	Callback function triggered on input change

TextboxElement

TextboxElement is a react wrapper around HTML <input type="text">, adding dynamic functionality, such as: ..., ...

API

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
[label]	string	User friendly text describing <input typ="text" /> purpose. Default: ""
[value]	string	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[onUserInput]	function	Callback function triggered on input change

TextareaElement

TextareaElement element is a react wrapper around HTML <textarea>, adding dynamic functionality, such as: ..., ...

API

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
[label]	string	User friendly text describing <textarea> purpose. Default: ""
[value]	string	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[onUserInput]	function	Callback function triggered on input change

DateElement

DateElement is a react wrapper around HTML <input type="date">, adding dynamic functionality, such as: ..., ...

API

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
[label]	string	User friendly text describing purpose of the element. Default: ""
[value]	string	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[onUserInput]	function	Callback function triggered on input change

NumericElement

API

NumericElement is a react wrapper around HTML <input type="number">, adding dynamic functionality, such as: ..., ...

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
min	number
max	number
[label]	string	User friendly text describing purpose of the element. Default: ""
[value]	string	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[onUserInput]	function	Callback function triggered on input change

FileElement

API

FileElement renders custom HTML used to upload files

Props	Type	Description
name	string	Element name. Must be consistent with values used on the backend.
[label]	string	User friendly text describing purpose of the element. Default: ""
[value]	string	Selected value(s). Default: undefined
[id]	string	Element unique id. Default: ""
[disabled]	bool	When set to true HTML5 disabled is applied to the element. Default: false
[required]	bool	When set to true HTML5 required is applied to the element. Additionally, a red 'asterisk' is displayed along the label. Default: false
[hasError]	bool	When set to true adds displays errorMessage and applies error styles to the element. Default: false
[errorMessage]	string	The error message, displayed only if hasError is set to true. Default: "The field is required!"
[onUserInput]	function	Callback function triggered on input change

StaticElement

API

StaticElement is a react wrapper around HTML <label>...

Props	Type	Description
[label]	string	User friendly text describing purpose of the element. Default: ""
[text]	string or object	Selected value(s). Default: undefined

ButtonElement

API

ButtonElement is a react wrapper around HTML <button>, adding dynamic functionality, such as: ..., ...

Props	Type	Description
[label]	string	User friendly text describing purpose of the element. Default: ""
[type]	string	HTML <button/> type. Default: submit
[onUserInput]	function	Callback function triggered on input change

LorisElement

Loris element is a generic component that receives a JSON representation of the element and renders an appropriate component from the list above. It infers the type of the element to be rendered from element.type property.

Usage

// The element will typically be received in the PHP LorisForm format, 
// but can also be defined as a Javascript object.

const el = {
  type: "select",
  // other props
}

<LorisElement
  element={element}          // JSON representation of a form element
  onUserInput={function(){}} // Optional callback function
  value={"123"}              // Optional props supported by the target element.
/>

---

FilterForm

Overview

FilterForm component renders a 'Selection Filter' panel with form elements, as seen in the screenshot below.

Main functionality

• Adds onUpdate callbacks to all children elements and passes them to FormElement for proper form rendering.
• Updates filter object values to correspond to formElement values and propagates changes to parent component on every update. (This is particularly useful to filter StaticDataTable by filter values).
• Updates browser query string using QueryString utility class in order to have persistent data in form fields across page updates

API

Props	Type	Description
Module	string	Module name
filter	object	An object containing the current values of form elements inside the filter
formElements	object	List of form elements in json format
[id]	string	Unique FilterForm id. Default: 'selection-filter'
[height]	string	The height of the selection filter panel. Default: 100%
[title]	string	Text displayed in the title bar of the panel. Default: 'Selection Filter'
[onUpdate]	function	Callback function triggered on input change in one of the form elements

Usage

1. Passing form elements as a prop.
   • Particularly useful when converting existing Loris selection filters from PHP to React.
   • In the example below, this.state.Data.form contains JSON encoded value of $this->form->form returned from PHP backend.

// Renders a Selection Filter (as seen on the screenshot above)
// Form elements are passed to <FilterForm /> as a formElements prop.
<FilterForm
  Module="media"
  name="media_filter"
  id="media_filter"
  columns={3}
  formElements={this.state.Data.form}
  onUpdate={this.updateFilter}    // Update filter on FilterForm update
  filter={this.state.filter}	  // Keep track of filter in the parent class
>
  <br/>
  <ButtonElement type="reset" label="Clear Filters" />
</FilterForm>

2. Passing form elements as children of <FilterForm />

// Renders a Selection Filter 
// Form elements are passed as children element of the <FilterForm />
<FilterForm
  Module="dicom_archive"
  name="dicom_filter"
  id="dicom_filter"
  columns={2}
  onUpdate={this.updateFilter}  // Update filter on FilterForm update
  filter={this.state.filter}    // Keep track of filter in the parent class
>
  <TextboxElement
    name={patientName}
    label="Patient Name"
  />
  <SelectElement
    name={site}
    label="Sites"
    options={siteList}
  />
  <ButtonElement
    label="Clear Filters"
    type="reset"
  />
</FilterForm>

---

Tabs

Wrapper around bootstrap tabs

---

Panel

Wrapper around bootstrap panel

---

Breadcrumbs

Wrapper around bootstrap breadcrumbs used for Loris navigation

---

PaginationLinks

Component used by StaticDataTable to add pagination to table results

---

Markdown

Used to render markdown text

---

MultiSelectDropdown

Used by DQT for ...some reason