Create a helper module for ProcessWire to generate FontAwesome icon markup

2014/01/15 10:56 PM • ProcessWire • Tutorial • Comments (1)

In this simple tutorial we gonna create a little module step by step that will help us deal with creating FontAwesome icons in our template markup. You'll be able to use it for also for other purposes and expand on it. Maybe it will help you understand a little better what can be archived with a simple module in ProcessWire.

This tutorial won't go into too much detail on how ProcessWire modules work. There's a lot of different types of modules that can be created and if you know a little more about the subject you might already found out or read that ProcessWire itself is built on a very clever modular stucture. Most of the admin back-end is built out of many modules that work together in some way.

So without further keeping you confused, let's start. You should be already a little familiar with how modules are created and where they are located and how they're installed.

Preparing the files

Let's create a new module and name it "MyHelper". Create a new folder, although you don't need to, in site/modules/ and we gonna call it "MyHelper". Within that folder we added, create a new file called MyHelper.module.

The basics

For the task of what want to achieve we need a simple WireData module. This means we create a new PHP Class that extends WireData. You don't need to fully understand what this means for the moment. It's just some base Class where already some methods are present we can use. Also since there's some sort of convention implemented in module Classes, we have to implement the Module interface of ProcessWire. This is to make sure all modules that implement this abstract Class are required to have certain methods. In this case it's the getModuleInfo() and the init() method. This is required by all modules, so that the system know some basic informations about your module.

So let's get our hands dirty. Add or write the following code to your newly created MyHelper.module :

<?php

class MyHelper extends WireData implements Module {
    // module code
}

This is the wrapper that defines our new Class or module. If you would install this module, you'd see ProcessWire throw an error that the abstract Module Class requires some static methods. That's namely the getModuleInfo() and init() method. Ok, so then now let's add the getModuleInfo() and the init() method.

<?php

class MyHelper extends WireData implements Module { 
    /** 
     * getModuleInfo is a method required by all modules to tell ProcessWire about them 
     * @return array 
     */ 
    public static function getModuleInfo() {
        return array(
            'title' => 'My Helper Module',
            'version'=> 1,
            'summary' => 'Example Helper Module to generate FontAwesome icon markup.',
            'author' => 'me',
            'singular' => true,
            'autoload' => true
            );       
    }
    
    public function init() {
        // yet empty
    }
}

The important part here is the 'autoload' => true in the module info array. This just tells ProcessWire to load this module on every request. Since we want out module to help us throughout the whole website, we set this to true. This could also be set to false, and we could load the module in our templates only where we need it with $modules->MyHelper->myMethod(). But we will use a technique that we will get into in a moment.

Adding the meat

Now comes the fun part. Let's say we want our module to output FontAwesome icon markup, we might need a way to handle the prefix "fa" it uses. Let's add a local property to the module. This can be set and defined for example in the init() method. To do this add we add the following line to the init()method:

$this->set("icon_prefix", "fa");

This adds the property icon_prefix to our helper module, so we can use this later in our module. Of course this is something we could leave out and handle directly by the markup we going to generate later, but for the sake of learning we do it this way.

Now, since our module is autoload, it would also be cool if we could maybe create a handy new template variable like $helper! In ProcessWire we can do this by doing the following. Add the following line also to the init() method:

wire("fuel")->set("helper", $this);

What this does, is add a new system variable $helper that will be available everywhere in ProcessWire. Like the variables $page or $pages we all know. Fuel is used to do that, and we simply set the value of this variable with $this, which means this module will be presented by this new variable. 

Now, let's add some method to generate our icon markup required by FontAwesome. We simply add a new public method let's say faIcon(). With this we want to generate and return markup like: <i class='fa fa-iconame'></i>. 

public function faIcon($name, $size = '') {
    if($size) {
        $size = " {$this->icon_prefix}-$size";
    }
    return "<i class='{$this->icon_prefix} {$this->icon_prefix}-$name{$size}'></i>";
}

(Here you can also see the property we added earlier to our class $this->icon_prefix being used.)

So to summarize, this method accepts two arguments. First being the name of the icon like "fa fa-name" and second the size of the icon. This is made optional by giving it a default value of ''. This can be handy if you want to give the icon a different size. So in this method we have some code to check if $size is anything and prepare it to be appended to the class. In case of FontAwesome this are those fa-2x etc you can see on their docs. At the end we return the string we constructed so we can output it in our template code.

We've done it, let's use it

Awesome! Now we are already finished with our module and can use it in our templates. Since we added this method as public we can now use, if installed, the $helper variable in our template like this:

// output the i markup with a shopping cart icon
echo $helper->faIcon("shopping-cart", "2x");
// outputs: <i class="fa fa-shopping-cart fa-2x"></i>

// or another example
echo "<p><a href='$somepage->url'>{$helper->faIcon('bars')} Menu</a>";
// outputs: <i class="fa fa-bars"></i>

This can be very handy, and you don't have to write the markup everytime you need it. Further if the markup of prefix of FontAwesome changes you can simply modify your helper class and everywhere you used it will be updated.

Module completed

Finishing this tutorial with the complete code and a link to a gist I created. Thanks for staying with me, and I hope it was useful and you learned one or two things. Happy wiring!

<?php

class MyHelper extends WireData implements Module {
    /**
     * getModuleInfo is a method required by all modules to tell ProcessWire about them
     * @return array
     */
    public static function getModuleInfo() {
        return array(
            'title' => 'My Helper Module',
            'version'=> 1,
            'summary' => 'Example Helper Module to generate FontAwesome icon markup.',
            'author' => 'me',
            'singular' => true,
            'autoload' => true
            );
    }

    public function init(){
        $this->set("icon_prefix", "fa");
        wire("fuel")->set("helper", $this);
    }

    public function faIcon($name, $size = ''){
        if($size){
            $size = " {$this->icon_prefix}-$size";
        }
        return "<i class='{$this->icon_prefix} {$this->icon_prefix}-$name{$size}'></i>";
    }

}

Download

Gist snippet: https://gist.github.com/8446801

2014/01/15 10:56 PM | ProcessWire | Tutorial

Comments

  • Jens Martsch 2014-01-16 12:52:33

    I really like this. Great work.