📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.
The Store Form app provides blocks responsible for displaying a user form connected to Master Data through a JSON schema.
⚠️ Before configuring the Store Form block in your theme, make sure you have already configured a JSON schema in Master Data. Otherwise, the customer form will not be saved appropriately. To learn more, please refer to Creating forms for your store users.
-
Add the
store-form
app to your theme dependencies in themanifest.json
. For example:"dependencies": { "vtex.store-form": "0.x" }
Now, you can use all blocks exported by the store-form
app. See the full list below:
-
In any desired store template, such as the
store.product
, add theform
block. In the example below, the form block is contained in a Flex Layout row:{ "store.product": { "children": [ "flex-layout.row#product-breadcrumb", "flex-layout.row#product-main" "flex-layout.row#form", "shelf.relatedProducts", "product-reviews", "product-questions-and-answers" ] }, ... }
-
Then, declare the
form
block. Remember to specify whichentity
andschema
from Master Data should be fetched to build the block.
{
"flex-layout.row#form": {
"children": [
"flex-layout.col#form"
]
},
"flex-layout.col#form": {
"children": [
"form"
]
},
"form": {
"props": {
"entity": "clients",
"schema": "person"
}
}
}
ℹ️ If the
form
block does not have any children configured, a default form will be rendered automatically based on the JSON schema in Master Data. This reading and interpretation of JSON schemas is facilitated by the Reacht Hook Form JSON Schema library, which supports the Store Form blocks logic behind the scenes.
Prop name | Type | Description | Default value |
---|---|---|---|
entity |
string |
undefined |
|
schema |
string |
undefined |
- If desired, complete the
form
block by adding and configuring an array of children blocks. You can use the blocks listed in the first table stated above. For example:
"form": {
"props": {
"entity": "clients",
"schema": "person"
},
"children": [
"rich-text#formTitle",
"form-input.text#firstName",
"form-input.text#lastName",
"form-field-group#address",
"form-input.checkbox#agreement",
"form-submit"
],
"blocks": ["form-success"]
},
"form-success": {
"children": [
"rich-text#successSubmit"
]
},
"rich-text#successSubmit": {
"props": {
"text": "Succesfully submitted the data!",
"textAlignment": "CENTER",
"textPosition": "CENTER"
}
},
"form-input.text#firstName": {
"props": {
"pointer": "#/properties/firstName"
}
},
"form-input.text#lastName": {
"props": {
"pointer": "#/properties/lastName"
}
},
"form-input.checkbox#agreement": {
"props": {
"pointer": "#/properties/agreement",
"label": "Do you agree that this is the best form component in the whole wide world?"
}
},
"form-field-group#address": {
"props": {
"pointer": "#/properties/address"
}
},
"form-submit": {
"props": {
"label": "Submit"
}
}
Prop name | Type | Description | Default value |
---|---|---|---|
placeholder |
string |
Placeholder for the text area input. | undefined |
Prop name | Type | Description | Default value |
---|---|---|---|
pointer |
string |
form-field-group block, the path must not include a schema's sub-property, only a schema's property. |
undefined |
accept |
string |
*.TYPEFILE . Learn more about the accept field. |
uiSchema
object:
const UISchema = {
type: UIType,
properties: {
// Note that the definition is recursive
childName: { UISchema },
childName: { UISchema },
// ...
childName: { UISchema },
},
};
Where childName
should be replaced for the desired sub-property name and the UIType
should be replaced for one of the following values:
default
: Will consider theform-field-group
own logic (e.g. using the React Hook Form JSON Schema library) for block rendering;radio
: The sub-property will be rendered as aform-input.radiogroup
block.select
: The sub-property will be rendered as aform-input.dropdown
block.input
: The sub-property will be rendered as aform-input.text
block withinputType
set toinput
.hidden
: The sub-property will be rendered as aform-input.text
block withinputType
set tohidden
.password
: The sub-property will be rendered as aform-input.text
block withinputType
set topassword
.textArea
: The sub-property will be rendered as aform-input.textarea
block.checkbox
: The sub-property will be rendered as aform-input.checkbox
block.upload
: The sub-property will be rendered as aform-input.upload
block.
The JSON schema created in Master Data is responsible for informing the form blocks about the data they should receive. It specifies the type of input expected for each form field from users.
When the user clicks the Submit
button, the form blocks retrieve all input data and send it to the Schema validation. This process, which involves understanding the expected input and sending it to Master Data, is facilitated by the React Hook Form JSON schema
library working behind the scenes.
If any unexpected answer is detected, and the form blocks does not match the Schema, Master Data will be unable to create a user form, and an error message will be returned to the user.
In order to apply CSS customizations to this and other blocks, follow the instructions in Using CSS handles for store customizations.
CSS handles |
---|
form |
formLoading |
formErrorLoading |
formSubmitContainer |
formSubmitButton |
formErrorServer |
formErrorUserInput |
Thanks goes to these wonderful people (emoji key):
doruradu 💻 |
Luiz Eduardo 💻 |
This project follows the all-contributors specification. Contributions of any kind are welcome!