Christchurch Weather Live source - configuration file

The LUA source code for the configuration file

local oo            = require("loop.simple")
local AppletMeta    = require("jive.AppletMeta")
local appletManager = appletManager
local jiveMain      = jiveMain

module(...)
oo.class(_M, AppletMeta)
 
function jiveVersion(meta)
     return 1, 1
end

function defaultSettings(meta)
     return {
             currentSetting = 0,
     }
end

function registerApplet(meta)
     jiveMain:addItem(meta:menuItem('weatherliveApplet', 'home', "Weather Live", function(applet, ...) applet:menu(...) end, 20))
end

Credits

Note: Some of the comments and descriptions below have been copied from SqueezePlay_Applet_Guide - thanks to the original authors.

Variable Declaration

 local oo            = require("loop.simple")
 local AppletMeta    = require("jive.AppletMeta")
 local appletManager = appletManager
 local jiveMain      = jiveMain

In the LUA programming language it is necessary to explicitly define all functions and classes you wish to use in your applet. This is done through require() statements, and in some cases, the pulling in of global variables into local space. See http://www.lua.org/pil/4.2.html for more details on local and global variables.

In LUA the keyword require() means to load and run a library. See http://www.lua.org/pil/8.1.html for more details

Note: this also needs to be done for Lua internal functions like tostring, setmetatable, etc.

So, in the code above we are defining four variables:

• oo
• AppletMeta
• appletManager
• jiveMain.

Module and Class Declaration

Next we define the type of file we are constructing:

 module(...)
 oo.class(_M, AppletMeta)

In essence what these two lines say are "this is a meta file, and we're going to define all variables to be used locally" or "new class (AppleNameMeta) inheriting from AppetMeta".

Note we had to define AppletMeta above by requiring our superclass jive.AppletMeta.

I have no idea what _M means but I assume it is a global variable defined somwhere.

See http://www.lua.org/pil/16.1.html for more details on Classes in LUA

Meta File Functions

Now on to the meta functions:

 function jiveVersion(meta)
       return 1, 1
 end

This sets the valid versions (min and max) that this applet will run under.

In this example, min and max are set to 1, which means that the jiveVersion has to be set to 1 for this applet to load.

• Note: this number does not correspond to the external SqueezePlay version number, e.g., 7.3.3

Default settings are important to define if a settings.lua file is going to be used:

 function defaultSettings(meta)
       return {
               currentSetting = 0,
       }
 end

settings.lua files are created dynamically by an applet, so it doesn't exist when first using the applet. This is where you define default settings so SqueezePlay doesn't balk when trying to getSettings() when it is running.

Finally we register our applet:

 function registerApplet(meta)
       jiveMain:addItem(meta:menuItem('weatherliveApplet', 'home', "Weather Live", function(applet, ...) applet:menu(...) end, 20))
 end

it may read easier like this

 function registerApplet(meta)
       jiveMain:addItem(
           meta:menuItem('weatherliveApplet', 'home', "Weather Live", 
              function(applet, ...) 
                  applet:menu(...)  
              end, 
           20)
       )
 end

This line is a bit complicated with all the different arguments.

What we are doing here is adding a menu item to the "home" area of Squeezeplay, which are those top-level menus that are managed by jive/ui/HomeMenu.lua.

The menuItem() function general form is

 menuItem(id, node, token, callback, [weight])

• id => unique key that HomeMenu uses to reference this item
• node => HomeMenu node to add this item to. 'home' places the item in the top-most menu. Other options include 'myMusic', 'extras', 'settings', and 'advancedSettings'.
• token => string token to be used for displaying the menu item
• callback => function to callback when this menu item is drilled into. Typically in a meta file you reference the corresponding applet file function to execute. When you see ... as a parameter to a function it means that there may be additional paramters passed other than those explicitly defined. See Lua Function Paramters for more details.
• weight => an optional parameter given to place the item higher or lower in the list. Default weight of unweighted items is 5, and by convention items sent from SqueezeCenter (e.g., Music Library) have weights between 10 and 100.

See also

• Christchurch Weather Live
• Christchurch Weather Live source code
• Christchurch Weather Live source - strings