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:
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.
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.
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:
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.
|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
This file would live in the root folder that contains a src folder. Inside src would be:
There can be more than one CSS file as well as more than one JS file.
Example CSS, JS and Templates
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
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.
The textsettings object can also be used inside the default object to set the default values
Example of the textsettings in the Page Builder User Interface
Text Areas are able to leverage the same textsettings object defined above.
Text Area Example
Radio Button Example:
Color Picker Example
Date Picker Example
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 Example
Image Selector Example
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.
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
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 Example
This will bring up a batch modal to select a category from a list of all categories in the store.
Values for default_type. If omitted, will default to URL which is a open text field to type in a URL.
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
use -1 for scale and percision for defaults. label is optional
The breakpoints are calculated as a value between 0 and 100 steps divided by the number of breaks
Distributed Slider Example
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 when active and expanded. A group can contain any of the other properties.
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:
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
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
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)
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 Tab for Component Properties
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
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.
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.
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.
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.
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:
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:
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
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
Once Extracted, all the files can be edited locally
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)
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