glFusion Wiki

Site Tools


glfusion:styling:custom_theme

Customizing Themes

There are two ways you can create a custom theme for your site:

  • Customize one of the existing themes - there is where you make small tweaks to the theme to meet your needs
  • Create your own theme - this is where you would have your own theme name and make customizations to meet your needs

If you just want to change the colors of the theme, it is probably best to simply customize one of the existing themes. There are several hooks that allow you to customize an existing theme:

  1. custom.css - this is where you can put your own custom styles - a great place to override the default colors of a theme.
  2. custom/ templates - if you just need to tweak a few templates (for example the story layout), you can copy the original template to the custom/ directory in the theme and make your changes there - this way you only need to update the few customized templates when you upgrade.

Tweaking a Theme

The easiest way to customize the look and feel of your site is to start with one of the base themes and simply tweak the things you want to change.

custom/ directory for templates

glFusion allows you to customize the theme template (.thtml) files without actually modifying the original files. This allows you to make your customizations with confidence that they will not be overwritten during an upgrade. glFusion does this by including a folder named custom in every directory where there are .thtml files. The template engine will first look in these custom directories for files, then in their regular locations, when building the page.

To customize a template, first copy it into the custom folder in the same directory, then make your modifications to that newly copied file.

To customize a template file located in the theme directory (i.e.; layout/cms/) copy the file to custom/ directory:

public_html/layout/cms/storytext.thtml

Copy to:

public_html/layout/cms/custom/

Plugins are handled a little differently. Since plugins have their templates files in the private/plugins/<plugin_name>/templates directory - we have do something slightly different. Below is an example:

private/plugins/<plugin_name>/templates/

copy the .thtml file into its /custom folder, or to create a theme specific version of that plugin file, copy it into the

public_html/layout/<theme_name>/plugins/<plugin_name>/ directory.

Notice we copied it from the private/plugin/<plugin_name>/templates/ directory over to the Theme directory in public_html/<theme_name>/plugins/<plugin_name>/ directory. This allows you to have custom plugin templates per theme.

Example

If you want to change the story layout, the template is storytext.thtml.

You could do the following:

  1. Copy the original storytext.thtml to the custom/ directory
  2. Edit the custom/storytext.thtml file and make your changes
  3. That is it!

Now, glFusion will use your custom template when displaying a story.

See How Do I Know What Template To Change below for more information on finding the right template to tweak.


custom.css - your customized styles

If you want to change some of the CSS styles, for example, to change the color of the header or menu, you can create a custom.css in the public_html/themename/ directory. All you need to put into the file are the styles you want to customize. There is a custom.css.dist file already in the directory that you can rename and edit.

Here is an example of how to change the header menu background to red:

.tm-navbar {
    background: #a11 none repeat scroll 0 0;
}

That's it - all you need to do is put this one style in your custom.css and now glFusion will use your .tm-navbar style to style your page.


uikit Styles

glFusion uses UIKIT as the UI framework. UIKIT offers 3 variations of styles, flat, almost-flat, and gradient. By default, glFusion's CMS theme uses the gradient style.

Flat

Almost Flat

Gradient

Changing the UIKIT Style

You can easily change from the gradient style to one of the other styles offered by UIKIT. The configuration setting is stored in the siteconfig.php file, located in the public_html/ directory of your site. Edit siteconfig.php and look for the $_SYSTEM['style_type'] setting.

$_SYSTEM['style_type'] variable in siteconfig.php

Valid settings are:

flat Set to just a period - '.'
almost-flat Set to '.almost-flat.' - Notice the periods that surround almost-flat
gradient Set to '.gradient.' - Notice the periods that surround gradient

Once you make the change in your siteconfig.php file, you will need to go into Command & Control and choose Clear Cache to ensure the cache files are rebuilt using your new style.


Theme's functions.php

Every theme must include a functions.php file. This file is responsible for setting up various configuration items for a theme. There are several options in functions.php which we'll document below.

If you want to change any of the default settings, you can create a custom/functions.php (there is a custom/functions.php.dist file included already that you can rename) where you only need to put your customizations.

$themeAPI This should always be set to 3
$_SYSTEM['framework'] Which UI framework does this theme use. Currently 'uikit' or 'legacy' are valid options. If you were to create a theme based on the Bootstrap framework, you would put 'bootstrap' here.
$_SYSTEM['disable_mootools'] Generally, this should always be true, glFusion now uses jQuery as the JavaScript library of choice.
$_IMAGE_TYPEThe image type extension to use. If you wanted to restyle all the images/ and change to jpg, place jpg here.
$_SYSTEM['disable_jquery_menu']FIXME - Add description
$_SYSTEM['disable_jquery_slimbox']FIXME - Add description

$uiStyles

The $uiStyles variable is used to define which UIKIT styles are used to control the page layout. There are 4 options available:

full_contentNo left or right columns
left_contentLeft column display and the center content column, no right column
left_content_rightLeft, Content, and Right columns are visible
content_rightContent and Right columns are visible

You can change which UIKIT classes are used to tweak the overall page layout. Keep in mind, the CMS and UIKIT themes shift the column layouts, so they map like this:

left_column → shifts to the right side of the screen right_column → Not used by the CMS or UIKIT themes - any blocks or content configured to show in the right column will display in the footer area.

See uikit's Grid Documentation for more information on how you can adjust the grid layout to meet your needs.


Custom .css or .js files

You can add custom or additional CSS or JavaScript files that will be loaded with each page load by adding new load lines:

  $outputHandle->addCSSFile(path to the CSS file);
  $outputHandle->addScriptFile(path to JS file);

glFusion will include these files in the style.cache.css or js.cache.js files and they will be loaded for all pages in glFusion.

We do our best to document all the changes we make to the templates and style.css files for each release. The Template Changes wiki page is always kept up-to-date for each release.

Remember, you only need to include the things you want to change in your custom/functions.php file.

If you only want to change the UI style to gradient, this is all you need in your custom functions.php file:

<?php
 
// this file can't be used on its own
if (!defined ('GVERSION')) {
    die ('This file can not be used on its own!');
}
 
// change the layout to a 6 column grid
 
$uiStyles = array(
    'full_content' => array('left_class' => '',
                            'content_class' => 'uk-width-medium-6-6',
                            'right_class' => ''),
    'left_content' => array('left_class' => 'uk-width-medium-2-6',
                            'content_class' => 'uk-width-medium-3-4',
                            'right_class' => ''),
 
    'left_content_right' => array('left_class' => 'uk-width-medium-2-6',
                                  'content_class' => 'uk-width-medium-4-6',
                                  'right_class' => ''),
 
    'content_right' => array('left_class' => '',
                             'content_class' => 'uk-width-medium-6-6',
                             'right_class'  => '')
);

How do Upgrades affect your customizations

By creating copies of templates in the custom/ directory and / or creating a custom.css file, we are protecting these files from being overwritten during a glFusion upgrade. glFusion does not include any custom/ files or a custom.css, so your customizations are safe from being overwritten.

There are times where we make changes to some of the templates you have customized. For example, with glFusion v1.6.3, we updated the storytext.thtml template. You will need to review the Template Changes for each release and if you have a custom/ copy of any of the updated templates, you'll need to make the changes to your copy.

How do I know What Template to Change?

glFusion themes have a lot of templates! Sometimes it can be difficult to find the right one to make a change. There are a few tools and tricks to help you find the right template.

Every template has a {# begin {templatelocation} #} and {# end {templatelocation} #} line at the beginning and end of the template file. You can use this to help locate what template is creating the content. You need to set the configuration option Include Template Comments in Page Source (located in Configuration → Theme → Advanced Settings) to true. This will include the begin / end lines in the page source.

Once you have the template comments enabled, you can now do a 'View Source' in your browser to see the raw HTML that glFusion produced for your page. You can now search for the area you want to customize, the find the <!– begin /home/www/templatename_goes_here –> line. Here is an example of finding the story title header:

  1. View the page that you want to customize
  2. Right Click on the page, select 'View Page Source'
  3. In the source page, find the content
  4. Look for the begin template line:
<!--  begin /home/www/dev.glfusion.org/public_html/layout/cms/featuredstorytext.thtml  -->
<div class="infinite-item">
  <article class="uk-article tm-article uk-margin-small-bottom">
    <header>
      <h1 class="uk-article-title tm-article-title uk-margin-bottom-remove">glFusion v1.6.2 Now Available!</h2>
      <h4 class="uk-margin-top-remove">
        <span class="tm-italic">Magical and Mystical!</span>
      </h4>

As we can see in the example above, the <!-- begin /home/www/dev.glfusion.org/public_html/layout/cms/featuredstorytext.thtml --> line is right before the story title - so I now know that I want to edit the featuredstorytext.thtml template to change how the title is presented.

Creating Your Own Theme

If you want to create your own theme, there are some hooks in place that helps you focus on just the areas you want to customize. A custom theme does have some requirements that it contains some core files required by glFusion.

To create a custom theme - create a sub-directory under the public_html/layout/ directory where the directory name will be the name of your theme. For this example, we'll use cms-custom as our theme name.

The following files are required to be in the cms-custom/ theme - it is probably best to simply copy these from the stock CMS theme and use them as a starting point:

css/
This directory contains all the CSS files from UIKIT.
fonts/
This directory contains the font files used by UIKIT
images/
This directory contains images used by the theme. This includes the Command & Control icons and several other images used throughout glFusion
js/
This directory contains the theme specific JavaScript files, including JavaScript for UIKIT
functions.php
Every theme must have a functions.php file which controls several options for the theme. See the functions.php documentation above. You can copy the functions.php from the CMS theme to get started.
css.php
Every theme must have a css.php file. This file is what loads the stylesheets. Generally, you do not need to edit or customize this file, but you do need to have a copy in your theme directory. Copy the css.php from the CMS theme.
js.php
Every theme must have a js.php file. This file is what loads the JavaScript. Generally, you do not need to edit or customize this file, but you do need to have a copy in your theme directory. Copy the js.php from the CMS theme.
style.css
Every theme must have a style.css. You can copy the one from the CMS theme or one of the other themes to get started and customize it to meet your needs.

Everything else, glFusion will first look in cms-custom/ directory, if not found, it will fall back to cms/. This allows you to only include the templates that you need to customize for your theme.

You can now copy over the templates you wish to customize and setup everything to meet your needs.

glfusion/styling/custom_theme.txt · Last modified: 2017/04/12 21:11 (external edit)

Page Tools