glFusion UIKIT Base Theme
With glFusion v1.5.0, we are moving towards standardizing the glFusion theme engine to the UIKIT Framework. UIKIT is a flexible framework that fits nicely with the needs of glFusion.
Definition of Themes
glFusion ships with the CMS theme. This is the default theme that is based on the UIKIT Framework.
The is designed to be a starting point for creating your own theme. It is very basic in colors and has a standard 2 column layout (content → right blocks). It could be used to power a glFusion site, but it was designed to give a starting point for creating new themes.
Note – there was a ‘packaging’ issue when I release UIKIT Framework Base theme v1.0 – it included both a uikit/ directory and uikit-theme/ directory. For the v1.0.1 release, it is now just the uikit/ directory, which is what should be used going forward.
How glFusion handles Themes
The heart of themes in glFusion is the functions.php file located in the theme directory. functions.php controls how certain things work in a theme.
The functions.php handles the following:
Multi Language Feature
Block template overrides
Default styles to use for left / right / content sections of the page
Block location / language settings
Defines UIKIT style Type (i.e.; gradient, almost-flat, normal)
Loads core UIKIT Framework CSS
Loads UIKIT Framework component CSS
This gives a ton of flexibility, but it also drives some complexity. Fortunately, most folks will only need to tweak one or two things above and can leave the rest as they are. Below we will document the settings that are key to customizing or modifying a UIKIT based theme.
The important ones to focus on for theme customization are:
UIKIT Style Type – if you use the UIKIT Customizer, knowing which style type you are using will help ensure you get the right UIKIT customized CSS
file in place.
$styleType = '.gradient.'; /* almost-flat - gradient - blank */
The UIKIT framework theme is really meant to be a starting point to customize your site. While it can be used as the primary theme for your site, you should consider customizing it for a unique look and feel.
At first look, theming a glFusion site can appear to be a very intimidating process. There are several parts to a theme and it can be a challenge to understand how it all works. Fortunately, it isn't all that difficult when you break it down into small pieces and understand how they all work and fit together.
glFusion uses lots of style sheets! Each has a specific function and it is important to understand the order things are loaded.
style.css - This is the primary style sheet and it is loaded first. This means if you want to override a style for a style sheet loaded after this one (like the UIKIT framework style sheets), you must specify the
!important attribute on the style.
After the primary style sheet is loaded - the following are loaded in the order below:
UIKIT Framework Style Sheets
Plugin Style sheets
glFusion Theming Basics
There are three (3) main components to a theme:
Don't worry, you do not have to be a PHP programmer to create or customize a theme. We've taken care of all that for you. You do need to have an understanding of HTML and CSS.
Templates hold the HTML that is used to display the pages.
CSS Styles control how things look (i.e.; colors, bold, layout, etc.)
PHP Code is used to create template variables that you use in your templates and also to set a few customizations' such as where blocks display, etc.
It is advised that you spend some time understanding the basics of the UIKIT Framework before you try to customize a glFusion theme. For more information on the features and capabilities of UIKIT, please refer to the UIKIT Framework Documentation.
The UIKIT Framework team has also provided an online customization tool to allow you to easily customize the colors, fonts, and other attributes of the framework.
Additional Customization Options
We have included several tm-* (tm stands for theme) styles in the base UIKIT theme to allow you to easily make minor customizations to the theme without having to use the customizer tool. The goal is to standardize these classes for use in all themes.
NOTE: There are several other styles available in the style.css. It is recommended you review the theme style.css for more information.
|tm-container ||Wrapper for content area - excludes header / footer
|tm-navbar ||Navbar styles
|tm-navbar-brand ||Navbar Brand style
|tm-dropdown ||Navbar dropdown - includes other dropdowns beyond navbar
|tm-navigation ||The right blocks on the page
|tm-container-extra ||Footer block
|tm-article ||Article wrapper
|tm-article-title ||Article Title
|tm-article-footer ||Article Footer
|tm-featured-article ||Featured Article Wrapper
|tm-article-meta ||Article meta data (i.e.; author, date)
|tm-comment ||Comment wrapper
|tm-comment-header ||Comment header
|tm-comment-avatar ||Comment user photo
|tm-comment-title ||Comment title
|tm-comment-body ||Comment Body
|tm-follow ||Follow us buttons
|tm-block-bottom ||Bottom Block wrapper
|tm-admin-navbar ||Administration nav bar
Obviously, you can use the style.css or custom.css to override or setup any of your own styles or classes.
How to tweak a theme
glFusion utilizes templates to build the final web page that is displayed. Generally, multiple templates are used to build a single page. For example, there is a template specifically to handle the header section and another template to handle the footer. The blocks (left / right or bottom) are also comprised of many templates.
It can be difficult or even overwhelming to know which template file should be modified to achieve a desired style change. Using some simple tricks and tips, it is actually much easier than you might think.
How to Find the Right Template
The first thing you should do is to enable Template Comments in the glFusion configuration (Command & Control → Configuration → Theme → Advanced Tab). Set Include Template Comments in Page Source to True.
When you now view a page on your site, you can use the View Source option of the browser to see the actual HTML code. With the HTML code, you can see where templates are used. See the example below:
<!-- begin c:/www/site.glfusion.org/public_html/layout/cms/header.thtml -->
<meta property="og:site_name" content="glFusion+CMS"/>
<meta property="og:locale" content="en_US"/>
<meta property="og:title" content="Fighting BOTs and spammers"/>
<meta property="og:type" content="article"/>
<meta property="og:url" content="http://site.glfusion.org/article.php/fighting_bots"/>
<meta property="og:description" content="Over the past couple of weeks, we've all seen the BOT traffic increase
on our websites. Many of us saw a large number of BOTs..."/>
<meta name="description" content="Over the past couple of weeks, we've all seen the BOT traffic increase
on our websites. Many of us saw a large number of BOTs..."/>
<link rel="stylesheet" type="text/css" href="http://site.glfusion.org/layout/cms/css/ui-uikit/jquery-ui-1.10.4.custom.min.css"/>
<link rel="canonical" href="http://site.glfusion.org/article.php/fighting_bots"/>
<nav class="uk-navbar tm-navbar">
<!-- begin c:/www/site.glfusion.org/public_html/layout/cms/logo-graphic.thtml -->
<a class="uk-navbar-brand tm-navbar-brand uk-hidden-small" href="http://site.glfusion.org">
<img class="uk-margin uk-margin-remove" src="http://site.glfusion.org/images/logof2e5b4c5.png" width="140" height="30" title="glFusion CMS" alt="glFusion CMS">
<!-- end c:/www/site.glfusion.org/public_html/layout/cms/logo-graphic.thtml -->
<!-- horizontal cascading menu template -->
<ul class="uk-navbar-nav tm-navbar-nav uk-hidden-small">
In this example, you can see several <!—begin… → and <!—end …> statements. Notice the part that is highlighted in yellow, you can clearly see the site logo is styled using the logo-graphic.thtml template file. Now you know to make changes to the logo, which template you need to work with.
This trick is helpful and it will assist in locating the right template. Keep in mind, templates are many times nested within other templates, again looking at the example above, we can see the
<!– begin c:/www/site.glfusion.org/public_html/layout/cms/header.thtml –> for the header.thtml, notice we do not see a corresponding
< –!end > line for header.thtml before we find the
<! – begin for logo-graphic.thtml. This means that logo-graphic.thtml is nested by header.thtml.
How to Change / Debug CSS
How Pages are Displayed
As we mentioned earlier, template files (.thtml extension) have the HTML used to display a page. Generally, it takes several template files to create a page. Think of it as a sandwich, we layer template files together to build the final page. Just like a sandwich has bread on both sides, this is similar to a page header and footer. What goes in the middle depends on what content is being displayed. For example, the main index page consists of several template files that are assembled by the glFusion code to create the page:
Now, let's take a closer look at the site header - we'll see that it is made up of several more templates:
As we can see, there are several templates in use. htmlheader.thtml contains the actual HTML to start the page. header.thtml holds the visual components. header.thtml also includes content from logo-text / logo-graphic.thtml (this is the logo in the upper left corner of the screen).