====== New works icon procedure ======

Icons can be quickly made on an ad-hoc basis as described in the [[conventions#settlements_described_in_the_work_get_the_most_apt_icons|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 [[wiki:wrap_plugin]] classes in the [[wiki:customizations|Hârnstrap3]] template will suffice for the icon's colors. If not, the description of the [[wiki:heading_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 [[wiki:icons_plugin]].

  * [[https://fontawesome.com/v4/icons/|Font Awesome v4.7]]
  * [[https://pictogrammers.github.io/@mdi/font/4.1.95/|Material Design Icons v4.1.95]]
  * [[https://nagoshiashumari.github.io/Rpg-Awesome/|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.

  - [[#Add the icon-itself page link to the relevant table]].
    - [[#General category icons are linked on the icons coding table]].
      - Link: [[coding#icons_coding_table|Icons coding]]
    - [[#Realm-specific icons are linked on the realm icon coverage table]].
      - Link: [[realm_icon_coverage]]
  - [[#Create the icon-itself page]].
    - [[#Replace the some-color-class placeholder wITH the desired CSS class]].
    - [[#Delete the mdi-icon class when not using an mdi icon]].
    - [[#Use the icons-pages line for general category icons]].
    - [[#Use the icons-pages-realms line for realm-specific icons]].
    - [[#Replace the icon-pack placeholder with fa, ra, mdi, or other pack]].
    - [[#Replace the some-icon placeholder with the icon name]].
    - [[#Clean up the title and label, if needed]].
  - [[#Add the icon reference page link to the relevant key]].
    - [[#General category reference pages are linked in the main key]].
      - Link: [[.pages:]]
    - [[#Realm-specific reference pages are linked in their own key]].
      - Link: [[.pages:realms:]]
  - [[#Create the icon reference page]].
    - [[#Edit the page title, if needed]].
    - [[#Add remarks]].
  - [[#Add the icon reference page to the relevant right sidebar]].
    - [[#General category reference pages go in the pages namespace]]
      - Link: [[.pages:rightsidebar|icons:pages:rightsidebar]]
    - [[#Realm-specific reference pages go in the pages-realms namespace]]
      - Link: [[.pages:realms:rightsidebar|icons:pages:realms:rightsidebar]]
  - [[#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.

===== Add the icon-itself page link to the relevant table =====

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 [[wiki:tags|tag]] for the category, use that for the pagename too. This pagename is also used for the icon reference page later.

==== General category icons are linked on the icons coding table ====

The //Icons coding table// is found on the [[coding#icons_coding_table|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.

==== Realm-specific icons are linked on the realm icon coverage table ====

A different table shows the [[realm_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.

=== Example ===

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.

<code>
| Emelrene         ||||||||||
</code>

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.

<code>
| Emelrene         | | | | | | | | |  [[map_emelrene|yes]]  |
</code>

===== Create the icon-itself page =====

These are the pages that are used with the [[wiki: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.

=== Example ===

Click the newly-created link. The [[.pages:i_template|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.

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

</code>

==== Replace the some-color-class placeholder wITH the desired CSS class ====

This value---and possibly the ''icon-pack'' and ''some-icon'' values to be used later---can be found on the [[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.

=== Example ===

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

==== Delete the mdi-icon class when not using an mdi icon ====

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.

=== Example ===

We are not using such an icon in our example.

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

<code>
<WRAP emelrene columbian-icon>
</code>

==== Use the icons-pages line for general category icons ====

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.

=== Example ===

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

==== Use the icons-pages-realms line for realm-specific icons ====

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.

=== Example ===

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.

==== Replace the icon-pack placeholder with fa, ra, mdi, or other pack ====

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.

=== Example ===

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.

==== Replace the some-icon placeholder with the icon name ====

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.

=== Example ===

We take the icon used in the general [[icons:pages:map|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.

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

==== Clean up the title and label, if needed ====

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.

=== Example ===

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

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

</code>

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.

===== Add the icon reference page link to the relevant key =====

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.

==== General category reference pages are linked in the main key ====

The [[.pages:]] 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.

==== Realm-specific reference pages are linked in their own key ====

The [[.pages:realms:]] 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.

=== Example ===

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.

<code>

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

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

</code>

===== Create the icon reference page =====

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 [[.pages:i_template|new general category reference page template]] or the [[.pages:realms:c_template|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.

=== Example ===

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

<code>
====== 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]]

</code>

==== Edit the page title, if needed ====

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.

=== Example ===

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

==== Add remarks ====

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.

=== Example ===

In our example, we are going to pinch the remarks (or even the whole page text) from the [[.pages:realms:map_azadmere]] page and swap in "Emelrene".

===== Add the icon reference page to the relevant right sidebar =====

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.

<code>
{{page>icons:our_icon_page&inline}}
</code>

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.

==== General category reference pages go in the pages namespace ====

The [[.pages: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.

==== Realm-specific reference pages go in the pages-realms namespace ====

The [[.pages:realms: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.

=== Example ===

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.

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

</code>

===== Replace any ad-hoc icons with include pages =====

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.

=== Example ===

In our example, we'll look for this.

<code>
"<WRAP emelrene columbian-icon>"
</code>

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

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

</code>

Becomes…

<code>
{{page>icons:map_emelrene&inline}}

</code>