StarfieldWiki:Riven

From Starfield Wiki
Jump to: navigation, search

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]

[Test Page]

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.

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.

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]

[Test Page]

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.

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.

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

Example[edit]

#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]

{{#findfirst:pages...}} (supports if/ifnot) [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 {{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]

{{#ifexistx:pagename|text if true|text if false}} (supports if/ifnot) [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.

#include[edit]

{{#include:pagename|pagename2|...}} (supports debug and if/ifnot) [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.

#pickfrom[edit]

{{#pickfrom:npick|arg1|arg2...|(seed=)|(separator=)|(allowempty=)}} (supports if/ifnot) [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.

#rand[edit]

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

#splitargs[edit]

{{#splitargs:subtemplate|nargs|...}} (supports debug and if/ifnot) [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.

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

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
{{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.
{{#splitargs:ID|1|00012345|xx012345|separator=<br>}}
{{ID|1=00012345}}<br>{{ID|1=xx012345}}
00012345
xx012345
{{#splitargs:Ordinal|1|1|2|3|4|5|separator=<br>}}
{{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}}
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 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]

cleantable[edit]

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

  1. Headers don't count. They are completely ignored in determining if a row is blank.
  2. Any row in which the non-header elements are all empty, whitespace, or raw {{{argument}}}s can be removed.
  3. 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
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
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}}}

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.