Introdução ao Uso do Lua no Fandom

Esse blog assume que você já está familiarizado com conceitos de programação, como variáveis e condicionais. Se você não for, você deve encontrar um curso para iniciantes sobre isso antes de aprender a como usar o Lua no Fandom.

Se você tem criado predefinições em sua wiki, mais cedo ou mais tarde você terá que aprender a como usar funções parser para criar códigos mais complexos. Seja {{#if:}} ou {{#switch:}}, eles ajudam você a ter blocos de construção mais poderosos para o seu conteúdo.

No entanto, em algum momento você encontrará um problema: usar muitos códigos #if torna difícil para ler o código fonte. Imagine que você quer auto-categorizar as páginas para os episódios em sua wiki sobre um programa de TV com as seguintes regras:

1. Se houver um parâmetro {{{season}}}, será adicionado [[Categoria:Episódios da temporada {{{season}}}]].
2. Se o parâmetro {{{season}}} estiver faltando, será adicionado [[Categoria:Episódios sem uma temporada]] para que você pode encontrá-lo mais facilmente.

Em uma predefinição, você precisará de um #if: tão simples quanto:

{{#if:{{{season|}}}|[[Categoria:Episódios da temporada {{{season}}}]]|[[Categoria:Episódios sem uma temporada]]}}

Então tendo muitos {{ }} e [[ ]] pode começar a parecer confuso, mas isso não é terrível... ainda. E se nós precisamos adicionar uma nova regra?

1. Se houver um parâmetro {{{special}}}, o que determina se o episódio é um episódio especial ou regular, ela deve adicionar uma [[Categoria:Episódios especiais da temporada {{{season}}}]].

Como nós podemos fazer isso? Talvez algo assim:

{{#if:{{{season|}}}|{{#if:{{{special|}}}|[[Categoria:Episódios especiais da temporada {{{season}}}]]|[[Categoria:Episódios da temporada {{{season}}}]]}}|[[Categoria:Episódios sem uma temporada]]}}

Agora está ficando um pouco mais difícil de ler, não é? Acabámos de adicionar uma única regra à nossa lógica! As funções parser se destacam em verificações simples, mas ficam mais complicadas quando você tenta implementar uma lógica mais complexa ao usá-las. O que nós devemos fazer então? Como linguagem de programação, a Lua é uma ferramenta mais poderosa que ajuda você a adicionar lógicas avançadas às suas predefinições, além de ser mais fácil de ler se você estiver familiarizado com ela. Mas antes de podermos converter o exemplo anterior, precisamos entender o que é e como você pode utilizá-la em suas wikis através dos módulos.

Iniciação rápido do Lua

Scripts Lua estão disponíveis nos namespace Módulo: em todas as wikis por padrão. Assim como todas as suas predefinições começam em Predefinição:, todos os scripts Lua estão em páginas que começam em Módulo:. A maioria dos módulos se parecerão dessa forma:

local p = {}

function p.main(frame)
  -- code
end

return p

Vamos fazer um resumo rápido dos exemplos anteriores:

• local p é uma variável, que abriga uma tabela vazia {}. Você precisa dela para manter todas as suas funções exportadas agrupadas juntas para que elas possam ser retornadas (return) no final. Outros módulos e páginas serão capazes de usar qualquer coisa na tabela exportada.
• Nós estamos criando uma função main dentro de nossa tabela p. frame é um agrupamento que todas as funções recebem quando elas são chamadas de uma página; você pode ler mais sobre os frame object, mas por enquanto nós somente precisamos saber que ele permite que você acesse os parâmetros usados na página. Por exemplo, em "{{Template|First|Second|hello=world}}", ele lhe daria acesso ao First parameter, Second parameter e o valor de um parâmetro nomeado hello, que é world.

Mantenha em mente: main é apenas um exemplo! Você pode usar qualquer nome válido para as suas funções.

Criando o nosso módulo

Agora, vamos olhar o código em si! Foque no conteúdo novo, que é tudo que está dentro da função main.

local p = {}

function p.categorize(frame)
  local args = require('Dev:Arguments').getArgs(frame)
  local season = args.season
  local special = args.special
  
  if season then
    if special then
      return string.format( '[[Category:Special episodes from season %s]]', season )
    else
      return string.format( '[[Category:Episodes from season %s]]', season )
    end
  else
    return '[[Category:Episodes with no season]]'
  end
end

return p

Passo-a-passo

Vamos dar uma olhada no que é tudo isso.

Acessando os parâmetro

Existem outras formas de acessar os parâmetros passados para o seu módulo a partir da página, porém o mais recomendado é usar Argumentos, um Módulo Lua Global disponível em todas as wikis. Ele exporta uma função getArgs que lhe dará uma tabela com todos os argumentos de seu objeto frame. Usando a mesma chamada de predefinição que tínhamos antes, "{{Template|First|Second|hello=world}}", ele fornecerá todos os argumentos em uma tabela como:

{
  "First",
  "Second",
  hello = "world"
}

Lembre-se que as tabelas Lua começam indexando a partir de 1! Então você poderá acessar qualquer parâmetro que você precisa como args[1] (First), args[2] (Second) e args.hello (world). Acessando qualquer chave que não existe irá retornar um valor nil, equivalente ao código undefined do JavaScript ou None do Python.

Implementando a sua lógica

Você já deve estar familiarizado com o if na programação. A sintaxe Lua pode ser diferente, mas é fácil de entender.

Assim como nós fizemos antes usando as funções parser, nós primeiramente checamos se o parâmetro episódio foi configurado (if the episode parameter was set). Se não foi, nós teremos um valor nil das nossas tabelas args, que seriam avaliadas como false.

A outra parte pode ter feito você se perguntar sobre o seu significado é o string.format. Lua possui formas diferentes para "interpolarizar" as strings, e essa é apenas uma delas. O primeiro parâmetro dessa função é a string da sua predefinição, onde cada instância de %s será substituída pelos seguintes parâmetros em ordem (nesse caso, o valor armazenado em season).

• If season is set, cheque if special is also set.
  • If special is set, adicione uma categoria [[Category:Special episodes from season %s]], onde %s será substituída com o valor em season.
  • Else, adicione uma categoria [[Category:Episodes from season %s]].
• If season is not set, adicione uma categoria [[Category:Episodes with no season]].

Assim como uma predefinição, o valor retornado de seu módulo será inserido no artigo.

Como eu uso isso?

Se tivéssemos o exemplo anterior em Module:Episode, você poderia chamá-lo em qualquer página usando {{#invoke:Episode|categorize|season=1}}. No entanto, você deve evitar isso. Embora a sintaxe seja muito semelhante aos modelos, ela pode confundir os novos editores: #invoke? Por que categorize? Onde está esse modelo?

Usualmente, os seus editores nunca usarão os módulos diretamente, mas ao invés de fazê-lo pela predefinição. Por exemplo, em sua Predefinição:Episode Infobox você pode chamar o seu módulo no final como: {{#invoke:Episode|categorize}}.

Você pode estar se perguntando: como ele saberá a temporada? Bem, seu objeto frame terá acesso a quaisquer parâmetros passados ao {{Episode Infobox}}! E graças ao módulo global Argumentos que usamos antes, ele lhe dará acesso fácil a esses parâmetros sem ter que modificar o seu módulo. Isso não é ótimo?

Resumo

Esse blog apenas lhe dá uma ideia de como você pode usar o Lua para simplificar a l´[ogica de suas predefinições, esperamos que você possa ser capaz de aplicá-los em cenários melhores para que elas sejam mais fáceis de manter! Aqui está uma pequena lista de quando você deve considerar usar o Lua:

• A sua predefinição possui muitas funções parser, especialmente se elas estiverem aninhadas.
• Você precisa processar qualquer número de parâmetros. Ao invés de manualmente adicionar {{{parameter 1}}}, {{{parameter 2}}}, {{{parameter 3}}} e assim por diante conforme as suas necessidades, você pode gerenciá-las usando o Lua.
• Apesar da centralização dos seus dados ser considerada uma má prática para as wikis, às vezes ele pode ser a melhor solução para as suas necessidades. E a melhor forma de centralizar os dados é através dos módulos Lua.

Mantenha em mente que os módulos Lua requerem alguém que conheça a linguagem para ser capaz de mantê-la. Tente seguir boas práticas de programação em seu módulo para que as outras pessoas seja capazes de entender o que ela deve fazer para que seja facilmente navegada caso precise de qualquer tipo de concerto. Por exemplo: use variáveis descritivas (local ip não dá tantas informações quanto local item_price) e separe o seu código em funções diferentes para deixá-la mais fácil de ler. E, é claro, adicione alguns comentários para deixá-la mais clara para os outros!

Você tem à sua disposição todas as ferramentas disponíveis em uma linguagem de programação para criar módulos poderosos para usar em seus artigos, ao invés de contar apenas com funções parser e outras funcionalidades básicas.

Tornando-se um Pro: Assuntos Técnicos

Introdução ao DynamicPageLists no Fandom

Introdução ao Uso do Lua no Fandom

Guia Sobre o Uso de Bots no Fandom

Aprenda o Básico Dê os Próximos Passos
Torne-se um Mentor da Comunidade