Medium Rare
Stack HTML Template Documentation & User Guide

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.

BEM Naming Convention


The underlying CSS in Stack follows the Harry Roberts style of block__element--modifier naming convention - or BEM.

Find out more about BEM at bem.info.

Terminology


For you to get the most out of reading this document, we'll introduce some of the terminology used throughout so you'll be able to follow exactly what is meant.

Conventions used in this documentation

  • <tag> or element

    A tag is required to define each part (or element) that makes up the page as a whole.

    • <div> is the tag used to define a page division, the fundamental building blocks of HTML. May also be referred to simply as a div element.
      <div class="container">
         ...
      </div>
      
    • <a> is the tag used to define a link, otherwise known as an anchor. May be referred to simply as an a element.
      <a href="http://mediumra.re">
        Medium Rare
      </a>
      
    • <i> is the tag used to define an icon. May be simply referred to as an i element.
      <i class="icon icon--sm"></i>
      
  • .class

    A reference to any element with the specified class, or a reference to a class that may be used to modify another element.

    • "the trigger's parent .modal-instance div" means a parent div of the trigger element which has class modal-instance.
      <div class="modal-instance">
          <a class="modal-trigger">Trigger</a>
      </div>
      
  • element.class

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

    • div.modal-content
      means a div element with class modal-content
      <div class="modal-content">
          ...
      </div>
      
    • a.inner-link
      means an a (link) element with class inner-link
      <a class="inner-link" href="#top">  
          Back to Top         
      </a>
      
    • i.icon.icon--sm
      Elements can have multiple classes, so this is an i (icon) element with two classes icon and icon--sm
      <i class="icon icon--sm">
      

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.

<ul class="accordion">
    <li>
        <div class="accordion__title">
            <span>Title</span>
        </div>
        <div class="accordion__content">
            ...
        </div>
    </li>
</ul>

Class Modifiers

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

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

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.

<div class="alert">
  <div class="alert__body">
    <span>Here is the alert text</span>
  </div>
  <div class="alert__close">
    &times;
  </div>
</div>

Class Modifiers

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

  • .bg--error - Changes the background to the theme's error colour
  • .bg--success - Changes the background to the theme's success colour
  • .bg--primary - Changes the background to the theme's primary colour

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.

<a class="btn" href="#">
    <span class="btn__text">
        Click Me
    </span>
</a>

Class Modifiers

You can modify buttons by adding the following classes to an a.btn element:

  • .btn--lg - Increases the button's size.
  • .btn--sm - Decreases the button's size.
  • .btn--transparent - Removes the border and background from a button (but keep it's default padding).
  • .btn--unfilled - Removes the background colour, but leaves the border.
  • .btn--primary - Change the background colour to the template's primary colour.

Colours

Description

Colour classes can be added to elements to modify either their background or text colours.


Markup

Modifying colours only requires the addition of a specific colour class to an element, below is a simple markup example of how you might change the background colour of a section.

<section class="bg--secondary">
    ...
</section>

Class Modifiers

You can modify the colour of most elements by adding the following classes:

  • bg--secondary - Makes an element a slightly offset colour from the templates default background colour (usually slightly darker or lighter).
  • bg--dark - Sets the elements background to a dark colour.
  • bg--primary , bg--primary-1, bg--primary-2 - Sets the background of element to one of the templates colour scheme colours. (Note: Not all themes have a primary-1 and primary-2 colour option)

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

<link href="css/theme-wildfire.css" rel="stylesheet" type="text/css" media="all">

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.

<span class="countdown" data-date="06/25/2019" data-date-fallback="Coming Soon"></span>

Modifiers

You can modify the countdown with the following optinal attributes:

  • 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 defauly 'days'. This is useful for sites in languages other than English

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:

<div || li class="dropdown">
  <span class="dropdown__trigger">Show Dropdown</span>
  <div class="dropdown__container">
    <div class="container">
      <div class="row">
        <div class="col-md-4 dropdown__content">
          ....
        </div>
      </div>
    </div>
  </div>
</div || li >

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:
    $outgoingServerAddress      = 'smtp.gmail.com';     // Consult your hosting provider.
    $outgoingServerPort         = '587';                // Options: '587' , '25' - Consult your hosting provider.
    $outgoingServerSecurity     = 'tls';                // Options: 'ssl' , 'tls' , null - Consult your hosting provider.
    
  • 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.

For a full range of documentation on configuring and using the Swift Mailer Library see here: http://swiftmailer.org/docs/sending.html

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

The Mail Transport sends messages by delegating to PHP's internal mail() function.

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:
$emailMethod                = 'phpmail'; // REQUIRED value. Options: 'smtp' , 'phpmail'

For a full range of documentation on configuring and using the Swift Mailer Library see here: http://swiftmailer.org/docs/sending.html

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


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-numbers-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

Stack can redirect your users to a confirmation page after successful submission of email forms or newsletter signup (MailChimp / Campaign Monitor) forms.

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:

<form class="form-email" data-success-redirect="http://mediumra.re/thanks.html" data-success="Thanks for your submission, we will be in touch shortly." data-error="Please fill all fields correctly.">
    <input type="text" class="validate-required" name="name" placeholder="Your Name">
    <input type="text" class="validate-required validate-email" name="email" placeholder="Email Address">
    <textarea class="validate-required" name="message" rows="4" placeholder="Message"></textarea>
    <input type="submit" value="Send Message">
</form>

The address given in the data-success-redirect attribute should be a fully formed URL including http:// to ensure maximum compatibility.

If the attribute data-success-redirect is left blank, or not included in the form tag, the default behaviour will occur (green box success message appears).


Forms - Google reCaptcha

Description

Stack supports Google's reCaptcha v2 to display the "I am not a robot" checkbox in your forms.

How to implement in 3 easy steps:

  • Register your site to sign up for a recaptcha key pair on the recaptcha admin page.
  • Add the data-recaptcha-sitekey attribute to your enquiry form with your site key as the value.
  • Edit mail.php in the mail folder of your site and paste your secret key into the captcha settings.
<form class="form-email" data-recaptcha-sitekey="pasteyoursitekeyinhere" data-success="Thanks for your submission, we will be in touch shortly." data-error="Please fill all fields correctly.">
    <input type="text" class="validate-required" name="name" placeholder="Your Name">
    <input type="text" class="validate-required validate-email" name="email" placeholder="Email Address">
    <textarea class="validate-required" name="message" rows="4" placeholder="Message"></textarea>
    <input type="submit" value="Send Message">
</form>

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.

<form class="form-email" data-recaptcha-sitekey="pasteyoursitekeyinhere" data-success="Thanks for your submission, we will be in touch shortly." data-error="Please fill all fields correctly.">
    <input type="text" class="validate-required" name="name" placeholder="Your Name">
    <input type="text" class="validate-required validate-email" name="email" placeholder="Email Address">
    <textarea class="validate-required" name="message" rows="4" placeholder="Message"></textarea>
    <div class="col-xs-12">
        <div class="recaptcha"></div>
    </div>
    <input type="submit" value="Send Message">
</form>

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.

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>

Class Modifiers

You can modify the gradient background in the following ways:

  • data-gradient-bg - A comma separated list of hex colour codes, the codes must use 6 alphanumeric characters.

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.

<div class="background-image-holder">
    <img alt="Background" src="img/background.jpg" />
</div>

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.

<section class="imagebg" data-overlay="9">
    <div class="background-image-holder">
        <img alt="Background" src="img/background.jpg" />
    </div>
    <div class="container">
       ...
    </div>
</section>

Class Modifiers

You can modify image background sections in the following ways:

  • image--light - On the .imagebg section to change the overlay to white and the text to dark
  • [data-overlay] - A value of 1 - 9 which overlays the section with a tint to aid with text readaibility.

Instagram

Description

Stack uses the Instagram Developer API in conjunction with the Spectragram javscript plugin to show a feed of your recent activity on Instagram.


Setting up Client ID and Access Token

This article will run you through the process of obtaining your Client ID and Access Token - both of these strings are necessary to successfully display an Instagram feed using the Instagram API.

Once you've obtained your Client ID and Access Token you can insert them as data attributes on the .instafeed element by using the data-access-token and data-client-id attributes.

<div class="instafeed" data-user-name="ACCOUNT" data-access-token="XXX" data-client-id="XXX"></div>

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.

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.

<a href="large-image.jpg" data-lightbox="Gallery 1">
    <img alt="Thumbnail" src="thumbnail-image.jpg" />
</a>

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.

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:

  <div class="map-canvas" data-maps-api-key="AIzaSJiT6D4E0PlvR45biSx0DoWRswL1kfdO9ZU" data-address="1095 High Street, Armadale, Victoria"></div>

The above key is a sample only and will not work for your site.


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:

 <div class="map-canvas" data-latlong="-37.858192,145.023019" data-maps-api-key="AIzaSJiT6D4E0PlvR45biSx0DoWRswL1kfdO9ZU" ></div>

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.

[
  {
    "featureType": "landscape.natural.landcover",
    "stylers": [
      { "visibility": "on" },
      { "weight": 0.7 },
      { "hue": "#00c3ff" }
    ]
  }
]

If editing HTML manually, The code above needs to be altered to look like the below:

[
  {
    &quot;featureType&quot;: &quot;landscape.natural.landcover&quot;,
    &quot;stylers&quot;: [
      { &quot;visibility&quot;: &quot;on&quot; },
      { &quot;weight&quot;: 0.7 },
      { &quot;hue&quot;: &quot;#00c3ff&quot; }
    ]
  }
]

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:

Australia [nomarker]; Perth, Australia; Melbourne, Australia; Sydney, Australia

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:

Midtown Manhattan, NYC [nomarker]; Downtown NYC; Lower East Side NYC; Upper West Side NYC

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.

 Melbourne, Victoria, Australia [nomarker]; -37.855151, 145.018092;  RICHMOND, VIC, AU; collingwood, vic, australia;  -37.851623, 144.991615;  williamstown, vic, au; werribee, vic, au; -37.849578, 145.111392; glen waverley, vic,au; manningham, melbourne, au; boronia victoria; ferntreegully, victoria; caroline springs, vic , au;st albans, vic, au; -38.079153, 145.483336

Map


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:

  <div class="map-canvas" data-map-zoom="12" data-maps-api-key="AIzaSJiT6D4E0PlvR45biSx0DoWRswL1kfdO9ZU" ></div>

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.


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.

<div class="masonry">
    <div class="masonry__container">
        <div class="masonry__item col-sm-6">
          ...
        </div>
        <div class="masonry__item col-sm-6">
          ...
        </div>
    </div>
</div>

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 sites 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

<div class="masonry">
    <div class="masonry__filters"></div>
    <div class="masonry__container">
        <div class="masonry__item col-sm-6" data-masonry-filter="Filter One">
          ...
        </div>
        <div class="masonry__item col-sm-6" data-masonry-filter="Filter Two">
          ...
        </div>
    </div>
</div>

Modifiers

You can modify the masonry in the following ways:

  • data-filter-all-text - On the masonry__filters element to specify what the 'Select All' text should say.

Modals

Description

Modals allow you to focus your user's attention on one important aspect or proposition of your site. Common uses for modals include limited-time sales, newsletter signup forms or newly added features.


Markup

The modal element requires a parent .modal-instance div, a .modal-trigger div (often a button - used to open the modal), followed by the modal itself .modal-container

<div class="modal-instance">
  <a class="modal-trigger">Trigger</a>
  <div class="modal-container" data-modal-id="optional">
    <div class="modal-content" data-width="80" data-height="80">
      ...
    </div>
  </div>
</div>

Data Attribute Modifiers

You can modify modals by adding the following data attributes:

  • 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.

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.


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.

<div class="modal-instance">
  <a class="modal-trigger">Trigger</a>
  <div class="modal-container" data-modal-id="optional">
    <div class="modal-content" data-show-on-exit="body, .btn--checkout" data-delay="1000" data-width="80" data-height="80">
      This is an exit modal that shows when the mouse exits the window or a checkout button.
    </div>
  </div>
</div>

Showing Modals With Javascript

Any modal can be shown using a few lines of 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.


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.


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.

Campaign Monitor example:

<form action="http://mrareco.createsend.com/t/d/s/dyikkh/" class="form--no-labels" method="post" id="subForm">
    <p>
        <label for="fieldEmail">Email</label><br />
        <input id="fieldEmail" name="cm-dyikkh-dyikkh" type="email" required />
    </p>
    <p>
        <button type="submit">Subscribe to Newsletter</button>
    </p>
</form>

MailChimp example:

<form action="//mediumra.us8.list-manage.com/subscribe/post?u=77142ece814d3cff52058a51f&amp;id=db05fb611a" class="form--no-labels" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate>
    <p>
        A minimal signup form with class <strong>form--no-labels</strong>.
    </p>
    <div id="mc_embed_signup_scroll">
        <div class="row">
            <div class="col-md-6">
                <div class="mc-field-group size1of2">
                    <label for="mce-EMAIL">Email Address  <span class="asterisk">*</span>
                    </label>
                    <input type="email" value="" name="EMAIL" class="required email" id="mce-EMAIL">
                </div>
            </div>
            <div class="col-md-6">
                <div class="mc-field-group">
                    <label for="mce-FNAME">First Name </label>
                    <input type="text" value="" name="FNAME" class="" id="mce-FNAME">
                </div>
            </div>
        </div>
    </div>
    <div class="clear"><input type="submit" value="Subscribe" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
</form>

Please note that these examples will not work for you as they are specially configured for a Medium Rare mail list.


Validation

  • Add class validate-email to email fields to validate only email addresses.
  • Add class validate-required to make the field required.
  • 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.

<div class="notification col-sm-3 pos-bottom pos-right" data-animation="from-bottom" data-autoshow="2000">
  ...
  <a class="notification-close">Shut It Down</a>
</div>

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.

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.

<section class="parallax">
  <div class="background-image-holder">
    <img alt="BG" src="img/bg.jpg" />
  </div>
</section>

Radials

Description

Stack includes support for radial progress bar elements via the use of the (easypiechart)[ https://github.com/rendro/easy-pie-chart] jQuery plugin.


Radial Markup

The radial requires a .radial element with a data-value attribute to work in its most basic form:

<div class="radial" data-value="90">
  <span class="radial__label">90%</span>
</div>

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

Spacing - Helpers

Description

Stack includes a number of spacing helper classes that allow you to modify the default margin and padding on elements.


Markup

The spacing classes should be added to the element you wish to effect, below is an example of removing the bottom padding on a section:

<section class="unpad--bottom">
  ...
</section>

Class Modifiers

The following spacing classes are included:

  • unpad - Remove top and bottom padding from an element
  • unpad--bottom - Remove bottom padding from an element
  • unpad--top - Remove top padding from an element
  • unmarg - Remove top and bottom margin from an element
  • unmarg--bottom - Remove bottom margin from an element
  • unmarg--top - Remove top margin from an element

Spacing - Sections

Description

Stack includes a number of spacing helper classes that allow you to modify the default padding of sections.


Markup

The spacing classes should be added to the relevant <section> to modify the padding:

<section class="space--xxs || space--xs || space--sm || space--md || space--lg || space--xlg">
  ...
</section>

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.

<div class="slider" data-arrows="true" data-paging="false" data-timing="5000">
  <ul class="slides">
    <li>
      ...
    </li>
  </ul>
</div>

Adjusting Slide Width

Adjust the width of each individual slide by adding a Bootstrap column classes to the <li> element of that slide.

<div class="slider">
  <ul class="slides">
    <li class="col-sm-6">
      ...
    </li>
  </ul>
</div>

Data Attribute Modifiers

You can modify the slider by adding the following attributes to the outermost div.slider element:

  • data-timing - a millisecond value determining how long each slide should wait before moving to the next.
  • data-arrows - true or false turns directional arrow navigation on and off.
  • data-paging - true or false turns paging naviagtion on and off.

RTL (Right to Left Direction)

Description

Stack includes support for RTL (Right to Left) layouts by employing an additional, RTL specifc stylesheet. Enabling the RTL feature requires two actions:


Adding the 'dir' attribute

The attribute 'dir="rtl' must be added to the <html> tag:

<html lang="ar" dir="rtl">
  ...
</html>

Including the stylesheet reference

The RTL specific stylesheet must then be included in the head of the document, below the theme.css reference like so:

<link href="css/theme.css" rel="stylesheet" type="text/css" media="all" />
<link href="css/theme-rtl.css" rel="stylesheet" type="text/css" media="all" />

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:

<section class="page-navigator">
    <ul>
        <li><a href="#my-section" class="inner-link" data-title="My Section"></a></li>
    </ul>
</section>
<section id="my-section">...</section>

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.

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

<ul class="tabs">
  <li class="active">
    <div class="tab__title">
      ...
    </div>
    <div class="tab__content">
      ...
    </div>
  </li>
</ul>

Class Modifiers

You can modify the tabs by adding the following classes:

  • active - Add this class to a <li> parent to make it open by default (as seen in above example).

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. 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.

<div class="typed-headline">
  <span class="typed-text" data-typed-strings="one,two,three,four,five"></span>
</div>

Modifiers

You can modify the typed text element in the following ways:

  • typed-text--cursor - Added to the .typed-text element displays a flashing cursor to enhance the typed effect.

Twitter Feeds

Description

This feature allows you to embed a feed of recent tweets from any Twitter user by utilising the Twitter Fetcher plugin.


Setting the feed

The Twitter feed element uses a HTML5 data attribute called 'data-feed-name' to determine which feed to display. Simply provide the username of the twitter feed you wish to display.

  • Twitter Widget IDs have been discontinued and are no longer available, but existing Widget IDs will keep working.
  • The latest version of Twitter Fetcher plugin no longer requires a Widget ID.
  • Our script is backwards compatible - those who wish to keep using Widget IDs do not need to change any HTML.
  • You can provide data-user-name or data-widget-id and achieve the same result, but data-widget-id will take precedence.
  • If no data-user-name or data-widget-id are provided, the feed will display the official @twitter feed.
  • Do not include the @ symbol, just the username.

Markup

The twitter feed requires a wrapping element .twitter-feed with an empty element .tweets-feed inside it.

<div class="twitter-feed">
  <div class="tweets-feed" data-feed-name="#####"></div>
</div>

Modifiers

You can modify the Twitter feed in the following ways:

  • .twitter-feed--slider - a class placed on the .twitter-feed element makes the feed render each tweet in a slide, rather than simply listing them out.
  • [data-amount] - a numerical amount placed on the .tweets-feed element that tells the plugin how many latest tweets to fetch.