User blog:Bitomic/Introduction to Using Lua On Fandom

This blog assumes you are familiar with programming concepts, like variables and conditions. If you aren't, you should find a beginner course for it before learning how to use Lua on Fandom.

If you have been creating templates on your wiki, sooner or later you may have to learn how to use parser functions to create more complex code. Be it either  or , these help you to have more powerful building blocks for your content.

However, at some point you may face an issue: using too many  makes it harder to read the source code. Imagine you wanted to auto-categorize the pages for episodes in your wiki about a TV show with the following rules:


 * 1) If there is a   parameter, it will add.
 * 2) If the   parameter is missing, it will add   so you can find it easily.

In a template, you would need an  as simple as:

So many  and   may start to look confusing, but it isn't terrible... yet. What if we needed to add a new rule?


 * 1) If there is a   parameter, which determines whether the episode is a special or a regular episode, it must instead add.

How could we do this? Maybe something like:

Now it is getting a little harder to read, isn't it? We just added a single rule to our logic! Parser functions shine at simple checks, but they get more complicated as you try to implement a more complex logic using them. What should we do, then? As a programming language, Lua is a more powerful tool that helps you to add advanced logic to your templates, while being easier to read if you are familiar with it. But before we can convert the previous example, we need to understand what is it and how can you use it on your wikis through modules.

Lua quickstart
Lua scripts are available in the Module: namespace in all wikis by default. Just like all of your templates start with Template:, all Lua scripts are in pages that start with Module:. Most modules will look like:

Let's do a quick summary of the previous example:


 * is a variable, which stores an empty table . You need it to keep all of your exported functions bundled together so they can be  -ed at the end. Other modules and pages will be able to use anything in the exported table.
 * We are creating a function  inside our table  .   is an argument all functions receive when they are called from a page; you can read more about the frame object, but for now we only need to know that it allows you to access the parameters used in the page. For example, in " ", it would give you access to ,   and the value of a parameter named  , which is.

Keep in mind:  is just an example! You can use any valid name for your functions.

Creating our module
Now, let's get into the actual code! Focus on the new content, which is everything inside the  function.

Step by step
Let's take a look at what all of this is.


 * Accessing the parameters
 * There are other ways to access the parameters passed to your module from the page, but the most recommended one is to use Arguments, a Global Lua Module available in all wikis. It exports a function  that will give you a table with all arguments from your   object. Using the same template call we had before, " ", it will give you all arguments in a table like:




 * Remember that Lua tables start indexing from 1! So you could access any parameter you need as  (First),   (Second) and   (world). Accessing any key that doesn't exist will return a   value, equivalent to JavaScript's   or Python's.


 * Implementing your logic
 * You should already be familiar with  statements in programming. Lua's syntax may be different, but easy to understand.
 * Just like we did before using parser functions, we first check if the  parameter was set. If it wasn't, we would have got a   value from our   table, which would be evaluated as.
 * The other part that may have you wondering its meaning is . Lua has different ways to "interpolate" strings, and this is just one of them. The first parameter of this function is your template string, where each instance of   will be substituted by the following parameters in order (in this case, the value stored in  ).
 * If  is set, check if   is also set.
 * If  is set, add a category , where   will be replaced with the value in.
 * Else, add a category.
 * If  is not set, add a category.
 * Just like a template, the value returned from your module will be inserted into the article.

How do I use it?
If we had the previous example in, you could call it in any page using. However, you should avoid this. Although the syntax is very similar to templates, it might potentially confuse new editors: ? Why ? Where is this template?

Usually, your editors will never use modules directly, but instead through templates. For example, in your  you could call your module at the end as:.

You may be wondering: how will it know the season? Well, your  object will have access to any parameters passed to  ! And thanks to the Arguments global module we used before, it will give you easy access to these parameters without having to modify your module. Isn't it great?

Summary
This blog only gave you an idea of how you can use Lua to simplify the logic in your templates, hopefully you will be able to apply it in better scenarios so they are easier to maintain! Here is a short list of when you should consider using Lua:


 * Your template has many parser functions, especially if they are nested.
 * You need to process any number of parameters. Instead of manually adding,  ,   and so on as you need, you can manage them using Lua.
 * Although centralizing your data is considered a bad practice for wikis, sometimes it may be the best solution for your needs. And the best way to centralize data is through Lua modules.

Keep in mind that Lua modules require someone that knows the language to be able to maintain it. Try to follow good programming practices in your module so other people are able to understand what should it do and easily navigate through it if they need to fix anything. For example: use descriptive variables ( doesn't give as much information as  ) and split your code into different functions to make it easier to read. And, of course, add some comments to keep it clear for others!

You have at your disposal all the tools available in a programming language to create powerful modules to use in your articles, instead of only relying on parser functions and other basic features.