Comrade:CriticalResist/sandbox/New homepage documentation

This is likely still in progress when you read this.

If anything's not clear don't hesitate to contact me that's the point of this documentation.

The new homepage unveiled in September 2024 is much more involved in its implementation than the old homepage. Fortunately, it relies mostly on copying-and-pasting and you don't need to know exactly what the stuff you'll be copying does. You will however need to translate some lines of text if you're importing the new homepage to another language instance.

The new homepage can be browsed here: ProleWiki:Main page

It relies on a few templates and, mainly, DPL lists. You don't need to understand the dpl code when you copy it but you will need to translate some of it.

Importing the new homepage[edit | edit source]

First things first, you need to click "View Source" while on the homepage and copy the entirety of the wikicode to your language instance, on the same location as the homepage -- the page people arrive on when they enter en.prolewiki.org (replace "en" with your instance's language code).

Secondly, you will need to import the following pages as well:

ProleWiki:Main page/styles.css (create as a subpage to your homepage)
Template:Pill
Template:button and
- Template:button/style.css
Template:History calendar and
- Template:History calendar/calendar event
Template:Infobox essay and
- Template:infobox essay.dpl
Template:Library work and
- Template:Library work.dpl
Some code inside Mediawiki:Common.js (Function to display testimonial from START to END, but you might want to copy everything anyway)
All of MediaWiki:Citizen.js
And for good measure, copy MediaWiki:Common.css over as well, replacing whatever you had in it.

You can import all of these templates and code into your language instance now before proceeding further.

Caution: you might already have the Infobox essay and Library work templates, but you still need to import the ones that finish with .dpl! We'll go through them later.

These imports assume that you have library works and essays to display in your language instance and that any one of them uses the library work and infobox essay templates respectively. If you don't have any library works or essays, you can translate an essay from the English instance and import any book to start with.

After that, you will need to start doing some translations. This is the more involved part, and I hope I didn't forget anything. Let's go through it section by section:

Homepage translation[edit | edit source]

SEO[edit | edit source]

On the homepage, you need to translate the SEO parameters (always the parts in bold):

{{Pill|title=Politics|image=Pillbox_Politics.png|link=https://en.prolewiki.org/index.php?title=Category:Politics&v=10}} 
...
</div>

You are allowed to put whatever page you want as a link to these pills, but you need to change the title to match your language of course, and the link to a page on your instance. If you don't have many pages, you can delete the extra pills until you have more pages, but I recommend keeping them in multiples of 3 for aesthetics (so having 3, 6, 9 or 12 at any time).

Library code[edit | edit source]

Next, scrolling down, we come across the library DPL code. This code pulls a random book on page refresh, provided that it has the "Library work" template on its page. I won't explain the code here but here's what needs to be translated:

<dpl>
        namespace=Library
        uses=Template:Library work
        notcategory=Reading lists|Song lyrics|Video Transcripts|Poems|Library works by Enver Hoxha|Works for archival
        notcategory=Reading lists
        notcategory=Song lyrics
        notcategory=Video Transcripts
        notcategory=Poems
        notcategory=Library works by Enver Hoxha
        notcategory=Works for archival
        includesubpages=false
        noresultsheader=Something went wrong! Don't worry, we're already on it.
        include={Library work}.dpl
        mode=userformat
        shownamespace=false
        addcategories=true
        randomcount=1
        randomseed={{#time:Ymd}}
</dpl>

The namespace for Library,
the "uses" parameter which is the Library work template (if you translated it to your language),
the categories we don't want to appear (notcategory) -- if you don't have many categories you can also delete the "notcategory" parameters in this code.
The "noresultsheader" (a message that appears when the code is unable to display a book for some reason).

Join us box[edit | edit source]

In the join us box, you need to of course translate the words, but also redirect the "Join us" link to your instance's Special:RequestAccount page. To find the link just open that page and change the "en" language code to your instance's language code, and it will find it automatically.

On this day box[edit | edit source]

The history calendar unfortunately doesn't have documentation yet, but you basically need to copy the History Calendar template, and then the events go into subpages like so: Template:History calendar/MM/DD (e.g. Template:History calendar/01/17)

Then add events into those subpages.

Featured article[edit | edit source]

<dpl>
        category=Featured page
        randomcount=1
        randomseed={{#time:Ymd}}
        mode=userformat
        ordermethod=none
        order=descending
        include=%0
        includemaxlength=300
        secseparators=,\n<br><br>'''Read more'''
</dpl>

We select an article from the "Featured page" category. In other words, only pages that have this category on them can be featured.

Originally, we wanted them to be content creators and other communists as we identified that a sizeable portion of visitors are interested in finding more people to follow. Since we didn't have many however, we started recommending past and present communists. You don't absolutely have to follow this schema but I would recommend it until we know who visits your language instance and why.

-> You should create your own "Featured page" category and inside of it, when creating it, simply add __HIDDENCAT__ and save.

Featured essay[edit | edit source]

Next, we have the featured essay. In the DPL code, translate this:

<dpl>
        namespace=Essay
        category=Essays
        notcategory=ProleWiki news (essays)
        mode=userformat
        mode=userformat
        includesubpages=false
        ordermethod=none
        order=descending
        randomseed={{#time:Ymd}}
        randomcount=1
        include={Infobox essay}.dpl
</dpl>

Refer to the Essays documentation if you need to understand the difference between the namespace and the category. Regardless, the namespace is normally already created on your instance in the proper language, and the category by convention is plural (Essays) to differentiate it with the namespace and because it lists all the essays, not just one.

You can remove the entire notcategory line if you don't have ProleWiki news announcement on your instance. It doesn't hurt to keep it though. If you do have official announcements published on your instance, then translate the category name.

Finally, you may have to translate "Infobox essay" if your Template:Infobox essay was translated.

That's all you need to manually translate on the new homepage and we'll now look through the templates directly.

Template translations[edit | edit source]

Library work and infobox essay[edit | edit source]

Earlier you were asked to import both Template:Library work and Template:Library work.dpl. Both names must always match! If you translated the name of the "Library work" template to "Oeuvre bibliothécaire" for example in French, then you need to write that too for the template that has .dpl added.

I won't go into what the .dpl does in this section but it is required for the new homepage to work. If you open the .dpl template, you'll see that it looks very similar to the non-dpl template, it just has much fewer parameters.

Copy both templates to their own respective page on your language instance and translate the parameters if you want to do that, that way editors in your instance will use the template in their own language instead of english. (e.g. {{{author}}} becomes {{{auteur}}} in French).

Parameters need to match exactly between the dpl and non-dpl template! This is the most important part. You'll know if something is wrong when a parameter doesn't show up on the new homepage.

-> It's the exact same procedure for Infobox essay and Infobox essay.dpl. Import both with the exact same name, and make sure their parameters have the exact same names across both templates as well.

I can't tell you exactly what to translate because this depends on how you decide to translate templates (if you translate the name as well as the parameters, just one, or neither), but parameters are always located inside three curly brackets (e.g. {{{author}}}) so you can just ctrl+f for the keyword "author" for example and replace all instances.

Common.js[edit | edit source]

We added a javascript function to display a random testimonial when the "join us" box becomes too big (this happens when the recommended book next to it has a cover for example, which makes the box it's in taller). You need to copy the function from Mediawiki:Common.js as explained earlier into your own Mediawiki:Common.js. Do not translate any words here, this is a hard-coded mediawiki page.

In the function, you only have one part to translate:

  const thresholdHeight = 375; //live value should be ~350-400
        const testimonials = [
            '<span>"The ProleWiki community is very welcoming and diverse, with a genuine curiosity towards a broad spectrum of topics, plus a democratic and empathetic approach to learning and decision-making"</span> — <a href="https://en.prolewiki.org/wiki/Comrade:ComradeTrash">ComradeTrash</a>'
        ];

You can of course translate the testimonial that already exists, and find your own from your own editors. If you want to add a testimonial, simply do it like this:

  const thresholdHeight = 375; //live value should be ~350-400
        const testimonials = [
            '<span>"The ProleWiki community is very welcoming and diverse, with a genuine curiosity towards a broad spectrum of topics, plus a democratic and empathetic approach to learning and decision-making"</span> — <a href="https://en.prolewiki.org/wiki/Comrade:ComradeTrash">ComradeTrash</a>',
            'testimony goes here'
        ];

Note the inclusion of a comma (,) and the opening and closing of apostrophes ('). Each new testimonial needs a comma after it except the very last one.

And that's it! With all of this you should have imported and translated the new homepage!

</dpl>

Technical things[edit | edit source]

This part is not for importers but for people who might need to work on the new homepage. It details how each function works.

Homepage[edit | edit source]

The new homepage works on a pseudo-bootstrap code we manually brought over from the original. Each "frame-container" also comes with a col-X (from 1 to 12) width, which determines how many columns out of 12 it occupies on a row. Much like Bootstrap 4 and up, we don't have to create rows with a div, those are created automatically since there are only 12 columns on a row. On mobile, all boxes take up all 12 rows.

Most everything is situated in ProleWiki:Main page/styles.css and works from there, though a little bit of code had to be added to Common.css and Citizen.js (the search function trigger).

Pills work through a template and there's not much to say, the interesting part is the DPL code.

Library recommendation[edit | edit source]

The way DPL works, to my understanding, is it first makes an invisible list according to our selection criteria (more aptly called a table). We can then work on that invisible table to bring out a visual list formatted the way we want.

The DPL code for the library book works like this, line by line:

namespace=Library

Selects only pages that are in the Library namespace.

uses=Template:Library work

Selects only pages that have the Library work template in them (+ every other selection criteria)

notcategory=Reading lists

notcategory=Song lyrics

notcategory=Video Transcripts

notcategory=Poems

notcategory=Library works by Enver Hoxha

notcategory=Works for archival

Purposely leave out pages that have these categories on them. I'm not sure if the | character actually works to say OR, so I added both methods to be sure.

includesubpages=false

Don't include subpages in the DPL table, only parent pages. E.g. Capital Vol. I/Chapter 1 will not appear in this table.

noresultsheader=Something went wrong! Don't worry, we're already on it.

If DPL is somehow unable to fetch a book to display as we ask it to, it will display this message instead. Not sure why but it does glitch sometimes.

include={Library work}.dpl

Include in DPL means to transclude the content of the tabled page to the DPL list. In this case we show the content of Template: Library work.dpl

mode=userformat

The mode is how we want to display our output list; userformat lets us decide exactly. In this case it's used by default because we output the content of a template. When using userformat, nothing is displayed by default and we decide exactly what we want to display and how.

shownamespace=false

Remove the namespace from being included in the output list, e.g. Library:Capital Vol. I becomes Capital Vol. I.

addcategories=true

Tell DPL we want to log each page's categories in its invisible table. We then display them with Library work.dpl

randomcount=1

Take one page from the invisible table, randomly, and display it -- in this case, we only display the Library work.dpl template since that's all we include and we are in userformat mode. If randomcount was 2 then it would display two templates from 2 different books.

randomseed={{#time:Ymd}}

The random seed is simply the number of the year-month-date, e.g. 20240626. It changes every day so that every day, a new table is created.

DPL only creates tables of up to 500 pages. Since we have around 1000 books now, we need to refresh the table every so often (in this case every day) to give every book a chance of appearing. Otherwise, only the same 500 books would be picked. Again, this is to the best of my understanding - DPL's documentation isn't exactly clear.

The important part here is the weird Library work.dpl template.

Basically, it's like a variable or a function in coding. We have the original Library work template, which is sort of the "parent" template. It has its own parameters, it can have its own CSS in /styles.css, etc.

What the .dpl template does is pass all parameters from the parent to the child, as well as five DPL-specific parameters (categories, author, date of last edit, and I don't remember the rest).

We can then use those parameters as we wish in the child template, effectively making it its own, but with data fed from the parent template.

This is the reason we need to specify "addcategories=true" in the DPL code, even though we display the categories from the .dpl template and not through the usual bulleted list DPL displays. By adding addcategories=true, it passes on the categories to the child .dpl template and we can display them from the template directly. Again, it only does that for 5 parameters which are specified in its documentation and are not important here.

So basically, what this DPL code does in English terms is:

Take all pages that exist in the Library namespace AND use the template called Library work. However, don't select pages that have either Poems or Works for archival (etc) as a category even if they fulfil the other two conditions. Next, we will only display the contents of the Library work template and nothing else. However, you will pass that data to the child Library work.dpl template instead and display that child template directly. Finally, we will only display 1 random book at a time from the selection.

DPL is very versatile and its parameters can be included in any order, by the way. For ease of reading I try to keep them grouped by function, but anything works.

The other DPL lists work similarly and I might go into them later, it's more of the same really.