• Miva Docs
• Reference Guide
• Miva 10 Flex Component

Flex Component

• Flex Component Overview
• Web Components
• Properties
• Advanced Properties
• Component Images
• Default Property Values
• Property Text Field Validation
• Using Property Values in JavaScript & Template Code
• Importing & Exporting Flex Components

The Flex Component is a brand-new way to build customer facing User Interface components for Miva, specifically to be used with Miva's Page Builder. It provides a library of admin UI components such as input, select, image pickers, etc. that developers can use to build reusable components for Miva without having to write a module and primarily allows developers to build within Javascript.

A flex component can be used to create end user website features such as hero images and sliders, text sections, promotional banners and images, embedded video or any number of other UI elements what would make up a website. Each of these components have developer defined properties which allow a non-technical Miva user to customize the content and look of each component using Miva's Page Builder tool.

The Flex Component completely changes how developers build admin user interface for Miva.

The Flex Component is made up of 5 parts:

1. Flex Configuration File (Properties, Defaults, etc)
2. JavaScript
3. CSS
4. Initialization Template
5. Instance Template

Properties - These are configurable settings for the component. They are defined by the component developer but have native UI in the Miva Page Builder so that non-technical users can add content and customize each component for their site and use case.

JavaScript - The JS associated with the Component to make any functionality work properly.

CSS - The CSS associated with the component for any required styling.

Initialization Template - Output once, on component initialization regardless of how many times the component is used on the page.

Instance Template - This is where you would have HTML/Template code that needs to be output for every occurrence (instance) of the component.

Anatomy of a Flex Component

Web Components

The Flex component is a developer tool which enables developers to build reusable UI elements faster all while providing an easy to use customer experience to customize the component for their specific content and site. While its flexible enough to output the HTML/CSS/JS in any format, we have chosen to leverage Web Components (https://developer.mozilla.org/en-US/docs/Web/Web_Components and https://web.dev/custom-elements-v1/ ) as the structure in which to output the code.

We chose Web Components for 3 reasons:

1. Leverages modern Web Technologies with broad Browser Support
2. Native Encapsulation (Multiple versions of the same component can be used on the same page without conflict of HTML, CSS, JS between each other)
3. Primary development language is JavaScript

Properties

Properties are the settings an end user will change to modify the content for each component. This includes content focused properties such as adding text to a banner, or uploading an image for a hero image on the homepage. But properties are also used to give the end user point and click ways to customize the look and feel of the component. This includes changing the component size, changes to font size, color and style among other things. There are two types of properties. Regular properties and advanced properties. They have the same functionality, but advanced properties will show in the "Advanced" tab in the Miva admin. This gives developers a way to hide non-critical properties and give priorty to others.

There are 18 core property types that can be used with the Flex Component. These 18+ property types are designed to become the building blocks of a Component. By leveraging these existing property types, as a developer, you can quickly build high quality, functional, User Interface elements in Miva with no manual HTML coding required to build each element.

There are also native validation rules you can apply to different properties such as data value types (email, phone number, etc) or min/max character counts.

The values selected/input by the customer for each property will be made available as variables to your instance of the flex component to be able to use to control the HTML, CSS or JavaScript. For example if you have a color picker component to set the background color of a part of the component, that value will be available as a variable in the JavaScript and Template Code which you can then use to set a CSS value for the background color.

Property Name	Property Type Code	JSON Example
Textbox	text	JSON Example - Textbox
Textarea	textarea	JSON Example - Textarea
Checkbox	checkbox	JSON Example - Checkbox
Radio Button	radio	JSON Example - Radio
Select	select	JSON Example - Select
Color Picker	color	JSON Example - Color Picker
Date Picker	date	JSON Example - Date Picker
Date/Time Picker	datetime	JSON Example - Date/Time Picker
Image Selector	image	JSON Example - Image Picker
Product Lookup	product	JSON Example - Product Lookup
Category Lookup	category	JSON Example - Category Lookup
Link	link	JSON Example - Link
Text/Icon Selector	selector	JSON Example - Selector
Text Editor	texteditor	Coming Soon!
Slider	slider	JSON Example - Slider
Distributed Slider	distributor_slider	JSON Example - Distributed Slider
List	list	JSON Example - List
Group Multiple Properties Together	group	JSON Example - Group

flex.json Configuration File

A flex component can be exported to a series of text files. Its gets deployed by compressing the folder as a tar.bz2 file and uploading it to the Miva admin. In the root folder of your component, you'll have a flex.json file which defines the component name, code and version as well as paths to scripts, CSS, initialization/instance templates, and properties.

flex.json Property Definitions

1. code (required) - The flex component code
2. name (required) - The flex component name
3. Version (required) - The flex version number
4. category (optional) - must be one of the following: image, image-slider, image-across, featured-product, product-carousel, category-carousel, text-utility, text-banner, image-text, video, text-editor. This is used to categorize the component in Page Builder.
5. resourcegroup_code (required) - This is the Miva resource group the CSS/JS will get output from.
6. initialization_template - Path to the initialization template. This is a .mvt text file that can contain Miva template logic.
7. images (optional) - This allows you to include images in your component that will get added to the server/store upon import.
8. instance_template (optional) - Path to the instance template. This is a .mvt text file that can contain Miva template logic.
9. properties (optional) - Array of JSON objects for the properties the component will provide in admin for the end user
10. advanced_properties (optional) - Array of JSON objects for the properties that will appear in the advanced tab
11. defaults (optional) - Object containing the default values for all properies

This file would live in the root folder that contains a src folder. Inside src would be:

1. css
2. js
3. templates

There can be more than one CSS file as well as more than one JS file.

Example CSS, JS and Templates

Property Definitions & Examples

Property definitions are all done in the flex.json configuration file. Each property will have the following required tags (in addition to type specific tags)

Code - This is the unique code to the property

Prompt - This is the text the end customer will see in the Miva admin for this property

Type - One of the types listed above. This defines what HTML element will get output

Property Type Definitions

Textbox - text

Both Text Fields and Text Areas have an optional "textsettings" object that can be defined in the property. If included it will output a Settings icon within the text box to enable advanced editing of the Text. This includes Font Size, Font Color and Text Alignment for regular text as well as focus, hover, active state.

Full Example:

Text Area (textarea)

Text Areas are able to leverage the same textsettings object defined above.

Text Area Example

Checkbox (checkbox)

Checkbox Example:

Radio Buttons (radio)

Radio Button Example:

Select List (select)

Example

Color Picker (color)

Color Picker Example

Date Picker (date)

Date Picker Example

Date/Time Picker (datetime)

Date & Time Picker Example

Image Selector (image)

Image Selector Example

Tablet/Module Responsive Image Generation

While the UI for Page Builder image component supports customers uploading their own custom images for mobile and tablet sized images, not all customers will do so. Miva has a fallback mechanism built into it, where if the tablet/mobile images are not uploaded by the customer, Miva will auto generate them based on the image sizes defined in the responsive images object for each image. This means that you'll always have a mobile and tablet image to use for the tag.

Product Lookup (product)

Product Lookup Example

This will bring up a batch modal to select a product from a list of all products in the store.

Category Lookup (category)

Category Lookup Example

This will bring up a batch modal to select a category from a list of all categories in the store.

Link (link)

Link Example

Text / Icon Selector (selector)

View a searchable list of available icons here

Text Selector Example

Icon Selector Example

Slider (slider)

Slider Example

Distributed Slider (distributedslider)

Distributed Slider Example

Group (group)

Group Example

List (list)

List properties allow you to create list of other properties that can be added or removed by the end user. An example would be a list of images used for a hero slider. Lists are supported with the following property types:

• List of Text Boxes - List Type: text
• List of Images - List Type: image
• List of Products - List Type: product
• Lists of Categories - List Type: category
• List of Color Pickers - List Type: color
• List of Date Pickers - List Type: date
• List of Date/Time Picker - List Type: datetime
• List of Links - List Type: link
• List of groups - List Type: group

Min/Max Modifiers

All lists also support min_count and max_count to limit how many of a list a user can add or remove. The following example allows a min of 3 and a max of 5

List Text Example

List of Images Example

List of Products Example

List of Categories Example

List of Color Pickers Example

List of Date Picker Example

List of Date/Time Picker Example

List of Links

List of Groups Example

Advanced Properties

When a customer is editing the property values of a component from within Page Builder in Miva, there is a default tab which contains all the core properties for that component and then there is an Advanced Tab. The goal of the advanced tab is to be able to hide less commonly used properties or more advanced properties to keep the most important content front and center.

Component Images

Its possible to package up and include image files in your component. Upon install of the flex component into a store, any images defined will get copied to the destination path specified. The source_filepath is the path of the image in the flex folder locally. The destination_filepath is where you would like the image copied on the Miva server. The default locaiton for images on a Miva store is graphics/store_id/image_name. A common use case for this could be including placeholder images for your component into the flex component file that gets imported.

Property Default Values

When creating properties for your component, its possible to set the default values that show up. This is important so that when someone adds a new component to their page, it comes set with default values as place holders which they can then modify. The default values are defined under the "defaults" object in the flex.json file. Below is an example of default values for most property types.

Text Field Validation

All text property type also have the ability to add additional validation on the type of data that can be input into the text field. The following additional field are available:

• required - true/false (defaults to false if omited) - NOTE: the required attribute is available on all property types not just text properties
• text_type - vaules include: text (default), number, email, url, password, tel
• validation_message - (Optional) Message used to display validation errors when validation using validation_pattern (below) fails
• validation_pattern - (Optional) Designate a regular expression pattern that can be used to validate the format of the input's value. Possible Values: Regular Expressions, similar to the HTML input-pattern attribute
• placeholder - (Optional) Provides a brief hint to the user as to what kind of information is expected in the field. It should be a word or short phrase that provides a hint as to the expected type of data, rather than an explanation or prompt
• label - Optional) Show a suffix/label to the right of the input ideal for displaying the units of an input. For example, a label of "px" could show after an input that collects the margin-top amount
• min/max/step
  • Optionally, when a text_type=number, min/max/step can also be defined
  • min = the minimum number/date allowed
  • max = the maximum number/date allowed
  • step = acceptible intervals within the min/max that should be provided
  • For example a text_type=number, min=0, max=1, & step=0.1 would allow users to enter: 0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8 0.9, & 1
• minlength/maxlength - when text_type=text, url, tel, email, and password, it defines the minimum/maximum number of characters the user can enter into the field

Using Property Values in JavaScript & Template Code

All the values of the properties a user has entered via the Miva admin are available in the instance template using the following structure:

The l.settings:instance is a structure containing all the property values of the component. It uses the codes you give to each property. For Example lets say we want to access the value the customer input for the subheading property

In this example "content" is the group code, and subheading is the property code. Here are some additional examples from the Video component:

Accessing Values In JavaScript

The entire l.settings:instance strcuture can be output to a JSON object which can them be used in your javascript files for your component

Flex Instances Index/Pos

The following variables are available in page templates, which grant access to the flex item, sequence item, sequence item position in its own sequence, and sequence item position in all output sequence item lists. These variables are helpful to output identifying information to the page for testing scripts, javascript tracking (google analytics impressions), A/B testing, etc

Importing & Exporting Flex Components

Flex Components cannot directly be edited via the Miva admin interface like other areas of the software. In order to modify a flex component you first need to export it which will give you a component-name.tar.bz2 file. Components can be viewed and exported under User Interface -> Flex Components

Packaging and Importing Flex Components

After you've made your edits to the flex component, you convert it back to a tar.bz2 file and import it to Miva. To do that, via command line terminal navigate inside your flex componnet folder and type: (where flex_component is the name of the file you want to create)

Once the new tar file is created you can import it back to miva under User Interface -> Flex Components ->Upload Component. Once it has been added to Miva, it will be available to any page that uses Page Builder