StarfieldWiki:Riven
Riven is a Mediawiki extension by RobinHood70 that provides a number of features that complement template development. All the features herein have been disabled or removed ("riven") from MetaTemplate in favor of using the modern MediaWiki methods of doing things, as well as splitting off features that are likely to work from MW 1.35 forwards and those that probably won't or will need a significant change in concept. In the future, this extension will be expanded to include the non-namespace-related features of UespCustomCode as well.
In the documentation below, those parameters that use a name and an equals sign (name=value) require that you type in the full parameter name and a value. Those that are listed only numerically (1 (name)) should not include a name or number and should just be the value. The names are just for clarity of purpose. If in doubt, pretty much everything works the same way you're used to from MetaTemplate.
Usage[edit]
Conditional Expressions[edit]
In MetaTemplate, conditional expressions were available on most or all functions. This has been retained in Riven, but the feature is specific to where it makes sense to have it rather than on absolutely everything. For several functions, having if/ifnot available didn't make much sense. In the unlikely event that they're being used (or you want to use them), they can always be added or you can use a traditional #if statement.
For those functions that do allow if/ifnot, the functionality has been expanded to allow both to be used simultaneously. The function will only run if both conditions are satisfied. Each expression can be as complex as necessary; all that matters is what's left after the entire expression has been evaluated. An easy way to check this is to copy everything after the equals sign to a regular page...what you see is generally what the function will evaluate.
| Parameter | Scope | Description |
|---|---|---|
| if | optional | The subroutine will only be executed if the expression evaluates to what PHP considers to be true. (See ifnot.) |
| ifnot | optional | The subroutine will only be executed if the expression evaluates to false. Unlike MediaWiki code, this includes not only empty strings, but also 0. Everything else will evaluate to true. |
If the same condition needs to be used multiple times, then it is probably most efficient to use #define or #local to evaluate the condition once, then use the #define'd variable in each necessary subroutine.
Debug Features[edit]
Features that rewrite your code in some fashion all support a debug option. Instead of behaving normally, the re-written MediaWiki code will be shown on-screen. This allows for you to debug any issues happening behind the scenes with the function or tag.
| Parameter | Scope | Description |
|---|---|---|
| debug | optional | If set to true, this will cause the output to be displayed on-screen, but the function will behave normally if accidentally saved with this option set. There is an exception to that, however, in that if this parameter is set to always, the output will be displayed even after being saved.
|
Multiple Values[edit]
If a function call sees multiples of the same value, only the last one will be evaluated and the rest will be discarded, comparable to wiki templates. In the case of #splitargs, if there's a conflict with template parameter names, the last parameter of a given name will apply to #splitargs, then any inner parameters with that name will be applied to the template.
Parser Functions[edit]
#arg[edit]
{{#arg:name|defaultvalue}}[Test Page]
The #arg function returns the value of the given URL argument. This allows template-like behavior when linking to a page with different argument values. The idea for this function came from DynamicFunctions, though the code was completely re-written.
| Parameter | Scope | Description |
|---|---|---|
| 1 (name) | required | The argument to search for. |
| 2 (defaultvalue) | optional | If the argument doesn't exist, this value will be returned. |
Because it's infrequently used, uses of this call are tracked in Category:Riven-Pages using arg.
Example[edit]
Example page in [{{fullurl:{{FULLPAGENAME}}/Arg Example|color=red}} red].
The same page in [{{fullurl:{{FULLPAGENAME}}/Arg Example|color=blue}} blue].
(Click the links to see the effect.)
#explodeargs[edit]
This is simply a shortcut to the exploding form of #splitargs. Rather than being parameter-based, like the other variants of #splitargs, this version is geared towards "exploding" text—in other words, dividing it into smaller chunks based on a specific character or word. There are currently two ways to use #explodeargs: the original way (now deprecated), where the text and delimiter came first, and the current way, which puts the subtemplate and number of arguments first, just like #splitargs does. To convert, simply move the first two parameters to become the last two or change the call to #splitargs. While the #splitargs version adds a little extra typing, it has the advantage of using the same command everywhere, regardless of what you're splitting on. In either case, the delimiter defaults to a comma, so you can leave that off if that's what you're using.
{{#explodeargs:text|delimiter|subtemplate|nargs}}should be converted to either of these{{#explodeargs:subtemplate|nargs|text|(delimiter)}}{{#splitargs:subtemplate|nargs|explode=text|(delimiter=delimiter)}}
Old versions of #explodeargs are tracked in Category:⧼riven-tracking-explodeargs⧽. They will disappear from that category once converted to either the new #eplodeargs format or #splitargs.
Conversion Examples[edit]
Other examples can be seen in the #splitargs entry, below.
Default delimiter
{{#explodeargs:{{{materials}}}|,|Online Furnishing Summary/List|2}}converts to either{{#explodeargs:Online Furnishing Summary/List|2|{{{materials}}}}}or{{#splitargs:Online Furnishing Summary/List|2|explode={{{materials}}}}}
Specific delimiter
{{#explodeargs:{{{materials}}}|~|Online Furnishing Summary/List|2}}converts to either{{#explodeargs:Online Furnishing Summary/List|2|{{{materials}}}|~}}or{{#splitargs:Online Furnishing Summary/List|2|explode={{{materials}}}|delimiter=~}}
#findfirst[edit]
Finds the first page out of a list of pages and returns its full, normalized title. This is expected to be of significant value for templates like {{Future Link}} and {{Lore Link}}, but may be useful in other cases as well. It's the equivalent of running #ifexistx multiple times, but saves the hassle of writing it all out. The same page will be checked only once, even if it's missing and listed with different namespace shortcuts. For example, if you searched for {{#findfirst:ON:Nothing|ESO:Nothing}}, #findfirst would only check Online:Nothing once. If that had matched, it would've returned Online:Nothing, despite the fact that "Online" is never used in the file list.
#ifexistx[edit]
Just like the #ifexist function, #ifexistx checks to see if a page exists and returns a value based on the result. Unlike that function, however, the requested page will not be added to the Wanted Pages list. While it may seem redundant to have if/ifnot values, the additional checks can be used to specify when not to run the {{#ifexistx}} check at all, thus saving on the number of "expensive" parser functions being called.
#include[edit]
The #include parser function allows subpage transclusion without creating red links or entries in Wanted Templates if the requested page doesn't exist. For example, if type=Hold, {{#include:Place Summary/Skyrim {{{type}}} }} would transclude the Place Summary/Skyrim Hold sub-template. But if type=Inn, nothing would be transcluded and no wanted template would be listed on Wanted Templates. If multiple pages are specified, they will each be transcluded in order, if they exist.
#pickfrom[edit]
Pickfrom randomly selects npick entries from the subsequent list of arguments and displays those entries in a random order. Any number of arguments can be provided.
| Parameter | Scope | Description |
|---|---|---|
| 1 (npick) | required | The number of entries to display. Unlike the MetaTemplate version of #pickfrom, if this number is greater than or equal to the total number of entries, the entire list will be shown in random order. |
| 2 | optional | The remaining arguments are the list of strings that are to be displayed. If none, this function will quietly abort. If npick is greater than the count of all entries, then the order will be randomized and the entire list will be displayed.
|
| seed | optional | This can be used to provide a seed for the shuffle function used to randomize the list of entries. By default, the current timestamp is used as the seed, which means a different result will be returned every second. The wiki's date and time variables can be used to create a seed that will make the result change less frequently. For example, |seed={{LOCALHOUR}} will make the list change only once every week. In most cases, the "LOCAL" time functions are preferable to the "CURRENT" functions, because they return the same value for all site readers.
|
| separator | optional | This can be used to provide any text that should separate the selected entries. The default value for separator is a newline character. C-style escape sequences are recognized (e.g., '\n' for newline, '\t' for tab). To include spaces in the separator, it needs to be enclosed in quotes (single or double); otherwise the wiki processing will automatically strip any spaces from the end of the string. For example, |separator=' ' will add a single space in between all strings; the pair of quote marks is not considered part of the string.
|
| allowempty | optional | Normally, #pickfrom will ignore entries that have no text in them. By adding allowempty=1, you can force pickfrom to allow them in the output, including any separators between entries.
|
Because it's infrequently used, uses of this call are tracked in Category:Riven-Pages using pickfrom.
#rand[edit]
{{#rand:(seed=)}}or{{#rand:to|(seed=)}}or{{#rand:from|to|(seed=)}}
The #rand function returns a random integer value. If no parameters are used, this will be in the range 1-6. If only one parameter is used, this will be in the range of 1-to. If both are provided, the number will be in the range from-to.
| Parameter | Scope | Description |
|---|---|---|
| Note that only the names are used here, since the meaning of a specific parameter depends on how many parameters you're using. | ||
| (from) | optional | The lowest number that should be returned. |
| (to) | optional | The highest number that should be returned. |
| seed | optional | This can be used to provide a seed for the shuffle function used to randomize the list of entries. By default, the current timestamp is used as the seed, which means a different result will be returned every second. The wiki's date and time variables can be used to create a seed that will make the result change less frequently. For example, |seed={{LOCALHOUR}} will make the list change only once an hour. In most cases, the "LOCAL" time functions are preferable to the "CURRENT" functions, because they return the same value for all site readers.
|
Because it's infrequently used, uses of this call are tracked in Category:Riven-Pages using rand.
#splitargs[edit]
Splitargs is a parser function that can be used to repeatedly call a sub-template, using a different set of arguments each time the sub-template is called. There are different ways that #splitargs can be called, but in all of them, the first two parameters are the same.
| Parameter | Scope | Description |
|---|---|---|
| 1 (subtemplate) | required | The template to be called. |
| 2 (nargs) | required | How many unnamed parameters should be passed to the sub-template each time it is called. The sub-template will be called repeatedly for each set of nargs parameters. (Note: this must be a positive integer or the entire #splitargs call will abort.) |
| separator | optional | Text to add between each of the templates in the final output. |
| named arguments | optional | Any named arguments within the argument list will always be passed to the sub-template verbatim each time it is called. If you need to use a named argument with the same name as a #splitargs parameter (e.g., separator), add the prefix "sa:" to the splitargs version and move it after the one that's intended for the template (e.g., |separator=*|sa:separator=', '). This is only supported for the delimiter, explode, and separator parameters. If any other parameter overlaps parameter names used in the template, it's easiest to simply allow an alternate parameter name in the template. It's also possible for the Riven code to provide alternates if, for whatever reason, altering the template is undesirable.
|
From there, there are three different ways that #splitargs can be used. In the event of a conflict, the template prioritizes old #explodeargs calls, then the following variants, in order:
Exploding[edit]
{{#splitargs:subtemplate|nargs|explode=text|(delimiter=delimiter)}}or{{#explodeargs:subtemplate|nargs|text|(delimiter)}}
With this version of #splitargs, the explode parameter is what is split on. By default, a comma will be used as the delimiter, but any other character can be used. A tilde (~) is a common alternative, since it has no meaning to the MediaWiki software outside of signatures, which require three to five in a row, and is almost never used for any other purpose.
With Arguments[edit]
{{#splitargs:subtemplate|nargs|text1|text2|etc.}}
If additional arguments are provided as part of the #splitargs call, then those arguments are used as the list of arguments which should be passed to the sub-template. The number of arguments which can be passed to #splitargs is unlimited. If no additional arguments are provided, #splitargs then looks to the parent template (see below). If there are no arguments found there, the call to #splitargs will be aborted.
Parent Arguments[edit]
{{#splitargs:subtemplate|nargs}}
If no additional anonymous arguments are provided to #splitargs, then the parent template's anonymous arguments themselves are used as the list of arguments to be passed to the sub-template.
Examples[edit]
| Details | Typing This | Is Equivalent To This | Resulting In This | |
|---|---|---|---|---|
| Exploding Most useful with a variable. |
Assuming a template called this with |fruit=red,Cherry,yellow,Banana,lime,Lime |
|
Cherry Banana Lime | |
| With Arguments Useful directly on pages or as a limited loop. |
{{#splitargs:ID|1|00012345|xx012345|separator=<br>}} |
|
00012345 xx012345 | |
| {{#splitargs:Ordinal|1|1|2|3|4|5|separator=<br>}} |
|
1st 2nd 3rd 4th 5th | ||
| Parent Arguments Most useful with templates that need to call another template repetitively with different arguments. |
From the pseudo-template UESPWiki:Riven/Example, which contains the following: {{UESPWiki:Riven/Example|separator=' • '|A|1|B|2|C|3}} |
Template:UESPWiki:Riven/Example | Template:UESPWiki:Riven/Example |
#trimlinks[edit]
{{#trimlinks:text to trim|(mode=smart)}}[Test Page]
This function takes the provided text and strips out all links, leaving just the label. This can be done in one of two ways. The normal way uses standard MediaWiki code to remove links. This will work as desired the vast majority of the time and as long as it's working correctly, it's the one you should use. The second way (mode=smart) parses the text more thoroughly but is much more server-intensive. It unlinks most internal links, but leaves Category, File, interwiki, and external links untouched. You can use this to transclude entire pages without the internal links and it will look nearly identical or completely identical to the original, just without internal links.
The raison d'être for this function is the place description pages. With this function, we can freely add links to any and all place descriptions—then use #trimlinks on Oblivion:Places or other pages where the links are overwhelming. In fact, the links on Oblivion:Places can be turned off by adding a single {{#define:trimlinks|true}} line at the top of the page. The variable is then inherited by the Place Link template, telling it to remove the links.
Examples[edit]
{{#trimlinks:[[ESO:Places|places to go]] and [[ESO:NPCs|people to see]]}}
This would result in the text "places to go and people to see".
{{#trimlinks:{{:Main Page}}|mode=smart}}
This would display the entire Main Page without internal links. You can see what that looks like here. As you can see, only the search box was corrupted. Everything else looks and works as expected, there are just no internal links anymore.
Tag Functions[edit]
Note that due to a long-standing bug in MediaWiki, some of the shortcuts that are normally available while editing a page—namely, the pipe trick, signatures, and substitution—are not available inside tag functions and will appear exactly as typed.
cleanspace[edit]
Cleanspace is designed to make templates more legible. Within <cleanspace></cleanspace> tags, any whitespace around links, parser functions, templates, and HTML code is removed before the page is rendered. Depending on mode, comments may also be removed, or space around external links. This space removal means that tags and parser functions can each be placed on separate lines. This can be especially useful for MetaTemplate functions like #define, #local, #preview, and the various data-related functions, along with traditional things like category links and HTML tables. The top option (see below) makes this useful not only for setup code, but sometimes even within the body of a template.
| Parameter | Scope | Description |
|---|---|---|
| mode | optional | Regardless of mode, cleanspace will always remove leading and trailing whitespace from any text inside the tags. The behavior after that is controlled by the following mode options:
|
| Difference | Mode | Example |
|---|---|---|
| Comment Handling | Text | [[Category:Example]] <!-- Comment --> [[Category:Example]] |
| Original | [[Category:Example]]<!-- Comment -->[[Category:Example]] | |
| Top | Comments are completely removed with the Top method.
[[Category:Example]][[Category:Example]] |
|
| Links inside other things (e.g., template parameters, |
Text | Space between links is handled differently.
{{#local:example|[[Oblivion:Oblivion|example1]] [[Skyrim:Skyrim|example2]]}}
|
| Original | Original mode gets everything, regardless of where it appears.
{{#local:example|[[Oblivion:Oblivion|example1]][[Skyrim:Skyrim|example2]]}}
| |
| Top | Top mode removes spaces only at the top level (i.e., not inside anything like a template call or #define).
{{#local:example|[[Oblivion:Oblivion|example1]] [[Skyrim:Skyrim|example2]]}}
| |
| Tag Handling | Text | Top mode looks for anything that might be a valid tag; original mode is more easily fooled. On the other hand, original mode will trim around external links, while top mode won't.
[[Skyrim:Skyrim|Skyrim]] <br> [[Oblivion:Oblivion|Oblivion]] <!--Valid--> [[Skyrim:Skyrim|Skyrim]] <gotcha> [[Oblivion:Oblivion|Oblivion]] <!--Close Enough--> [[Skyrim:Skyrim|Skyrim]] > [[Oblivion:Oblivion|Oblivion]] <!--Not A Tag--> [[Skyrim:Skyrim|Skyrim]] <Haha!> [[Oblivion:Oblivion|Oblivion]] <!--Invalid Syntax--> [https://en.uesp.net] <br> [https://starfieldwiki.net] <!--Top Mode Fail--> |
| Original | [[Skyrim:Skyrim|Skyrim]]<br>[[Oblivion:Oblivion|Oblivion]]<!--Valid-->[[Skyrim:Skyrim|Skyrim]]<gotcha>[[Oblivion:Oblivion|Oblivion]]<!--Close Enough-->[[Skyrim:Skyrim|Skyrim]] >[[Oblivion:Oblivion|Oblivion]]<!--Not a Tag-->[[Skyrim:Skyrim|Skyrim]]<Haha!>[[Oblivion:Oblivion|Oblivion]]<!--Invalid Syntax-->[https://en.uesp.net]<br>[https://starfieldwiki.net]<!--Top Mode Fail--> | |
| Top | [[Skyrim:Skyrim|Skyrim]]<br>[[Oblivion:Oblivion|Oblivion]][[Skyrim:Skyrim|Skyrim]]<gotcha>[[Oblivion:Oblivion|Oblivion]][[Skyrim:Skyrim|Skyrim]] > [[Oblivion:Oblivion|Oblivion]][[Skyrim:Skyrim|Skyrim]] <Haha!> [[Oblivion:Oblivion|Oblivion]] [https://en.uesp.net] <br> [https://starfieldwiki.net] |
cleantable[edit]
Any tables found within <cleantable>...</cleantable> tags, including nested tables, are "cleaned" of any empty rows they may have. This means that many infobox templates can be significantly simplified. It is no longer necessary to embed entire sections of the table in #if statements, which in turn means that the need for magic words such as {{!}} can be reduced or even eliminated, making infoboxes and other data-driven tables in templates much easier to work with.
For a cell to be considered blank, it must be a normal cell with only whitespace or raw arguments ({{{argument}}}) in it. In the case of rowspans, the cell is only evaluated in its "home" position—the one that has the colspan or rowspan attributes; in any other cell or row, the data will be ignored. If a row is removed where some of the cells are part of a rowspan, the rowspan count will be adjusted accordingly. A cell will also be considered blank if content is being added via the CSS content attribute. Unlike MetaTemplate, HTML tags in a cell are not ignored—the debug feature should help track down problem templates and the like.
Note: while HTML allows you to skip parts of a table, such as having a stand-alone <td> element, cleantable does not support this. Any manually entered HTML tables must have all three levels of a table properly emitted (i.e., it must have a <table>, <tr>, and either a <th> or <td>, as appropriate). Without those, results are unpredictable.
| Parameter | Scope | Description |
|---|---|---|
| protectrows | optional | This allows you to specify the number of rows from the top that are protected from deletion (default: 1). This typically ensures that a table will not be removed in its entirety, but it can be set to 0 to specifically allow the entire table to be removed. Note that if the cleantable tag covers multiple tables, all tables will have the same number of rows protected. Use separate cleantable tags if different tables have different numbers of header rows that need to be preserved. |
How It Works[edit]
Cleantable makes an internal map of which cells are where in a table. It then scans through them to see what can be removed based on three rules:
- Headers don't count. They are completely ignored in determining if a row is blank.
- Any row in which the non-header elements are all empty, whitespace, or raw {{{argument}}}s can be removed.
- Any row consisting entirely of header cells (typically a section header) will be removed if there were non-header (content) rows below it and all of those rows have been removed. If protectrows is zero, then the top row of that table can also be removed if it's the only row left and it's a header row. In the event that the last row is removed from the table, the table will be removed from the page altogether. Note, however, that any whitespace surrounding the removed table will remain untouched, which could leave large gaps on a page if this hasn't been accounted for.
Conceivably, the option of completely blanking a table could be combined with #if statements to take actions based on whether the table was blanked or not. For example:
{{#local:table|{{Some Table Template}}}}
{{#if:{{{table|}}}|{{{table}}}|Nothing to see here!}}
Examples[edit]
| Test | Before Cleaning | After Cleaning | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Simple Table |
|
| ||||||||||||||||||||||||||||||||||||
| Deleted Table (protectrows=0) |
|
| ||||||||||||||||||||||||||||||||||||
| Complex Rowspan |
|
| ||||||||||||||||||||||||||||||||||||
| Columns |
|
| ||||||||||||||||||||||||||||||||||||
| Triple-Nested Empty Tables (protectrows=0 debug=1) |
|
|||||||||||||||||||||||||||||||||||||
Variables[edit]
SKINNAME[edit]
{{SKINNAME}}[Test Page]
This variable contains the name of the current skin. It replaces the {{#skin}} function from DynamicFunctions.
Because it's infrequently used, uses of this call are tracked in Category:Riven-Pages using skinname.
Example[edit]
You are currently using {{SKINNAME}}.
You are currently using darkvector.
Installation Notes[edit]
Riven is dependent on the ParserHelper library. At development time, there was no clear, unified way of loading PHP dependencies, so for now, you need to manually add wfLoadExtension('ParserHelper'); to your extension list before the equivalent line for this extension. In future, this may become an entry in composer.json or similar.
See Also[edit]
- Magic Words — A list of custom magic words provided by both MediaWiki and UESP-specific extensions.
- MetaTemplate — The extension that used to provide most of the functions found in the one, and which still houses storage- and variable-related functions.
- UespCustomCode — Customizations specific to UESP's setup, focusing mainly on custom namespace functions.
