Metroliumv1.2

WordPress Theme Documentation

Before we get started, we would first like to say a big thank you for purchasing our theme!

Within this documentation we will take you through the basic process required to get your new theme up and running, along with taking you through all the fantastic functionality we have crammed into this theme.

If you have any questions about the theme, you can join our community support forum to get your question answered. You can find the forum at www.eski.io/support

This documentation might seem a bit overwhelming at first due to it's length, but we have taken the time to carefully organise the document, splitting it into smaller, easier to manage sections. You can find a list of contents at the very top of the page. Clicking this will help you jump to the required section.


Find us online


Documentation Version
v1.2
Last Update
August 13th 2013
Created By
eski
Theme Demo
eski.io/demo/metrolium
Support Forum
eski.io/support/forum/metrolium/

Getting Started

The .ZIP you have downloaded from ThemeForest contains everything you need (plus more) to get started with the theme. Most importantly the .ZIP contains the theme itself (Zipped and Unzipped), but it also includes other goodies such as the original PSD created during the design process, this documentation, the licence file and some sample dummy data to get the ball moving.

.ZIP Contents & Folder Structure

In the .ZIP you will see the following folders:

  • Documentation — What you are reading now.
  • Dummy Data — Three files containing example dummy data from our demo.
  • PSDs — All the original design artwork.
  • Theme — The parent and child theme in both Zipped and Unzipped forms.

Theme Requirements

As this theme runs on WordPress, all of this themes requirements are defined by WordPress themselves. We have added nothing to the mix, if your server can run WordPress, then it can also run this theme.

WordPress requires a web server that supports PHP and MySQL. There are many different versions of PHP and MySQL, and there are also many versions of WordPress too, each with their own unique requirements. For that reason we always recommend using the very latest version of WordPress. Doing so will give you a much smoother experience. WordPress is constantly evolving and improving, using an old version just doesn't make sense.

  • To download the latest version of WordPress click here
  • To view the most up-to-date minimum requirements click here

Installation & Setup

Installing WordPress

Before you can install the Metrolium theme you need to set WordPress up on your web server and do some basic configuration. Metrolium theme then sits within WordPress to add the extra functionality and style. Installing and setting up WordPress is beyond the scope of this documentation, but you can find an in-depth guide here.

Installing Metrolium

If you have managed to get WordPress up and running, you will do fine with this next section as some of the steps you did to get WordPress installed will help you here too.

There are three main methods to get a WordPress theme installed:

Method 1 — Envato Automatic Installation

Possibly the easiest method for downloading, installing and updating the Metrolium theme is with the Envato Marketplace Toolkit Plugin.

This handy plugin developed by the team at Envato (ThemeForest) interfaces with your Envato marketplace account, and displays a list of supported themes you have purchased that can be installed directly from within WordPress. Furthermore it also supports updates and backups. Whenever a theme is updated you will be informed (similar to the way WordPress informs you of plugin updates), you can then choose to update at a time that suits you.

We have included the plugin within Metrolium as one of our suggested plugins.

  1. From within the WordPress Admin, click on Appearance and then Install Plugins
  2. Find and hover over 'Envato Toolkit' in the list, then click Install
  3. The plugin will then be installed. You can then click Return to Required Plugins Installer to activate the plugin
  4. On the left hand menu, you should now see an Envato Toolkit item. Click on this to continue.
  5. To establish an Envato Marketplace API connection navigate to the 'Envato Toolkit' page and insert your Marketplace username and secret API key in the designated input fields. To obtain your API Key, visit your 'Settings' page on any of the Envato Marketplaces.
  6. Once the API connection has been established you will see a list of themes within your account that can be auto installed.
  7. Find the theme you wish to install (hopefully this one) and the on screen instructions will guide you through the rest.

Method 2 — Upload Tool

WordPress comes with a built in tool to help you install themes and plugins. You simply upload a .ZIP file to WordPress, and the rest is taken care of.

  1. Login to your WordPress admin environment.
  2. Click on Themes under the Appearance menu.
  3. In the tabs at the top of the page, click Install Themes.
  4. Just under the tabs there is a row of links, click on Upload.
  5. Using the file selection box, navigate to the folder where you extracted the contents of the .ZIP you downloaded from ThemeForest. Within this folder, click into /Theme/ and select metrolium.zip, then click Install Now.
  6. WordPress will now upload metrolium.zip, extract it and add it to the correct folder.

The theme is now installed, all that needs to be done now is to make it active. Within the WordPress admin, browse through to the Themes page under Appearance and activate Metrolium.

This upload method can behave differently depending on the server environment and the security protocols being enforced on the web server. If you encounter problems with Method 2, move onto Method 3

Method 3 — FTP Upload

Method 3 requires the use of an FTP client to connect directly to the Web Server and upload the theme files manually. You will need to acquire the FTP details from your Web Host provider.

Once you have your FTP details you will need an FTP client to help you connect to the web server and transfer the files. FileZilla is a free FTP tool and has been my personal choice for many years. Once you have both your FTP details and an FTP client, continue with the instructions below.

  1. Connect to you Web Server using the FTP details your host provided you with.
  2. Browse to the WordPress installation you wish to install this theme into.
  3. Within /wp-content/ click through to /themes/
  4. Unzip metrolium.zip to an easy to access destination on your computer (The desktop is usually a good location)
  5. Upload the whole /metrolium/ folder into the /themes/ folder using the FTP client.

The theme is now installed, all that needs to be done now is to make it active. Within the WordPress admin, browse through to the Themes page under Appearance and activate Metrolium.

File & Folder Permissions

Upon installation of Metrolium, there is one final step you will need to make in order to get the most power out of Metrolium. In order for Metrolium to work properly, it needs access to certain files so it can perform certain tasks. When customizing the colors of Metrolium, specifically when saving your config, it creates/updates a file which is then included within your site. In order for Metrolium to update this file, it needs the correct permissions. You will need to log in via FTP to do this.

Once logged in to your websites FTP, you will need to locate your WordPress install. From there take the following folder path: /wp-content/themes/metrolium/assets/css/. Within this folder you will see skin-override.css, this is the file we need to update. Right clicking this file should present an option allowing you to change its permissions. You need to change the permissions to 666. Then click OK, and you're done.

In short, you need to change the permissions of skin-override.css to 666

What the file permissions window could look like

Multisite Setup

If you are using a WordPress multisite configuration, Metrolium will make one stylesheet for each site within the network. They will be named in a similar way mentioned above, with the addition of the blog ID on the end, for example skin-override-2.css. The instructions outlined above will have to be carried out for each of these files.

Child Theme

Metrolium comes packaged with a child theme so you can develop on top of Metrolium as a base whilst retaining the ability to update the theme without fear of having your changes overwritten. Even if you don't plan on making any development changes to Metrolium, we still recommend you activate the child theme instead of the parent.

As standard, the child theme will look and function no differently than if you had the parent theme active.

To use the child theme, it's really easy. All you need to do is upload both themes, the main/parent theme (Metrolium) and the child theme (Metrolium-child) and activate Metrolium-child, not Metrolium. The child theme then inherits all styles and functionality from its parent.

WordPress stores certain themes settings in a safe way so they don't conflict with settings from other themes, old or new. As a child theme is technically a new theme, these certain settings won't be transfered over if you switch between parent and child themes. This is another reason why we suggest using the child theme from the start, as changing down the line could cause unnecessary problems and require you to reconfigure certain settings.

For a more in-depth read into child themes, WordPress has a much more substantial write up on the topic that explains how they work and some best practices when developing within them.

codex.wordpress.org/Child_Themes

Child theme styles

By default, the child theme inherits all the styles from the parent. If you wish to turn them all off and simply use Metrolium as a functionality base, then you can add the following line to your child-themes functions file:

define( 'INCLUDE_PARENT_STYLES', false );

Configuring Theme Options

Suggested Plugins

Within Metrolium we have included a selection of suggested plugins. None of these are required for the theme to function, but they all add an extra level of functionality that you might wish to make use of. Two of these plugins are premium plugins, which would cost $30 to buy, but we have included them for you to use absolutely free of charge.

To see and install the suggested plugins:

  • First log in to the WordPress admin panel.
  • From within the WordPress Admin, click on Appearance and then Install Plugins
  • Simply hover over a plugin within the list, then click Install
  • The plugin will then be installed. You can then click Return to Required Plugins Installer to activate the plugin

Global Settings

Once the Metrolium theme is activated, a new item will appear in the WordPress admin menu on the left called Theme Options. Click this to access some of the configurable options.

The options are split up into several different tabs to make them easier to browse. You will see the following tabs:

  • Welcome — A welcome message (can be disabled)
  • Global — Site wide options along with ability to add custom CSS
  • Sidebars — Add your own custom sidebars
  • Blog — Configuration for the blog
  • Portfolio — Configuration for the portfolio
  • Help — How to get help with Metrolium

Colors & Styling

The theme customizer is probably the most powerful feature of metrolium and really enables you to add your own creative flare to your website. To change the colors, you need to browse through to the Themes page under Appearance within the WordPress admin area.

Once there, and providing that the Metrolium theme is active, within the Current Theme section you will see a Customize link. Clicking this will take you to a new page with a sidebar on the left and a preview of the site on the right. Within the sidebar are many sections, each one dedicated to controlling a section of the site.

Describing how this system works with words wouldn't do it any justice, so we have made a video to help illustrate how easy to use and powerful this tool is.

Example .XML Data

Metrolium comes packaged with three .XML files that contain example data for pages, posts and the portfolio to give you a quick boost of content when setting your site up. The content will also help those who learn by doing instead of reading.

To import the data, login to the WordPress admin and navigation to Tools > Import. From here you will be given a list of content types to import. Select the bottom in the list, labelled 'WordPress'. This will install the "WordPress Importer" plugin. Click Activate Plugin & Run Importer to get started.

On the next screen, click Choose File and select one of the three files that was contained within the Metrolium .ZIP, post.xml for example. Then click Upload file and import. WordPress will then give you some basic options on how you want to setup the data, once done press Submit and the data will be imported.

Simply repeat this for the other two files if you wish. All data is optional, if you only want to see how the pages work, then you only need to import page.xml

Tools > Import

Basic Configuration

One of the first things you might want to do after setting up WordPress is to configure what page is your home page. By default WordPress displays your blog posts on the home page. If you want to have a static home page and choose to display your blogs elsewhere, enter the WordPress admin and click on Settings then Reading

Once on this page, at the very top is the controls to pick your home page. As mentioned above, by default "Your latest posts" will be selected. Changing to "A static page" will then enable you to pick a new home page.

If you imported the sample .XML page data, then these lists should already be populated with page titles. Select whichever page you would like to be your home page, and because we no longer have a defined section to show our blog posts, we should set up a page for this too.

Settings > Reading

Navigation & Menus

Metrolium offers two menu locations:

  • Primary Navigation - This appears at the very top of the page and is what it says on the tin, the primary navigation for the whole site.
  • Trim Links - This appears at the very bottom of the page, and is designed primarily for adding the traditional legal links such as privacy policy and terms & conditions etc but its entirely up to you.

To make use of these theme locations, you first need to create a menu and add some links to it using the on screen interface. You can then assign your new menu to one of these theme locations. Upon first installation of Metrolium you should setup a minimum of two menus, one for each location and assign them. You can create additional menus for use elsewhere around the site such as in sidebar widgets.

TIP - It's a good idea if you plan on making any significant changes to an already active menu, or are making changes that will only be in place temporarily, to make a brand new menu, set it up as needed, then simply switch the menu location to that of the new menu. Then, if you need to revert back it can be done instantly by switching back to the old menu.

Configuring Content Options

Each page can have its options independently configured enabling you to have complete control over how each and every page looks and feels. This gives you the power to break out of the traditional template structure other themes can use, where you have a small number of strict templates.

Breadcrumbs

Whilst the breadcrumbs are a very useful tool for navigating around a website, the majority of the time you would want these enabled. You can however turn them off on certain pages if you wish. Within the "Page Options" panel is a checkbox enabling you to disable them. By default they are on.

Sidebars

In the "Page Options" panel is a drop down list enabling you pick which sidebar (if any) you would like to show. Once a sidebar is chosen, an additional box will appear allowing you to configure which side you would like the display the sidebar, left or right.

Please note, pages that make use of the [band] shortcode are unable to have sidebars.

Title Bar

By default the Title bar is disabled. You can enable it within the "Page Options" panel. Other than 'hidden', there are two other options: 'Slider' and 'Active'. By selecting 'Slider', a new input box will appear where you can enter the shortcode of the slider you wish to display. By selecting 'Active', several new checkboxes and radio buttons will appear, enabling you to configure most aspects of the now active title bar.

Post Formats

You can only select 'Post Formats' for post items (the blog). When adding or editing a blog, you can choose its post format from the 'Format' panel (usually found in the right column near the top). There are several formats to choose from. By picking the most relevant post format to the content you are posting, you can tailor the way the content gets displayed on the front end. For example, selecting the 'Video' post format will tell Metrolium to show the video content you are posting about more prominently.

Selecting certain post format will cause additional option panels to display. These additional panels contain input boxes specific to the current post format selected.

Portfolio

To setup the slider that appears on a single project page, simply follow these instructions:

  • When editing a single project, click Add Media button that appears just below the title.
  • In the new window that pops up, click on Create Gallery on the left.
  • Select all the items from your Media Library that you wish to appear in the slider.
  • Click Create a new gallery in the bottom right.
  • You can then fine tune the order of the images along with some other options.
  • Finally, click Insert Gallery in the bottom right.

If you add more than one [gallery] to a page, all the images accross all galleries will be merged together to create the slider.

Shortcodes

Shortcodes are small text snippets that you can insert into your page, post or projects content. These shortcodes then get processed by WordPress and output to the front end. Shortcodes can be very powerful, with all the heavy lifting done by the theme and WordPress. Entering a seemingly simple shortcode can produce something much more functional and attractive to the front end.

Shortcodes are easily recognisable by their square brackets, e.g. [button]Click me[/button].

Shortcodes usually come in matching pairs. You might have noticed in the example above the button shortcode seemed to be mentioned twice. In fact this is all one shortcode, the first instance is known as the open, and the second instance the close. The subtle difference between an opening and closing shortcode is the addition of a forward slash at the start of the close. Everything between the open and close is the content of that shortcode. Take the button example above, which will output a button with the label 'Click me'.

It is crucial that this pattern is adhered to. Failure to do so will almost guarantee that your front end page will not turn out as you thought it would.

There are some shortcodes that only require an opening shortcode, for example [gap], a simple shortcode that inserts some white space into the page, useful for creating layouts and page structure. As the shortcode is fairly simple in its mechanics, it doesn't require any content, therefore it doesn't require a closing [/gap].

You can find out more information on all the specific shortcodes included within Metrolium by reading our extensive Shortcode Reference Guide

You can place shortcodes within shortcodes to create more advanced layouts and functions. However, due to a limitation with the WordPress core, there are certain restrictions to this. You cannot nest shortcodes within each other if they share the exact same name. For example, using the [box] shortcode, you can easily add a [button] inside like so: [box] [button] Click Me! [/button] [/box]. You cannot add another [box] within a [box]. As the shortcodes share the same name, WordPress incorrectly outputs the code on the front end, and is almost certain to look awful. For more information on nesting shortcodes, you can read the official WordPress documentation here.

Example Templates

Homepage 1 (Marketing)

Homepage 2 (Classic)

Homepage 3 (Product)

Homepage 4 (Corporate)

Homepage 5 (Magazine)

Homepage 6 (Portfolio)

Homepage 7 (Landing)

About Us

Contact Us

FAQ's

Jobs

Meet the Team

Testimonials

Services

Sliders

Within the Metrolium theme, there are two included premium slider plugins, LayerSlider and Slider Revolution. Both of these plugins are fantastically powerful and great at what they do.

For instructions on how to install and activate these two plugins, read the Suggested Plugins section

The documentation for both of these plugins is far beyond the scope for this documentation. However we have included links to the developers own documentation pages below.

LayerSlider

Taken from the LayerSlider codecanyon page:

This is the WordPress plugin of LayerSlider! You can create as many layers and sublayers as you want. You can use unlimited images with links. The script is very user-friendly, you can add global settings or local (per slide) settings to each layer or sublayer. You can change delay times, easing types, durations and much more.

You can view the LayerSlider documentation here

Slider Revolution

Taken from the Slider Revolution codecanyon page:

Create a responsive(mobile friendly) or full width slider with must-see-effects and meanwhile keep or build your SEO optimisation (all content always readable for search engines). See the heaps of custom transitions/animations for each object on the page! Customize this slider with our convenient drag&drop backend to your very needs.

This plugin features tons of unique transition effects, an image preloader, video embedding, autoplay that stops on user interaction and lots of easy to set options to create your own effects.

You can view the Slider Revolution documentation here

Updating Metrolium

The best way to update your theme is via the Envato WordPress Toolkit. We covered the envato toolkit in section 2.2.1.

By using the Envato WordPress Toolkit, the process of updating a theme is handled for you. The toolkit periodically checks to see if a new version is available, and informs you of any updates. Then it's just the simple task of clicking "Update" and the rest is done for you.

If you have the technical experience, you could update via FTP. This will require knowledge of your web servers FTP details, an FTP client along with knowledge of how to use it, and experience and knowledge in the best practices and processes of updating in order to protect yourself from technical or user error should something go wrong.

Updating live files via FTP has its risks. Things can go wrong so make sure you take proper precations when working via FTP by making backups and checking site functionality as you go to ensure everything is still working.

Shortcode Reference

Accordion

Accordions are great for showing a lot of content in a small space. Each accordion panel can be expanded to reveal the content inside. Each accordion should have a title.

Attributes
required title
string of characters

Band

Bands are a great way to organise content into different sections (bands) and bring emphasis and a creative flare to it. Choose from the default or alternative variates, both of which are highly configurable from with the theme customizer.

Attributes
variation
default, alternative
inset
yes, no
backgroundimage
URL to image resource
bordertop
shorthand css border value
borderbottom
shorthand css border value
paddingtop
value with units (e.g. 3px)
paddingbottom
value with units (e.g. 3px)

Blockquote

Create a page of client testimonials or display your favourite quote aswell as everything in between. Two styles to choose from, a simple blockquote or a testimonial.

Attributes
type
blockquote, testimonial
important author
string of characters
role
string of characters
image
URL to image resource

Blog

Display blog posts in a grid like fashion. Choose how many to show, how many column, what order and many other options.

Attributes
columns
2, 3, 4, 5
load
numeric value, or -1 to show all (4)
orderby
title, date, rand, random, menu_order, ID, author, none, modified, comment_count
order
asc, desc
category
comma seperated list of category slugs
post_format
comma seperated list of post format names
id
comma seperated list of post ID's
showimage
yes, no
showtitle
yes, no
showdate
yes, no
showexcerpt
yes, no
excerpt_length
numeric value above 0 (20)
boxed
yes, no
ShowBiz Attributes
showbiz
yes, no
sb_entry_size_offset
px value (0)
sb_container_offset_right
px value (0)
sb_height_offset_bottom
px value (0)
sb_carousel
on, off
sb_visible_elements_array
Defines how many entries are visible in the 4 different responsive levels (4,3,2,1)
sb_drag_and_scroll
on, off
sb_navigation_side
left, right, center

Box

Great for bringing emphasis to a section of content. Choose any background colour, border colour and even make the box look inset into the page or outset on top of the page.

Attributes
borderradius
value with units (e.g. 3px)
padding
shorthand css padding value

Break

For adding line breaks in blocks of text to fine tune typographic layout and flow

Button

Hyperlink to any URL or resource online whilst picking from three preset colour ways, or provide a hex colour for compete control. You can easily link to internal WordPress resources simply by passing it the ID of the object. You can also link to any external resource by passing it the full URL.

Attributes
important link
URL or Object ID (#)
size
xsmall, small, medium, large
colour
gray, black, red, orange, yellow, green, blue, pink, purple
target
_blank, _self, _parent, _top

Callout

Entice your visitors to perform an action with the callout shortcode.

Attributes
important title
string of characters
icon
FontAwesome icon name (minus 'icon-' prefix) reference
boxed
yes, no
important buttontext
string of characters
buttonsize
xsmall, small, medium, large
important buttonlink
URL or Object ID (#)
buttontarget
_blank, _self, _parent, _top

Clear

Useful for fine tuning layouts. For a very technical and detailed explanation on what clearing means, view this page.

Gap

Handy for fine tuning the horizontal space between page elements without adding any visual clutter. The default height is 10px tall, but this can be easily changed to provide a larger gap.

Attributes
height
numerical value without units e.g. 20 (10)

Horizontal Rule

Great for organising content and pages into sections. Choose from three styles, a simple line, an elegant and subtle shadow effect or a line with an icon in the middle to add a more descriptive content divider.

Attributes
style
line, icon, shadow
icon
FontAwesome icon name (minus 'icon-' prefix) reference (star)

Icon List

Very similar to the standard un-ordered and ordered lists you might be familiar with, but this list enables you to specify icons for each individual item. If no icon is specified it defaults to a tick.

Attributes
icon
FontAwesome icon name (minus 'icon-' prefix) reference (ok)

Lead

Highlight the start of a page or blog post the with lead shortcode.

Notice

Have anything you want to be particulary visible to the customer? Perhaps they have just completed a form succesfully, or you performing some maintenance on the site and you want to let customers know.

Attributes
type
error, success, warning, default

Person

Great for constructing a team members page. All social links and emails are optional.

Attributes
important link
URL
boxed
yes, no
important image
URL to image resource
important name
string of characters
role
string of characters
email
email address
twitter
full URL to Twitter profile
facebook
full URL to Facebook profile
linkedin
full URL to LinkedIn profile
googleplus
full URL to GooglePlus profile

Portfolio

Display portfolio projects in a grid like fashion. Choose how many to show, how many column, what order and many other options.

Attributes
columns
2, 3, 4, 5
load
numeric value, or -1 to show all (4)
orderby
title, date, rand, random, menu_order, ID, author, none, modified, comment_count
order
asc, desc
category
comma seperated list of category slugs
id
comma seperated list of post ID's
showtitle
yes, no
showdate
yes, no
ShowBiz Attributes
showbiz
yes, no
sb_entry_size_offset
px value (0)
sb_container_offset_right
px value (0)
sb_height_offset_bottom
px value (0)
sb_carousel
on, off
sb_visible_elements_array
Defines how many entries are visible in the 4 different responsive levels (4,3,2,1)
sb_drag_and_scroll
on, off
sb_navigation_side
left, right, center

Pullquote

Highlight a quote or short sentence from a page or blog post by pulling it either left or right within the page and adding some colour. The rest of the article wraps around the pullquote giving it a great look.

Attributes
align
left, right

Row/Columns

Attributes
important width
one-half, three-eighth, four-tenth, one-third, etc
offset
one-half, three-eighth, four-tenth, one-third, etc
linearise
yes, no

Tabs

Tabs are great for showing a lot of content in a small space. Flick between tabs to reveal the underlying content. You can also add an optional icon to each tab.

Attributes
required title
string of characters
icon
FontAwesome icon name (minus 'icon-' prefix) reference

Tag List

Teaser

A teaser is a great way to construct a portal page that will help your visitors get to where they want to go faster, wheather its a list of your services, products or any other sub page.

Attributes
important title
string of characters
important link
URL or Object ID
important image
URL to image resource
boxed
yes, no
target
_blank, _self, _parent, _top

Sources & Credits

  • LayerSlider - Responsive WordPress Slider Plugin
  • Slider Revolution - Responsive WordPress Slider Plugin
  • FlexSlider - An awesome, fully responsive jQuery slider toolkit.
  • FitVids - A lightweight, easy-to-use jQuery plugin for fluid width video embeds
  • TGM Plugin Activation - an efficient way to allow WordPress theme authors to reference and include required plugins within their themes.