Editing 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 '''Soft Refresh'''.

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

---

This new essays page relies heavily on simple templates as well as DPL. The templates used are the following ones at this time:

* [[Template:Essays homepage|Essays_homepage]]
* [[Template:Infobox essay|Infobox_essay]]
* [[Template:Essay lastupdate|Essay_lastupdate]]
* [[Template:Essay categories|Essay_categories]]
* [[Template:Essay authors|Essay_authors]]
** [[Template:Essays numberofworks|Essays numberofworks]] inside the above template
We also use two modules:

* [[Module:Reading time]] transcluded in the Infobox_essay template to estimate reading time. It can be invoked on any page though.
* [[Module:Number of works]] which was made for the library to pull the number of pages (or "works") in a given category page, transcluded in Essays_numberofworks so that it can work with DPL on the author sidebar item.

While each template has its own stylesheet, we really only use the ones associated with Essays_homepage and Infobox_essay (found at /style.css). On MediaWiki, once a stylesheet is called on a page (through a template for example), it will apply to ''everything'' it can on that page. By selectively declaring properties in either essays_homepage or infobox_essay, we can control what appears (and how) on the new essays page (called the '''essays feed''') AND on individual '''essay pages''' (one such example: [[Essay:A nutrition and fitness guide]]) as well.

This documentation goes through each template and the module one by one.

== New category ==
You guessed it, I updated the essays page.

The documentation is still valid with just one addition: you need to add the '''Essays''' category to your essay to have it published. I also limited the count to 15 essays on the [[ProleWiki:Essays|front page]], and added a link to "all essays" at the end of the list, which takes you to the category page which uses the ''exact same code'' as the front page, except without the count limit for the feed (although I had to limit the width of the overall container because category pages are wider for some reason).

That's the only difference, I've updated the dpl codes below to reflect this. 

== Essays_homepage ==
The nesting logic of the essays feed is as follows (named after classes):

* ESSAYS-PAGE
** essays-sidebar
*** essays-sidebar-item
**** X-container (lastupdate ; categories ; authors -- set in each individual item template)
** essays-list (main feed that contains all essays in big format)
*** .infobox-essay
**** and then everything in the infobox template (title, image, excerpt, etc)

Essays_homepage, the template, is only invoked on the new essays page to do CSS. The template by itself only calls its stylesheet at /style.css.

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 <nowiki><span class=”essay-small”> inside 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.</nowiki>

This template is also where we set the styling of each sidebar-item directly. To do that, we simply target .essays-sidebar-item > div (''the first div immediately nested inside .essays-sidebar-item''). This means if you create a template to spice up the sidebar a bit, you only have to add it inside <nowiki><div class="essays-sidebar-item"> (and in the proper nest obviously) and it will look like the others. It makes working on all sidebars at once much easier.</nowiki>

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

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

There is '''one CSS declaration''' that's in MediaWiki:Citizen.css, at the very bottom: .essay-sidebar-item background-color. This is because Citizen has a dark mode and uses color variables to control light and dark mode. Thus the new essays feed is compatible with Citizen dark mode.

== Infobox_essay ==
This is the big template that must be included ''somewhere'' in every essay. It doesn't ''have'' to be at the very top for the content to be transcluded.

First, it changes the display title of the essay to remove the namespace mention using <nowiki>{{DISPLAYTITLE}}</nowiki>. DisplayTitle is included in the template directly. I've also added a <nowiki>{{{name}}}</nowiki> parameter that essentially allows us to name essays however we want without touching the URL (aka permalink). The name parameter works pretty simply with an #if condition: if the parameter name is filled, then use that. Otherwise, use the title parameter.

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 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 the date of the last edit from whichever page it <u>appears</u> on, not from the essay itself. If REVISIONTIMESTAMP appears on the essays feed page when it's transcluded, it will pull data from that page. So I just hid it for now until we find a solution.

(The difference between span and div: spans stay inline, divs are blocks. This means divs will break the line and go to the next and span will not).

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 (!important essentially overrides all other rules).

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.

The code:<blockquote><nowiki><dpl></nowiki>

category = Essays

ordermethod = lastedit

order = descending

mode = userformat

count = 7

listseparators = \n

addeditdate=true

titlemaxlength=57

userdateformat = Y-m-d format = ,\n* <span class="essay-small">%DATE%</span>, <span class="lastupdate-title">[[%PAGE%|%TITLE%]]</span>,

</ dpl></blockquote>What it does is create a list of the 7 most recently updated essays (that is, when an edit was committed) **as long as they are in the Essays category**. You can change that 7 count to anything else in the template by editing '''count = 7''' in the DPL code.

titlemaxlength sets how many characters can appear in the title variable before we truncate it with ... I picked 57 (60-3 to account for the ellipses the code adds) so that it still looks good on desktop (about 2 full lines of text), but we can change it at any time.

Notably we also order by last edit (ordermethod), meaning the most recently updated essay will be pushed to the top of the list.

%DATE%, %TITLE% etc are variables that can be used in dpl, see the documentation.

---

Essay_lastupdate is built in a div container called lastupdate-container. All sidebar items should be inside their own <nowiki><div> container made from their template directly. Well, just look at this template's code and copy and paste for any new template you want to make.</nowiki>

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

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.

I chose to keep the Essay_categories manual instead of pulling it from DPL for two reasons: one, it kinda reduces the server load (again I don't know how much resources it takes to generate all this DPL code) and 2, it prevents people from creating categories and creating chaos. I totally expect that with time, some editors might not take the time to check if a category already exists and create their own duplicate. By adding categories manually, they can not only be named properly, but they can be discussed with the editorship too. 

The (X works) mention gets added by the [[Module:Number of works]]. 

== Essay_authors ==
The essay_authors template also uses DPL. It's pretty simple to use it as a user and it pretty much tells you all you need to know about it, just refer to the user guide section: [[ProleWiki:User guide#Adding author category]].

DPL pulls the contents of the category "Essays by author", simple as that. So you just need to add your author category (Essays by X) to that parent category. I provide the full code to also spice up your author category, since this is the category people will actually visit (Essays by author is really just sort of a holding or container category so that we can use DPL).

So that everyone is equal, I made it so that the authors list is ordered by last update (''to the category''), meaning if you publish a new essay (or happen to remove one from the category, basically updating the category page in any way), you'll get bumped to the top.

The module from just above is used here as well.

== 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 <nowiki><div> are simply templates. They don’t necessarily needed to be templates, but I like that everything is in its own self-contained area.</nowiki>

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 also appear before the feed in the HTML code). If you changed ''reverse-row'' to ''row'', the sidebar would appear on the left. Likewise if you changed the direction on mobile the sidebar would appear after the feed, at the bottom. It's all pretty flexible and can be easily changed all from Essays_homepage/style.css at any time.

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. That is to say, the parent is flex, the child is flex too, etc.

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.

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 <nowiki><ul> list (bullet points).</nowiki>

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

<blockquote><nowiki><dpl></nowiki>

category=Essays

mode=unordered

includesubpages=false

ordermethod= firstedit,pagetouched

order=descending

include={Infobox essay}

<nowiki></dpl></nowiki></blockquote>



<nowiki><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.</nowiki>

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.

''Pagetouched'' is a bit different, basically it looks at when the page was last updated in such a way that the cache was refreshed. Since we grab pages by their inclusion in a category, we want to know when new pages are added to the category, not when the ''category page'' itself was updated (since we don't update a category page once it's created, meaning we go into the editor and commit an edit). You can categorize with more than one parameter and that's what we did, we first categorize by date of first edit, and then by page touched. Not entirely sure why this works but basically it ensures we get essays ordered by the date they got the category added for the first time only. Otherwise every time you updated your essay in any way it would get bumped to the top of the list.

I think it's technically possible that if you remove the Essays category and add it again you can bump your essay to the top of the feed but I trust our editors not to do that and play fair.

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. You can go really deep with the include property, I recommend looking it up on the documentation.

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 [[:Category:ProleWiki official (essays)|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 can also be a pain on mobile as currently you can't collapse the sidebar items.

It’s super easy to add a sidebar item though, just make a template for them (and DPL allows some cool stuff so we can use that as well), transclude that template on the essays feed in the '''.essays-sidebar''' div (and into a child '''essays-sidebar-item''' of course).

You need to put your entire template into a <nowiki><div> container though. Again I recommend just copying the code from Essay_lastupdate and repurposing it.</nowiki>

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

* Add more sidebar items if we can find any.
* Make it so we can collapse sidebar items for mobile users (probably need JS due to MW HTML restrictions)
*make the table of contents available (tried a few things already but it just doesn't get pulled by DPL on the feed page)
*remove the "Essays by " mention in author sidebar item. Possible with DPL but then number of works doesn't work.
*Allow essays to not show up on the feed if someone wants that for a reason. Could be combined with a personal blog page for every editor. Technically you just wouldn't include the infobox_essay template on your essay but then you don't get the formatted look with image, author, reading time etc.
*Make it so the DISPLAYTITLE tag (set through name parameter) also applies on DPL lists, for example in "Last updated" and also in the meta title tag for thumbnails.