Guidelines:Modules: Difference between revisions

Jump to navigation Jump to search

Guidelines:Modules (view source)

Revision as of 11:44, 9 July 2023

720 bytes added ,  9 July 2023
no edit summary
VisualWikitext
No edit summary
No edit summary
(7 intermediate revisions by 2 users not shown)
Line 2: Line 2:
{{Big|Overview|3}}<br/>
{{Big|Overview|3}}<br/>


'''Modules''' are {{Wp|Lua (programming language)|Lua}} scripts for making [[Help:Templates|templates]] using a full-fledged programming language. You can ask questions about Zelda Wiki modules in the <code>#modules-and-templates</code> [{{Discord}} Discord] channel.
'''Modules''' are {{Wp|Lua (programming language)|Lua}} scripts for making [[Help:Templates|templates]] using a full-fledged programming language. You can ask questions about Zelda Wiki modules in {{Discord|channel= wiki-tech}}.


==Templates==
==Templates==
Line 82: Line 82:


====<code>#invoke</code>====
====<code>#invoke</code>====
The <code>#invoke</code> {{Mediawiki|Help:Extension:ParserFunctions|parser function}} is what bridges the gap between templates and module scripts. For example, the {{Mediawiki|Transclusion|transcluded}} content of [[Template:Figurine]] is as follows:
The <code>#invoke</code> {{Mediawiki|Help:Extension:ParserFunctions|parser function}} is what bridges the gap between templates and module scripts. For example, the {{Mediawiki|Transclusion|transcluded}} content of [[Template:Color]] is as follows:
<pre>
<pre>
{{#invoke:Figurine|Main}}
{{#invoke:Color|Main}}
</pre>
</pre>


This invokes [[Module:Figurine]], which could look something like:
This invokes [[Module:Color]], which looks something like:


{{Hide
|visible= true
|header= Module:Color
|content=
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
local p = {}
local p = {}
local h = {}


local Franchise = require("Module:Franchise")
...
...


function p.Main(frame)
function p.Main(frame)
     local args = frame:getParent().args
     local args = frame:getParent().args
     local result = h.getFigurine(args[1], args[2])
     return p.color(args[1], args[2])
    return result
end
end


function h.getFigurine(game, name)
function p.color(color, text)
...
    ...
end
end


return p
return p
</syntaxhighlight>
</syntaxhighlight>
}}


A page can invoke any function that is a field on the module's '''export table'''. The export table is the <code>table</code> object returned by the module, which is always named <code>p</code> by convention. In this case, <code>Main</code> is the only function in the export table.
A page can invoke any function that is a field on the module's '''export table'''. The export table is the table object returned by the module, which is named <code>p</code> by convention (short for "package").
 
In the above example, <kbd>Main</kbd> and <kbd>color</kbd> are the functions in the export table. Only <kbd>Main</kbd> can be used by [[Template:Color]] via <code>#invoke</code>. The <kbd>color</kbd> function can be used by other modules (see [[#require|<kbd>require</kbd>]] below).
 
By convention, {{SITENAME}} uses <kbd>UpperCamelCase</kbd> to indicate functions meant for <code>#invoke</code>, and <kbd>lowerCamelCase</kbd> for all other functions.


====<code>args</code>====
====<code>args</code>====
Line 115: Line 121:
*<code>frame.args</code> is a table of the arguments to <code>#invoke</code>. (There are none in the above example.)
*<code>frame.args</code> is a table of the arguments to <code>#invoke</code>. (There are none in the above example.)
*<code>frame:getParent().args</code> is a table of the arguments to the ''template''.
*<code>frame:getParent().args</code> is a table of the arguments to the ''template''.
**Example: If a page has <code><nowiki>{{Figurine|TMC|Minish Ezlo}}</nowiki></code>, then <code>frame:getParent().args[1]</code> evaluates to the string <code>TMC</code> for that invocation.
**Example: If a page has <code><nowiki>{{Color|TWWHD Vermilion|merchant's oath}}</nowiki></code>, then <code>frame:getParent().args[1]</code> evaluates to the string <code>TWWHD Vermilion</code> for that invocation.


The <code>#</code> operator and most other table functions don't work on <code>frame.args</code>.
The <code>#</code> operator and most other table functions don't work on <code>frame.args</code>.


====<code>require</code>====
====<code>require</code>====
A module can import another module and use its exported functions. This is done with the <code>require</code> function, as shown in the above example with [[Module:Franchise]].
A module can import another module and use its exported functions. This is done with the <code>require</code> function.
 
For example, [[Module:Cite]] imports [[Module:Color]] in order to use the <kbd>color</kbd> function to color quotes of characters whose dialogue text is a special color in-game.
 
{{Hide
|visible= true
|header= Module:Cite
|content=
<syntaxhighlight lang="lua">
local p = {}
 
local Color = ("Module:Color")
 
...
 
function p.Main(frame)
    ...
    Color.color(color, quote)
end
 
return p
</syntaxhighlight>
}}


====<code>mw</code>====
====<code>mw</code>====
Line 168: Line 196:
Once you are able to produce working code, make sure it adheres to Zelda Wiki's coding standards.
Once you are able to produce working code, make sure it adheres to Zelda Wiki's coding standards.


It is particularly important to use a consistent naming pattern, as plain text [[Special:Search|searching]] is the only way to observe function usage.<!--
It is particularly important to use a consistent naming pattern, as plain text [[Special:Search|searching]] is the only way to observe function usage.
-->{{#vardefine:Don't|{{Exp|Don't|[[File:TFH Red Link desperate.png|48px|link=]]}}}}<!--
 
-->{{#vardefine:Do|{{Exp|Do|[[File:TFH Green Link ok.png|36px|link=]]}}}}
===Importing===
===Importing===
{| class="wikitable"
{| class="wikitable"
!colspan=2| Use lower <code>camelCase</code> for imported utility modules
!colspan=2| Use lower <code>camelCase</code> for imported utility modules
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|<syntaxhighlight lang="lua">
|<syntaxhighlight lang="lua">
local UtilsString = require("Module:UtilsString")
local UtilsString = require("Module:UtilsString")
</syntaxhighlight>
</syntaxhighlight>
|-
|-
! {{#var:Do}}
! {{Good|tooltip= Do}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 189: Line 216:
!colspan=2| Avoid importing [[:Category:Submodules|submodules]] unless absolutely necessary
!colspan=2| Avoid importing [[:Category:Submodules|submodules]] unless absolutely necessary
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 195: Line 222:
</syntaxhighlight>
</syntaxhighlight>
|-
|-
! {{#var:Do}}
! {{Good|tooltip= Do}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 204: Line 231:
!colspan=2|Don't index the result of the <code>require</code> expression.
!colspan=2|Don't index the result of the <code>require</code> expression.
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 210: Line 237:
</syntaxhighlight>
</syntaxhighlight>
|-
|-
! {{#var:Do}}
! {{Good|tooltip= Do}}
| If you must assign the function separately:
| If you must assign the function separately:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 223: Line 250:
!colspan=2|Default to double quotes
!colspan=2|Default to double quotes
|-
|-
! {{#var:Do}}
! {{Good|tooltip= Do}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 232: Line 259:
</syntaxhighlight>
</syntaxhighlight>
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|  
|  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 243: Line 270:
!colspan=2|Template calls must not throw script errors on purpose. Use warnings and error categories instead.
!colspan=2|Template calls must not throw script errors on purpose. Use warnings and error categories instead.
|-
|-
! {{#var:Do}}
! {{Good|tooltip= Do}}
|   
|   
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 257: Line 284:
[[Module:UtilsArg]] can help with this.
[[Module:UtilsArg]] can help with this.
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 266: Line 293:
</syntaxhighlight>
</syntaxhighlight>
|-
|-
! {{#var:Don't}}
! {{Bad|tooltip= Don't}}
|
|
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 282: Line 309:
High-usage modules may require additional effort for them to work well at scale. "High usage" can mean one of two things:
High-usage modules may require additional effort for them to work well at scale. "High usage" can mean one of two things:


'''Modules used many times per page'''
'''1. Modules used many times per page'''


Examples: [[Module:Cite|Cite]], [[Module:Color|Color]], [[Module:Term|Term]]. Some pages invoke these modules 300+ times.
Examples: [[Module:Cite|Cite]], [[Module:Color|Color]], [[Module:Term|Term]]. Some pages invoke these modules 300+ times.
Line 293: Line 320:
* Follow https://dev.fandom.com/wiki/Lua_templating/Optimisation
* Follow https://dev.fandom.com/wiki/Lua_templating/Optimisation


'''Modules used on many pages'''
'''2. Modules used on many pages'''


Examples: [[Module:FileInfo|FileInfo]], [[Module:Franchise|Franchise]], [[Module:UtilsArg|UtilsArg]].
Examples: [[Module:FileInfo|FileInfo]], [[Module:Franchise|Franchise]], [[Module:UtilsArg|UtilsArg]].


Every time such a module is updated, every page that uses it (directly or indirectly) must be updated. This can set off a large {{Mediawiki|Manual:Job queue|job queue}}. When there are many active jobs in the queue, any changes to other templates (high-usage or no) may take several hours to propagate to all the pages that use them.
Every time such a module is updated, every page that uses it (directly or indirectly) must be updated. This can set off a large {{Mediawiki|Manual:Job queue|job queue}}. When there are many active jobs in the queue, any changes to other templates (high-usage or no) may take several hours to propagate to all the pages that use them. The same goes for [[Special:ReplaceText]] operations, which are also sent to the back of the job queue.


What you can do:
What you can do:
Line 309: Line 336:


To generate a profiler report, preview a page on the wiki. The report is located at the bottom of the page under the editing area, in the '''Parser profiling data:''' section which may be collapsed by default. It looks something like this:
To generate a profiler report, preview a page on the wiki. The report is located at the bottom of the page under the editing area, in the '''Parser profiling data:''' section which may be collapsed by default. It looks something like this:
The Lua Profile section only appears when total Lua time usage on the page is above 1000ms. <!-- I think. -->


{| class="wikitable"
{| class="wikitable"
Line 343: Line 368:
|[others] || 320 ms || 23.5%
|[others] || 320 ms || 23.5%
|}
|}
The Lua Profile section only appears when total Lua time usage on the page is above 1000ms (1 second). <!-- I think. -->


{{Guidelines Nav}}
{{Guidelines Nav}}
Retrieved from "https://zeldawiki.wiki/wiki/Special:MobileDiff/966053...1083022"

Navigation menu