glFusion Wiki

Site Tools


glfusion:uikit

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:

  • Enable / disable various JavaScript framework items.
  • 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
  • Loads UIKIT JavaScript components
  • Loads custom.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 */.
  • UIKIT core framework – by default, we load the minimized version of each file – you may wish to load the non-minimized version during theme development / testing. To do this - you would remove the min. from the file names below.
$outputHandle->addCSSFile($_CONF['path_layout'].'css/uikit'.$styleType.'min.css');
$outputHandle->addCSSFile($_CONF['path_layout'].'css/components/accordion'.$styleType.'min.css');
...

Getting Started

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.

Stylesheets (.css)

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:

  1. UIKIT Framework Style Sheets
  2. custom.css
  3. Plugin Style sheets

glFusion Theming Basics

There are three (3) main components to a theme:

  • Templates
  • CSS Styles
  • PHP Code

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.

UIKIT Framework

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.

Class Description
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-panel-navigation
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-table Tables
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&#039;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&#039;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"/>
</head>
<body>
 
 
<nav class="uk-navbar tm-navbar">
  <div class="uk-hidden-small">
<!--  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">
</a>
<!--  end c:/www/site.glfusion.org/public_html/layout/cms/logo-graphic.thtml  -->
</div>
 
  <!--  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

The best way to learn how CSS styles affect the page or to see what styles are being applied to a particular item is to use the Firebug plugin for Firefox Browser. There is an excellent article that goes over some of the benefits of these tools: http://www.techrepublic.com/blog/software-engineer/debug-javascript-html-and-css-with-firebug/

Firebug allows you to see (and change) a style that is applied to an element.

Good video on using Chrome's Dev Tools to debug HTML / CSS - https://www.youtube.com/watch?v=Z3HGJsNLQ1E

Chrome Dev Tools - https://developer.chrome.com/devtools/docs/elements-styles

https://developer.chrome.com/devtools

https://developers.google.com/web/tools/chrome-devtools/

Edit / Inspect styles with Chrome - https://developers.google.com/web/tools/chrome-devtools/inspect-styles/edit-styles

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:

  • htmlheader.thtml
  • header.thtml
  • content here…
  • rightblocks.thtml
  • footer.thtml

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

glfusion/uikit.txt · Last modified: 2017/04/12 21:09 (external edit)

Page Tools