View source for Template:Perks/doc

== Overview ==

Displays data about Perks, Cornerstones, and other effects based on search parameters and exclusions. There are a few ways the data can be displayed.

== Parameters ==

All parameters are optional. If no parameters are given, a table of '''all''' 300+ Perks will be displayed, showing their icon and name linking to the Perk's page, descriptions, rarity, sources, and price when purchased from a trader.

=== Selection, Filtering, and Exclusion ===

You may combine the first three parameters to return more Perks. The result will be the union of your selections, without duplicates. Then use <code>exclude</code> to remove any Perks that are unrelated to your purposes with their IDs or filter by rarity or source.

Remember that IDs are not visible int he game, so you may need to look them up first.

{|class="wikitable"
! Parameter !! Description
|-
| id || A list of IDs of Perks, Cornerstones, and effects, separated by commas. Since IDs are unique, each matched ID adds exactly one Perk to the table. Will not throw an error if an ID is invalid.
|-
| name || A list of terms to search for in names. Adds all Perks with any part of their names matching those terms to the table.
|-
| description || A list of terms to search for in descriptions. Adds all Perks with any part of their descriptions matching that string to the table.
|-
| search || A shortcut parameter for the previous two. <code>search=criteria</code> is the same as <code>name=criteria|description=criteria</code>. Using this parameter does not prevent you from or override searching by name or description too, but it kind of defeats the purpose.
|-
| rarity || Filters any Perks found by the first search parameters by the specified rarity. Does not throw an error if you misspell the term; here are the correct options:
* <code>Uncommon</code>
* <code>Rare</code>
* <code>Epic</code>
* <code>Legendary</code>
* <code>Mythic</code>
|-
| source || Filters any Perks found by the first search parameters by the specified source. Does not throw an error if you misspell the term; here are the correct options:
* <code>Altar</code> (the Forsaken Altar)
* <code>Cornerstone</code>
* <code>Order</code>
* <code>Relic</code> (from Glade Events)
* <code>Trader</code>
|-
| exclude || A list of IDs, separated by commas, that will be excluded from the display. Will not throw an error if an ID is invalid.
|}

=== Output Overrides ===

These parameters allow you to customize the appearance of the results.

{|class="wikitable"
! Parameter !! Default !! Description
|-
| caption || "Perks and Cornerstones" || Captions are calculated automatically based on your search and filtering criteria. However, if you want to override the default caption for the table, you can specify it here.
|-
| show_id || hidden || Use <code>show_id=show</code> if you want to '''show''' a first column in the table that shows the ID of the Perk. (In list or inline display, the ID is shown in parentheses after the Perk's name.)
|-
| show_rarity || shown || Use <code>show_rarity=no</code> if you want to '''hide''' the rarity column from the table. (In list or inline display, the rarity is never shown.)
|-
| show_description || shown || Use <code>show_description=no</code> if you want to '''hide''' the description column from the table. (In list or inline display, the description is never shown.)
|-
| skip_sources || not skipped || Use <code>skip_sources=skip</code> if you want a table that skips the section of five columns indicating the sources of the Perk. This breaks from the naming convention of the other parameters because the template logic is different.

If you want to hide individual columns to make comparisons easier, see below, but take note of two things: (1) in list or inline display, sources are never shown and (2) if you hide all of the source columns individually, without skipping the sources section, the table headings will become misaligned.
|-
| show_source_altar || shown || Use <code>show_source_altar=no</code> to '''hide''' the Forsaken Altar source column.
|-
| show_source_cornerstone || shown || Use <code>show_source_cornerstone=no</code> to '''hide''' the Cornerstone source column.
|-
| show_source_order || shown || Use <code>show_source_order=no</code> to '''hide''' the Order source column.
|-
| show_source_relic || shown || Use <code>show_source_relic=no</code> to '''hide''' the Glade Event Relic source column.
|-
| show_source_trader || shown || Use <code>show_source_trader=no</code> to '''hide''' the Trader source column.
|-
| show_price || shown || Use <code>show_price=no</code> to '''hide''' the price column from the table. (In list or inline display, the price is never shown.)
|-
| display || a table || For use when including these Perks inside other tables or within paragraphs, the '''display''' parameter condenses the output to just the links to the pages on each Perk:
* Use <code>display=list</code> to convert the table layout into a basic bulleted list with simple links and no icons.
* Use <code>display=inline</code> to convert the table into an inline list of links, separated by commas, also with no icons.
|-
| list_type || bullet || When displaying as a list instead of a table, you can specify <code>list_type=number</code> to show the list as a numbered list instead.
|}

== Errors ==

=== No results from search ===

If you specify parameters intending to select or search for terms, sometimes there is no result. This can be because you misspelled an id, rarity name, or source name or asked for a search term that was no present in any name or description—or ultimately excluded every item that was found. In this situation, the template, will instead render a plain-text message that nothing was found. (This error display is used for all display modes, table, list, or inline.)

<pre>{{Perks
|id=IDs are easy to misspell
}}</pre>

Yields:
{{Perks|id=IDs are easy to misspell}}

== Table Examples ==

=== Selecting Perks by their IDs ===

IDs to select are normalized, so you do not need to worry about case. Spelling, spacing, and punctuation must all be correct, however.

<pre>{{Perks
|id=accidental barrels
}}</pre>

Is the same as the following:

<pre>{{Perks
|id=Accidental Barrels
}}</pre>

Yields:
{{Perks|id=accidental barrels}}


You can select multiple Perks this way, by separating multiple IDs by commas.

<pre>{{Perks
|id=Amber for Trader Visit, Trader Interval +25, Trading Packs
}}</pre>

Yields:
{{Perks|id=Amber for Trader Visit, Trader Interval +25, Trading Packs}}


=== Excluding Perks by their IDs ===

Likewise, you can exclude specific Perks by listing their IDs. This works with any of the other search criteria below, like name or description or rarity. Similar to selecting by IDs, case does not matter, but spelling, spacing, and punctuation all do matter.

<pre>{{Perks
|id=Accidental Barrels,
    Accidental Jerky,
    Accidental Wine,
    Accidental Crystalized dew,
    Accidental Pigment,
    Accidental Skewers,
    Accidental Oil,
    Accidental Bricks,
    Accidental Lizard
|exclude=accidental lizard
}}</pre>

Yields:
{{Perks|id=Accidental Barrels,Accidental Jerky,Accidental Wine,Accidental Crystalized dew,Accidental Pigment,Accidental Skewers,Accidental Oil,Accidental Bricks,Accidental Lizard|exclude=accidental lizard}}

=== Searching names and descriptions ===

The following example shows searching the same term in both name and description, but you could search different things in each field or use only one and not the other. As a shorthand, when you want to search for the same thing in both name and description, you can use the '''search''' parameter instead.

<pre>{{Perks
|name=blightrot cyst
|description=blightrot cyst
}}</pre>

Note this is the same as this:
<pre>{{Perks
|search=blightrot cyst
}}</pre>

Yields:
{{Perks|name=blightrot cyst|description=blightrot cyst}}


Similar to selecting IDs, You can also search for multiple terms in names and descriptions by separating additional terms with commas. This allows you to combine Perks into one table that otherwise seem unrelated, and may be easier than selecting all of their IDs.

The results are combined so the number of results increases, like with an '''or''' boolean operation, and this cannot be changed.

<pre>{{Perks
|name=mist,ashes
}}</pre>

Yields:
{{Perks|name=mist,ashes}}

=== Filtering by rarity or source ===

Rarity and source are filters, not selectors. If you do not select any Perks by id, name, or description, then the entire list of Perks is returned. If you then specify a rarity or source, the results are then filtered to your selections. For example, if the term you searched for in the description returns 20 Perks, but you only filter to <code>source=trader</code>, then only a few of those Perks that match the description will be displayed, the ones that can be purchased from traders.

<pre>{{Perks
|description=amber
|source=trader
}}</pre>

Yields:
{{Perks|description=amber|source=trader}}


You can also filter by rarity instead of source. For example, if the term you searched for in the description returns 20 Perks, but you only filter to <code>rarity=Legendary</code>, then only 6 {{c|{{PerkOrange}}|Legendary}} Perks that match the description will be displayed, the ones with that rarity.

<pre>{{Perks
|description=amber
|rarity=legendary
}}</pre>

Yields:
{{Perks|description=amber|rarity=legendary}}


In these examples, you can see that filtering by both rarity and source may result in nothing that meets all of your criteria.

<pre>{{Perks
|description=amber
|rarity=legendary
|source=trader
}}</pre>

Yields:
{{Perks|description=amber|rarity=legendary|source=trader}}

=== Hiding rarity ===

<pre>{{Perks
|id=Accidental Barrels
|name=Barrel
|show_rarity=no
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=Barrel|show_rarity=no}}

=== Hiding descriptions ===

<pre>{{Perks
|id=Accidental Barrels
|name=Barrel
|show_description=no
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=Barrel|show_description=no}}

=== Skipping source columns ===

Compare the following table with the one above. If the sources are not as relevant to your purposes, but the descriptions are (and they usually are), then you may want to skip the entire section of the table on sources with <code>skip_sources=skip</code>.

<pre>{{Perks
|id=Accidental Barrels
|name=Barrel
|skip_sources=skip
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=Barrel|skip_sources=skip}}


You can also skip individual columns. For example, none of the following "Delivery Line" Perks are available from the Forsaken Altar or from traders, so we can safely hide those columns without hiding valuable information from the reader.

<pre>{{Perks
|name=delivery line
|show_source_altar=no
|show_source_trader=no
}}</pre>

Yields:
{{Perks|name=delivery line|show_source_altar=no|show_source_trader=no}}

=== Hiding prices ===

When hiding the trader source column, it's probably also a good idea to hide prices, but this is not enforced.

<pre>{{Perks
|name=delivery line
|show_source_altar=no
|show_source_trader=no
|show_price=no
}}</pre>

Yields:
{{Perks|name=delivery line|show_source_altar=no|show_source_trader=no|show_price=no}}

=== Showing Perk ID ===

When you need to show the ID, remember that the table can get very wide. If showing IDs, consider carefully whether you need to show all of the other columns.

<pre>{{Perks
|id=Accidental Barrels
|name=Barrel
|show_id=show
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=Barrel|show_id=show}}

=== Custom caption ===

<pre>
{{Perks
|caption=Every Uncommon Perk in the game
|rarity=uncommon
|show_rarity=no
|show_source_altar=no
|show_source_cornerstone=no
}}</pre>

Yields:
{{Perks|caption=Every Uncommon Perk in the game|rarity=uncommon|show_rarity=no|show_source_altar=no|show_source_cornerstone=no}}

== List Examples ==

=== Bulleted ===

This example reproduces the table above, when searching by id and name, in a list format.

<pre>{{Perks
|id=Accidental Barrels
|name=barrel
|display=list
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=barrel|display=list}}

=== Numbered ===

<pre>{{Perks
|id=Accidental Barrels
|name=barrel
|display=list
|list_type=number
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=barrel|display=list|list_type=number}}

=== List with IDs ===

<pre>{{Perks
|id=Accidental Barrels
|name=barrel
|display=list
|show_id=show
}}</pre>

Yields:
{{Perks|id=Accidental Barrels|name=barrel|display=list|show_id=show}}

== Inline examples ==

<pre>{{Perks|id=Accidental Barrels|display=inline}}</pre>

Yields the following, shown in the middle of a paragraph to highlight its usefulness. When you lack any kind of vessel, look for {{Perks|id=Accidental Barrels|display=inline}} to get some for free every time you make Planks!

<pre>{{Perks|id=Accidental Barrels|display=inline|show_id}}</pre>

You can also show the ID of the Perk alongside the link, like {{Perks|id=Accidental Barrels|display=inline|show_id=show}}, if your readers need to see it too.

== View ==

The functionality of the '''Perks''' template is accomplished through the [[Wiki data model]]. This '''Template:Perks''' calls the controller module, which in turn interfaces with the data model module. It also interfaces with the view module for the table or calls a template to display the list version.

Only the last, List/item, is called from the controller. All others are still here in the off chance they may be useful to an author for manually creating tables of perks. However, it is strongly recommended to learn how to use [[Template:Perks]] instead. The table version of the view is accomplished with [[Module:PerksView]], which cannot be invoked directly, but is invoked by [[Module:PerksController]].

{|class=wikitable
|+ Related templates
! Template !! Purpose
|-
| [[Template:PerksCornerstonesTable]] || Primary, default table header template
|-
| [[Template:PerksCornerstonesTable/row]] || Default table row template
|-
| [[Template:PerksCornerstonesTable/end]] || Table markup closing
|-
| [[Template:PerksCornerstonesTable/SkipSources]] || Table header template, but without the sources columns
|-
|white-space="nowrap"| [[Template:PerksCornerstonesTable/row/SkipSources]] || Table row template, but without the sources columns
|-
| [[Template:PerksCornerstonesList/item]] || List version row template (there is no list header template)
|}

[[Category:Lua-based templates]]