New works icon procedure

Icons can be quickly made on an ad-hoc basis as described in the Icon conventions. This procedure describes a fuller integration of a new icon with the rest. It works through the two pages that need be made and all the places they need be linked for each new works icon.

This assumes that existing Wrap plugin classes in the Hârnstrap3 template will suffice for the icon's colors. If not, the description of the Columbian headings css should provide some guidance with that, provided that one has access to the wiki's backend files.

This also assumes that a suitable icon has been selected from one of the icon packs. The following are widely used in the wiki already, though more are available to the Icons plugin.

• Font Awesome v4.7
• Material Design Icons v4.1.95
• RPG Awesome

If, alternately, one is interested in doing all of a realm's hold & location icons in bulk, that process can be found at Adding all realm icons.

The steps are as follows.

1. Add the icon-itself page link to the relevant table.
   1. General category icons are linked on the icons coding table.
      1. Link: Icons coding
   2. Realm-specific icons are linked on the realm icon coverage table.
      1. Link: Realm-specific icon coverage
2. Create the icon-itself page.
   1. Replace the some-color-class placeholder wITH the desired CSS class.
   2. Delete the mdi-icon class when not using an mdi icon.
   3. Use the icons-pages line for general category icons.
   4. Use the icons-pages-realms line for realm-specific icons.
   5. Replace the icon-pack placeholder with fa, ra, mdi, or other pack.
   6. Replace the some-icon placeholder with the icon name.
   7. Clean up the title and label, if needed.
3. Add the icon reference page link to the relevant key.
   1. General category reference pages are linked in the main key.
      1. Link: Icons key
   2. Realm-specific reference pages are linked in their own key.
      1. Link: Realm-specific icons key
4. Create the icon reference page.
   1. Edit the page title, if needed.
   2. Add remarks.
5. Add the icon reference page to the relevant right sidebar.
   1. General category reference pages go in the pages namespace
      1. Link: icons:pages:rightsidebar
   2. Realm-specific reference pages go in the pages-realms namespace
      1. Link: icons:pages:realms:rightsidebar
6. Replace any ad-hoc icons with include pages.

For our example, we will memorialize the creation of an icon for a map in Emelrene, which has already been faked on a couple works: pages. The process for making one realm-specific icon is very similar to that for making a more general category icon with a few distinctions that this procedure will attempt to highlight.

A link needs to be made in order to create the icon-itself page, and it is natural to do that from the place it has to be linked to when all's said and done. This is on one of two pages.

Pick a pagename that fits well with the names already present. If there is already a tag for the category, use that for the pagename too. This pagename is also used for the icon reference page later.

The Icons coding table is found on the Icons coding page. Check the values present in the Pack and Icon name columns to verify that the new icon to be added doesn't conflict with any of them. Alternately, make note of the values for an icon being reused.

These categories include base realm categories, like “Kaldor”. Realm-specific categories are the ones that combine two general categories like “City in Kaldor”.

The link we need to insert goes in the Icon page column, though a new, full line should be created. Follow the example of the lines already present; indeed, many values can be copied from similar lines. It is not strictly necessary to line up all of the pipes (|) and carets (^).

Note: The rendering of the icon in this table is just a simple “monitor” to show it. What happens later when we use the Icons plugin on the new icon-itself page is different.

A different table shows the Realm-specific icon coverage. This is a matrix of holds in the columns and realms in the rows that displays which icons have already been created and which have not.

Again, it is not strictly necessary to line up all of the pipes and carets.

In our example, we will go to the realm-specific table, where there is already a line for Emelrene with enough extra pipes to complete the table.

| Emelrene         ||||||||||

To add a link, place it between the two appropriate pipes with at least two spaces on either side to center it. The Map column is at the end, so it should look something like this.

| Emelrene         | | | | | | | | |  [[map_emelrene|yes]]  |

These are the pages that are used with the include plugin, and they contain only the fully-formatted icon itself. OK, they also have the top-level page heading, but the include plugin has the noheader flag set as the default.

Click the newly-created link. The New icon-itself page template should get us most of the way there. When we click our example link, this is what we see, minus the instructions and smileys to be deleted.

====== Map emelrene icon ======

<WRAP icon-pad>
<WRAP some-color-class columbian-icon mdi-icon>
[[icons:pages:map_emelrene|{{icon-pack>some-icon?30&align=left|Map emelrene}}]]
[[icons:pages:realms:map_emelrene|{{icon-pack>some-icon?30&align=left|Map emelrene}}]]
</WRAP>
</WRAP>

This value—and possibly the icon-pack and some-icon values to be used later—can be found on the Icons coding page if an existing Wrap class is being used. If using a new Wrap class that has already been added to the Hârnstrap3 CSS, use that value minus the wrap_ prefix needed in the CSS file.

In our example, the class we want is called emelrene.

These are needed to tweak the positioning of icons from the Material Design Icons pack. Perhaps there's a better way to arrange the CSS to avoid this kludge, but the present editor got this to work and moved on.

We are not using such an icon in our example.

We have now completed the first line to edit, which looks like this.

<WRAP emelrene columbian-icon>

The next two lines provided by the template are the same except that the links to the icon reference page to be created later go to two different namespaces. Only one is correct.

For general category icons, the first line with icons:pages: is the one pointing to the correct namespace. Delete the line after, linking to the same pagename in icons:pages:realms:, which would be the wrong place.

Keep the first line and delete the second.

We are not making a general category icon, so we remove the first of the two lines.

For realm-specific icons, the reverse of the above is true. The icon reference page goes in the icons:pages:realms: namespace and not in its parent.

Keep the second line and delete the first.

In our example, we are creating a realm-specific icon. The link to the icon reference page should then be in the icons:pages:realms: namespace, so we delete the first of the two lines.

The icon-pack placeholder is where the Icons plugin gets the value for the correct icon pack, like Font Awesome, etc. This placeholder is replaced with the appropriate value for the plugin.

In our case, we need fa for Font Awesome here. The other icon packs in common use in HârnWiki are ra for RPG Awesome and mdi for Material Design Icons.

The some-icon placeholder is where the name of the desired icon goes when using the Icons plugin. This value is replaced with that icon's name.

We take the icon used in the general Map category for our example, map-o. Were we making a whole new category, we'd need to select a new icon from one of the icon packs.

We've edited another line, which looks like this. In fact, two lines look like this since the first has been removed.

[[icons:pages:realms:map_emelrene|{{fa>map-o?30&align=left|Map emelrene}}]]

The @!PAGE@ replacement pattern in the new page template is replaced by the name a new page is created with. Furthermore, underscores are replaced by spaces, and it is changed to sentence case as per our wiki's style. This often can be kept as is, but sometimes it needs to be edited.

This pattern appears in two places: the top-level page heading and at the end of the icon-defining line in the label that appears in a tooltip when a wiki user hovers the mouse over the icon. Changes may need to be made in both places.

Our example page should look like this after the changes we've made so far.

====== Map emelrene icon ======

<WRAP icon-pad>
<WRAP emelrene columbian-icon>
[[icons:pages:realms:map_emelrene|{{fa>map-o?30&align=left|Map emelrene}}]]
</WRAP>
</WRAP>

It's almost there, but the two places that say “Map emelrene” in the title and the link label should say “Map in Emelrene”. Make those changes.

As above, a link needs to be made to the icon reference page too. This is the page that we've made a link to in the icon-itself page that describes what the icon represents.

Again, these are required on one of two places. Go to the relevant page, open the DokuWiki page editor, and select a model for copying.

Note: These pages should have the same pagenames in their proper namespace as the icon pages do in the icons: namespace.

The Icons key shows links to all of the icon reference pages. The right sidebar also displays all of the formatted icons for more visual browsing.

Here, similar categories are grouped together under the following headings.

• Publishers
• Wide areas
• Regions
• Realms (in different sections for each region)
• Holds & locations
• Maps
• HârnMaster
• Magic
• Religion
• Other

Pick the best heading for the new category and insert it into the sequence in the table, keeping it in alphabetical order.

The Realm-specific icons key links to the icon reference pages for all of the realm-specific icons. This page has been included at the bottom of the main key too, so it can also be edited there by scrolling to the bottom and pressing the Edit (icons:pages:realms:start) button provided by the include plugin.

In our example, this is the first realm icon of any kind in the Trierzon region, so we go to the bottom and insert the following after the end. In this case, we add an empty row after Emelrene to get the table to format properly.

===== Trierzon realms =====

^  Emelrene | [[map_emelrene|Map in Emelrene]] |
^           |  |

Clicking on the newly-created link, a new page template will provide the icon reference page's content. Which template is used depends on the namespace in which this page is created, either the new general category reference page template or the new realm-specific reference page template.

Much of the work is done, except for coming up with something meaningful to say about the category. If we've given the reference page the same name in its namespace as the icon page has in the icons: one, then all three links to the latter will match up.

Clicking our link in the Realm-specific icon key will give us something that looks like the following.

====== Map Emelrene reference ======
<WRAP icon-sidebar>
{{page>icons:map_emelrene&inline}}
</WRAP>

[remarks]

Paste for editors: ''%%{{page>icons:map_emelrene&inline}}%%''
[[icons:map_emelrene|Link]]

Again, the template generates a top-level heading from the pagename with which the new page is created. Often this is fine as is, but look it over to check.

In our example, we need to insert the word “in” between “Map” and “Emelrene”.

Describe what the icon is meant to signify. So far the descriptions have been pretty terse, perhaps too much so. Still, there doesn't have to be a lot here.

In our example, we are going to pinch the remarks (or even the whole page text) from the Map in Azadmere reference page and swap in “Emelrene”.

Now we need to link our new page on the appropriate right sidebar page so that it appears visually in the Icons key. Again, this is in one of two places.

When editing the page, the syntax is readily apparent. Indeed, it is the same syntax that can be used everywhere in the wiki now.

{{page>icons:our_icon_page&inline}}

What varies is the container we place around several icons. Here, it is inside a <WRAP icon-sidebar> group. In headings in the works: namespace, this is <WRAP icon-line>. These containers manage the space around the icons differently.

This link should be put in the place on the right sidebar that corresponds with the place in which the reference page's link was inserted on the Icon key page itself.

The rightsidebar for the icons:pages: namespace is what is displayed on every page in that namespace, unless overruled by a more specific one in a sub-namespace.

The rightsidebar for the icons:pages:realms: namespace overrules the one from its parent, and that is what is shown an all pages in this sub-namespace.

Our Emelrene page goes at the very bottom of the latter. Once again, we need to open up a whole new section for it.

So we look, again, to Azadmere. That opens a section too; we even get to copy that part easily. As you can see, we use the include plugin to bring in the icons themselves.

In our example, we paste this there at the bottom of the page.

**Trierzon realms**\\
**Emelrene**
<WRAP icon-sidebar>
{{page>icons:map_emelrene&inline}}
</WRAP>

Now check if any ad-hoc icons are there that can be upgraded to the real thing. Now they'll have links that show wiki users what the icon means and have the right sidebar allowing that user to browse all the rest of them.

One can do this by using the search box at the top of any page. Look for one of the lines used to display the icon with the Icons plugin. There will be hits for our new icon-itself page, but there may be others too.

In our example, we'll look for this.

"<WRAP emelrene columbian-icon>"

Then we replace the manual icon construction with the include link.

<WRAP icon-pad>
<WRAP emelrene columbian-icon>
{{fa>map-o?size=30&align=left}}
</WRAP></WRAP>

Becomes…

{{page>icons:map_emelrene&inline}}