@agsci/customfield-svelte-components
v0.0.16
Published
A reusable NPM module to generate form fields based on LabCore's `customfields` data structure.
Downloads
103
Readme
customfield_svelte_components
A reusable NPM module to generate form fields based on LabCore's customfields
data structure.
The data structure for a LabCore customfield
looks like this:
{
"id": 114,
"name": "Name of CustomField",
"value": [],
"default_value": "text of default, see below",
"options": [
{
"name": "Option 1",
"ordering": 1
},
{
"name": "Option 2",
"ordering": 2
},
{
"name": "Option 3",
"ordering": 3
}
],
"ordering": 4,
"required": true,
"help_text": "Helpful prompt for this field",
"field_type": "R"
}
Description
The keys in the JSON represent the following:
id
: The primary key of theCustomField
in the backend databasename
: The name of the custom field. To be rendered as the<label>
of the form field.field_type
: This can beT
- text,R
- radio,C
- checkbox,D
- date,M
, date-time,N
numeric orU
user orA
- textarea.required
: This is true or false, which can be used in form validation.help_text
: This is a prompt that can get displayed under the input as help text.options
: This is a list of objects, each containing thename
andordering
of options. Options are required in the case ofradio
andcheckbox
. If anumeric
field has options, then the field is treated as a physical quantity input field, and the options are considered to be units associated with the physical quantity. For the User selection field, options are provided as a list of arrays like so:[['username', 'UserFirst UserLast"]]
. Options are ignored for other field types.value
: This is the current value of the field. When creating a form object, this is blank, but when editing, it may have a value. This value is always a string (empty or otherwise), with the following exceptions:- If the
field_type
is aC
, we store an array of strings, which can be empty if no options are selected. - If the
field_type
isN
and no options are present, we store it as a number - If the
field_type
isN
and options are present (i.e. this is a physical quantity), then we store it as an array of a number and its units as a string, e.g. [45, 'lb/ac']
- If the
default_value
: When rendering a form field, and the value is empty, this value should be used as the default input if present. Follows the same rules asvalue
, including the exceptions.ordering
This defines the order in which form fields appear, and can be generally ignored, since the database will send the fields in the proper ordering.
Usage
Install this library using
npm i @agsci/customfield-svelte-components
In your svelte LabCore project, you will get a data structure comprising of a list of fields like above. You can create a form with them using something like this on your svelte page:
<script>
import { LCCustomFieldForm } from '@agsci/customfield-svelte-components';
</script>
<div>
<form>
<LCCustomFieldForm bind:formData>
<input type="submit" />
</form>
</div>
The svelte page is responsible for providing form tags and input submit buttons etc. The preferred way is to use form actions to submit the data to the server.
Individual form fields may also be rendered independently for more control, like so:
<script>
import { LCCustomFieldFormField } from '@agsci/customfield-svelte-components';
</script>
<div>
<form>
{#each formField in formData, (formField.id)}
LCCustomFieldFormField bind:formField>
{/each}
<input type="submit">
</form>
</div>
REPL
Here's a live example
Styling
The form and fields currently use Bootstrap 5 class names for styling, (which provides some default style options). It also provides the following class names that can be used to customize the styling:
<div class="mb-3">
<div class="lc-cf-formfield">
<label class="lc-cf-control-label"> </label>
<input class="controls lc-cf-component-[R|C|T...]" />
</div>
</div>
The inputs can be styled together using the controls
class, or you can style each component type distinctly
using the lc-cf-component-X
classname.
The radio and checkbox widgets are nested in one more level of divs and follow the Bootstrap 5 pattern, where
the <label>
and <input>
tags are siblings rather than nested.
Changelog
- v0.0.7 Sep 2 2023. Small update to formatting
- v0.0.6 Aug 22 2023. Updated dependencies to allow installation without --force
- v0.0.5 Aug 17 2023. Updated checkbox component to be reactive to changes in data packet.
- v0.0.4 Aug 6 2023. Updated index.js to allow for proper imports into other projects.
- v0.0.2 Aug 3 2023. Bugfixes so that checkbox and multiselect are now working better.
- v0.0.1 Aug 2 2023. First commit
Contributors
Aditya Shukla, EC Infosolutions. Kaustubh Bhalerao, AgSci LLC Chetan Bawankule, EC Infosolutions.