UESPWiki: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.

UsageEdit

Conditional ExpressionsEdit

Conditional expressions allow the same functionality as the built-in {{#if:...}} function, but with an abbreviated syntax that can be both cleaner and more convenient when writing a template. They're available on most functions in Riven, tagged below with "(supports if/ifnot)". In the unlikely event that they're needed on a function they're not currently available on, they can easily be added or you can use a traditional #if statement.

You can use if/ifnot individually or together, in which case 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 what the expression evaluates to is to copy it out to the main part of the template—what you see is what the function will evaluate.

Conditional Parameters
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.

Debug FeaturesEdit

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.

Debug Parameter
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.

Parser FunctionsEdit

#argEdit

{{#arg:name|defaultvalue}}

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.

#arg
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.

ExampleEdit

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.)

Example page in red.
The same page in blue.

#explodeargsEdit

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. 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:subtemplate|nargs|text|(delimiter)}}

{{#splitargs:subtemplate|nargs|explode=text|(delimiter=delimiter)}}

Conversion ExamplesEdit

Other examples can be seen in the #splitargs entry, below.

Default delimiter

{{#explodeargs:Online Furnishing Summary/List|2|{{{materials}}}}} or

{{#splitargs:Online Furnishing Summary/List|2|explode={{{materials}}}}}

Specific delimiter

{{#explodeargs:Online Furnishing Summary/List|2|{{{materials}}}|~}} or

{{#splitargs:Online Furnishing Summary/List|2|explode={{{materials}}}|delimiter=~}}

#findfirstEdit

{{#findfirst:pages...}} (supports if)

Test Page

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 {{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.

#labelEdit

{{#label:text}}

Test Page

This parser function removes any text in parentheses at the end of a page name. For example, {{#label:{{PAGENAME}}}} used on Lore:Vivec (god) would produce "Vivec".

#ifexistxEdit

{{#ifexistx:pagename|text if true|text if false}} (supports if)

Test Page

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.

#includeEdit

{{#include:pagename|pagename2|...}} (supports debug, if)

Test Page

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.

#pickfromEdit

{{#pickfrom:npick|arg1|arg2...|(seed=)|(separator=)|(allowempty=)}} (supports if)

Test Page

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.

#pickfrom
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.

#randEdit

{{#rand:(seed=)}} or

{{#rand:to|(seed=)}} or

{{#rand:from|to|(seed=)}}

Test Page

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.

#rand
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.

#sortableEdit

{{#sortable:text}}

Test Page

This parser function takes a page name and moves the words "A", "An", or "The" at the beginning of the page name to the end. For example, {{#sortable:{{PAGENAME}}}} used on Lore:The True Nature of Orcs would produce "True Nature of Orcs, The".

#splitargsEdit

{{#splitargs:subtemplate|nargs|...}} (supports debug, if)

Test Page

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.

ExplodingEdit

{{#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 ArgumentsEdit

{{#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 ArgumentsEdit

{{#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.

#splitargs
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.
Exploding
`explode`	optional	When using the exploding variant of #splitargs, this is the text that will be split apart.
`delimiter`	optional	When using the exploding variant of #splitargs, the delimiter is what separates items in the original text (default: comma). For example, if you want to use a tilde instead of a comma, you would use: `\|explode=1~2~3\|delimiter=~`.
With Arguments
`3+`	optional	Any anonymous arguments after the first two form the arguments to be sent to the template. Be careful to always provide at least one argument to this version or else it will take its anonymous arguments from the parent template (if they exist) rather than the #splitargs call.

ExamplesEdit

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

{{FC|1=red|2=Cherry}}<br>{{FC|1=yellow|2=Banana}}<br>{{FC|1=lime|2=Lime}}

Cherry
Banana
Lime

With Arguments
Useful directly on pages or as a limited loop.

{{ID|1=00012345}}<br>{{ID|1=xx012345}}

00012345
xx012345

{{Ordinal|1=1}}<br>{{Ordinal|1=2}}<br>{{Ordinal|1=3}}<br>{{Ordinal|1=4}}<br>{{Ordinal|1=5}}

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}}

{{Project:Riven/ExampleSub|1=A|2=1}}&#32;•&#32;{{Project:Riven/ExampleSub|1=B|2=2}}&#32;•&#32;{{Project:Riven/ExampleSub|1=C|2=3}}

A=1 • B=2 • C=3

#trimlinksEdit

{{#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.

ExamplesEdit

{{#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 FunctionsEdit

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.

cleanspaceEdit

<cleanspace mode=>...</cleanspace> (supports debug)

Test Page

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.

<cleanspace>
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: original: For backwards compatibility, this is the default option. It works strictly on a search-and-replace basis, removing spaces between anything ending in `] } >` and anything starting with `[ { <`. top: This cleans comment blocks as well as spaces between HTML tags, links, templates, and arguments, but only at the top level...it won't look "inside" links, templates, or parser functions (including #if and the like). For the most part, this will be more useful in templates, but there are times where the original works better. See the examples for more information. ~~recursive: This uses the exact same approach as above, but it does look inside links or templates found within it.~~ Currently unavailable.

Examples

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, image links)	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]

cleantableEdit

<cleantable protectrows=>...</cleantable> (supports debug)

Test Page

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.

<cleantable>
Parameter	Scope	Description
`cleanimages`	optional	By default, images are removed before determining whether a cell is empty. Setting this to 0 will disable that feature and images will count as content.
`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 WorksEdit

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, images, 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!}}

ExamplesEdit

Test

Before Cleaning

After Cleaning

Simple Table

Table Header
Cell Header
Cell Header 2	Data

Table Header
Cell Header 2	Data

Deleted Table
(protectrows=0)

Header
Header2

Complex Rowspan

Funky Table	Data 0	Cool!
Header	Data 1

	Data 3	Below Cool
Another row

Funky Table	Data 0	Cool!
Header	Data 1	Cool!
Header	Data 3	Below Cool!
Another row

Columns

Infobox Header
Left		Right


New Section
This section has actual data.

Infobox Header
New Section
This section has actual data.

Triple-Nested Empty Tables
(protectrows=0
debug=1)

Data

Inner Header

Stupid level of nesting
{{{missing}}}

VariablesEdit

SKINNAMEEdit

{{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.

ExampleEdit

You are currently using {{SKINNAME}}.

You are currently using minerva.

Installation NotesEdit

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.

UESPWiki ^β

UESPWiki:Riven

UsageEdit

Conditional ExpressionsEdit

Debug FeaturesEdit

Parser FunctionsEdit

#argEdit

ExampleEdit

#explodeargsEdit

Conversion ExamplesEdit

#findfirstEdit

#labelEdit

#ifexistxEdit

#includeEdit

#pickfromEdit

#randEdit

#sortableEdit

#splitargsEdit

ExplodingEdit

With ArgumentsEdit

Parent ArgumentsEdit

ExamplesEdit

#trimlinksEdit

ExamplesEdit

Tag FunctionsEdit

cleanspaceEdit

cleantableEdit

How It WorksEdit

ExamplesEdit

VariablesEdit

SKINNAMEEdit

ExampleEdit

Installation NotesEdit

See AlsoEdit

UESPWiki β

UESPWiki:Riven

UsageEdit

Conditional ExpressionsEdit

Debug FeaturesEdit

Parser FunctionsEdit

#argEdit

ExampleEdit

#explodeargsEdit

Conversion ExamplesEdit

#findfirstEdit

#labelEdit

#ifexistxEdit

#includeEdit

#pickfromEdit

#randEdit

#sortableEdit

#splitargsEdit

ExplodingEdit

With ArgumentsEdit

Parent ArgumentsEdit

ExamplesEdit

#trimlinksEdit

ExamplesEdit

Tag FunctionsEdit

cleanspaceEdit

cleantableEdit

How It WorksEdit

ExamplesEdit

VariablesEdit

SKINNAMEEdit

ExampleEdit

Installation NotesEdit

See AlsoEdit

UESPWiki ^β