Introduction

Thanks for purchasing Stack HTML template by Medium Rare. This documentation will give you an overview of the template's main features and how they can be customised to suit your requirements. This guide assumes basic knowledge of HTML and CSS.

We have endeavoured to make this documentation as comprehensive as possible but understand that at times, you many need to contact us for additional support. You can reach out for this support by opening a ticket at our dedicated forum on
Ticksy. You will need your purchase code in order to signup, you can find this
here.

Using an HTML template

Stack is an HTML template - this means that all domain and hosting should be organised by you.

F.A.Q

What do I need to upload to my server?

You'll need to upload all HTML files along with all directories (css,js,mail,video,img) in the structure that they appear in your download package. That is, all HTML files should reside in the root directory, and all other files should reside inside their associated folder.

Should I upload the Variant folder?

No, you don't need to upload the Variant folder - the builder works offline and does not require a server to function.

I uploaded the pages, but they look strange and bare

This is usually a result of the CSS folder not being uploaded correctly. Ensure the CSS folder is uploaded in the same directory as your HTML files so they have correct access.

Where should I add my CSS style changes?

Ensure that you only make style changes inside custom.css. This will make it much easier to update the template later - you'll only need to preserve your custom.css file.

element.class

A reference to an element by
tag followed by a
class to distinguish its primary purpose.

div.modal-contentmeans a div element with
classmodal-content

<div class="modal-content">
...
</div>

a.inner-linkmeans an a (link) element with
classinner-link

<a class="inner-link" href="#top">
Back to Top
</a>

i.icon.icon--smElements can have multiple classes, so this is an i (icon) element with two
classesicon and icon--sm

<i class="icon icon--sm">

Setting Global Options

Plugins usually offer a wide range of settings which can be configured by passing in an object when initialising the plugin. These often include translation options for buttons such "previous", "next" in a wizard, or options for formatting text such as for the
countdown plugin.

Due to the nature of Stack as an HTML template, our predefined scripts file comes ready with a configuration that will suit most users, but only provides a subset of the available options. Translation options are not always available to the user through the common data attributes mentioned here in the documentation.

In order to address this shortcoming, we've implemented a system by which you may provide a full array of supported options for some plugins in a custom scripts file, loaded before the main scripts.js file. This alleviates the need to customise scripts.js and means you can keep your customisations separate, which means less to worry about when updating scripts.js.

Features listed in this documentation which support global options will include a section on setting global options, detailing which options can be set and how they override other options such as data attributes.

The following code snippet shows how to include the file before your scripts.js file in your pages. This would need to be done on each page.

Create a new file named options.js. Your file could be named anything of your choosing with a .js extension. Just be sure that the name matches the <script> reference in your HTML. Advanced users with more complex build systems may even compile these options into the scripts.js file, which will work so long as the options are declared before the main scripts modules.

Inside options.js, simply declare a global window.mr object, and populate it with options. Here, we are declaring the format option of the
countdown plugin.

Accordions

Description

Accordions are useful for containing large chunks of information in discrete portions and letting the user decide what is relevant to them — alternative to bombarding them with a wall of text. An accordion also helps to keep the visual layout of the page uncluttered and more visually balanced.

Markup

The accordion element is structured using a standard unordered list <ul> and functions by the user clicking on the title panel div.accordion__title to open the associated content, div.accordion__content.

Class Modifiers

You can modify the accordion by adding the following classes to the top level ul.accordion element.

accordion--oneopen - Changes behaviour so only one panel can ever be active at once.

Linking to an accordion panel using an ID

By adding an ID attribute to any accordion panel's .accordion__title element, the panel can be activated in a number of ways. The example below has had the ID panel1 added to the div.accordion__title element.

Alerts

Description

Alerts are dismissable elements placed inline with the page content to notify the user of something.

Markup

The alert element is structured using a <div> with class .alert with a child .alert__body which houses the contents of the alert ie. the text and an element with class .alert__close which, when clicked - dismisses the alert.

Boxed Layout

Description

Stack supports both full-width and boxed layout modes. The boxed layout mode restricts the width of the content from extending past a certain screen width. Once the maximum width is reached, the layout stays aligned to the center of the page.

Markup

Simply add the class boxed-layout to the <body> element to activate the boxed layout:

<body class="boxed-layout">
...
</body>

Modifiers

The maximum width of the boxed layout can be adjusted in the following ways:

Edit the @boxed-layout-width variable in the theme-variables.less file

Buttons

Description

Buttons are used in various places throughout the template to implore the user to continue exploring other parts of the site, or to call them to perform an action such as sign up, book now, become a member etc.

Markup

Buttons are housed in a basic <a> element with a <span> child denoting the button's text.

Colour Schemes

Description

Stack includes multiple colour schemes that you can choose to switch to, either inside Variant builder or by replacing a CSS reference in the head of the document. For instructions on how to do this in Variant, please see the Variant documentation.

Markup

Switching the colour scheme requires you to change from the default
theme.css reference in the head to the reference for your colour scheme, example:
theme-blue.css

Countdown Timer

Description

Stack includes support countdown timers via use of the
Final Countdown plugin. Countdowns are useful for coming soon pages, timed sales and more.

Markup

The countdown timer can be initialized on any empty text element (such as h1-h6,p,span etc.) by adding the class countdown with the data-attribute data-date which specifies the date to countdown to (in MM/DD/YYYY) format.

Modifiers

data-date-fallback - Specifies some text to show once the timer has reached zero.

data-days-text - Specifies a string of text to use instead of the default 'days'. This is useful for sites in languages other than English

data-date-format - A custom format that will override the format option set in mr.countdown.options.format.

Setting Global Options

If you prefer to set more specific options globally rather than by HTML, you can set the following
global options for the countdown plugin using the object mr.countdown.options specified in your options.js file:

mr.countdown.options.format - specifies a custom text format following the patterns in the
plugin instructions

For clarity, here is the order in which the format setting will be overridden:

If present, data-date-format attribute on the countdown div will be used. This is to allow a per-countdown override.

If data-date-format is not present on the div, the global option mr.countdown.options.format will be used.

If mr.countdown.options.format is not set, data-days-text attribute on the countdown div will be used within the default format (see below).

If data-days-text is not present, the default format of: %D days %H:%M:%S will be used.

Markup

Global Options

Pickadate offers a multitude of options for customisation and translation which can be viewed at the
pickadate website. You can apply any of the plugin's options using mr.datepicker.options via
global options specified in your options.js file.

Here is an example of how you could translate some elements of the datepicker for Español using global plugin options in options.js:

Dropdowns

Description

Stack includes support for dropdown elements. Dropdowns are especially useful for creating concealed options, often used in navigation bars.

Markup

Dropdowns require a parent .dropdown element with two children: the .dropdown__trigger element which is used to trigger the display of the dropdown, and the .dropdown__container element which is the element to be shown when the trigger is clicked. The dropdown__container element houses Bootstrap container, row and column markup to achieve its sizing and should follow this markup pattern:

Modifiers

You can modify dropdowns in the following ways:

.dropdowns--hover - Place this class on the <body> element to make all dropdowns respond to hovers instead of the default click

.dropdown--click - When using the .dropdowns--hover class on the <body> element, you may still want some dropdowns to respond to clicks, in this case place the class .dropdown--click on the desired individual .dropdown element.

.dropdown--hover - When using the default click method for dropdowns, you may want some dropdowns to respond to hover. In this case, place the .dropdown--hover on the desired individual .dropdown element.

Forms - SMTP Server

Description

When a user submits a form in Stack, the contents of the form are sent via email to an address you specify. To configure a sending server and to specify who receives this email, you need to make some changes in mail.php located inside the mail folder.

Your mail form will not work unless you have your files running on a hosting server with PHP 5. When you have your files ready on your hosting server, you need to edit the settings in /mail/mail.php to make the email function work.

Please note that you should first get your SMTP mail settings from your hosting provider before proceeding. It is also a good idea to set up your sending email address in cPanel before proceeding. Contact your hosting provider for support in this area, as we don't have access to your system to sort out these details.

Make these changes in mail.php

Line 13: Change to your own SMTP mail server address, either a hostname or ip address. Usually mail.yourdomain.com if you want to use your cPanel hosting server's email system. Otherwise you can use your ISP mail server but beware you'll need to provide account login details either way.

Line 14: Change the port number to the port for your outgoing server supplied by your hosting provider.

Line 15: Change the security layer used by your outgoing/SMTP server. This can either be 'ssl', 'ssl3', 'tls' or null if you want to use no security layer. Note that when using null, there are no quote marks around the word, just the word null.

NOTE FOR GMAIL USERS: Gmail requires that you use port 587 with TLS security so your lines 13, 14 and 15 would look like this:

Line 19: Change to your sending email account username, usually the entire email address at your domain eg: test@mediumra.re . You might need to create an email account in your cPanel for this if you don't already have one set up. Otherwise you can use the SMTP mail account info from your ISP.

Line 20: Change to the password for your sending email account at your domain. You might need to create an email account in your cPanel for this if you don't already have one set up.

Line 23: Change to the email address of the person who will be receiving and handling all the emails from the users who enquire through the website.

Line 24: Change to the name of the recipient who will handle all emails that come from the website.

Line 27: Change this to what you want the subject of the email to be in the recipient's email.

Line 28: Here is where you name your website, for instance "Yum Yum Restaurant Website" - this name will be used when the user does not supply a name, or when there is no email input on the form. Eg. when the form has only name and phone fileds, the email will appear to come from "Yum Yum Restaurant Website".

You will receive feedback from the Swift Mailer system on your page. You will be given an error until you get the sending settings just right. When the settings are correct, you'll receive a green box with a success message. Swift Mailer is used because it is reliable in sending, and gives feedback when message has been sent.

If you encounter a "Connection refused" problem with the contact form you may need to contact your server or email host to determine the correct SMTP settings, or fall back to using the standard mail function (see next section). When you see a timeout message, it could be that the supplied port number or security setting is wrong for your particular SMTP server.

Of course we are always here to help too! Please open a support ticket at our forum on
Ticksy

Forms - Native PHP mail()

Description

In our experience, the mail() function is not particularly reliable. We only recommend using this if you can't get a satisfactory result using the above mentioned SMTP method.

The problem with mail() is that it "tries" to simplify things to the point that it actually makes things more complex due to poor interface design. The developers of Swift Mailer have gone to a lot of effort to make the Mail Transport work with a reasonable degree of consistency.

Serious drawbacks when using this Transport are:

Unpredictable message headers

Lack of feedback regarding delivery failures

Lack of support for several plugins that require real-time delivery feedback

It's a last resort, so use SMTP instead where possible.

Using the mail() transport

Open mail/mail.php and make the following changes:

Line 9: Make sure line 9 has $emailMethod set to phpmail. That is, "phpmail" within the quotation marks on the right-hand-side of the equals sign like this:

Of course we are always here to help too! Please open a support ticket at our forum on
Ticksy

Forms - Overriding form action

Description

Forms with class form-email are automatically set up to submit to mail.php in the mail folder. If you server requires a different path for the mail folder, you can specify a different path to override the default mail/mail.php path by adding a custom action attribute to your form element.

Forms - Validation

Description

Forms in Stack are able to take advantage of the inbuilt validation functions.

Currently available validation rules are:

validate-required ensures the value of the field is not empty.

validate-email ensures the field meets email address requirements.

validate-number-dash allows only numerals (0-9) with the possibility of one or many dash (-) characters in the value. This is handy for phone numbers.

To validate a field with one of the above rules, the containing form must have class form-email or form-newsletter and the field must have one of the above validation classes.

Select elements (drop-down boxes) must contain an option with value="" in order to use validate-required effectively.

Radio controls should have checked="checked" on one of the options to ensure one is always selected when the page is loaded. This ensures that a valid selection is always passed on.

Use validate-required on checkboxes that should be ticked.

Forms - Redirect

Description

Default behaviour is to send the form then display a success message in a green box. Setting the data-success-redirect parameter on any form will override the default behaviour and send the user to your specified page instead of showing the green box. A form with a success redirect parameter would look like this:

Many captcha widgets may be added to a page, but only one captcha widget should be added to each form.

Placement of the widget

Using the quick method described above, the captcha will be automatically appended directly before the form's existing submit button on page load.

If you need to specify the width or placement of the captcha in your form, you may skip the automatic placement by adding your own div with class recaptcha to the form manually. When the script finds a div.recaptcha, the reCaptcha widget will be rendered inside.

The rendering of the widget is handled by Google's javascript, so to position the widget you must use a wrapping div which can use Bootstrap's column classes for width and offset.

Size and Colour Scheme

Google allows each recaptcha widget to be given basic style tweaks by way of size (compact or normal) and colour (light or dark) attributes.

You define these options on your form element, then the Stack script passes these values to the reCaptcha render script on page load.

To set size, use the data-recaptcha-size attribute. Options are compact and normal. Default if none is provided: normal.

To set colour, use the data-recaptcha-theme attribute. Options are light and dark. Default if none is provided: light.

Forms - Confirmation Message

Description

The form script can be configured to send a confirmation email to the user after they submit a form on your page. This is configured in
mail.php.

Open
mail.php and under the
Confirmation Message heading you will find:

$sendConfirmationToUser = false; // leave false to disable confirmation, or use path to an html email template.
$confirmationSubject = "Thanks for contacting Company Name"; // The subject of the confirmation email
$confirmationFromName = "Company Name"; // Used in the "from" field of the email.
$userEmailField = "email"; // Name attribute of the email field on the form - to be used as user's email address for sending email.
$defaultUserName = "User"; // Used if the form does not include a "name" field.

$sendConfirmationToUser: set to false (no quotes) by default.

false means the confirmation message is turned off.

To turn on confirmation messages, change false to the path of an html template file such as "confirmation.html" (include quotes). The html file should be an email compatible html template and should be located in the same folder as mail.php.

$confirmationSubject: a string representing the subject line of the confirmation email (include quotes).

$confirmationFromName: the name to be used in the
From field of the confirmation email.

$userEmailField: email by default. Change this to your form's email name attribute. eg. if your form has an email field with name="userEmail" then change this option to "userEmail" (with quotes).

$defaultUserName: Used in the
To field of the email with the user's email address if no
name field was submitted with the form.

Forms - Saving to CSV

Description

The form script can be configured to save the user's input after they submit a form on your page. This is configured in
mail.php. This only applies when using an email form, not a subscribe form such as MailChimp or Campaign Monitor.

Open
mail.php and under the
CSV heading you will find:

$saveToCSV = "email_form.csv";

$saveToCSV: set to "email_form.csv" (including quotes) by default. You should change this to suit what name you want for your file. The file name you specify here will be created automatically in the mail folder if it does not exist.

To protect your CSV file from prying eyes, you should add an index file to the mail folder. This will prevent anyone from seeing what files are in that folder. Alternatively you can adjust your server config to disable index listing for the mail folder.

Alternatively, you could set the path of your CSV file to a different location by setting $saveToCSV to point to a location which is not accessible to the public, such as "../../email_form.csv".

By changing the name of your CSV file, you lower the risk of anyone guessing the filename and being able to download it. You should change the name to something obscure.

Gradient Backgrounds

Description

The gradient background features uses the
granim.js plugin to display a background to your section that can fade seamlessly between a list user-defined of colours.

Markup

The gradient background requires the data attribute data-gradient-bg on the candidate element.

<section data-gradient-bg="#F7DC6F,#CEF76F,#8AF76F">
...
</section>

Setting this gradient using the data-gradient-bg attribute will override the gradient set in your
global options. This allows for per-gradient customisation.

Class Modifiers

Global Options

Gradient backgrounds can be displayed using settings in the
global options. To do this, the data-gradient-bg attribute
must be set, and must be left empty as shown in this example:

<section data-gradient-bg>
...
</section>

Granim offers a multitude of options for customisation which can be viewed at the
Granim website. You can apply any of the plugin's options using mr.granim.options via
global options specified in your options.js file.

Here is an example of how you could set some options on Granim using global plugin options in options.js:

Icons

Description

Icons serve different purposes depending on where they are used - often they are used as decoration, to illustrate a particular service for example. In other cases icons are used to help users navigate a site (a downward arrow denoting a dropdown menu for example).

Markup

Icons use the <i> element and require a specific class depending on which icon set is in use.

<i class="icon icon--sm icon-specific-class"></i>

Class Modifiers

You can modify icons by adding the following classes to any i.icon element:

icon--lg - Increase the default size of the icon

icon--sm - Decrease the default size of the icon

Image Backgrounds

Description

Stack uses the CSS background-size:cover property to fit background images to an element. This means that the image will always be correctly fitted to the element without distortion regardless of the screen size or device.

Markup

The image background requires a .background-image-holder element with a child <img> element.

Overlays

Often you'll want a section with an image background and text on top. In this case, you'll need to add the class .imagebg to the parent section and a data attribute data-overlay with a value of 1 - 9. This value determines how heavily to overlay the background image. A heavier overlay value (9 for example) will make the text stand out in higher contrast to the background image.

Alternatively, you can add the Access Token and Client ID strings into the scripts.js file below the comment "Replace with your own Access Token and Client ID".

Feed Markup

The basic usage of the Instagram feed requires the data-user-name attribute on a .instafeed element. This specifies the Instagram account from which to pull media.

<div class="instafeed" data-user-name="ACCOUNT"></div>

Modifiers

You can modify the Instafeed element in the following ways:

[data-amount] - Numerical 1 - 20 value which specifies the number of images to retrieve

[data-grid] - Numerical 2 - 6 value which specifies how many images per row to lay the feed out in.

Your max option set in
global options will be overridden by data-amount if it is set. This is to provide per-feed customisation where necessary.

Global Options

Instagram feeds can be displayed using settings in the
global options.

Spectragram offers some options for customisation which can be viewed at the
Spectragram website. You can apply any of the plugin's options using mr.instagram.options via
global options specified in your options.js file.

Here is an example of how you could set some options on your instagram feeds using global plugin options in options.js:

LESS Files

Description

Stack allows you to control the appearance of many features using compilable LESS files. The most visible style features are controlled by manipulating the theme_variables.less file.

The template is built using a number of modular components. Component LESS files are separated into two directories: framework_components and theme_components.

Theme Variables (theme-variables.less)

This file allows you to control the appearance of colours, fonts, spacing, default text sizes etc.

Framework Components (/framework_components)

The Framework Component LESS files include basic styling for the base elements in Stack. These components are shared among many Medium Rare templates and lay the foundation for the theme components.

The Framework Components are included in the theme.less file

Theme Components (/theme_components)

The Theme Component LESS files override some aspects of the Framework Component files to provide the distinct look and feel of Stack.

The Theme Components are included in the theme-overrides.less file

Building your own CSS files

By including or excluding features from the theme.less and theme-overides.less files, you can build a CSS file that is better tuned and doesn't contain unnecessary code - decreasing the overall CSS file size.

Compiling LESS files

The Stack LESS files can be compiled to CSS using your preferred LESS compiler, whether it be command line or GUI. Point your compiler to the theme.less file and run it. The required files will be included and the resulting theme.css file will be generated with the adjutments made in the LESS files.

Using Koala

Koala is a user-friendly LESS compiler which runs on Windows, Mac and Linux.

Before compiling in Koala, take a copy of the original css/theme.css file for safekeeping. To back it up, you could copy/paste to another folder or just rename it to theme-original.css.

To compile theme.less to theme.css in Koala, simply drag the less folder from your Stack folder and drop it onto the left-hand column. The Stack LESS files will appear in a list on the centre pane. Find theme.less in the list and click
compile.

You should then see the resulting theme.css file has been written into the css folder - which will likely automatically overwrite any existing theme.css file in that folder.

Lightbox

Description

Stack uses the
Lightbox javscript plugin by Lokesh Dhakar. The lightbox feature allows you to display a number of images as thumbnails that expand to a larger gallery when clicked. This is especially useful for galleries with multiple images.

Markup

The lightbox image requires a wrapping <a> element with the attribute data-lightbox whose href attribute points to the large version of the image. Inside the <a> element is a standard <img> element which serves as the thumbnail.

Modifiers

You can modify the lightbox element in the following ways:

[data-lightbox=""] - This data attribute is used to initalize the plugin but also groups the images together in galleries. Change this attribute's value to the name of your gallery to group images together in a cohesive set.

Global Options

Lightbox global options are set on the lightbox object,
not on the mr object.

Google API Maps

Description

Stack offers the use of two different Google map implementations. Iframe maps are basic maps embedded directly from Google's Maps service
http://maps.google.com, while Google API maps require an API key but allow colour styling of the map, removal of obtrusive UI elements and the ability to specify your own map marker, placed in multiple locations on the map.

When to use Javascript API

You want full control over the style of the map

You don't want Google's default controls overlayed on the map

You want to use a custom map marker(s)

When to use an Iframe embed

You don't want to obtain a Maps API Key

You don't mind the default map styling

Obtaining a Google Maps API Key

Follow Google's instructions
here on how to obtain an API key. When you have your key, proceed to the next section to learn how to set up your pages with the API key and the map.

Inserting your API Key into the map

In Variant, you need to click the key icon on the section with your map. When prompted, paste your API key into the box provided and click Save. This only applies to sections with a Google Maps javascript API enabled map - and the key icon will not appear on a section that uses an iframe map, as it is not necessary for an iframe embedded map.

If you are editing HTML outside of Variant, you need to add a data-maps-api-key attribute to the .map-container like so:

Setting the center of your API Map

In Variant, you need to click the pin icon on the section with your map. When prompted, type your address into the box provided and click Save. Be as specific as you can with the address, and even provide your state and country to give Google as much information as possible to provide you with an accurate point on the map. If an abiguous address is given, and no certain location can be matched, no marker will be shown.

If you are editing HTML outside of Variant, you need to add a data-address attribute to the map container like so:

The data-latlong attribute is optional, and will only be used if no data-address attribute is provided. You can set the data-latlong attribute in Variant by clicking the target icon on the section containing your Google javascript API enabled map.

Styling the API Map

Google Maps API enabled maps can be styled to show and hide map details, and recolour any element. The template will use a default colourless style which you can override with your own style using some JSON style code.

You may choose a predefined map style from the hundreds available ar
Snazzy Maps, then simply copy the JSON stye code into Variant.

Alternatively, make your own from scratch with this
Style Generator, then simply copy the JSON stye code into Variant.

If you are editing HTML outside of Variant, add a data-map-style attribute to the .map-container element. The JSON code used will need to be edited to make it compatible since the quote character used in the JSON code will break the HTML. Before pasting your JSON into your HTML page, copy the text into a blank text document and replace all instances of the " (quote) character with the string " to make the JSON embeddable inside HTML markup.

This only applies to sections with a Google Maps javascript API enabled map - styling an iframe embedded map is not possible.

Map Markers

You can provide multiple addresses for your map by separating them with a semicolon.

A marker is added for each address supplied.

The map is always centered around the first address supplied. This can be a country name if you want.

If you want to show two markers (eg. one at each end of the continent) on your map but centre the map around another point, add [nomarker] at the end of the first address.

[nomarker] can be added to any address without interfering with the address geocoding, however the map always centres around the first address supplied.

Change the map marker or 'pin' image by replacing mapmarker.png in the template's img folder.

Your mapmarker.png image should be 300 x 300 pixels (which is scaled down to 50 x 50 pixels on the map to account for high-res displays. Just make sure the point of the pin in your image is in the centre at the bottom of the image. See the supplied mapmarker.png as an example.

Example 1: Multiple locations across a country

To add a country with multiple markers, add a country name as the first "address" to centre the map there, and add [nomarker]. Then add some other addresses, all separated by semicolons to show map markers at each address. See the example address code for Australia (Zoom level 4 = further away) below and the resulting map:

Example 2: Multiple outlets in one city

To add a city with multiple markers, specify the middle of a city as the first "address" to centre the map there, and add [nomarker]. Then add a few other addresses, all separated by semicolons to show map markers at each address. See the example address code for New York (Zoom level 12 = closer) below and the resulting map:

Limitations

Google only allows 10 addresses to be geocoded at one time. If you reach 10 addresses and need more markers on your map, just add any point by using latitude and longitude coordinates in the same address box. These are simply comma separated coordinates ended by a semicolon like the textual addresses. Coordinates can be interspersed with your textual addresses.

Map Zoom Controls

By Default, the map zoom controls are hidden. To show them on the map, add the data-zoom-controls attribute to the map canvas div. A full list of available positioning options is available at the
Google Maps API Documentation.

This only applies to sections with a Google Maps javascript API enabled map - setting the zoom level for an iframe embedded map is a different process explained below.

Map Zoom Level

You must set the zoom level appropriately to show the map of your desired area at the right size. In Variant, click the zoom in icon on the section with your map and provide a number between 1 and 18 where 18 is fully zoomed in and 1 is zoomed out completely. In Variant, the map will reset at the specified zoom level. If you are editing HTML outside of Variant, add a data-map-zoom attribute with a number as the value like so, save, then refresh the page:

This only applies to sections with a Google Maps javascript API enabled map - setting the zoom level for an iframe embedded map is a different process explained below.

Iframe Embedded Google Map

To embed a simple map without requiring the use of a Google Maps API key, simply visit
Google Maps and search for an address. When you have cetered your map to your desired location and set the appropriate zoom level using the map controls, get the iframe embed code. At the bottom right-hand corner of the map, click the gear/cog symbol and choose Share or Embed Map. A new modal window appears - choose the tab at the top that says Embed Map and select the whole code in the given text box starting with <iframe ... and ending with </iframe>. Copy that to your to your clipboard with Ctrl+C (Windows) or Command+C (Mac) or right-click -> Copy on your mouse.

In Variant, click the pin icon at the top-right corner of the section containing the map and paste the code from Google Maps into the provided "Edit map Embed" box uaing Ctrl+V (Windows) or Command+V (Mac) or Right-click -> Paste on your mouse.

If editing HTML outside of Variant, simply replace the contents of the iframe src=" ... " attribute in the map section of your HTML markup with the contents of the src=" ... " attribute of the iframe you copied on Google Maps.

Events

An event is fired from the map's div.map-container element when the map is initialised.

mapCreated.maps.mr fires on map initialisation. After this, the google map object can be accessed from the mr.maps.instances array.

Events are fired for both native javascript and jQuery handlers.

Manipulating JS API Maps

When a map is created, its Google Maps object is stored in the mr.maps.instances array in order of where the map appears on the page.

This allows the developer to access properties of the map or adjust the map by adding more pins, and changing the map's position.

For instance, to begin manipulating the map when it has been created, we can listen for the mapCreated.maps.mr event, then add a pin to it:

Global Options

Google API Maps can be displayed using settings in the
global options.

The Google JS API offers a vast array of options for customisation which can be viewed in the
Google Maps Documentation. You can apply any of the provided options using mr.maps.options.map via
global options specified in your options.js file.

Masonry

Description

Masonry is a layout technique that automatically arranges elements to fit nicely together in a brickwork (or Masonry) like layout. Stack uses the
Isotope plugin to achieve masonry layouts.

Markup

A masonry layout requires a parent .masonry element with a child .masonry__container element. Inside the .masonry__container element, each item is housed inside a .msonry__item wrapper. The width of each masonry item can be controlled by using the
Bootstrap column classes column classes.

Masonry Filters

In addition to the standard masonry layouting, the Isotope plugin also allows for the addition of selectable filters that help the user to narrow down relevant items.

This requires the addition of a .masonry__filters element which resides alongside the .masonry__container element. This element is left empty and populated by the javscript using the data attribute data-masonry-filter on each .masonry__item

Data Attribute Modifiers

data-modal-id="mymodal" - Used on div.modal-container to link any element with class .modal-trigger to a modal with the same data-modal-id.

Example: an image of a team member that triggers a 'more info' modal about the team member.

data-autoshow="4000" - When placed on div.modal-container this attribute will automatically show the modal after the specified time. Example: data-autowshow="6000" would wait 6 seconds, then show the modal.

data-width="50%" , data-height="50%" - Used on the .modal-content div to explicity set the width and height of the modal as a percentage of the window.

data-cookie="promo_modal_dismissed" - Used on the .modal-content div in conjunction with data-autoshow to set a cookie when the user dismisses the modal. This function is intended to prevent the modal from autoshowing again on the next page load. The name of the cookie is derived from the value of the data-attribute you set. The value of the cookie is set to true, and is checked next time the autoshow modal is due to be shown. You can give all of your autoshow modals across your site the same data-cookie attribute if you want the user to dismiss a modal once and never see those modals again. This is handy for the mandatory EU cookies policy messages.

data-show-on-exit=".element-selector" - Used on div.modal-container to show the modal when the user's mouse pointer leaves the element with the specified selector. See section on Exit Modals below.

data-delay="2000" - Used on div.modal-container in conjuction with data-show-on-exit to delay the onset of an exit modal.

Class Modifiers

You can modify modal behaviour by adding the following classes:

modal--prevent-close - adding this class to your div.modal-container will prevent the modal closing when a user accidentally or otherwise clicks the modal overlay.

section-modal - if you have a section in your modal, adding this class to your div.modal-content provides special handling to pass a click through the section div to close the modal.

Scrolling

If the height of the .modal-content div reaches the window height, it will be made scrollable automatically.

Autoshow by ID in URL

By adding the optional data-modal-id to the modal-container div of your modals, you can summon any modal to show automatically by including the ID in the page URL like so: eg. to show modal with ID
project-1 your URL would look like this:

http://yoursite.com/projects.html#project-1.

Clicking a Link to Show Modal

By adding the optional data-modal-id to the modal-container div of your modals, you can summon any modal to show upon link click by including the modal's ID in the href attribute of a link like so: eg. to show modal with ID
create-account your link would look like this:

<a href="#create-account">Create Account</a>.

Exit Modals

By adding attribute data-show-on-exit to the modal-container div of your modal, you can cause the modal to show when the user's mouse pointer leaves any specified element on the page. The selector specified in the data attribute can be any element/s in the page such as a section, a button or even the body element, so your modal can appear when the user's mouse leaves the browser window. The exit modal can be delayed by adding the optional attribute data-delay with a set number of milliseconds to delay the showing of the exit modal.

Exit modals support the data-cookie attribute to prevent the modal showing more than once if the user dismisses the modal.

In the example below, the modal will show when the mouse leaves the body of the page or leaves a checkout button. A delay of 1 second (1000ms) is added also.

Showing Modals With Javascript

To show a modal, call mr.modals.showModal, passing a selector, jQuery object or javascript element reference to any modal-container div.

In this example, we first use jQuery to find our .promo-sale-modal div and pass it into the mr.modals.showModal function.

HTML:

<div class="modal-container promo-sale-modal">
...
</div>

Javascript:

var modal = $('.promo-sale-modal');
mr.modals.showModal(modal);

In the next example, we keep the same HTML but cut down the javascript code by simply passing the selector for the modal to the function call.

mr.modals.showModal('.promo-sale-modal');

Modal Show Delay

mr.modal.showModal accepts a second, optional argument to delay the opening of the modal.

Pass in a number representing the number of milliseconds you wish to delay the opening of the modal.

In this example, we use the same code from the previous example, and add the optional milliseconds delay argument, which will delay showing by 2 seconds.

mr.modals.showModal('.promo-sale-modal', 2000);

Hiding Modals With Javascript

mr.modal.closeActiveModal() is used to hide the currently active modal.

This function does not accept any arguments.

Events

An event is fired from the div.modal-container element each time a modal opened or closed.

modalOpened.modals.mr fires on modal openening

modalClosed.modals.mr fires on modal closing

Events are fired for both native javascript and jQuery handlers.

Newsletter Signup Forms

Description

Stack natively supports signup forms for mailing lists on MailChimp and Campaign Monitor. You can embed signup forms directly from the form building pages in your MailChimp or Campaign Monitor control panel.

All available form fields are supported natively. This means you can have simple (name, email) or complex forms (drop-downs, checkboxes etc.) to capture whatever data you require.

Form elements automatically take on the style of Stack upon loading.

Signup forms are automatically handled by Stack's scripts to submit via AJAX, so your users will not need to leave your page upon signing up.

Users are given feedback from your mail list provider via response text in a green (success) or red (failure) notification after submitting.

To build a subscribe form, you must first have a subscriber list set up in MailChimp or Campaign Monitor. Then you will need to create a signup form for that list in the form management section of MailChimp or Campaign Monitor.

With your form created, and the desired inputs added to the form, you then need to get the embed form code.

Your Stack form will be composed in the normal way, but will take certain details from the embed form, such as the action attribute and the input field name attributes. Other details are necessary and are listed below.

Markup

Keeping the attributes of form elements intact is important to the success of your signups. Form name attributes
must be kept the same as you see them in MailChimp or Campaign Monitor, as these values map directly to your list data.

These parts of your subscribe form must be present in order to sucessfully submit to your form provider:

The
action attribute of the original form must be copied to the form in your page.

Name attributes on the input elements must match in order for data to be copied properly to your subscribers list.

The hidden
anti-spam input must be present in the form. In the case of MailChimp, this is a blank text input with a long and random name attribute, usually included before the submit button.

Validation Classes such as validate-required should be added to the form inputs.

data-success and data-error attributes should be added to the form element to provide feedback to the user.

Validation

Add class validate-required to any checkbox element and all checkboxes with a matching name attribute will be checked. Validation will pass if one matching checkbox has been checked.

Modifiers

Class form--no-labels on the form element hides labels next to each form field.

Class form--no-placeholders on the form element takes placeholders out of form fields.

data-success-redirect attribute on the form with a valid URL will redirect the page to that URL after a successful submission.

Notifications

Description

Notifications allow you to prompt the user with an important piece of information without obscuring their entire view of the page (as opposed to modals). Common uses include cookies agreements, newsletter subscription forms, sales or promotions.

Markup

The markup for the notification element can be placed at any point within the <body> of your page (though, just before the end of the <body> is logical) and uses a number of data attributes and classes to dictate its behaviour.

An element with the .notification-close class will dismiss the notification when clicked. If one hasn't been set, a cross will appear to allow users to dismiss the notification.

Data Attribute and Class Modifiers

You can modify notifications by adding the following classes and data attributes:

data-autoshow="4000" - Required to tell the page when to show the notification. Provide number of milliseconds to delay notification.

data-autohide="4000" - An optional attribute added to the .notification element that will automatically hide the notification after the specified time (in milliseconds).

data-animation="from-top,bottom-left-right" - Required to tell the notification which direction to animate from.

data-cookie="eu_cookies_message_dismissed" - Used on the outer .notification div in conjunction with data-autoshow to set a cookie when the user dismisses the notification. This function is intended to prevent the modal from autoshowing again on the next page load. The name of the cookie is derived from the value of the data-attribute you set. The value of the cookie is set to true, and is checked next time the autoshow notification is due to be shown. You can give all of your autoshow notifications across your site the same data-cookie attribute if you want the user to dismiss a notification once and never see those messages again. This is handy for the mandatory EU cookies policy messages.

Classes: pos-right, pos-left, pos-bottom, pos-top - Added to the outermost div.notification to tell the notification where in the window to appear.

Showing Notifications With Javascript

Any notification can be shown using a few lines of javascript.

To show a notification, call mr.notifications.showNotification, passing a selector, jQuery object or javascript element reference to any .notification div.

In this example, we first use jQuery to find our .promo-notification div and pass it into the mr.notifications.showNotification function.

Parallax Backgrounds

Description

Parallax is the name given to the effect of one layer of the page moving at a different speed to the rest of the content. In Stack this refers to background images that scroll slower than the rest of the page - creating an implied depth effect.

Markup

The parallax effect can be enabled on any element that has an image as a background and requires you to add the class .parallax to the <section> which contains the image.

Data Attribute Modifiers

You can modify the appearance of radials with the following data attributes:

data-value - A percentage amount that specifies the amount to 'fill' the pie with

data-size - A numeric value in pixels, controls the size of the radial

data-timing - A numeric value in milliseconds, controls the speed of the animation

data-color - A hex code value that controls the color of the progress bar

data-bar-width - A numeric value in pixels that controls the width of the bar

These data-attributes will override any
global options you use for radials. This is to allow for per-radial customisation.

Global Options

Easypiechart offers some options for customisation which can be viewed at the
easypiechart website. You can apply any of the plugin's options using mr.easypiecharts.options via
global options specified in your options.js file.

Here is an example of how you could set a global default for all options on radials:

Markup

Class Modifiers

The class modifiers below refer to an amount of padding added to, or subtracted from the default section padding. The default section padding is measured in em units to achieve better cross-device scaling.

The following spacing classes are included:

space--xxs - 25% of the default padding

space--xs - 50% of the default padding

space--sm - 66.667% of the default padding

space--md - 133% of the default padding

space--lg - 200% of the default padding

space--xlg - 400% of the default padding

Sliders

Description

Sliders are useful for grouping similar content into a more attrative and digestable format. Common uses range from basic photo slideshows to showcasing important content from around your site.

Markup

The slider element requires a parent (<div> or <section>) with class '.slider' and a child <ul> with class '.slides'. Each <li> element inside is a separate slide. Uses data-attributes to dictate the sliders behaviour.

data-draggable - true or false makes the slider draggable with a mouse or finger. Defaults to false.

data-accessibility - true or false allows keyboard arrows to control the slider when set to true. Defaults to false.

data-rtl - true or false reverses the slider direction for use in RTL layouts. Defaults to false.

data-initial - true or false starting at 0, you can set the first slide to initialise the slider on. Defaults to 0.

data-freescroll - true or false makes the slider freely scrollableand will not snap to each slide. Defaults to false.

Global Options

Flickity offers a broad range of options for customisation which can be viewed at the
Flickity website. You can apply any of the plugin's options using mr.sliders.options via
global options specified in your options.js file.

Here is an example of how you could set a global default for options on all sliders:

window.mr = {
sliders:{
options: {
autoPlay: 5000
}
}
};

The global options you provide will be overridden by any data-attribute settings on the individual slider to allow for per-slider settings where necessary.

Helper Classes

The following helper classes can be used in conjunction with the RTL feature:

.ltr - This class switches the element to LTR layout, instead of RTL, this is useful for text such as numbers, which require LTR direction.

In Page Navigation

Description

Smooth scrolling links are ideal for navigating users around a one-page layout without disorienting them. Common uses include directing users to a section from the top navigation menu (as used in this documentation), or directing them to a particular section such as 'signup' when a button or link is clicked.

Markup

The smooth scroll link requires two <a> elements: one is clicked by the user and the other is placed at the desired destination point in the page. The link that is clicked requires the class inner-link and a href value matching the destination link's id attribute:

<a class="inner-link" href="my-destination">
Take Me There
</a>

<a id="my-destination"></a>

In Page Navigator

The In Page Navigator is a vertical navigation element that runs down the right-hand side of the page. Each section in the navigator is represented as a dot. The Page Navigator works using a number of <li> items each with a <a class="inner-link"> element that points to the relevant section on the page.

As the user scrolls the page, the In Page Navigator shows a highlighted dot to help orient the user on the page. This is achieved by the class .inner-link--active being added to the .inner-link element.

In Page Navigator Markup

The In Page Navigator requires its own unique section markup as follows:

Modifiers

You can modify the Smooth Scroll element in the following ways:

[data-smooth-scroll-offset] - A numerical value interpreted in pixels placed on the <body> element and offsets the smooth scroll by the specified amount. This is useful for accounting for the height of a sticky nav bar when smooth scrolling.

Global Options

Smoothscroll defaults can be overridden by settings in the
global options.

The Smoothscroll API offers some options for customisation which can be viewed at the
Smoothscroll Documentation. You can apply any of the provided options using mr.smoothscroll.options via
global options specified in your options.js file.

Here is an example of how you could set some global options for Smoothscroll in options.js:

Tabs

Description

Tabs are useful for containing large chunks of information in discrete portions and letting the user decide what is relevant to them — alertnative to bombarding them with a wall of text. Tabs also help to keep the visual layout of the page uncluttered and more visually balanced.

Markup

The tabs element is structured using a standard unordered list <ul> element and functions by the user clicking on the tab title div.tab__title to open the associated content div.tab__content

Toggle Class

Description

Stack's toggle class feature is a powerful ability that allows you to bind the jQuery toggleClass event to any element on the page, by clicking another element.

A common use for this feature is the hamburger menu used to toggle the display of a menu on mobile devices. When the hamburger menu is clicked, a toggleClass change is triggered on the menu element that switches its display properties.

Markup

The feature requires the [data-toggle-class] attribute and accepts two values. The element(s) you'd like to trigger the class toggle on, and the class to toggle. These values must separated by a semi-colon.

<a href="#" data-toggle-class="#menu;active">
Make Menu Active
</a>

<div id="menu">
...
</div>

The above would toggle the class 'active' on the element '#menu' when the <a [data-toggle-class]> element is clicked.

Typed Text

Description

Stack features the typed text effect provided by the
Typed.js plugin. This is a neat visual effect that simulates the typing of a set of specified strings and is useful for adding some visual flourish to your pages.

Markup

The typed text element requires a parent .typed-headline element with a child text element that has class .typed-text. The .typed-text element requires a [data-typed-strings] attribute which includes a comma separated list of strings to type.

Wizards

Description

Using the
jQuery Steps plugin, you can provide your users a step-by-step experience for onboarding or data-collection. This plugin offers advanced wizard functionality and is ideal for developers who require multi-part onboarding, signup, tutorial processes and more.

Markup

The basic layout for the Wizard requires parent .wizard element which houses h5 elements that serve as the title for each panel in the wizard and section elements which house the content for each panel. This is demonstrated in the markup snippet below: