Lumikki manual & sample template

Updated 30-Jun-04 /AK

Applies to Lumikki v.0.05

Lumikki manual

This file is both a manual of Lumikki and a sample on its use. For more feedback and support, visit the development site at luaforge.net/projects/lumikki.

Picture copyright (c) Giulia Carrozzino.
All rights reserved.

What Lumikki is:

What Lumikki is NOT:


Using Lumikki

With Lumikki, you can craft your documentation using familiar HTML tags (s.a. '<i>' for italics, '<b>' for bold and so on..) However, many of the more cumbersome tags (s.a. '<a href=...>' and '<gra src=...>') can be replaced by Lumikki specific, functional tags.

Functional tags - what are they?

Well, much of this doc will probably focus on them. The basic idea of Lumikki (and pretty much the _only_ idea) is to allow functional tags within the HTML template to call Lua functions, named appropriately. This interaction of part static HTML (and text), part functions and their returned strings, will generate your website.

Or, as in the case of this 'manual', a single HTML page.

Still with us?

Let's take a short sample (I won't craft a long one, since just looking at the template of this file - manual.htl will serve as a 'real' example).

    Sample Lumikki template.
    Calling a <@EVAL>1+2</@EVAL> function.

Now, when this template is run through the Lumikki system (lua lumikki.lua manual.htl(*), it generates (roughly) this output:

    <HTML><BODY>
    <P>Sample Lumikki template. Calling a 3 function.</P>
    </BODY></HTML>

*) If you want to save the output, just add '>manual.htm' redirection at the end.

Note that Lumikki has added the HTML and BODY tags, making the output be proper HTML. Also, it has added paragraph tags (P and /P).

Furthermore, it has calculated 1+2 but how did it do that?

Simply, by calling a predefined 'EVAL' function, which is part of the lumikki.lua code. It could be defined as:

    function EVAL( tbl, text )
        return loadstring( "return "..text )()
    end

Now, what this does is add "return" to the beginning (of 1+2) and then make a Lua on-the-fly function of it ("return 1+2"). Running such function (the "()") obviously returns 3, which is fed back to Lumikki. Lumikki replaces the <@EVAL> portion in the template with this string (or anything the function returned). Nice.

Well, apart from the apparent stupidity of this sample, you probably get the point. Having full access to both the template (well, you make them :) and the Lua functions (you can craft your own, use the built-in ones, or expand their functionality) gives you total control on how your code is done, and what the functions are being used for.

I mean, you can use CSS (cascading style sheets) with Lumikki, or you might not. Same applies for JavaScript, Dynamic HTML, whatever.. Lumikki is ignorant of any such higher level tools, but versatile to work with them if taught so. The 'teaching' means crafting appropriate Lua functions that will do their job.

Broaden your mind

The Lua functions called don't necessarily need to be plain-through filters (string in, string out). They can also store interim data for later use in Lua data structures. This way, you can for example cause a <@NEWSITEM> tag (not implemented yet) to actually collect data on the news items that have passed through it. Eventually, a <@NEWS> tag would be able to make a list of such articles based on the collected data. Cool.

Functions

Well, I think it's time to go into the bread-and-butter, namely the built-in functions. Consider this as a short reference manual (you won't get more!) of what's available.

Note that all this functionality is easily replacable or expandable by you simply by defining new global functions that behave the way you like.

Basics

You may have noticed the 'tbl' parameter in our sample above, that didn't get used. That is where you get tag params. Like:

    <@TAG param1[=val1] [param2[=val2] [...]]>
        ...text...
    </@TAG>

The table will hold any named parameters that were given inside the starting tag.

You can also omit giving them a value (see examples below) in which case they'll hold 'true'.

Actual text within the starting and ending tags is received in the second function param (as used in the simple example).

Also, the ending tag is optional. If your tag doesn't need the text input, there's no need for a terminating tag, either. (we're not XML here ;)

Functions (again..)

DOCUMENT [title=str] [author=str] [keywords=str] [stylesheet=str] [background=str]

If used, must be the first tag of a Lumikki document. Causes the <HEAD> and <BODY> sections to be inserted in the generated HTML.

If you omit the tag, the output will still have basic HTML formatting.

EVAL

Evaluates a Lua expression (within <@EVAL> and </@EVAL>) and replaces it in the output.

FUNC

Defines a new Lua function, that can be used as a tag (same as built-in ones) after the definition. See also <@LUA>.

GRA src=url [align=left/center/right] [border[=N]] [x=width] [y=width] [link[=url] [popup]]

Adds a picture, like the regular <img> tag, but with some spicies.. :)

The text (if any) is written in small font italics underneath the picture. It is not the same as an 'alt=' tag (which is normally invisible).

INCLUDE url=str [expand]

Fetches text from the given file (or URL) and includes it in the output. If 'expand' param is given, extension tags in the file are also processed.

LINK [popup] [url=str]

Conveniency function to do pretty much the same as traditional <A> tag has done. If no URL is given, the string contents are used (so no need to write the same thing twice).

Also, "mailto:" or "http://" are automatically added if omitted.

LUA

Allows any Lua code to be embedded in the HTML template. Most often, this contains definitions for new tag functions.

Note that no empty lines are allowed within the <@LUA> block (at least in the current implementation). Use Lua comments ('--') instead.

SMILEY

A very important one. :) Expands currently to ';)' but could be made to generate a link to some smiley graphics somewhere on the net.. Or even take in a plethora of grin configurations? ;P

TAG xxx

Easy inclusion of tag names (s.a. <A> or <@FUNC> within HTML template. Avoids the clumsy &lt; &gt; notation.

Note: unlike other Lumikki tags, here the parameter names are variable (ie. <@TAG @FUNC>) for brevity.

...

The rest is still undocumented - please send a note.

Defining your own functions

If the built-in functions don't suit you, you can of course define your own. This can be done either in the Lua side or embedded into the HTML template.

For this purpose, a special @FUNC tag can be used:

<@FUNC>
    MYTAG( tbl, text )  -- this is Lua code :)
        --
        return "<h3><b><u>"..text.."</u></b></h3>"
    end
</@FUNC>

What this does is pretty obvious. You can use any Lua directives within the code, just as you would in regular .lua programs.

Here's a sample of what the above tag does

Note: The @FUNC block may not contain empty lines - use comments '--' if you need some space.

Bottom line

What more to say? There's more simple, tiny details to Lumikki, but looking at the sample code should make them obvious. If you have any questions, please be my guest and join us at LuaForge for discussion forum, mailing list, news archive, the lot!

I hope you will enjoy this little tool and -I hope- it will remain little. Smallness and simplicity has been one of the strengths of the Lua language and I hope that applies to Lumikki as well.

Yours truly, Asko Kauppi
asko.kauppi@sci.fi


License terms:

Lumikki is released under the GPL license. You are free to use the software in any project, for any purpose, as long as you don't (need to) make modifications to it. If you need to modify, you also need to provide the modifications to others that might benefit from them. This is how GPL works in a nutshell.

The original author of the package can be reached at: asko.kauppi@sci.fi


This page was created by Lumikki