Creating a Journey Plugin

What are Plugins?

Journey plugins are Lua scripts that will be executed when a custom helper in your theme is called.

Consider the following line in a .hbs file within your theme:

<h1>{{customheader}}</h1>

The customheader helper is not part of the standard repertoire of Journey. The helper will output an empty string, which means the above line will be rendered as:

<h1></h1>

However, once you write a plugin in Lua, put it in your /path/to/journey/content/plugins directory, and register it as the customheader helper, the above line could look like this:

<h1>The string your Lua script returns from its customheader function</h1>

How to Write a Plugin

A plugin only needs to implement two functions to be fully operational:

register()

which needs to return a table of strings and

helpername()

which needs to return a string. helpername needs to be replaced with the name of the helper you'd like to implement. customheader in the above case.

A Basic Example

Let's write a plugin that implements the customheader helper.

Create a new directory named headerplugin in /path/to/journey/content/plugins.

Create a new file in /path/to/journey/content/plugins/headerplugin and name it customheader.lua.

Paste in the following code

-- This function registers our plugin with Journey and tells it which helpers should be handled by the plugin.
function register()
	return {"customheader"}
end
-- This function gets called every time Journey needs the customheader helper.
function customheader()
	return "This is great!"
end

and save the file.

Here's what you just did:

• You created the register function which needs to return a table with the names of the helpers you want this Lua script to implement.
• Then you created the customheader function which gets called every time an .hbs template with the {{customheader}} helper is rendered. That function needs to return a string. That string will replace the helper in the source of the rendered html page.

Now restart Journey to load the plugin. Assuming that you have a theme with the following line in a .hbs file:

<h1>{{customheader}}</h1>

that line will now be rendered as:

<h1>This is great!</h1>

Loading External Modules

To write complex plugins you probably want to import modules into your Lua script. It's a good idea to keep those modules in a sub folder of your plugin directory to make the plugin portable.

Let's say you have a module in a sub folder relative to your .lua file: mymodule/mymodule.lua with the following content:

local mymodule = {}

function mymodule.foo()
    return "foo!"
end

return mymodule

To import Lua files from a sub folder, you need to add that folder to the package.path. To get the current directory of a Lua script at runtime, Journey plugins can use the getCurrentDir() function:

-- Adding the directory of our module to the path.
package.path = getCurrentDir() .. "/mymodule/?.lua;" .. package.path
-- Loading our module.
MM = require "mymodule"
-- This function registers our plugin with Journey and tells it which helpers should be handled by the plugin.
function register()
	return {"foo", "bar"}
end
-- This function implements the foo helper and uses our module.
function foo()
	return MM.foo()
end
-- This function implements the bar helper.
function bar()
	return "bar!"
end

Functions To Interact With Journey

To get information out of Journey, you can use the following functions in your plugin:

• getCurrentDir(): Returns the directory of the current .lua file as a string.
• print(argument): Prints its argument to the Journey log.
• getNumberOfPosts(): Returns the number of posts attached to the currently rendering page as an integer.
• getPost(index): Returns the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getAuthorForPost(index): Returns the author of the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getTagsForPost(index): Returns the tags of the post at the given index. (index must be an integer equal to or smaller than the one returned by getNumberOfPosts(). Note: The index starts with 1, as that is the Lua way.)
• getBlog(): Returns the blog data.
• getArguments(): Returns the arguments attached to the helper.

Data Types Returned by Functions

Post

table:

{ ["id"] = number, -- always an integer
["uuid"] = string,
["title"] = string,
["slug"] = string,
["markdown"] = string,
["html"] = string,
["isfeatured"] = boolean,
["ispage"] = boolean,
["ispublished"] = boolean,
["date"] = number, -- date of publication as unix timestamp, always an integer
["image"] = string }

Author

table:

{ ["id"] = number, -- always an integer
["name"] = string,
["slug"] = string,
["email"] = string,
["image"] = string,
["cover"] = string,
["bio"] = string,
["website"] = string,
["location"] = string,
["role"] = number, -- 1 = Administrator, 2 = Editor, 3 = Author, 4 = Owner, always an integer }

Tags

table of tables:

{ { ["id"] = number, -- always an integer
["name"] = string,
["slug"] = string }, ... }

Blog

table:

{ ["url"] = string,
["title"] = string,
["description"] = string,
["logo"] = string,
["cover"] = string,
["assetpath"] = string,
["postcount"] = number, -- always an integer
["postsperpage"] = number, -- always an integer
["activetheme"] = string }

Arguments

table:

{ string = string, -- e.g. if the helper was {{test absolute="true"}}, this would be "absolute" = "true" (quotation marks around the second part are ignored). {{test argument}} on the other hand would be "argument" = "".
string = string,
string = string, ... }

Notes

• If you'd like to use your custom helper as an if argument in a theme, your Lua function needs to return an empty string ("") for false, any other string (e.g. "t") for true.
• Journey uses GopherLua to execute plugins. GopherLua implements its own Lua VM, so please refer to the GopherLua Read Me for differences to the standard Lua VM.