Editing Module:Article history/doc

{{Module rating|protected}}
{{High-use}}
{{Lua|Module:Article history/config|Module:Article history/Category|Module:Yesno|Module:Arguments}}
{{Uses TemplateStyles|Module:Message box/tmbox.css|Module:Article history/styles.css}}
This module implements {{lt|Article history}}. Please see the template page for documentation of how to use it.

== Technical details ==

This module has a configuration module at [[Module:Article history/config]], which can be used to translate/modify the template for use on other wikis. See the config module for instructions on how to modify it. The configuration for the English Wikipedia is very complicated, but it is also possible to use it much more simply. If you want to use the more advanced features provided by the module, you can consult the class documentation below.

There is also a Category class at [[Module:Article history/Category]], which is used by both the main module and the config module.

== Class documentation ==

This is technical documentation for Lua programmers who are looking to adapt this module for use on different wikis.

=== Category ===

The Category class is used to generate all of the module's categories. It is loaded in both [[Module:Article history]] and [[Module:Article history/config]]. You can create a category with Category.new:

<syntaxhighlight lang="lua">Category.new(cat, sort)</syntaxhighlight>

The <var>cat</var> variable is the category text, and <var>sort</var> is its sort key.

Once category objects are created, they have the following properties:
* <code>category</code> - the category name
* <code>sortKey</code> - the sort key

They can be rendered into category links by calling <code>tostring()</code> on them.

=== Message ===

The Message mixin contains common message-related methods which are available in all classes apart from the Category class. These methods are:

* <code>Message:message(key, ...)</code> - fetches a message with the key <var>key</var> from the config's msg table, and substitutes parameters $1, $2 etc. with the subsequent values it is passed.
* <code>Message:raiseError(msg, help)</code> - formats <var>msg</var> and uses it to raise an error. <var>help</var> is an optional page that will provide help for the error that the user encountered. This is intended to be caught with ArticleHistory:try, and is for errors after which further processing in that object becomes impossible.
* <code>Message:addWarning(msg, help)</code> - formats <var>msg</var> and uses it to add a warning. <var>help</var> is an optional page that will provide help for the error that the user encountered. This is for errors that should be fixed, but that do not prevent the module from outputting something useful for that object.
* <code>Message:getWarnings()</code> - returns an array of all warnings added for the object.

=== ArticleHistory ===

An ArticleHistory object does the main work of the module. It fetches the different Row objects, renders the box, renders the error messages, and renders category links. ArticleHistory objects can use all methods from the [[#Message|Message]] mixin. They also have the following public properties:

* <code>args</code> - a table of the arguments passed to the module by the user.
* <code>currentTitle</code> - the [[mw:Extension:Scribunto/Lua reference manual|title object]] for the current page.
* <code>cfg</code> - the module config table. This is taken from the config module at [[Module:Article history/config]], but is structured slightly differently due to preprocessing by the main module. Any table with an "aliases" subtable has this table removed, and the aliases are added as keys that the table can be accessed from. Conceptually, the config table {{code|1={ foo = {"a value", aliases = {"bar", "baz"} } }|2=lua}} would become {{code|1={foo = {"a value"}, bar = {"a value"}, baz = {"a value"} }|2=lua}}. (Although "bar" and "baz" would actually be references to the "foo" table, rather than completely new tables.)
* <code>prefixArgs</code> - a table of the arguments passed to the module by the user, sorted by their prefix and then their number. Non-string keys and keys that don't contain a number are ignored. (This means that positional parameters are ignored, as they are numbers, not strings.) The parameter numbers are stored in the first positional parameter of the subtables, and any gaps are removed so that the tables can be iterated over with ipairs. For example, the arguments {{code|1={a1x = 'eggs', a1y = 'spam', a2x = 'chips', b1z = 'beans', b3x = 'bacon'}|2=lua}} would translate into the prefixArgs table {{code|1={a = { {1, x = 'eggs', y = 'spam'}, {2, x = 'chips'} }, b = { {1, z = 'beans'}, {3, x = 'bacon'} } }|2=lua}}.

ArticleHistory objects have the following public methods:

* <code>ArticleHistory:try(func, ...)</code> - calls the function <var>func</var> with the arguments passed, and returns the first value produced by it. If any errors are encountered, they are caught and added to the object's internal errors table for later rendering by ArticleHistory:getErrorMessages.
* <code>ArticleHistory:getActionObjects()</code> - returns an array containing the Action objects for any actions specified by the user.
* <code>ArticleHistory:getStatusIdForCode(code)</code> - for the status code <var>code</var>, returns the canonical status ID.
* <code>ArticleHistory:getStatusObj()</code> - gets the status object for the template. This returns nil if no current status can be found.
* <code>ArticleHistory:getStatusId()</code> - returns the status ID for the template. This returns nil if no current status can be found.
* <code>ArticleHistory:getNoticeObjects()</code> - returns an array containing the template's Notice objects.
* <code>ArticleHistory:getCollapsibleNoticeObjects()</code> - returns an array containing the template's CollapsibleNotice objects.
* <code>ArticleHistory:getAllObjects(addSelf)</code> - returns an array containing all Status/MultiStatus, Notice, Action and CollapsibleNotice objects. if <var>addSelf</var> is true, the ArticleHistory object is appended to the array as well.
* <code>ArticleHistory:getNoticeBarIcons()</code> - returns an array of icons to be displayed on the notice bar (at the top-left of the collapsible table).
* <code>ArticleHistory:getErrorMessages()</code> - returns an array containing all error and warning strings. Errors are typically raised with Message:raiseError and caught with ArticleHistory:try, and warnings are added to individual objects with Message:addWarning.
* <code>ArticleHistory:renderHtml()</code> - renders the HTML table comprising all the visible output of the template, including status, notices, actions, collapsible notices, error messages and warnings. The result is returned as a string.
* <code>ArticleHistory:renderCategories()</code> - renders all category links and returns them as a string.

Calling <code>tostring()</code> on an ArticleHistory object gives you the HTML table made with ArticleHistory:renderHtml concatenated with the category links made with ArticleHistory:renderCategories.

=== Row ===

Row objects can use all methods from the [[#Message|Message]] mixin. They also have the following public properties:

* <code>currentTitle</code> - the same as ArticleHistory.currentTitle.
* <code>cfg</code> - the same as ArticleHistory.cfg.

Row objects have the following public methods:

* <code>Row:getData(articleHistoryObj)</code> - get memoized data for the object that has been created with a makeData function in the module config page. This mechanism is used to stop config page functions from having to do the same data processing more than once. It must be passed an ArticleHistory object to find the data from. This returns nil if no data was generated or an error was encountered while generating the data.
* <code>Row:setIconValues(icon, caption, size)</code> - set icon values for the object. <var>icon</var> is the icon filename without any namespace prefix, <var>caption</var> is a caption to use with the icon, and <var>size</var> is the size of the icon when output with a large banner. <var>icon</var> and <var>caption</var> can be functions which take an ArticleHistory object as input and return the icon or caption value respectively. Sizes should include any suffixes, e.g. "30px".
* <code>Row:getIcon(articleHistoryObj)</code> - get the icon filename. It must be passed an ArticleHistory object. Returns nil if no icon was set.
* <code>Row:getIconCaption(articleHistoryObj)</code> - get the icon caption. It must be passed an ArticleHistory object. Returns nil if no caption was set.
* <code>Row:getIconSize()</code> - get the icon size.
* <code>Row:renderIcon(articleHistoryObj)</code> - renders the icon for the object. Returns nil if no icon was set.
* <code>Row:setNoticeBarIconValues(icon, caption, size)</code> - set notice bar icon values for the object. (The notice bar icons are the small icons that appear at the top left of the collapsible box containing the actions.) <var>icon</var> is the icon filename without any namespace prefix, <var>caption</var> is a caption to use with the icon, and <var>size</var> is the size of the icon. <var>icon</var> and <var>caption</var> can be functions which take an ArticleHistory object as input and return the icon or caption value respectively. Sizes should include any suffixes, e.g. "15px".
* <code>Row:getNoticeBarIcon(articleHistoryObj)</code> - get the notice bar icon filename. It must be passed an ArticleHistory object. Returns nil if no icon was set.
* <code>Row:getNoticeBarCaption(articleHistoryObj)</code> - get the notice bar icon caption. It must be passed an ArticleHistory object. Returns nil if no caption was set.
* <code>Row:getNoticeBarIconSize()</code> - get the notice bar icon size.
* <code>Row:exportNoticeBarIcon(articleHistoryObject)</code> - returns the rendered notice bar icon link. This method must be passed an ArticleHistory object.
* <code>Row:setText(text)</code> - set the text for the object to output. This may be a string or a function that takes an ArticleHistory object as input and returns the text as output.
* <code>Row:getText(articleHistoryObject)</code> - gets the row text. This method must be passed an ArticleHistory object.
* <code>Row:exportHtml(articleHistoryObject)</code> - returns the rendered row. This method must be passed an ArticleHistory object.
* <code>Row:setCategories(val)</code> - sets the objects categories. <var>val</var> may be either an array of strings, or a function that takes an ArticleHistory object as input and returns an array of Category objects as output.
* <code>Row:getCategories(articleHistoryObj)</code> - returns an array containing the object's Category objects. This method must be passed an ArticleHistory object.

=== Status ===

Status objects generate the row detailing the current status of the article. They inherit all properties and methods from [[#Row|Row]] objects, including the [[#Message|Message]] mixin methods. They have the following additional properties:

* <code>id</code> - the status ID.
* <code>name</code> - the status name.
* <code>statusCfg</code> - the status config table for the object's status ID.

=== MultiStatus ===

MultiStatus objects are variations on [[#Status|Status]] objects for articles that can have multiple current statuses, e.g. Good Article and Former Featured Article. They can be used interchangeably with Status objects.

=== Notice ===

Notice objects generate rows containing notices about the article that aren't part of its current status, e.g. the date the article was featured on the Main Page. They inherit all the properties and methods from [[#Row|Row]] objects, including the [[#Message|Message]] mixin methods. They don't have any additional properties or methods.

=== Action ===

Action objects generate rows detailing a single action in the history of an article, e.g. a Featured Article candidacy. They inherit all properties and methods from [[#Row|Row]] objects, including the [[#Message|Message]] mixin methods. They have the following additional properties:

* <code>paramNum</code> - the parameter number for that action. Used to format error messages.
* <code>id</code> - the action ID. For example, featured article candidacies have an ID of "FAC". There is only one ID for each kind of action.
* <code>actionCfg</code> - the action config table for the object's action ID.
* <code>link</code> - the link set for the action, or the current talk page name if not set.
* <code>resultId</code> - the ID for the result of the action. For example, featured article candidates that were promoted have a resultId of "promoted". There is only one resultId for each possible result of an action.
* <code>date</code> - the date the action was carried out, or the 'action-date-missing' message if a date was not set.
* <code>oldid</code> - the oldid for the action. Nil if not set.

Action objects have the following additional methods:

* <code>Action:getParameter(key)</code> - finds the original parameter name for the key <var>key</var> that was passed to Action.new.
* <code>Action:getName(articleHistoryObject)</code> - gets the name of the action. This method must be passed an ArticleHistory object.
* <code>Action:getResult(articleHistoryObject)</code> - gets the result text of the action. This method must be passed an ArticleHistory object.

=== CollapsibleNotice ===

CollapsibleNotice objects generate rows containing notices that go in the collapsible part of the template, underneath the list of actions. They can also include a collapsible text field. This is used for notices that are not important enough to be displayed as a (more prominent) [[#Notice|Notice]] object, e.g. DYK notices. CollapsibleNotice objects inherit all the properties and methods from [[#Row|Row]] objects, including the [[#Message|Message]] mixin methods. They don't have any additional properties, but they have the following additional methods:

* <code>CollapsibleNotice:setCollapsibleText(s)</code> - set's <var>s</var> as the text to be displayed in the object's collapsible text field.
* <code>CollapsibleNotice:getCollapsibleText(s)</code> - returns the text to be displayed in the object's collapsible text field.

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||
<!-- Categories go here and interwikis go in Wikidata. -->

}}</includeonly>
<noinclude>
[[Category:Module documentation pages]]
</noinclude>