Store Morph Technology (SMT) - Working with Page Templates

Miva Merchant, with Store Morph Technology™ (SMT), provides full control over the contents and layout of each store page. SMT page templates define the appearance of each page, and control the functionality. You can add new components to a page, or remove components that aren't needed, to create an entirely new store interface.

Working with these templates is much like creating Web pages. Familiar HTML (HyperText Markup Language) code can be used, including text, links, tables, lists, and so on. Experienced Web designers will be immediately comfortable with the structure of template code.

Along with ordinary HTML code, templates take advantage of dynamic SMT items and entities — representative snippets of code that display customized formatting or content on the page.

All the design features you may already be familiar with from earlier versions of Miva Merchant are still available including global, category, and product headers and footers, the navigation bar, colors and fonts, buttons, and product and category images. SMT tools further enable you to further fine–tune the look and functionality of your store.

Where to Find Examples

The best set of page template examples is right in your own store administration interface. Each page in the store is defined by a template that you can edit. To work with your own page templates expand the menu for the store, in the left navigation area. Click Pages. You will see a list of all the pages that make up the store. To examine one of these pages and see the template code, click Edit, to the right of the page name.

On the Edit Page screen you will see several tabs. For those tabs where the template code can be manually edited (the BODY Tag tab), click Advanced Mode at the bottom of the screen to work on the code directly.

Making Changes and Recalling Versions

If you save any changes by clicking Update, they will be saved to the version history for that page. You can include notes to name each version. If you are not happy with the results of a change you make you can Recall any other version even going all the way back to the original. If you select Clear History only the current state and the original will be saved—all intermediate versions will be lost. For more information see Working with Version History.

Page Templates

Each page template can have text, HTML tags, item tags for items that are assigned to the page, and entities from items that are assigned to the page.

Structure of a Page Template

When you look at existing pages templates under Pages in the store administration interface, you will notice that there is something special about the body tag, instead of the usual HTML form, the body of the page is enclosed as follows:

We will discuss more differences between ordinary HTML and the added power of Store Morph Technology as we look in greater detail at the contents of templates.

Contents of a Page Template

A Miva Merchant page template could include nothing more than plain HTML code. You might create a page displaying directions to your warehouse and a map. But if you want the page to use design elements and settings that are specific to your store. Miva Merchant SMT makes that easy to accomplish.

You control what information is displayed and its appearance through the use of entities and items.

SMT Item Tags

An item is a single user interface element or a collection of elements that make up a distinct part of the store interface.

Items look like HTML tags. Each one has a name and sometimes a parameter. Then entire item can be used or just one aspect of it. Then the entire item is used no parameter is necessary. When just one aspect is being used the parameter specifies which one it is.

The navigation bar is an item as is the product display area or the shopping basket. Putting the item <mvt:item name="navbar" /> into a page template will display the navigation bar.

The sets of store fonts, store colors, and store buttons are also items. The <mvt:item name="fonts" param="body_font"> refers to the font specified in your store body text, under Edit Store / Fonts. When the face, size, or color is changed via that screen, the font changes anywhere a template uses this item.

Technical comment, for those who are interested: These SMT items are SGML tags with the namespace prefix of "mvt".

Like in HTML, there are two types of template language item tags: container tags, and empty tags. Container tags enclose content between an opening tag and closing tag, while empty tags carry information within the tag itself.

Open/Close or Container Tags

You are familiar with these tags from HTML. Common container tags in HTML are those used for formatting the display of text, like to italicize the contents, or to display the contents in boldface type. For example:

Likewise, in page template language, you would format text in the store body font like this:

In both plain HTML and page template language, the tags can be on the same line, or separate, whichever you prefer.

Empty Tags

Empty tags stand alone, and do not enclose other information. Common empty tags in HTML are the line break tag, , the horizontal rule tag <hr>, and the image tag <img src="bigtree.jpg" alt="Photo of a big tree">

Empty tags in page template language display information or provide a function. You would insert a navigation bar on a page like this:

While it is common in HTML to omit the slash character before the closing angle bracket, the page template language is more strict. Empty item tags require the slash to be present, as shown in the example above.

SMT Entities

An entity is a bit of text that will be replaced with a single piece of information, like the store name, or the same color as the category tree background. It is similar to a variable or token. When the information is changed for the store, any place an entity uses that information will reflect the change.

Entities start with an ampersand (&), and end with a semicolon. The first part, &mvt, tells us this is a Miva Merchant page template entity. The middle part, like store or colors, tells us what part of the store interface is being referenced. The last part, like name, or lhdr_bg, gives the specific piece of information to use from the specified area of the interface.

The entity &mvt:store:name; will display the name of the store. One place this entity is used at the top of the storefront page (page code SFNT). Remember that the store item must be assigned to the page before entities from it can be used there.

In another case, on the Checkout Shipping/Payment Selection page (page code OSEL), on the Basket Contents tab, the entity &mvt:colors:lhdr_bgt; defines the background color of a table column like this: <td align="left" valign="middle" bgcolor="&mvt:colors:lhdr_bg;">. When the list header color is changed in the usual way, via the administration interface, background color of this table column will be changed along with it.

Entity Syntax

Entities start with &mvt, and can have an optional additional character, either an e, or a, for entity encoding or attribute encoding, respectively.

Entities beginning with &mvt are replaced directly in the HTML code with the information they represent. So in bgcolor="&mvt:colors:lhdr_bg;", the entity would be replaced with the actual list header color number in hex, giving bgcolor="#000080".

Entities beginning with &mvte are "entity encoded". Their values will be formatted to appear on the screen, with any special characters being displayed verbatim ("as is"), rather than being interpreted according to their special meaning. If the entity you want to display includes the "<" character ("less-than" sign), entity encoding will cause that character to appear, unchanged, on the screen, rather than being interpreted as the beginning of an HTML tag.

Entities beginning with &mvta, are "attribute encoded". That is, their values will be formatted so they can be included in a URL, with any special characters being transformed into characters that can be understood by a web browser. For instance, you have probably seen attribute-encoded characters in URLs, such a space characters that are represented as %20. When a category name, for instance, is to be included in a URL, and may contain characters that would require this special formatting, use &mvta.

A Simple Example Using an entity

In ordinary HTML code, you would typically specify the background color for a table cell explicitly, like this:

With Miva Merchant page templates, you can use colors from elsewhere in the store, so that the look of each page updates when the store colors are changed. This snippet of code illustrates how the same color as that used for active links is used as the background color for a table cell:

Control Statement Tags

Control statement tags specify the order in which the code should be executed, or if it should be executed at all.

Making Decisions

The if statement in template code can be used alone or with an else statement. In either case, a closing tag must be used.

If the expression is true or non-zero the code between the <mvt:if> and </mvt:if> will be executed and displayed in the store. For example, from the Search Results page if text was entered for a search this will display either a message ("No products matched your search criteria") or will display the products found in the search results:

The following bit of code checks for an image to use as the category title. If an image exists, it will be displayed, with the category name as the alt text. Otherwise, the category name will be displayed in the store header font:

The expressions in <mvt:if> statements can use a variety of operators to compare or evaluate numbers or strings of characters.

Stepping Through Collections of Things

The foreach statement gives you a way to step through a collection of things, one by one, handling each one the same way. On the Category Display page each of the products in the category is displayed. For each product the image, name, code, and price might be displayed.

These collections of things - products in a category, items in a basket, related products, and so on - are stored in arrays. We step through these arrays by referencing a single key piece of information. So we would step through the items in a basket item-by-item or the products in a category product-by-product. The key piece of information is called the iterator.

So on the Basket Contents page, under the Basket Contents tab, the information about each item in the basket is displayed by code with the following form:

Stopping When Nothing Further is To Be Done

This empty tag causes the code to exit from the current process rather than continuing through the rest of the code on the page. It might be used, for instance, when the customer's basket is empty and it is not necessary to go through all the steps to display the items in the basket. The snippet of code below is the same as that in the example for <mvt:if> except that we have inserted an exit statement (highlighted) in the code that will be executed if the basket is empty.

Operators

Operators in the page template language are only used as part of <mvt:if> statements.

Operators in SMT Template Language are generally written in all capital letters as you will see in the examples below. You could use lower–case letters as well, they will work the same, but you will find your page templates are easier to read if you follow the convention of using capital letters for the operators.

Comparison Operators

Evaluates to 1 (true) when the expression on the left is equal to the expression on the right.

Evaluates to 1 (true) when the expression on the left is greater than the expression on the right.

Evaluates to 1 (true) when the expression on the left is less than the expression on the right.

Evaluates to 1 (true) when the expression on the left is not equal to the expression on the right.

Evaluates to 1 (true) when the expression on the left is greater than or equal to the expression on the right.

Evaluates to 1 (true) when the expression on the left is less than or equal to the expression on the right.

Logical Operators

These operators are used with 'true' or 'false' expressions in <mvt:if> statements.

NOT - Logical NOT

Evaluates to 1 (true) when the expression is false. This logical operator works with a single expression rather than comparing two expressions (that is the NOT operator is unary).

NOT can be used in conjunction with ISNULL to determine the existence of a value. In this snippet of code from the Invoice page under Order Contents information about product attribute options will be displayed if it exists. If there are no options just the attribute code will be displayed:

<mvt:if expr="some_expression"> will evaluate to false if some_expression is either null or zero, whereas <mvt:if NOT ISNULL expr="some_expression"> will evaluate to false only if some_expression is null (has no value) and true if some_expression has a value of zero.

AND - Logical AND

This would be true if both expressions are true. You might create a feature in your store so that a special message is shown when a shopper is logged into their customer account and has more than a certain number of items in their basket.

OR - Logical OR

Text String Operators

The page template language also supports a number of built–in string functions as part of <mvt:if> statements. These will be familiar to you if you already know MivaScript.

For example 'apple ' $ 'pies' would result in 'apple pies'. Note that the space between the words was originally included at the end of the first string. So 'sun' $ 'flower' with no spaces in either string would become 'sunflower'.

For simply displaying several entities on the screen with or without additional text you can use ordinary HTML with the entities inserted where needed. You do not need to use the $ operator. At the top of the storefront screen (SFNT) you would normally see the name of the store and possibly other information. Refer to the page template for the Product Display page as an example. At the top of the template you will see:

This will cause the store name and product name to appear near the top of the screen with a colon between them:

IN/CIN - Beginning position

See the table below which illustrates the differences and similarities between IN, CIN, EIN, and ECIN.

Returns the beginning position of the first instance, from left to right, of expr_a contained in expr_b.

For example 'da' IN 'Canada' returns 5 because 'da' begins at the fifth letter in 'Canada'.

If there is no match within string_b for the sub-string given by string_a both IN and CIN will return 0 (zero). This can be used to check for the presence of a given character in a string in any position. We could check for the '@' character as a way of confirming that the shopper entered a complete e-mail address:

The IN operator is case-sensitive. It will find a match only if the sub-string has the same case (upper or lower) letter-by-letter. So 'at' IN 'Cat' would return 2, but 'at' IN 'CAT" would return 0 (zero).

The CIN operator is case-insensitive. It will find a match if the letters are the same regardless of case (upper or lower). So 'at' CIN 'Cat' or 'at' CIN 'CAT" would both return 2.

If you use literal strings (as opposed to SMT entities) in this expression you have to surround them with single quotes.

EIN/ECIN - End position

Also see the table below which illustrates the differences and similarities between IN, CIN, EIN, and ECIN.

For example, 'dia' IN 'canadian' returns 7 because 'dia' ends at the seventh letter in 'canadian'.

Note that although these operators find the end of the sub-string both search starting from the beginning (left-hand end) of the string. So 'na' EIN 'banana' would return 4 not 6.

The EIN operator is case-sensitive. That is it will find a match only if the sub-string has the same case (upper or lower) letter-by-letter. So 'at' EIN 'Cat' would return 3, but 'at' EIN 'CAT" would return 0 (zero).

The ECIN operator is case-insensitive. That is it will find a match if the letters are the same regardless of case (upper or lower). So 'at' ECIN 'Cat' or 'at' EIN 'CAT" would both return 3.

Note that if you use literal strings (as opposed to SMT entities) in this expression you have to surround them with single quotes.

Table Comparing IN/CIN and EIN/ECIN Operators

Arithmetical Operators

7 MOD 3 would be 1, because 3 goes into 7 two times, with 1 remaining. Likewise, 9 MOD 3 would be 0 because 9 is evenly divided by 3, with no remainer.

In a real–world example we can display products on the category page three to a row with a horizontal rule between each row. The modulo operator is used to determine whether or not we are at the end of a row of three products. When stepping through an array, in a foreach loop, the current position in the array is given by the pos1 variable. So here we check after displaying each product to see if the number of products displayed is evenly divisible by 3. If it is we end the current row and create a new row containing with a single three-column-wide column with a horizontal rule in it, end our new row, and begin a fresh one to display the next three products.