How to Store Data in Custom Blocks

What are Element Proptypes?

Element Proptypes are the different types of data that you can use when building custom Blocks using Element for the VOLT Store.

Each Element Proptype represents a data field that will be editable by the user of the custom Block in VOLT’s Site Designer.

This article will discuss each available Proptype in detail to help you understand what can be configurable as props when building custom Blocks.

“In React, we pass data to our React components as props, whether it be from another component or from the Redux store or from anywhere else. [...] The ‘prop-types’ library is used to type check data as it moves into a component. PropTypes can help us debug our code more efficiently and ensure that our code is squeaky clean before deployment.” —Jackattack in LevelUp Coding.

There are over a dozen Element Proptypes for storing various types of data, such as numbers, text, and images.

Additionally, there are a few Element Proptypes for organizing and grouping the data fields in custom Blocks.

Finally, there are optional flags (or properties) to make Element Proptypes read-only (for helper or instructional text) or private (fields that are shown to agencies, not merchants).

The complete list of Element Proptypes is found in the Element Platform Documentation.

Beyond the Basics of Building a Custom Block

This reference article is meant for readers already familiar with how to create and publish custom Blocks for the VOLT Store using Element.

If you have never done so, please read the 15-minute article “Building An Element Page Tutorial” (from the Element Platform Documentation) to learn how to make a custom Block. You may also want to watch the YouTube video playlist “Element Tutorial | VOLT Learning Center” (27 minutes runtime).

You will need authorization from Volusion to develop custom Blocks in order to use the Element Proptypes discussed in this article. Please refer to the page “How To Get Approved To Develop Blocks” (from the Element Platform Documentation) for instructions on getting authorized.

For details on adding Element Proptypes to a custom Block, see the article How to Add Element Proptypes (from the Element Platform Documentation), which has step-by-step instructions on adding new Element Proptypes to an existing Block.

This article will discuss all available Element Proptypes including their use and configuration.

Element Proptypes Inform what VOLT Store Users Can Configure

When building custom Blocks for the VOLT Store using Element, there are a variety of different data types that you may want the user to be able to configure.

Element uses user-configurable Element Proptypes to represent different types of stored data, including boolean values, numbers, and strings.

Element Proptypes provide the data type for the props that the user of the Block can configure in VOLT’s Site Designer.

The user may want to change text, of course, but Element offers much more flexibility than that: users can edit images, colors, dates, and much more in custom Blocks.

Element Proptypes can be used to allow custom styles to be applied to custom Blocks. An example would be allowing the user to change the style of font used in the Block, as discussed in previous articles on setting font size and changing font faces in custom Blocks.

The following article explains the various Element Proptypes available, so that you can build new custom Blocks mixing whichever combination of Proptypes will work best for your project.

As mentioned previously, the list of all Element Proptypes is available in the Element Platform Documentation. That list includes a screenshot of how every Element Proptype is displayed in VOLT’s Site Designer as well as instructions for what to include in the /src/configs.js file in order to use the Proptype.

Every Element Proptype in this article links back to its documentation in that list for reference.

Summary of Element Proptypes

Element Proptypes give configuration control to the end user, allowing the user to choose data without needing the developer to submit changes to the custom Block.

Element Proptypes belong to one of six categories: data primitives, user selectors, text editors, VOLT Store products, nested data, and organizational helpers.

Primitive Data Proptypes: Booleans, Numbers, and Strings

User Selector Proptypes: Colors, Dates, Images, and Sliders

Text Editor Proptypes: Rich Text Editors

VOLT Store Proptypes: VOLT Store Products

Nested Data Proptypes: Arrays of Proptypes

Organizational Proptypes: Organizational Helpers

Combining these Proptypes provide the user of your custom Block (or several Blocks together in a Theme) with powerful developmental flexibility for configuring the VOLT Store.

Code examples for Element Proptypes

In the next section, each Element Proptype is given with an example of a custom Block using that Proptype in the /src/Block.js file and/or the /src/getStyles.js file.

For the “category” and “product” Proptypes, which are used for retrieving product data from the VOLT Store, examples are provided for the /src/getDataProps.js file.

At times, the /src/configs.js file is shown if it is relevant to working with the PropType.

Primitive Data Proptypes: Booleans, Numbers, and Strings

The “bool” Proptype

The “bool” Proptype is a true-or-false JavaScript boolean value. It is useful for making certain things optional, like whether or not to include a button call-to-action in a custom Block.

const Block = (props) => {
const { bool } = props
return (
<div>
{bool && <p>It was true</p>}
{!bool && <p>It was false</p>}
</div>
)
}

export const getStyles = (blockConfig) => {
const { bool } = blockConfig
return {
example: {
fontWeight: bool ? "bold" : "normal",
},
}
}

The “number” Proptype

The “number” Proptype stores a numeric value as a JavaScript number. It can accept integers or decimal values, and it can be useful for configuring custom CSS styles, such as font size.

const Block = (props) => {
const { number } = props
return <div>{number} is a terrific number</div>
}

export const getStyles = (blockConfig) => {
const { number } = blockConfig
return {
example: {
fontSize: `${number}rem`,
},
}
}

The “string” Proptype

The “string” Proptype holds arbitrary text in the form of a JavaScript string. It is useful not only for holding any type of text used in the Block, including headings and also URLs for links.

const Block = (props) => {
const { string } = props
return <div>{string}</div>
}

export const getStyles = (blockConfig) => {
const { string } = blockConfig
return {
example: {
fontSize: string,
},
}
}

User Selector Proptypes: Colors, Dates, Images, and Sliders

The “color” Proptype

The “color” Proptype provides the user with a color picker tool in VOLT’s Site Designer that will save the selected color in rgba format. This is useful for picking text and background colors.

export const getStyles = (blockConfig) => {
const { color } = blockConfig
return {
example: {
color: color,
},
}
}

The “date” Proptype

The “date” Proptype offers a date picker tool in VOLT’s Site Designer that will save the selected date as a JavaScript Date object. It is useful for including a date in a custom Block for any reason. For example, you may want to advertise an upcoming sale that starts on a certain date.

const Block = (props) => {
const { date } = props
return <div>Sale starts {date.toLocaleDateString()}</div>
}

The “dateRange” Proptype

The “dateRange” Proptype offers another date picker tool in VOLT’s Site Designer, one that allows a selection of two dates. The selected date will be saved as an array containing two JavaScript Date objects, the start date and the end date. The date range selector is useful for showing a custom Block only between certain dates, such as to show a Block during a sale.

const Block = (props) => {
const { dateRange } = props
const [startDate, endDate] = dateRange
const now = new Date()
return now > startDate || now < endDate ? (
<div>During the sale</div>
) : (
<div>Not during the sale</div>
)
}

The “slider” Proptype

The “slider” Proptype creates a drag-and-drop slider oriented horizontally or vertically. The slider lets the user conveniently assign a numeric value from a designated range when editing the custom Block in VOLT’s Site Designer. It can be used to control font size, for example. The slider’s selected value is saved as a number, in the slider.selectedValue prop, as shown here.

export const getStyles = (blockConfig) => {
const { slider } = blockConfig
const sliderValue = slider.selectedValue
return {
example: {
fontSize: `${sliderValue}rem`,
},
}
}

Text Editor Proptypes: Rich Text Editors

The “editorFull” Proptype

The “editorFull” Proptype provides a rich text editor (also known as a WYSIWYG editor) for use inside VOLT’s Site Designer. The user will have the ability to change headings or font styles for the text in the custom Block, then the rich text is saved as HTML markup inside of Element.

In React, the method to change the HTML markup contained inside a DOM element (Element.innerHTML) is called dangerouslySetInnerHTML (for reasons that are explained here).

(Note that the rich text editor used by the editorFull Element Proptype does not allow <script> tags, so the user cannot run their own JavaScript, in what is called cross-site scripting or XSS.)

The dangerouslySetInnerHTML method allows you to insert the HTML saved from the rich text editor created by the editorFull Proptype. The editorFull Element Proptype returns html as text, such as <h1>Heading</h1>, so it needs to be converted into proper HTML markup by React.

To do so, React requires an object with the __html property to mark it as HTML, as shown below.

const Block = (props) => {
const { editorFull } = props // Rich text (HTML)
const outputAsMarkup = { __html: editorFull }
return <div dangerouslySetInnerHTML={outputAsMarkup}></div>
}

The “editorMinimal” Proptype

The “editorMinimal” Proptype works equivalently to the editorFull Proptype. The difference is that the editor provided to the user in VOLT’s Site Designer has minimal features. This is useful for offering some customization options to the user but not as much control as the full text editor.

const Block = (props) => {
const { editorMinimal } = props // Rich text (HTML)
const outputAsMarkup = { __html: editorMinimal }
return <div dangerouslySetInnerHTML={outputAsMarkup}></div>
}

VOLT Store Proptypes: VOLT Store Products

The “category” Proptype

The “category” Proptype offers a dropdown menu that allows the user of the custom Block to select a category. The prop’s value will be the ID of the selected category.

For details on the getByCategoryID method used below, please refer to the Element SDK documentation.

const Block = (props) => {
const { data } = props
const products = data.items
return (
<ul>{products && products.map((product) => <li>{product.name}</li>)}</ul>
)
}

export const getDataProps = (utils, props) => {
const { category } = props
return utils.client.products
.getByCategoryId({ categoryId: category, sort: "name a-z" })
.then((data) => data)
.catch((e) => console.log(e))
}

The “product” Proptype

The “product” Proptype offers a dropdown menu so the user of the custom Block can select an individual product. The prop’s value will be the ID of the selected product.

For details on the getByID method used below, please refer to the Element SDK documentation.

const Block = (props) => {
const { data } = props
const product = data
return <div>{product.name}</div>
}

export const getDataProps = (utils, props) => {
const { product } = props
return utils.client.products
.getById(product)
.then((productObject) => productObject)
.catch((e) => console.log(e))
}

Nested Data Proptypes: Arrays of Proptypes

The “arrayOf shape” Proptype

The “arrayOf shape” Proptype allows you to create a JavaScript array composed of shapes, which are simply a defined combination of different Element Proptypes.

The user of the VOLT store is provided a dropdown menu of these shapes, with the ability to add items to the list from within VOLT’s Site Designer.

An example of an “arrayOf shape” would be a list of links, containing two “string” Proptypes for the link URL and the link text, as shown below.

const Block = (props) => {
const { arrayOfShapes } = props
return (
<ul>
{arrayOfShapes.map((link) => (
<li>
<a href={link.url}>{link.text}</a>
</li>
))}
</ul>
)
}

export const configSchema = {
arrayOfShapes: {
label: "Array of Links",
type: ElementPropTypes.arrayOf(
ElementPropTypes.shape({
text: { label: "Text", type: ElementPropTypes.string },
url: { label: "Link", type: ElementPropTypes.string },
})
),
},
}

The “oneOf” Proptype

The “oneOf” Proptype creates a dropdown menu from a JavaScript array of arbitrary items, which can be of strings, numbers, boolean values, or some other data.

For example, an array of strings can allow the user to select text alignment, as shown below.

export const configSchema = {
oneOf: {
label: "Dropdown Menu for Text Alignment",
type: ElementPropTypes.oneOf(["left", "center", "right"]),
},
}

export const getStyles = (blockConfig) => {
const { oneOf } = blockConfig
return {
example: {
textAlign: oneOf,
},
}
}

Organizational Proptypes: Organizational Helpers

The “isPrivate” Proptype

The “isPrivate” Proptype is simply a boolean flag that can be added to any other Element Proptype definition in the /src/configs.js file. A private Proptype is only shown to agency accounts, but not to merchant accounts using that custom Block in the VOLT Store.

export const configSchema = {
privateString: {
label: "Won't be shown to merchants, but agency accounts can see it",
type: ElementPropTypes.string,
isPrivate: true,
},
}

The “readOnly” Proptype

The “readOnly” Proptype is informational text that is shown to the user when editing the custom Block in VOLT’s Site Designer. Its purpose is to offer instructions, and it cannot be modified.

Unlike the “sectionHeader” Proptype, discussed next, an empty label is recommended for the “readOnly” Proptype, as shown below.

Without specifying an empty label property, the “readOnly” Proptype will include the name of the prop as a label by default.

In comparison, the “sectionHeader” Proptype does not include any label by default.

export const configSchema = {
readOnly: {
label: "",
type: ElementPropTypes.readOnly,
},
}

export const defaultConfig = {
readOnly: "Text when this Block is edited in VOLT's Site Designer",
}

The “sectionHeader” Proptype

The “sectionHeader” Proptypes are simply headings that will appear when the custom Block is being edited in VOLT’s Site Designer. These straight-forward organizational headings help to organize the display of the configuration settings for your custom Block into sections.

export const configSchema = {
sectionHeader: {
type: ElementPropTypes.sectionHeader,
},
}

export const defaultConfig = {
sectionHeader: "Heading when this Block is edited in VOLT's Site Designer",
}

Conclusion

Element is the powerful and flexible framework for building custom Blocks for the VOLT Store. Being able to use multiple Element Proptypes in the same Block is one of the key features that provides VOLT with its superb developmental flexibility.Built-in color pickers, rich text editors, sliders, dropdown menus, and section headings are just some of the Element Proptypes available for use in your custom Block.

This article provides a detailed explanation of each Proptype available for use in VOLT. The goal of using Proptypes is to allow the user of the custom Block the ability to customize your Block to best fit their VOLT Store.For example, your end user may want the ability to choose font and background colors, alter text alignment with a dropdown menu, or change font size with a slider. Element Proptypes allows you to create custom Blocks that dynamically change CSS style properties based on user input. Proptypes also allow you to store images, dates, and rich text for display in custom Blocks. Using Element Proptypes in custom Blocks can empower the end user the ability to customize the look and feel of the VOLT Store using VOLT’s Site Designer, without the developer of the custom Block needing to change any configuration.