User:RurinGas/DPL Tutorial

Hello hello one and all! Welcome to DPL 101. I'm sure you've probably seen alot of us ranting and raving about the glory of all that is DPL and want to know how it works. And well, I may not know why it works, but I sure as hell know how, so I may as well get the knowledge out there.

This Tutorial's gonna cover three things; What DPL Is, A Simple DPL, and a Complex DPL.

This Tutorial will not cover absolutely posolutely everything a DPL is capable of doing, only what it does that is often used on the wiki. Consider everything I've not covered as your homework.

What Is A DPL
DPL is short for Dynamic Page List, it's an extension we use pretty much everywhere these days to take all the pages in a given category, and have them automatically spat and formatted onto a big table, or occasionally into a big gallery. It's useful for something like, Category: Fallout 3 characters for instance, because adding every character from Fallout 3 onto one table manually would be a massive pain in the ass.

Specifically, the flavor of DPL we use around this part of the woods is DPL3. There are two versions of DPL that preceed it; Dynamic Page List, and Dynamic Page List (Third-Party). All you really need to know about that, thanks to efforts from the extension's creators to maintain backwards compatability, instructions for one or the other are usually good for DPL3 too. ''Emphasis on "Usually". Don't come cryin to me if somethin don't work.''

DPL doesn't just take a bunch of names and slam them into a list though (Although, it can do just that if you really want), it can also take lines from infoboxes and other templates, and put them in the table too! If you want every character in one category listed with their location beside them, so long as that information's in the template, you can put it there! Pretty neato, ain't it?

Simple DPL
Alright, barebones stuff. So, whenever you want to do a DPL, you have to start off by putting {{#dpl: This shouldn't be too unfamiliar if you've ever put a template onto a page at any point. Next, is a handful of variables. Lets cover em all real quick, first up the ones that can go in basically any order (Though I have listed them in the recommended order, so that future editors don't have to try too hard to change anything about it)

Category
First up we have Category, super simple this one, just put whatever category you want to pull from here (With the Category namespace included). If you want to include more than one category to pull from, just seperate it by a pipe escape (not a pipe). Here's an example of this one. Example |category = Category:Winter of Atom characters |category = Category:Winter of Atom characters | Category:Fallout Shelter characters

However, the pipe escape functions as an OR gate, if for instance you want to use an AND gate, just put the category parameter in again. Example |category = Category:Winter of Atom characters
 * category = Category:Fallout 3 characters

In this example; the DPL will pull pages that are from Winter of Atom chartacters and Fallout 3 characters. Or in other words, characters that feature in both Fallout 3 and Winter of Atom, but not in just one of them.

Notcategory
Super simple again, this one is the opposite of the one above; any categories you state in this will be excluded from the DPL. For example, if you wanted to take all the Fallout Shelter characters, but cut out every Fallout 3 character from it, you would put Example |category = Category:Fallout Shelter characters
 * notcategory = Category:Fallout 3 characters

Also as above, you can use pipe escapes or multiple instances of the parameter if you want to include OR or AND gates.

Ordermethod
Okay, this is one of the parameters that doesn't actually get too much change. It determines the order in which the pages that you pull from the category will be listed. You're either gonna put "title" or "sortkey" most of the time, though there are a handful of other things you can put in there for different orderings, "firstedit" will order with the oldest created page first for instance. Example
 * ordermethod = title

Nottitlematch
Right, so this one is a bit of a way to cheat, on account that it pretty much lets you pick and choose specific pages to exclude from the DPL. Basically, just put the name of the page here and it gets cut out. If you want to list more than one page, put one of these funky things ¦ between each one. (You might wanna keep that funky thing on your clipboard because it gets alot of use later). If, however, you have a bunch of pages with roughly the same name that you wanna exclude, you can cheat inside the cheat for some beautiful cheatception by using wildcards. In this type of DPL, wildcards are the % symbol and determine anything and everything. For instance, "A%" will cut out each and every page beginning with the letter A. Example
 * nottitlematch=Child%¦%outfit

Uses
Alrighty! This is where the real meat 'n' potatoes begins. The Uses parameter targets templates on all the pages in the category you selected. If you want a list of characters for instance, you'll probably be wanting to set your sights on Template:Infobox character. We get to define what specifically we want to take from the templates in just a little bit, but for now, just list the templates. Much like with the categories earlier, you need to include the namespace (in this case Template:) and if you want to pull from more than one, you'll be seperating each one with a pipe escape. Example
 * uses = Template:Infobox association | Template:Infobox faction | Template:Infobox location

Include
You'll want to pull up a chair while typing this bit, it's a long one. So, this is where you determine what stuff you want to pull from the templates you just listed, on each of the pages. Say if your template is a list of slogans, and you wanna pull the Slogan variable and the Game variable from the Association and Faction infoboxes, you'll be wanting to put Example
 * include = {Infobox association}:slogan, {Infobox faction}:slogan, {Infobox association}:game, {Infobox faction}:game

This part can easily become spaghetti once you start calling alot of variables from alot of templates, but it's recommended for ease of reading and ease of converting to other types of table and DPL, that you keep the ordering as consistent as you can. Keep all of the first variable you want together, and all of another variable together, and so on. And in addition, make sure that each called template is kept in the same order within those groups of variables. For instance, notice how in my example, I stated Association before Faction in both instances.

In some instances, you can simplify this by ordering things a slightly different way. In this alternate ordering, you only need to say which template you want to pull from once, and then list each variable you want to pull from after it. This can be more legible in bigger templates where putting things the usual way might look pretty spaghetti, but does not always work as it should and is not as easy to convert to other types of table or DPL. Example
 * include = {Infobox association}:slogan:game, {Infobox faction}:slogan:game

Format
This is where you but the assorted bits and pieces that tell the DPL how to lay out all the information you've told it to get. In 99.9% of cases, you'll want it as a table. As such, here is a little excerpt for you to copy-paste that'll make it a table. Example {¦ class="ace-table ace-table-shaded ace-table-center" style="width:100%;"¶ ! Heading 1¶ ! Heading 2¶ ! Heading 3¶ ! Heading 4,,,¶ ¦}

Naturally, replace "Heading 1" and so on with whatever you want for your table, just make sure that each row begins with a ! and ends with a ¶, and also that the final heading has the three commas just before it's ¶. I'll be honest, I don't know why the commas need to be there, I just know they have to be. The reason for the ¶ is pretty simple though, and is because of the next parameter

Secseparators
Secseparators are easy as easy can be, because it'll always be the same thing. They determine what the DPL treats as a new line for its formatting, but not for its parameters. Consider it like a when you're editing pages, except one you need to put or the line wont break otherwise. Example
 * secseparators = ¶¦-¶

Everything else you need
And now for the weird part, the bit where you tell it where exactly on your table to put the information. You can sorta treat this as "Formatting 2" and it might even just be part of the formatting parameter, but it goes after the Secseparators and doesn't have an actual parameter name, so I'm treating it like this. Basically, after your secseparators, just go on down to the next line and put all this whatevers.

For each heading you've got (I used 4 in my example so I will use 4 here), make a new line and begin it with ¦ (I told you it would come back!). These are the first cell in each row. So the first ¦ you've got will be the first box for heading 1, the second ¦ you've got will be the first box for heading 2, and so-on. It seems intimidating but is quite easy; for each template you called in your parameter (We covered it earlier), you'll want to put two commas. Just two commas each. And then, after the commas, top the line off with one of those ¶ we used earlier. Remember; unless you're doing something uber unique, each line should have the same amount of commas as the other lines.

Example ¦ ,,,,,,,,¶ ¦ ,,,,,,,,¶

Sometimes, you'll get an exception to just putting a bunch of commas though, but they're easy.

If you want to handle images in one collumn, just put all the stuff you'd usually put down to put an image onto a page, but where you'd usually put the image name, just put all of the commas I just mentioned, like so

Example ¦ ¶ ¦ ,,,,,,,,¶

And if you want to put the name of the pages into one collumn, just ignore commas altogether for that line and just put in

¦ ¶ ¦ ,,,,,,,,¶

So, I'm not 100% sure on the why this has to be, but my working theory is do to with that parameter we covered earlier. Notice how we seperated each variable we're calling from the template with commas? I'm pretty sure that we have to state two commas because that's how it hones in on what we've typed there. For example in the example I used in that section ,,,, would be setting the section's sights on {Infobox faction}:slogan.

If you want to add another template or variable to an existing DPL, it's not very hard. Just go back to, slam in a pipe escape, and then slam in whatever new template you want in. Then, go to that bit, and slam in all the variables you want in (Try to keep things orderly though for future editors!), and then go down to that bit with all the commas, and just add another two of them on each line (Unless it's like the page name line, as shown above). Naturally, if you added two new templates, add four commas, or if you added four new templates, add eight new commas, and so on.

And lastly, but not leastly, Slam in one o' these puppies to close off your DPL, and hit preview.

}}

If everything has gone down right, you should be looking at what you want and then hit publish (just to make sure you don't lose anything), if not...

Well, DPL has basically a two-step troubleshooting process for most issues. One, make sure all of the stuff is typed out properly, without any typos or shorthand or anything like that; and Two, try adding or removing commas from the comma sections, each line should still have the same amount as the last, but try just adding or removing them in sets of twos until something looks right-er. Solution 2 usually works when your issue is that everything you're wanting to pull from has been smooshed together into one cell, or the wrong cell, or one row.

Example
Incase you want to look at an example of what a whole working DPL looks like, to compare your work to, here is an abridged version of the Slogans page;

Complex DPL
Right! I hope you read (or already knew) that stuff from the simple DPL section, because Now we're gonna move onto Table DPLs! Now you see, what the Simple DPL section does is effectively take a DPL, and then take a Table, and smoosh them together. But what this kind of DPL does is make the DPL as a table. It's a minor difference, but one that changes how you type one up, and the stuff it can do. The primary benefit is that it lets you use #if parsers in it, which lets you do basically all of the fun and wacky stuff you can do in normal tables in a DPL, something you can't completely do in your standard DPL. The drawback however, is that it's behaves in a bit more of a peculiar manner, and you have to occasionally fight to make it put content in the right cells. Fortunately for you, and the other users on this site, I've whipped up a handful of templates that'll hopefully turn "Pulling teeth" into "just a bit tricky".

First off, certain parameters I mentioned in the simple DPL section either don't work or don't need using; Secseparator and Format especially can be tossed out the window, and we can introduce you to your new best friends, Table and Tablerow.

Table
Table is basically your alternate universe version of, it contains all the same kinds of stuff, but laid out ever so slightly different. Three types of things go here; Table Class, Table Style, and Table Headings. Class and Style are easy to get, they're just the same stuff HTML uses, and the same stuff you'd punch into any table on the wiki, and the same thing you would have put into the format box in a regular DPL. The extra good news is that the wiki's got such consistant formatting, you'll probably never need to change the class from

class="ace-table ace-table-shaded ace-table-center"

Following that, is either your Table Style (Which isn't essential) and your Table Headings. The headings are so easy it almost doesn't require saying, it's just a comma-seperated list, HOWEVER the first variable should be

,-,

This is so that the table doesn't try to automatically start with the page name. You're welcome to skip it if you want the page name to be the first collumn, but for most uses you might wanna put it in the second collumn, or apply some kind of formatting to it, or use Template:Pagename nd to drop anything in brackets. Here's an example of a good Table parameter. Example |table= class="ace-table ace-table-shaded ace-table-center" ,-, Image, Name, Slogan, Game

Tablerow
Much like how Table is the alternate universe, Tablerow might as well be the alternate universe version of because everything that goes a-proper in your table goes here. However don't be decieved, unlike how Format and Table are, Tablerow is laid out in an entirely different way, so for this you may as well throw out all that.... or well, MOST of that....

It's actually a little simpler than the normal DPL, instead of a couple commas, we use a couple of percentage symbols. %% is used as the placeholder for any information that goes in those cells. It'll call your template parameters, but it will call them in order, your first pair will be the first parameter, the second pair will be your second, so keeping each variable called in the recommended order is no-longer a soft recommendation, but more of a hard requirement if you're working with multiple templates.

However here's the issue, you cannot simply just string %% together until the sun explodes in this kind of DPL, that'll just cause the template to repeat the first variable over and over and over... The solution? A custom template, fresh from RurinCo! Just cram a between each %% and slam a comma wherever you want to move onto the next cell, and you're good to go! It's that easy! Example |tablerow= %% %%  %%,

Aaaand you'd think that'd be it, right? Wrong! Because you get all sorts of fringe issues using the table format. Firstly, I mentioned about moving the name to a different cell earlier yeah? Well, the Table-specific formatting prefers you to explicitly call for the name from the template. It's a small issue, and thankfully it's easily resolved. In your section, just make sure to inlude %PAGE% as a variable, like so: {Infobox consumable}:%PAGE%

and then after that, just go back down to where all your stuff about rows is, and slam in

into the appropriate cell you want the name to go into. Except that.... Doesn't work.... See, for reasons that work but I cannot explain, for this template in particular, it seems to only like being called once, but will fill itself as you would otherwise want it to, if you leave space for it to in the cell. So, instead of copying it all the times you'd need, just slam in one of those things, and a space for each template you're pulling a page name from, like so: ,

So, that's it? Wrong again, dingus! We got one more thing to deal with. See, because of how works, sometimes (not always) it breaks templates and other formatting, for example when using it to put images into a cell. Oh no! Buuutttttt, there's a solution! A custom template, fresh from RurinCo! is effectively two templates in one, but they both do the same thing. If you're doing something that causes the DPL to spit out an error code or garbage text, pull it out. It's a simple template, so that it checks if something is there before calling it.

See, because of how DPL works, it checks every page it covers for every template, but unlike Simple DPLs, this type will try and cram it into the cell even if there's nothing to cram. Usually it just causes nothing to happen; but Modules will throw big red error text out, and images will leave behind a whenever there's nothing to put in there. The usage of Template:DPLcell is documented on it's page, however the basics are to just put whatever template or other content you want to not throw an error for into it's second variable (Remember to use a pipe escape instead of a pipe for it!), like so

And, if you want to put an image into your DPL, just use

with the second variable being the image dimensions.

So! With Tablerow all set up and functioning, you should end up with something that might look like this; Example ,
 * tablerow=

,

%% %%  %%,

Magic Parser Junk
Okay, so, whole seperate section on this junk. Parsers! If you don't know how to do all this #if parser junk yet, I'd recommend getting fully abreast on how to do it, like by reading this here, or you can just skip over this little section if you don't have the time.

Basically, much like how you've gotta use funky alternative symbols all over, like the pipe escape, you can't just use the ol' curly bois like we usually use, but never fear! There's a solution. DPL's got a handful of things built in to function as stuff that otherwise wouldn't behave prettily in it. I'll list the useful ones here for ease of use;

First off, we got the HTML tags, you'll see em all over like  and stuff. To use em in DPLs, you gotta replace the < > with « », so now you have to put «div» instead to get it to work. And naturally, the complimentary closing tag would also use the same symbols, and be «/div»

Your curly bois mentioned previously are much the same. Instead of, you'll find yourself having to use ²{ }². I'm not actually entirely sure when they need to be used, as templates seem to work fine enough inside this version of DPL. So far as I've seen, the only thing that hard requires the fake curly bois are parser fuctions, so keep it in your brain if you plan on using those.

And lastly, our returning champion, ¦. I've seen some folks around call it the broken pipe, and it replaces your standard pipe (That would be | that thing) when even a pipe escape ( | ) would be weird or not work... With the exception of your category and template lists, if what you're doing is a part of DPL, you want ¦, and if what you're doing is a part of a template you're trying to put into DPL, you probably want |.

Here's an example of a working #if parser using some of these funky symbols and is read correctly by the DPL, a pretty abridged version of DPLcell; ²{#ifeq:%%¦ ¦ ¦%%}²

Example
So, much like with the simple DPL, incase you want to know what a working version of this kind of DPL looks like behind the curtain, here's once more an abridged version of the Slogans page;

Aaaand that... should be the whole shebang! Congratulations, you now know everything I can think of off the top of my head! Have fun with in miscellaneous tabulated adventures! Peace.
 * - ffxiv.png~-~ Rurin ~-~ RurinGasIcon.png