@stubber/form-fields v1.0.11

stubber-form-fields-pkg

How to use

git clone git@github.com:stubber/stubber-form-fields-pkg.git form-fields-pkg
cd form-fields-pkg
cp .env_dev .env
pnpm install
pnpm run dev

Quick start

Use this as a quick demo

<script>
  import { Form } from  'stubber-form-fields-pkg';

  let initial_form = {
    spec: {
      fields: {
        fullname: {
          fieldtype: "text"
        },
        gender: {
          fieldtype: "select",
          params: {
            options: [
              {
                label: "Male",
                value: "male"
              },
              {
                label: "Female",
                value: "female"
              }
            ]
          }
        }
      }
    }
  }

  let form;

</script>

<Form
  bind:form
  {initial_form}
/>

Form

• Can render a list of fields
• All fields in a form have access to the state and data of other fields in the form
• initial_form can be passed as a prop to this component to initialize the stores with some data
• All props from this component are passed down to child components

props

initial_form

• Use to initialize the form

{
  "spec": {
    "test": {
      "fieldtype": "text"
    }
  },
  "data": {
    "test": "Hi there"
  }
}

form

• use this to bind to the internal store

field_wrapper

• Use to render fields differently
• Below is the default wrapper as a guideline

<script>
	// fieldWrapper
	export let fieldcomponent;
</script>

<svelte:component this={fieldcomponent} {...$$props} />

dependencies

• Many fields require extra dependencies that you can pass via this prop

Concepts

There are a few concepts to be aware of when using this library

Field definition

This is the JSON object, primarily as it comes from the template

common settings

• name
  • always gets set to the key of the object and cannot be overwritten
• fieldtype
  • sets the field component to render in the form
  • default value is'text'
• description
  • use to describe what the field is there for
  • default value is''
• title
  • use to set the label of the field
  • default value is a human readable form of [name]
• hide_label
  • set to true if you don't want the field to show a label
  • default value isfalse
• details.keyname
  • use to set where in data to write the field value to
  • default value is [name]
• details.datapath
  • use to nest the value deeper inside data
  • default value is ''
• initvalue.default
  • use to set the value of the field if the field value is not yet set
• initvalue.override
  • use to set the value of the field regardless of if the field value is set or not
• conditions
  • use to conditionally render a field
  • array of jsonata expressions that evaluate using the fieldContext
  • default value is []

// example conditions
[
  "form.data.gender = 'male'"
]

• validations
  • use to ensure a valid field value
  • default value is {}

// example validations
{
  "is_required_validation": {
    "validationtype": "required",
    "valid_message": "Looks good!",
    "invalid_message": "This field is required"
  },
  "passes_regex_check": {
    "validationtype": "regex",
    "params": {
      "regex": "regex here"
    },
    "invalid_message": "something is wrong"
  },
  "jsonata_check": {
    "validationtype": "jsonata",
    "params": {
      "jsonata": "field.data = 5"
    },
    "invalid_message": "something is wrong"
  }
}

• fields
  • Nest multiple fields under this field
• params is where any field-specific settings are set

fieldtypes

arraybuilder

• params.new_entry_field
  • this is a fieldspec for how new entries are added to the array
  • details.keyname and details.datapath don't function in the new_entry_field

checkbox

• params.checkedvalue
  • this is the value that the field will be set to if the box is checked
  • default value is true
• params.uncheckedvalue
  • this is the value that the field will be set to if the box is not checked
  • default value is false

currency

• params.currency
  • set the currency of the field
• params.currency_whitelist
  • set array of currencies that can be selected
• params.currency_blacklist
  • set array of currencies that cannot be selected

dataindication

date

datetime

file

hidden

jsoneditor

• params.readonly
  • Shows a non-editable jsoneditor

map

multistep

note

radio

• params.options
  • set the options here

[
  {
    "label": "Red"
  },
  {
    "label": "Green",
    "value": "green"
  },
  {
    "label": "Blue",
    "value": {
      "hello": "world"
    }
  }
]

renderfield

• params.dynamic_fieldspec
  • Set the fieldspec here with values as jsonata expressions

richtext

scrollandreaddisplay

• params.displaytext
  • Set the text that should be displayed and scrolled through

section

select

• params.options
  • set the select options here

[
  {
    "label": "Red"
  },
  {
    "label": "Green",
    "value": "green"
  },
  {
    "label": "Blue",
    "value": {
      "hello": "world"
    }
  }
]

signature

telephone

text

Dependencies

The dependencies prop is used by certain fields that only function with third party services. All the optional dependencies are listed below.

• file.upload_url
  • Where files should be uploaded to (e.g. /api/file-server/upload)
• map.mapboxAccessToken
  • Access token for mapbox account
• map.mapboxStylesheetUrl
  • Stylesheet url for maps

Publishing

We use semantic-release to automate the versioning and package publishing process. To publish a new version of the package, follow these steps:

Simply make a commit with a message that follows the Conventional Commits specification, and push it to the master branch. The commit message should include a type (feat, fix, chore, etc.) and an optional scope.

For example:

# will create a new major release.
breaking: change button color to red
feat!: add new button component

# will create a new minor release.
feat: add new button component

# will create a new patch release.
fix: fix button color

See default ruleset here

force-publish