User:Aldyron/Tutorial/DPL parameters

This page aims to be a tutorial on DPL parameters generating a single, specific query. What's here can be applied to most DPL applications, but it won't be an exhaustive tutorial: there's a dedicated web site available, too.

Primary target audience is myself, a few months from now: I'm likely to eventually forget the specifics of how to do most of what I've done here, so this page will serve me first and foremost to quickly regain proficiency in case of need.

Hopefully, then, it will be helpful to anyone else with the slightly masochistic desire to dip their feet in DPL waters. To you all I say: good luck, and may the god of queries never spit on your selections!

Query code

{{#dpl:
|dplcache       = 1
|uses           = Template:Infobox-monster
|category       = Troglodyte race monsters
|category       = Fiendish Troglodyte sub-race monsters
|addpagecounter = true
|addpagesize    = true
|include        = {infobox-monster}:MM type:MM type:[[%PAGE%]]:habitat:habitat:habitat:habitat:MM type
|format         = ,,¶¦Static data 1¶¦align="center"¦%COUNT%¶¦Static data 2¶¦align="center"¦%SIZE%,
|table          = class="wikitable sortable",-,MM category,MM kind,Name,(Non-regex'd) Habitat,MM habitat,Level,Pack,Volume,Static header 1,Count,Static header 2,Size
|tablerow       = 
²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM category}²,
%%,
%%,
%%,
²{#dplvar:set¦MM habitat¦²{#dplreplace:%%¦/^[^\[]*\[\[([^\]\x7c]+).*$/s¦$1}²}²[[²{#dplvar:MM habitat}²]],
align="center"¦²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Quest}:level}²,
²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Adpack}:adpack}²,
align="center"¦²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM volume}²
}}

This DPL query will access several other pages (monsters, quests, adventure packs), use some templates, hack, slash, mix, knead and bake text and links found there, and produce a sortable table as its output.

This table is an overgrown subset of the Monster Manual experiment I'm currently working on, and from this moment on it will live its own life (meaning it is not part of the MM experiment, it is just a tutorial on DPL parameters).

Part of the data presented in the table is redundant or pointless in itself, but it's an excuse to show certain parameters in action.

Please, keep in mind that the following parameter breakdown shows how to configure the parser function for this query. In all likelihood, different queries will be configured in different ways.

DPL parameter breakdown

WARNING! Parts of this section were written while under kobold menace. I was distracted. If you believe I made mistakes somewhere, maybe I did. Feel free to tell me (or ask, if in doubt).

{{#dpl:

This just opens up the query statement, using standard parser function syntax.

|dplcache       = 1

The dplcache parameter turns on caching, which is simple in practice, but not banal in the manual. There are some interactions to take into account. After that, since there doesn't seem to be a downside, in practice you almost always want to turn it on by simply specifying 1 as its value; you can use the same value, 1, in different pages; if you have more than one query in a single page, use different values (1/2/3, alpha/beta/gamma, william/leonard/deforest...)

The cache's default expiration period of one day can be overridden with the dplcacheperiod parameter. Given the rate of editing for this wiki, one day seems a reasonable compromise to me. The server's owner may want to dictate otherwise for performance considerations, though.

|uses           = Template:Infobox-monster

The uses parameter constrains page selection to those which employ the specified template, in this case Template:Infobox-monster.

This is likely redundant, given the include parameter's behaviour.

|category       = Troglodyte race monsters

The category parameter constrains page selection to those belonging to the specified categories, in order to limit server load during tests.

|category       = Fiendish Troglodyte sub-race monsters

Idem.

It makes the previous category parameter redundant, but I want to limit the page selection even more since I'm starting tests that are potentially heavy CPU-wise (don't think so, but you can never be too prudent).

Keep this and you're expecting twelve-ish records, strike this to see fifty-ish.

|addpagecounter = true
|addpagesize    = true

The addpagecounter and addpagesize parameters add the corresponding page metadata to each record's available output fields; they do *not* add them to the corresponding final output row.

These are actually useless to the monster manual: I only included them here to test the feature for future reference.

|include        = {infobox-monster}:MM type:MM type:[[%PAGE%]]:habitat:habitat:habitat:habitat:MM type

The include parameter, with those subparameters, adds the corresponding page data (extracted from the specified template data in each page) and metadata to each record's *and* row's output fields.

Note you can specify a certain field multiple times, freely positioning them in the order you like. Most of those multiple copies will be transformed later.

|format         = ,,¶¦Static data 1¶¦align="center"¦%COUNT%¶¦Static data 2¶¦align="center"¦%SIZE%,

Let me rewrite that for clarity:

|format     =     ,     ,     ¶¦Static data 1     ¶¦align="center"¦%COUNT%     ¶¦Static data 2     ¶¦align="center"¦%SIZE%     ,

The format parameter, with those subparameters, adds the corresponding static data (mostly pointless, but it can have its uses in limited cases: I only included them here to test the feature for future reference) and metadata to each final output row's *rightmost* output fields. Metadata will be centered and sorted as numeric fields.

This, being specified in the third subparameter, will not be overridden by the table parameter (as specified in the manual).

That's a good occasion for noting the altered syntax necessary to mark dpl parameters and subparameters inside an outer parser function.

|table          = class="wikitable sortable",-,MM category,MM kind,Name,(Non-regex'd) Habitat,MM habitat,Level,Pack,Volume,Static header 1,Count,Static header 2,Size

The table parameter, with those subparameters, sets up a sortable wikitable with the appropriate column headers.

It overrides the format parameter except for its third subparameter (as specified in the manual).

Columns' amount and order is defined (here) by the include and format parameters: include specifies eight columns, format specifies four, for a total of twelve.

Article title (default first column) is skipped (with the dash character) in order to have it in the third column. That's the monster name, in this table's case.

|tablerow       = 
²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM category}²,
%%,
%%,
%%,
²{#dplvar:set¦MM habitat¦²{#dplreplace:%%¦/^[^\[]*\[\[([^\]\x7c]+).*$/s¦$1}²}²[[²{#dplvar:MM habitat}²]],
align="center"¦²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Quest}:level}²,
²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Adpack}:adpack}²,
align="center"¦²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM volume}²,
%%,
align="center"¦%%,
%%,
align="center"¦%%

The tablerow parameter, with those subparameters, regexes out data from certain fields, uses templates to transform data and specifies formats (arguably) appropriate for each column.

This is most likely *not* how you want to do this. I believe a better (and certainly cleaner) way to do this would involve phantom templates. I'm probably reinventing two or three wheels as well, but this is primarily an exercise to see what can be done, and how, so there you are.

Anyway, I think this is complex enough to warrant a breakdown all for itself.

• |tablerow       =

This just opens up the parameter.

• ²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM category}²,

Since the monster type we find in Template:Infobox-monster does not map one-to-one to MM category (e.g.: Elf -> Player Races instead of Humanoid), this subparameter employs an auxiliary template to map kind to category. It may surprise some to know that the template is called User:Aldyron/Sandbox/Template Mm kind to category or volume :-)

Since this is the first subparameter, %% represents the first field specified earlier in the include parameter, i.e. MM type.

• %%,

Second subparameter, so %% represents the second field specified earlier in the include parameter, i.e. a second instance of MM type. There's no auxiliary text nor formatting around %%, so this is taken verbatim from input to output, because we're now at the actual MM type column.

• %%,

Third field, [[%PAGE%]], verbatim.

N.B.: the PAGE in question is the single-monster page currently selected by the query. That is, here, PAGE name = monster name.

• %%,

Fourth field, habitat, verbatim.

I call it "non-regex'd habitat" to distinguish it from the regex'd one, which is the one I actually want listed as habitat.

I include it here as a reference for the next field, in order to show what can be done with a regex and a dpl variable.

Please note that the original format of this field is not strictly defined, and it's currently up to the editors' taste, so you can find a little of everything here: a single line, multiple lines, a multi-level bullet list, a table (I think), nothing... wikilinked, plain text (I think)... with auxiliary notes, without...

• ²{#dplvar:set¦MM habitat¦²{#dplreplace:%%¦/^[^\[]*\[\[([^\]\x7c]+).*$/s¦$1}²}²[[²{#dplvar:MM habitat}²]],

Fifth field, habitat, regex'd.

I needed a clean value for the next fields. In order to extract a clean value from the relative mess that is the previous field, I thought of pulling out the link target of the first wikilink (if any). Sub-optimal, but it's a start. I used the dplreplace function for that. Its result I put into a variable for later use (it will be valid throughout the rest of the tablerow parameter; maybe after it, too, but I don't need it, so didn't test it). Then, since I also need to use it here, I pull the value out of said variable. Breakdown follows.

• • ²{#dplreplace:%%¦/^[^\[]*\[\[([^\]\x7c]+).*$/s¦$1}²

Let me rewrite that for clarity:

• • ²{     #dplreplace:     %%     ¦     /^[^\[]*\[\[([^\]\x7c]+).*$/s     ¦     $1     }²

The dplreplace parser function, with those parameters, uses a regular expression (regex) to parse %% (i.e. habitat) like this: find out the first occurrence of [[, scan the characters until the first occurrence of either ] or |, and return the characters scanned as its result. I may have been reinventing the wheel, here, but it was a nice exercise for me.

That's a good occasion for noting the altered syntax necessary to nest a dpl function inside an outer parser function.

By the way, I thought I'd be using the Unlink template in some fashion, but I couldn't find it installed on DDO wiki (I may be wrong, I didn't look for it much).

• • ²{#dplvar:set¦MM habitat¦²{#dplreplace:%%¦/^[^\[]*\[\[([^\]\x7c]+).*$/s¦$1}²}²

Let me rewrite that for clarity:

• • ²{     #dplvar:     set     ¦     MM habitat     ¦     (previous function)     }²

The dplvar function, with those parameters, creates or recycles a variable called MM habitat, and sets its value using the results of the previous function (i.e. dplreplace).

• • [[²{#dplvar:MM habitat}²]]

Let me rewrite that for clarity:

• • [[     ²{     #dplvar:     MM habitat     }²     ]]

This employs the dplvar again, this time to retrieve the value of the variable called MM habitat, then wikilinkifies it for output. This is what actually goes out to the table cell.

• align="center"¦²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Quest}:level}²,

Let me rewrite that for clarity:

• align="center"     ¦     ²{     #dpl:     noresultsheader=      ¦     title=²{#dplvar:MM habitat}²     ¦     include={Quest}:level     }²,

This specifies the cell's format (centered), then proceeds to use the dpl function again to sub-query another page.

The page is selected by title, with a direct match to the MM habitat variable (set earlier).

From that page, if it's a Quest page, we extract the nominal quest level via Template:Quest. N.B.: here, "if it's a quest page" practically means "if it employs Template:Quest".

If no result can be found, we don't want to hear anything about it, so noresultsheader=  suppresses output of a warning and outputs a blank (actually a non-breaking space).

Note that we're ignoring the sixth field (i.e. another instance of MM habitat), and we use the sub-queried data in its stead.

By the way: I wanted it right-aligned but it turned out fairly unreadable :-(

N.B.: this is an unfinished implementation, since a monster's habitat can also be a Wilderness adventure area or a hostile public area. Completing the implementation could be done in a number of ways: deciding which one should require consensus, so I stopped here for now.

• ²{#dpl:noresultsheader= ¦title=²{#dplvar:MM habitat}²¦include={Adpack}:adpack}²,

Let me rewrite that for clarity:

• ²{     #dpl:     noresultsheader=      ¦     title=²{#dplvar:MM habitat}²     ¦     include={Adpack}:adpack     }²,

No explicit formatting. Otherwise, similar to the previous one.

Ignoring the seventh field (i.e. another instance of MM habitat).

• align="center"¦²{User:Aldyron/Sandbox/Template Mm kind to category or volume¦MM kind=%%¦map to=MM volume}²,

This subparameter employs an auxiliary template to map kind to volume. Not surprisingly now, the template is called User:Aldyron/Sandbox/Template Mm kind to category or volume :-)

Eighth field, MM type again, centered.

}}

This just concludes the query statement.

The resulting dpl-generated table itself

(Placeholder: the legend goes here)