Comrade:CriticalResist/sandbox/Essays documentation

If you’re looking at how to use the new essays page, refer to the user guide. This is the technical documentation for maintenance purposes.

This page relies heavily on DPL3 (Dynamic Page List 3), documentation here: https://help.fandom.com/wiki/Extension:DPL3/Manual. DPL has a 1 day cache and will not update before then. To force it to update, go to the essays homepage and in the menu click on Hard Refresh.

I’m unsure how many resources DPL needs to make the page, I can only hope the server supports the load once we start getting a lot of essays.

---

These are the templates used for the new essays page. They all have their own /style.css sheet.

Essays_homepage

Only used to call a CSS stylesheet. Notably it removes the list styling that DPL creates by default, preventing the bullet points from appearing. DPL code for the main feed is explained in its own section.

This template also sets up the flex-boxes (you create the divs in HTML but then set them up as flex in CSS) that make the whole essays homepage work properly on mobile and desktop.

Essays_homepage also contains a specific CSS declaration: .essay-small and .essay-big. These classes only do one thing: make text a bit smaller or a bit bigger. This makes it easy to just add <span class=”essay-small”> to other templates (such as Essay_lastupdate) for aesthetics reasons. But it only works IF essays_homepage is called. That is to say, these classes are used in other templates but will not show up as working if Essays_homepage, the template, is not called into the page where those other templates are called.

Finally, this template also does something very important: it brings back the display property of .infobox-essay (which is the div container that contains the data on the infobox_essay template, managed from that template). See infobox_essay section for more info.

The template doesn’t do anything by itself otherwise, it only calls the stylesheet.

Infobox_essay

This is the big one which must be included at the top of every essay.

First, it changes the display title of the essay to remove the namespace mention using {{DISPLAYTITLE}}. DisplayTitle is included in the template directly.

Then it uses different parameters to essentially create a blog list feed with a picture, title, author, publication date, and excerpt. All of these fields are filled in manually.

The "last update" mention is wrapped in a span class called .update-disappear. This class is only acted on in the Essays_homepage template, all it does is make the mention of the last update disappear on the essays home page. The reason for this is because we use the REVISIONTIMESTAMP magic word which pulls this data from whichever page it appears on, not from the essay itself. This is sort of a workaround until we find something better.

Infobox_essay also contains .essay-big and .essay-small because, since the template is originally transcluded on individual essay pages, it will not call .essay-small from Essays_homepage. This is important to note: on MediaWiki, custom (template) CSS will apply on any element that is in the HTML on the page, no matter if it's native to the page or called by another template.

The reason for this is so that the whole infobox is not displayed on individual essay pages, but only on the essay homepage. It is display:none; on the individual essay page, but then with the use of !important, it is brought back to visibility on the essay homepage.

Finally, I recently added a reading time estimate. This works through the Module:Reading time and it can be used on any page! This module works super simply, but I'm unsure of server load if we spread it on more pages. It just counts the number of words in a given page, then using two estimates for words per minute (which are set in the module itself) we can run some simple math to give an estimate in increments of 5 minute.

Essay_lastupdate

This template is filled in automatically with DPL, and does not need to be changed. It creates its own container which might not be necessary but if it’s not broken, don’t fix it.

What it does is create a list of the 7 most recently updated essays (that is, an edit was committed). You can change that 7 count to anything else in the template by editing count = 7 in the DPL code.

Essay_lastupdate is built in a div container called lastupdate-container. The only reason we need this div is to apply the CSS (gray background, padding, etc).

It also contains a stylesheet at /style.css that styles the container (currently gray background with rounded corners and some padding). The reason we need to apply the styling to the template itself and not from the Essays_homepage template is because of the padding, so that it moves the content away from the box properly.

Essay_categories

This is a manually filled in template. Like Essay_lastupdate, it calls its own stylesheet that contains exactly the same code.

The reason I had the stylesheets separated for each sidebar item is so that we can style them differently, for example using a different background-color.

Categories are added into the template manually. I suggest they all contain the mention (essays) at the end, e.g. “World news (essays)” to differentiate it from a wiki category that could be called world news too.

Also uses a div container in the template to apply the CSS to it.

The code is otherwise pretty straightforward, it just repeats for every category with the names and links changed. I also reused the library module Number of works to count how many pages are in the category.

Essay_authors

The essay_authors template works exactly like the categories template, just with authors instead. Not much else to say.

Homepage setup

So by the way, you can use some HTML in MediaWiki and that’s exactly how we set up the new essays page. It’s just divs, maybe spans (to apply CSS to only portions of text), and that’s about it. For this reason, you need to edit the page in the source editor as visual will remove the closing tags. Inside the <div>s are simply templates. They don’t necessarily need to be templates, but I like that everything is in its own self-contained area.

The new essays homepage is set up with nested flex boxes.

The flex go in a row direction on mobile, and a reverse-row on desktop, which is why the sidebar appears on top of the essays feed on mobile but to the right on desktop view (the sidebar boxes appear before the feed in the HTML code). If you changed reverse-row to row, the sidebar would appear on the left.

This is controlled by simply changing the width of the two flex boxes: essays-list (the feed of all essays in their full format) and essays-sidebar (the container for sidebar items).

The setup is otherwise pretty simple with HTML. There’s an overall container called essays-page, which contains the sidebar and its nested individual items (essay-sidebar-item), and then the essays-list which is created with DPL code.

Flex is applied in CSS in the parent element, and only the first-level children elements will be flexed. This is why we need to use nested flex boxes.

Sidebar items are made using templates and those get transcluded into a div called essay-sidebar-item so that they inherit the proper CSS from Essays_homepage template.

Those items, in their template page, have their own stylesheet however. For coherence purposes, all sidebar items should have the same CSS.

There is no pagination; all essays ever published will be included in the main feed. I’m looking at making pages with DPL though.

DPL code for main feed

DPL simply creates automated, curated outputs of Wiki pages. It doesn’t necessarily create a list format like with bullet points or numbers, but by default it creates an <ul> list (bullet points).

For the main feed, the one that contains all essays (containing the template), the code is really easy once explained (you will find this code in the essay homepage directly):

<dpl>

namespace=Essay

mode=unordered

includesubpages=false

ordermethod=firstedit

order=descending

include={Infobox essay}

</dpl>

<dpl> tags are needed to mark the code between them as DPL. Namespace= is the namespace we want to grab from. We can also add category= to grab from one (or more IIRC) categories. We can combine both or just one either one.

Mode= uses ordered for a numbered list, unordered for a bullet list, or userformat. Userformat allows you to specify a format= parameter and essentially code whatever output format you like. See DPL documentation for more information.

includesubpages= is self-explanatory, we don’t include /subpages.

ordermethod= is how the output will be sorted. Firstedit means that it will list the output by first edit made, i.e. page creation. Lastedit is the last edit made (used for Latest Updates). There’s several other ordering methods available.

order=ascending or descending to sort the list one way or the other.

include= this is the important one. Include allows you to include something specific with your output, pulled from the page. In this case we pull the content of the infobox_essay template.

This code together creates a bullet-point list ordered from most recent to oldest essay and pulls the infobox essay template under each bullet point.

But there are no bullet points on the essay page. They do exist, they are just set to display:none; in the Essays_homepage template!

With more display:none; trickery, we are able to make only the infobox template appear on the essays homepage, and we are able to select specifically which parameters we want to appear on an essay page. For example, we keep the image, author and publication date, but we remove the title and excerpt because it’s only a duplicate of what’s already on the essay page. This simply works by targeting display:none; properties on Template:essays_homepage and on Template:infobox_essay (infobox_essay makes them disappear, and essays_homepage makes them reappear with an !important clause in the CSS, which overrides all other rules on the element).

Categories

Individual categories (see https://en.prolewiki.org/wiki/Category:ProleWiki_official_(essays) for example) use DPL as well. The code can be copied from the category above by going into the source editor and pasted into each new category we want to add to our essays.

This DPL code will simply grab all pages in the category (you have to specify it manually) and order them chronologically with the publication date in parentheses.

This makes browsing category pages a bit easier for the end user so that instead of having an alphabetical table list, they will see a chronological linear list.

I named essay categories with an (essays) mention at the end so that we differentiate them from wiki categories. For example we might have a world news category for wiki pages, and there should be no overlap between the two.

To make a new category just create it any way you prefer, then add the DPL code from any other category in it and that's it. Just change category= in the DPL code obviously. Then to add it to the Essay_categories template, just copy any other line and change the name as needed.

Adding more sidebar items

We can also have as many sidebar items as we want, the sidebar will just get longer than the essays feed if we have too many. It’s super easy, just make a template for them (and DPL allows some cool stuff so we can use that as well), add the /style.css subpage, copy the styling from any other sidebar item into it, transclude that template on the homepage in the .essays-sidebar div (and into a child essays-sidebar-item of course). Don’t forget to close your divs and do this from the source editor, the visual editor will break everything.

Future stuff

Random future stuff that I want to fix or implement on that page.

• fix image display. Right now it centers the image vertically and horizontally. Image width is 100% because on citizen skin you can change the page width, so I don't want to use absolute pixel numbers. For the library we set them as float:left and this allows us to specify a top: and left: position to center them correctly, but their size (height and width) is fixed in the library no matter on desktop or mobile.
• Remove CSS from the sidebar item templates and put it in Essays_homepage instead, so that they instantly look coherent.
• Add more sidebar items if we can find any.