VTable has been deprecated, which means it will not be updated, and support and maintenance are no longer provided.
VTable is a dynamic user interface designed to handle data from Master Data v2 directly from VTEX Admin. It allows you to create custom applications for managing and visualizing data from documents efficiently, using JSON schemas.
To render an app in VTable you must follow these steps:
- Step 1 - Creating a JSON schema
- Step 2 - Building the app schema
- Step 3 - Validating the app schema
- Step 4 - Saving the app schema to Master Data
VTable interface displays up to 14 documents in each app. It is not possible to increase this limit, since VTable is deprecated.
Below you can also learn more about all necessary JSON schema configurations.
Step by step
Step 1 - Creating a JSON schema
First, create a data entity and a JSON schema associated with it to store data in a specific format.
You can create it with the Save schema by name endpoint. Use your JSON schema as a request body, as exemplified below.
Check the JSON schema configurations section to learn how to configure each field for your specific needs.
Example JSON schema (request body)
_35[_35 {_35 "name": "v1",_35 "schema": {_35 "properties": {_35 "email": {_35 "type": "string"_35 },_35 "firstName": {_35 "type": "string"_35 },_35 "lastName": {_35 "type": "string"_35 }_35 },_35 "v-indexed": [_35 "email",_35 "firstName",_35 "lastName"_35 ],_35 "v-default-fields": [_35 "id",_35 "email",_35 "firstName",_35 "lastName"_35 ],_35 "v-cache": false,_35 "required": [_35 "email",_35 "firstName",_35 "lastName"_35 ]_35 }_35 }_35]
Step 2 - Building the app schema
To create a VTable app, you must define a schema that specifies the data VTable will use to render a table.
The app schema you create must follow the structure indicated by the VTable app objects schema below.
For now, start with the Example app schema below and edit it according to your data.
You will validate your app schema's structure in the following step.
VTable app objects schema
_134{_134 "properties": {_134 "name": {_134 "type": "string",_134 "minLength": 1,_134 "maxLenght": 50_134 },_134 "title": {_134 "type": "string",_134 "minLength": 1,_134 "maxLenght": 50_134 },_134 "tables": {_134 "type": "array",_134 "minItems": 1,_134 "items": {_134 "type": "object",_134 "properties": {_134 "id": {_134 "type": "string",_134 "minLength": 1_134 },_134 "title": {_134 "type": "string",_134 "minLength": 1_134 },_134 "entity": {_134 "type": "string",_134 "minLength": 1_134 },_134 "model": {_134 "type": "string",_134 "minLength": 1_134 },_134 "list": {_134 "type": "array",_134 "minItems": 1,_134 "uniqueItems": true,_134 "items": {_134 "type": "string",_134 "minLength": 1_134 }_134 },_134 "editor": {_134 "type": "object",_134 "properties": {_134 "settings": {_134 "type": "object",_134 "properties": {_134 "sections": {_134 "type": "array",_134 "minItems": 1,_134 "items": {_134 "type": "object",_134 "properties": {_134 "name": {_134 "type": "string",_134 "minLength": 1_134 },_134 "fields": {_134 "type": "array",_134 "minItems": 1,_134 "uniqueItems": true,_134 "items": {_134 "type": "string",_134 "minLength": 1_134 }_134 }_134 },_134 "required": [_134 "name",_134 "fields"_134 ]_134 }_134 }_134 },_134 "required": [_134 "sections"_134 ]_134 }_134 },_134 "required": [_134 "settings"_134 ]_134 },_134 "fields": {_134 "type": "object",_134 "properties": {_134 "id": {_134 "type": "object",_134 "properties": {_134 "width": {_134 "type": "integer"_134 }_134 },_134 "required": [_134 "width"_134 ]_134 }_134 },_134 "required": [_134 "id"_134 ],_134 "additionalProperties": {_134 "type": "object",_134 "properties": {_134 "width": {_134 "type": "integer"_134 }_134 },_134 "required": [_134 "width"_134 ]_134 }_134 }_134 },_134 "required": [_134 "fields",_134 "entity",_134 "model",_134 "id",_134 "title",_134 "list",_134 "editor"_134 ]_134 }_134 }_134 },_134 "required": [_134 "name",_134 "title",_134 "tables"_134 ]_134}
Example app schema
_42{_42 "name":"users",_42 "title":"Users Admin",_42 "tables":[_42 {_42 "id":"main",_42 "title":"Users",_42 "entity":"users",_42 "model":"user-v1",_42 "fields":{_42 "id":{_42 "width":200_42 },_42 "email":{_42 "width":200_42 },_42 "firstName":{_42 "width":300_42 }_42 },_42 "list":[_42 "email",_42 "firstName",_42 "lastName"_42 ],_42 "editor":{_42 "settings":{_42 "sections":[_42 {_42 "name":"Personal Data",_42 "fields":[_42 "firstName",_42 "email",_42 "lastName"_42 ]_42 }_42 ]_42 }_42 }_42 }_42 ]_42}
You can use this example app schema as a foundation to create your own app. Check the meaning of fields in the example app schema:
| Field | Type | Description |
|---|---|---|
name | string | Name of the schema in Master Data v2. |
title | string | App title. |
tables | array of objects | List of objects containing information about the tables. |
tables[i].id | string | Table ID. |
tables[i].title | string | Table title. |
tables[i].entity | string | Table entity that corresponds to the data entity in Master Data, which must exist before creating the app. |
tables[i].model | string | Model that relates to the schema associated with the Master Data data entity. |
tables[i].fields | object | List of fields to be displayed. Each field specifies the width it occupies in the table. |
tables[i].fields.id | object | Field name. |
tables[i].fields.id.width | integer | Width of the id field. |
tables[i].fields.email | object | Field name. |
tables[i].fields.email.width | integer | Width of the email field. |
tables[i].fields.firstName | object | Field name. |
tables[i].fields.firstName.width | integer | Width of the firstName field. |
tables[i].list | array of strings | Defines the fields to be rendered in the table. |
tables[i].editor | object | Object responsible for configuring the form's rendering. |
tables[i].editor.settings | object | Form settings. |
tables[i].editor.settings.sections | array of objects | List of form sections and their respective settings. |
tables[i].editor.settings.sections[j].name | string | Setting name. |
tables[i].editor.settings.sections[j].fields | array of strings | List of fields shown in the form. |
Read the JSON schema configurations section to learn how to configure each field for your specific needs.
Step 3 - Validating the app schema
To validate your app schema, use a tool such as JSON Schema Validator, which allows you to paste the code from VTable app objects schema and the code from your app schema created in step 2 to check if the structure of your app schema is valid.
Step 4 - Saving the app schema to Master Data
To save the app schema to Master Data, send a PUT request to the Create document with custom ID endpoint, adding your app schema as the request body and filling the URL with the information below:
PUT https://{accountName}.{environment}.com.br/api/dataentities/vtable/documents/{appName}?_schema=app
Your app schema will be saved as a document in the VTable data entity.
After that, you will be able to access the app data in VTable at https://{accountName}.myvtex.com/admin/vtable/, replacing {accountName} with your VTEX account name.
JSON schema configurations
VTable parses the JSON Schema configuration and each field to a corresponding UI component. These are some examples of possible configurations:
Checkbox
Set the value of the type field as boolean to render a checkbox.
_10"approved": {_10 "type": "boolean",_10 "title": "Approved"_10}
Dropdown
Add the enum property to render dropdown options.
_10"gender": {_10 "type": "string",_10 "enum": [_10 "Male",_10 "Female"_10 ]_10}
DatePicker
Add the format property with the value date-time to render a date picker.
_10"birthdate":{_10 "type":"string",_10 "format":"date-time"_10}
TextArea
Add the type string and the property multiline set to true in the app configuration to render a TextArea field.
JSON Schema configuration:
_10"lastName":{_10 "type":"string",_10 "title":"LastName",_10 "maxLenght":250_10}
App configuration:
_10"lastName":{_10 "width":300,_10 "multiLine":true_10}
Link
The LinkControl represents the reference of one data entity to another data entity. To render the LinkControl set the properties link and linked_field where the value of link is the link to the referenced schema and the value of linked_field is the field that will be referenced.
The LinkControl lets you navigate between the related tables. For that, you need to set the properties relatedApp and relatedTable in the app configuration.
JSON Schema configuration:
_10"user":{_10 "type":"string",_10 "link":"http://api.vtex.com/{accountName}/dataentities/users/schemas/user-v1",_10 "linked_field":"email"_10}
App configuration:
_10"user":{_10 "width":300,_10 "relatedApp":"users",_10 "relatedTable":"main"_10}
TextBox
Add a string, number, or integer to render a TextBox. All properties of the JSON Schema that are used to validate the field (e.g., pattern, minLength, maxLength) will be used by VTable to validate the value of the field.
You can add a mask to the field in the app configuration to require a specific value format.
JSON Schema configuration:
_10"phone":{_10 "type":"string",_10 "maxLength":100,_10 "title":"Phone",_10 "pattern":"[0-9]{10,11}"_10}
App configuration:
_10"phone":{_10 "width":200,_10 "mask":"(99) 99999-9999"_10}
MultiOptions
Set the field type to array and define that each item must be a string to render a MultiOptions control. Each item must contain the enum property, which is an array with the possible strings for that field.
_14"nationality":{_14 "type":"array",_14 "items":{_14 "type":"string",_14 "enum":[_14 "Brasil",_14 "Argentina",_14 "Colombia",_14 "Uruguai",_14 "Chile",_14 "Paraguai"_14 ]_14 }_14},
ArrayControl
If the field type is array and the field schema does not match a special case, VTable will use ArrayControl.
_21"list":{_21 "type":"array",_21 "title":"List",_21 "items":{_21 "type":"object",_21 "properties":{_21 "productId":{_21 "type":"string",_21 "title":"ProductId"_21 },_21 "quantity":{_21 "type":"integer",_21 "title":"Qty"_21 },_21 "name":{_21 "type":"string",_21 "title":"Name"_21 }_21 }_21 }_21}
ObjectControl
Set the field type to object to render an ObjectControl field. The ObjectControl field is recursive, so it can hold another object as a property.
_36"complex":{_36 "type":"object",_36 "title":"Complex",_36 "properties":{_36 "name":{_36 "type":"string",_36 "title":"Name"_36 },_36 "age":{_36 "type":"number",_36 "title":"Age",_36 "minimum":0,_36 "maximum":100_36 },_36 "birthdate":{_36 "type":"string",_36 "title":"BirthDate",_36 "format":"date-time"_36 },_36 "innerObject":{_36 "type":"object",_36 "properties":{_36 "innerName":{_36 "type":"string",_36 "title":"InnerName"_36 },_36 "innerAge":{_36 "type":"number",_36 "title":"Idade 3",_36 "minimum":0,_36 "maximum":100_36 }_36 }_36 }_36 }_36}
To learn more, check the Master Data v2 API documentation.