Try our new AI assistant by clicking the chat icon in the lower right corner.


Flex Component

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: Here is a sample configuration file for flex.json

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.

Note

The textsettings object can also be used inside the default object to set the default values

Full Example:

text settings

Example of the textsettings in the Page Builder User Interface

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

Note

If serverdate is set to false or omitted, the clientside timezone is used. If the browser timezone is different than server, UTC time is displayed to normalize the date/time.

Date/Time Picker (datetime)

Date & Time Picker Example

Image Selector (image)

Image Selector Example

Note

The responsive_images object is optional but recommended. If used and custom images are not uploaded by the client, Miva will generate the proper image sizes which can then output in the picture element so the correct sized image always outputs.


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)

Text/Icon Selector

The icon values must match the name using the MivaIconMap in admin/ui.js


View a searchable list of available icons here


Text Selector Example

Icon Selector Example

Slider (slider)

Flex Slider

use -1 for scale and percision for defaults. label is optional


Slider Example

Distributed Slider (distributedslider)

Distributed Slider

The breakpoints are calculated as a value between 0 and 100 steps divided by the number of breaks


Distributed Slider Example

Group (group)

Group Closed

A group is just a container for other properties and a way to organize the properties on the screen logically. A group is collapsable and can have an optionally enable/disable toggle

Group Open

Group when active and expanded. A group can contain any of the other properties.


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:

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 of Text Boxes

Lists of text boxes can be expanded or collapsed as well as reordered. You can also add new text boxes or delete them. The template object defines the default value the the "Add New" link is clicked.


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

Note

Lists of Groups have a "item_prompt_property" property which is used to tell the outer list what property to use for the display (ie, you change this field in the inner group, set the title of the list entry to that value)

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.

Default Component Properties Tab

Default Tab for Component Properties


Advanced Component Properties Tab

The location of the properties is up to the component developer but in general more advanced or less used properties should live under the Advanced Tab


Note

Advanced Properties will be defined under the "advanced_properties" object. To set the default values for Advanced properties there is a "advanced" object inside the "defaults" object.

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.

Note

There is an optional %STORE_ID% placeholder value you can use in the destination path which will get replaced with the actual store id (ex: 00000001) upon import.



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:


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

Subheading Example

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

Flex Component Download

Select a flex component you wish to downlaod from the batch list and click "Download" This will download a component-name.tar.bz2 file which you can extract and edit locally


Folder Structure

Once Extracted, all the files can be edited locally


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)


Note

Make sure you run this command from inside the component folder. Don't forget the end period which will include all files in the current folder.

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

Looking for Developer Docs?

We have a whole section for that, including: Developer Training Series, Template Language docs, Module Development tutorials and much, much more.

Head to the Developer Section

This website uses cookies to identify visitors, track visitors to our website, store login session information and to remember your user preferences. By continuing to use this site you agree to our use of cookies. Learn More.

This website uses cookies. By continuing to use this site you agree to our use of cookies. Learn More.

Accept

Copyright © 1997 – 2021 Miva©, Miva Merchant©, MivaPay©, MivaCon© Miva, Inc. All Rights Reserved.