Word Clock – Part 5

Creating a Word Clock Module

One important principle of developing is to not create cluttered spaghetti code. It is hard to read and hard to maintain.

Spaghetti code is a phrase for source code which is tangled, has a complex structure and is hard to comprehend for the programmer.

One way to avoid this is to modularize your code. Try to capsule certain logic parts of the code, so that it is in its own file and maybe even reusable in other projects.

In our final app we display a word clock above some weather informations. These are two bricks that can be written in its own module. In this chapter we will start writing a module for the word clock part.

What Is a Module

To know what a module is you need to know what Lua tables are.

I have written a short article about Lua tables. It should give you an overview of the most important aspects of Lua tables.

I really recommend to read that article first. And then continue this chapter.

Folder Structure

Clean code needs a clean folder structure.

In this case I will rebuild the final word clock project like you can download from the download section. Of course you can create your own folder structure which is a my approach of an organized structure.

So let’s create a new folder called devilsquid.

In this folder I move all my modules.

In the devilsquid folder we have to create a new subfolder called wordclock.

In this devilsquid/wordclock/ folder we will create two files: one file for the word clock part and one file for the weather part.

So your project folder should like in the screenshot now.

Creating Our First Module File

Now let’s create a new lua file that will be the base for our word clock module.

Open the Word Clock project in Sublime Editor and create a new empty file. You can use File>New File in Sublime’s menu or use Cmd+N shortcut.

Like a composer scene file, a module file follows a certain design pattern – this means that a module is always build up in the same code structure.

Let’s create a minimal example. Enter the following lines of code in your new file in Sublime Editor. Then save the file into the devilsquid/wordclock/ folder and call it wordclock.lua.

local Wordclock = {}
return Wordclock

In fact this micro module can already be used in your app. But the module does not do anything yet.

It only creates an empty table called Wordclock (with an uppercase W – Lua is a case sensitive language) and returns it.

So let’s add some more code. Put it between the two lines above and save the file:

function Wordclock:new()
	print("Wordclock:new()")
	wordclock = {}
	return wordclock
end

Here we added a first function to our module called new(). The new() function is our initializing function. This one is needed when we create the word clock object. It is comparable with a constructor function if you are familiar with object oriented programming (OOP).

This new() function creates a table object called wordclock (with lowercase letter!) which is not same as the surrounding Wordclock table (with uppercase letter). In the end the wordclock table is returned.

We will see later what the wordclock table is for.

I added a print() statement into the new function. This is just for testing and debugging purposes in our next step so that we can see that our setup is working.

Loading the Wordclock Module

Open the clock.lua file we created in part 4. We want to load and initialize our new Wordclock module.

So at the top part after the composer library gets required, add a new require command to load the module:

local Wordclock = require( "devilsquid.wordclock.wordclock" )

Here we required the wordclock.lua file (remember to omit the .lua suffix) and store the module instance in the local variable called Wordclock.

When requiring files in Lua we do not use slashes in the path string, we need to use dots instead of slashes. And again, we need to omit the .lua suffix. I don’t know why it is like this.

So require(“devilsquid.wordclock.wordclock”) means we load the file from “devilsquid/wordclock/wordclock.lua”

Now let’s initialize the Wordclock module by calling its new() function. In the scene:create() function add the following line of code:

local myWordClock = Wordclock:new()

When you compile the code you should see the “Wordclock:new” string in the console – this way you can see that our initializer function new() has been fired properly and our setup is working.

The new local myWordClock now contains our wordclock table (without capital letter). All functions we add to our Wordclock module will be in this table.

Source Code

Here are the final source codes for the new wordclock.lua module and the clock.lua file.

wordclock.lua:

local Wordclock = {}
	function Wordclock:new()
		print("Wordclock:new()")
		wordclock = {}
		return wordclock
	end
return Wordclock

clock.lua

local composer 	= require( "composer" )
local Wordclock = require( "devilsquid.wordclock.wordclock" )

local scene = composer.newScene()
 
function scene:create( event )
    local myWordClock = Wordclock:new()
end
 
function scene:show( event )
    if ( event.phase == "will" ) then 
    elseif ( event.phase == "did" ) then 
    end
end
 
 function scene:hide( event )
    if ( event.phase == "will" ) then 
    elseif ( event.phase == "did" ) then 
    end
 end
 
 function scene:destroy( event )
 end
 
 scene:addEventListener( "create", scene )
 scene:addEventListener( "show", scene )
 scene:addEventListener( "hide", scene )
 scene:addEventListener( "destroy", scene )
 
 return scene

And of course you can download the final source code of this part of the course at the end in the Links section.

Conclusion

Here you learned how to create a very basic module skeleton and how you load it in our clock.lua scene file.

In the next part we will display something in the simulator and further extend our new word clock module.

– René