The Basics of Craft Plugin Development

By: Adam McCombs | Founder at Taecho

Published Feb 2, 2016 | Last Updated Feb 16, 2016

Tech Reviewed by Lindsey DiLoreto | Edited by Terry Martinez


Craft includes some amazing functionality out of the box but if you're looking to extend Craft, it's as easy as building a simple plugin. In this tutorial, we'll build a plugin to output your usual "Hello World" variable.

TL;DR - Download our Hello World Craft plugin from github.

What can Plugins do? #

Craft plugins cover a variety of uses, including outputting variables (like "Hello World"), creating admin interfaces, use of custom fields and any complex functionality beyond what the Twig templating allows for on the front end.

The Plugin Name and Handle #

One of the most important parts of building your Craft plugin is picking a plugin name that is easy to work with. Craft is case and structure sensitive when it comes to plugins and all of your related plugin files.

For the purpose of this tutorial, we're going to name our plugin "Hello World." This is going dictate a few different things.

The Primary Plugin Class #

The primary plugin class is where all the magic happens. This is the only required file for a plugin to function and it registers your plugin with Craft, allowing it to be installed and enabled/disabled. We're going to name this file HelloWorldPlugin.php and place it inside our helloworld plugin folder. 

Lets take a look:

<?php
namespace Craft;
class HelloWorldPlugin extends BasePlugin
{
    public function getName()
    {
        return Craft::t('Hello World');
    }
    public function getVersion()
    {
        return '0.1';
    }
    public function getDeveloper()
    {
        return 'Craft Plus';
    }
    public function getDocumentationUrl()
    {
        return 'https://github.com/CraftPlus/Hello-World';
    }
    public function getDeveloperUrl()
    {
        return 'https://craftpl.us/';
    }
    public function hasCpSection()
    {
        return false;
    }
}

Now you can review each of the methods available in the Craft docs. Let's look at some important ones:

getName()

This function sets the user facing name that will be displayed within the Craft admin panel. Wrapping the name inside Craft::t() will allow the Name to translated for internationalization.

hasCpSection()

This function, set to true or false, determines if the plug has a control panel area. While not applicable for this tutorial, if set to true, your plugin name and icon will display within the Craft admin panel and reference files in your /templates folder.

Tip: If you've created your plugin folder and primary plugin class and your plugin still doesn't display in the admin, double check the spelling and case of the plugin folder, the primary plugin class file name and the actual class.

The Variable File #

Once you've got your primary plugin class created, let's move on to creating our variable folder and file. Inside your helloworld plugin folder, create a /variables folder (make sure to include the s on the end - variables, not variable).

Inside our /variables folder create a new file called HelloWorldVariable.php (remember CamelCase is important).

Inside this file we will create our Class that will register this variable file. It will look sometime like this:

<?php
namespace Craft;
class HelloWorldVariable
{
}

Notice that the HelloWorldVariable class matches the file name. It's important that these match so the variable class gets registered correctly.

Now let's add a function so we can output our hello world variable. The file should look something like this:

<?php
namespace Craft;
class HelloWorldVariable
{
    public function hello()
    {
        return "Hello World";
    }
}

Outputting Hello World #

So far, we've created a primary plugin class and a variable file with our first function. 

Lets look at outputting our variable: 

{{ craft.helloWorld.hello }}

Inside the double bracket variables are broken down into 3 different elements. 

Craft initiates craft. This works just as if you were working with entries: craft.entries.section.

helloWorld references our plugin (remember CamelCase).

hello references the function we created in our variables file.

Go ahead and paste the following code into your index.html file or any other twig template.

{{ craft.helloWorld.hello }}

If all goes well you should see Hello World when you refresh your browser. 

Congrats! You've created your first craft variable! Now get to crafting.



Want great tutorials like this in your inbox?

Sign up for our newsletter!

Click to subscribe

Already working with Craft?

Checkout these awesome plugins!