Component Registration
A display component definition consists of two parts: a server definition and the actual JSX/Javascript code that implements the component on the client. This section focuses on the server-side definition.
On the server, a component definition consists of a simple JSON configuration file (see examples in the definitions directory). The configuration object contains 3 items:
- name - the name that will display for selection on a page.
- description - a description that will be displayed during configuration of the component.
- data - an array of data definitions, as described below.
- props - an array of property definitions, described below.
- state - an array of state variables, for future use.
Each data definition item consists of a tag, a name, a description, and a type. The name and description are used on the configuration page of a component. The type is the type of data that is being described: card, cardset, dataset or multidataset. The tag is used within the React component implementation to access the data (obviously different data definitions must have distinct tags).
This definition is used on the site administration pages to determine what information the user must configure for the component. It is also used to determine what data to transmit to the the front-end app and how to organize it.
The following is the component definition for SimpleCard. The component takes and outputs a single card: Two of them are used, for example, on the About page on the Asheville budget site](http://avlbudget.org/About): one has the basic About page content, and the other simply embeds a Google form.
{
"name": "SimpleCard",
"description": "Just a simple display of a single card",
"props": {},
"data": [
{
"tag": "mycard",
"name": "Your Card",
"description": "Pick a card, any card",
"type": "card"
}
],
"props": {
"headerTag": {
"value": "1",
"configurable": true,
"label": "Select type of header tag",
"type": "select",
"options": [
{
"name": "No header",
"value": "0",
"description": "No header"
},
{
"name": "H1",
"value": "1",
"description": "H1"
},
{
"name": "H2",
"value": "2",
"description": "H2"
},
{
"name": "H3",
"value": "3",
"description": "H3"
},
{
"name": "H4",
"value": "4",
"description": "H4"
},
{
"name": "H5",
"value": "5",
"description": "H5"
}
]
}
}
}The props array is particularly useful for creating properties that the user can configure for a particular use of the component. If configurable is set to true, the configuration page for the component will automatically generate a dialog for the property. Right now only the select type is supported. In the example above, the headerTag property lets the user specify how the title on the card displays (H1, H2, ... or not displayed).
New components may be registered on the server in the Components tab of the system administration section (i.e., you must be a superuser). In addition, you may place the definition JSON file in gbe/resources/definitions/components and the component will be automatically registered during server initialization (in the system seeder). During development on your own instance of a server, re-initializing the system is straightforward. From the gbe subdirectory on the server, run:
./artisan migrate:rollback
./artisan migrate --seed
The configuration file for the HistoryTable is even simpler, since it has no options. It simply specifies that the user should select one or more datasets:
{
"name":"HistoryTable",
"description": "Interactive table component for exploring multi-year data. Takes 2+ datasets.",
"data": [
{
"tag":"mydatasets",
"name":"Datasets for HistoryTable",
"description":"Add datasets in any order - sequencing is handled automatically.",
"type":"multidataset"
}
],
"props": {
},
"state": {
}
}