Board Thread:General Discussion/@comment-15636815-20131029040121

Yes, yes, I know. This post is long. Really long. It's so long, you may start it, then need to eat a meal before you finish it. That's okay. Take your time, and read the whole thing.

"What? The whole thing?  There must be some parts I can skip." No, there aren't. Everything here either is a critical part of the plan, or it explains a critical part, or it mentions a problem with a critical part. If you skip something, you probably will start asking questions that are answered in the part you skipped. That's one of the fastest ways to annoy me, so please don't. Yes, the whole thing.

Background
In this blog post and its related comments, the community recognized and affirmed the need for Shop tables to have consistent methods of input and output. Below is the structure of my idea for filling this need. Some details are missing from this structure; these omissions are related to as-yet-unsolved problems.

Community feedback is welcome.

Community feedback is VITAL to the success of this project. The finished product will be used by different people with different sets of technical skills, especially after Wikia releases the new VisualEditor. Therefore, all users are allowed and ENCOURAGED to add their comments to the discussion.

Proposal
I propose creating a Template:ShopBuildingTable and a Template:ShopBuilding, both of which are similar in design and function to Template:ShopTrainTable and Template:ShopTrain, respectively. In addition, I propose several features (functions) for Template:ShopBuilding that the current method lacks. I will explain each of these items as they appear.

(The names of the proposed templates are open to negotiation. I chose these names for consistency with the train table names.  Another option is to replace the existing Template:ShopTable and Template:ShopItem.  This option has two advantages: We already are familiar with those names, and the names are shorter.)

Component 1 - Template:ShopBuildingTable
Currently, the primary methods for creating and editing tables of buildings are the visual editor, which creates overly complex source code, and manually editing the overly complex source code. The most likely reason that editors use these methods instead of the existing table templates is that the table templates use fewer columns of data than our users require.

Current Template
Below is the wikitext for Template:ShopTable, copied verbatim. It is shown here only for reference.

Note: I have added line numbers before each line, contained in [brackets]. Their purpose is only for reference while we work on the project. They are not part of the actual template.

[01] {| border="0" cellpadding="1" cellspacing="1" class="article-table" style="width: 670px;" [02] ! scope="col" style="white-space: nowrap;"| Name [03] ! scope="col" style="text-align: center;"| Contract [04] ! scope="col" style="white-space: nowrap; text-align: right;"| Cost [05] ! scope="col" style="text-align: right;"| [06] ! scope="col" style="text-align: center;"| Pass/hr

[07] ! scope="col" style="white-space: nowrap;"| Size

[08] ! scope="col" style="text-align: center; white-space: nowrap;"| / [09] ! scope="col" style="white-space: nowrap;"| Notes [10] |- This template contains the start of the Building Shop Table.

Proposed Template
I built this template using ShopTrainTable as a model. (Reminder: The code shown above is for ShopTable.) The basic structures of the two tables are the same. Column names differ, of course. A few minor adjustments improve the table's appearance and functionality.

Note: I have added line numbers before each line, contained in [brackets]. Their purpose is only for reference while we work on the project. They are not part of the actual template.

[01] {| border="0" cellpadding="0" cellspacing="0" class="article-table sortable" style="width:100%; font-size:88%; text-align:right;" [02] ! scope="col" style="text-align:left; white-space:nowrap;" |Name [03] ! scope="col" style="text-align:center; white-space:nowrap;" |Lvl [04] ! scope="col" style="text-align:center; white-space:nowrap;" |Lim [05] ! scope="col" style="text-align:center; white-space:nowrap; width:18%;" |Cost [06] ! scope="col" style="text-align:center; white-space:nowrap; width:18%;" |Complete Sam Cost [07] ! scope="col" style="text-align:center; white-space:nowrap;" | [08] ! scope="col" style="text-align:center; white-space:nowrap;" |Pass/hr [09] ! scope="col" style="text-align:center; white-space:nowrap;" |Size

[10] ! scope="col" style="text-align:center; white-space:nowrap;" |/

[11] ! scope="col" style="text-align:center; white-space:nowrap;" |Notes [12]

Changes
Note: Unless otherwise indicated, line numbers refer to the Proposed Template.

The first thing you notice about ShopTable is the use of the | template instead of the pipe (|) character. While some situations do require |, this is not one of them. The code is unnecessarily difficult to read. The proposed version uses pipes, as does ShopTrainTable.

Specific changes are:
 * 1) Copied Template:ShopTrainTable verbatim, overcoming many consistency issues instantly, including the use of |.
 * 2) Line 01 - Changed font size from 90% to 88%. Combined with column-specific width settings, this change allows entries such as "" to display on one line instead of wrapping the resource symbol to a new line.
 * 3) Line 01 - Added code to right-align all data (non-header) cells in the table. Excluding the "Name" and "Notes" columns, all columns contain numerical data, which tends to look best with right alignment.  The two text columns can be formatted for left alignment with cell-specific attributes.  For details, see the "Template:ShopBuilding" section below.
 * 4) Line 02 - Left-aligned header to keep it in line with the text below it.
 * 5) Column header lines include the "nowrap" style attribute, which the current source code does not. This attribute forces the sorting arrows to appear next to their relevant headers instead of appearing on new lines.
 * 6) Lines 05,06 - Added column-specific forced width of 18% for the two Cost columns to resolve the wrapping issue mentioned above.
 * 7) Line 07 - Used preferred code to display symbol.
 * 8) Current Template, Line 10 - Good programming practices suggest that every line of code end with a new line, or carriage return, character, including the final line. All other lines of code end this way.  Why shouldn't the final line end the same way?  This practices also provides consistency, which is the core goal of this project.
 * 9) Line 11.5 - Removed "new row" indicator ( |- ). A new row indicator belongs with the row following it because row-specific formatting appears on the same line as the new row indicator.

Issues

 * 1) Sorting on the two Cost columns provides little benefit, if any. I propose making these two columns unsortable, along with any other columns the community chooses.
 * 2) I saw a template that had the option to remove the "Notes" column from a particular table if the column contained no data. I don't remember where I saw it, and I'm not going digging for it right now.  The question is, do we want to do this?  Removing the column when unused will leave more room for the other columns, but it could give an inconsistent appearance.

Current Template
Below is the wikitext for Template:ShopItem, copied verbatim. It is shown here only for reference.

Note: I have added line numbers before each line, contained in [brackets]. Their purpose is only for reference while we work on the project. They are not part of the actual template.

[01] | [02] | style="text-align: center;"| [03] | style="text-align: right; white-space: nowrap;" | [04] | style="text-align: right; white-space: nowrap;" | [05] | style="text-align: center;"| [06] | style="text-align: center;"| [07] | style="text-align: center;"| [08] | [09] |-

Model Template
Below is the wikitext for Template:ShopTrain, copied verbatim. It is shown here only for reference.

Note: I have added line numbers before each line, contained in [brackets]. Their purpose is only for reference while we work on the project. They are not part of the actual template.

[01] [02] | style="text-align:left;font-size:90%;white-space: nowrap;" | [03] | style="text-align:center;font-size:90%; white-space: nowrap;" | [04] | style="text-align:center;font-size:90%; white-space: nowrap;" | [05] | style="text-align:center;font-size:90%; white-space: nowrap;" | [06] | style="text-align:center;font-size:90%;" | [07] | style="text-align:center;font-size:90%;" | [08] | style="text-align:center;font-size:90%;" | [09] | style="text-align:center;font-size:90%;" | [10] | style="text-align:left;font-size:90%;" | [11] |- [12]

Proposed Template
WARNING: This template was complex when I found it, and I greatly increased its complexity. If you're not sure that you understand something properly, read it again, and use a search engine for help. If you're still not sure, ask! If you don't ask, you could miss the spark of inspiration that makes this project super special! :-D

I built this template using Template:ShopTrain as a model. The basic structures of the two tables are the same. Otherwise, the templates have little in common because of large differences in required input, required output, and proposed output.

Note: I have added line numbers before each line, contained in [brackets]. Their purpose is only for reference while we work on the project. They are not part of the actual template.

[01] |- [02] | align="left" | [03] | [04] | [05] | [06] | {{#if:{{{cost|}}} | {{cost-Sam|{{{cost}}} }} [07] | {{XP|{{formatnum:{{{buildxp}}} }} }} [08] | {{#if:{{{pax|}}} | {{formatnum:{{{pax}}} }} | }} [09] | {{formatnum:{{{size}}} }} [10] | {{#if:{{{size|}}}|{{#if:{{{pax|}}}|{{formatnum:{{decimals|{{{pax|}}}/{{{size|}}}|2}}}} | no pax }}| no size }} [11] | align="left" | {{#if:{{{notes|}}} | {{{notes}}} }} [12] {{TSTemp}}

Changes
As you probably already noticed, the Proposed Template retains the | templates used by the Current and Model Templates. Yes, that means we meed them in this situation. The Proposed Template uses the column headers most commonly found in building tables on the TS Wikia, displayed in the most common order.


 * 1) Used the abbreviation "pax" for "passengers" throughout. The term is used in all major transportation industries, and it's shorter than all other options our Wikia uses currently.
 * 2) Line 01 - Removed carriage return after tag. It is unnecessary, and it can lead to inconsistencies in formatting.
 * 3) Lines 02-11 - Removed all cell-specific formatting. Although the current visual editor tends to add these instructions, they actually do more harm than good.  Remember the "text-align:right" and other style attributes on Line 01 of the Proposed Template for ShopBuildingTable?  Those work for the entire table.  Repeating the same instructions for every - single - cell - in - the - table is tedious for humans, even with copy and paste.  Worse, it causes the computer to pause briefly to format each cell before writing data into it.  Though the delay is tiny, the effect can compound on pages with large tables and/or multiple tables.  Users with slower connections experience even greater delays.  I can't prevent the visual editor from adding this crap, but that doesn't mean I'm going to mimic the visual editor's stupidity.
 * 4) Lines 02,11 - Added cell-specific code to align left. These two columns need left alignment because they contain text.
 * 5) Line 02 - Added code to process the display text for internal links where the link text and display text differ. If no display text exists for that row, the template uses the link text to build a normal internal link.
 * 6) Lines 03,04,05,06,08 - tags allow the template to leave a cell blank if it has no input for that parameter.  This allows the Wikia to use only one template for all types of buildings--regular, special, award, etc.--instead of creating separate templates for each type of building.
 * 7) Lines 03,04,07,08,09,10 - Used parser function "formatnum" for all numberic output. This provides consistency in appearance by inserting commas to separate groups of three digits, while eliminating the need for the user to remember which cells need commas and which do not.  The two Cost columns do not use "formatnum" because Template:Cost takes care of that function.
 * 8) Lines 03,04,07,08,09,10 - When "formatnum" caused a string of 5 or more consective curly braces }}}}}, inserted a space so the template won't get conused and process the braces incorrectly.
 * 9) Line 10 - Used Template:Decimals (copied from MediaWiki under Fair Use) to compute and format the pax-to-size ratio.
 * 10) Prevents human error in calculations.
 * 11) Prevents wear and tear on humans from performing calculations.
 * 12) Prevents inconsistencies in rounding.
 * 13) Formats all numbers in tise column consistently, using trailing zeroes when needed. Trailing zeroes keep the numbers in this column decimal-aligned.
 * 14) Used in columns that currently don't need it, such as Level and Limit, for consistency, and for expandability. You never know how far Pixel Federation will take this thing in 20 years.
 * 15) Line 06 - THIS IS THE BIG ONE!!!!! This line calls Template:Cost-Sam, which generates the discounted cost paid by users who have completed all of Sam's achievements.
 * 16) Prevents human error in calculations.
 * 17) Prevents wear and tear on humans from performing calculations.
 * 18) Does not yet exist. All posts addressing the inability to find Template:Cost-Sam will be answered only with silence.

Issues
tags between each resource. The template receives only the finished product, complete with images and line feeds.
 * 1) I built the Proposed Template using named parameters, because they make it easier to see how the template works. I would prefer to replace all of the named parameters with numbered parameters in the final version.
 * 2) Named parameters encourage laziness. If you look at the source code for any train table, you will see data entered in at least a dozen arrangements, and it's unlikely that any of them match the display order.  This makes the entries hard to read and harder to edit.
 * 3) A double pipe ( || ) in the input string shows clearly which cells should be blank on a given row.
 * 4) Line 10 - This line computes and formats the pax-to-size ratio for each building. If data for either pax or size is missing, this line generates an error message in the pax-to-size column.  Special Buildings do not have a pax attribute by design, but this code generates errors on Special Buildings, too.  Is there a way to add an  function to this line to prevent false errors?
 * 5) Template:Cost-Sam does not yet exist because I have no idea how to make it work, even after hours of study.
 * 6) The idea is for the user to input cost data once and for the template to display the cost data plus the discounted cost data without further user interaction.
 * 7) Both Cost columns accept the same input, which the user enters in this format: cost=.
 * 8) Before the template receives the parameter, Template:Cost reformats the user's input into the  format for display, adding
 * 1) Template:Cost-Sam must use the only input available to it, which is the final display format that Template:Cost generates. Cost-Sam must somehow parse through the display format to find the numbers, apply the discount, identify the images, and reformat everything so Template:Cost will accept the input and generate the desired output.
 * 2) Is that complicated enough for you?

Component 3 - Template:ShopBuildingDual
The Proposed Template for Component 2 cannot format buildings that have a "dual cost" (gems OR materials). The source code method uses "rowspan" attributes. Since ShopBuilding is so complex already, I decided that the easiest way to input data for dual-cost buildings would be to use a separate template. I've done absolutely nothing to design this third template. With Cost-Sam, it should be fairly easy. Without Cost-Sam, I cannot complete this template at all. Therefore, there is no reason to work on this template until Cost-Sam is complete. You need to know it's part of the plan, though.

Conclusion
All of this structure and accompanying ideas are just that--ideas. I'm not married to them, so I won't be offended if you have an idea that you think is better (or actually is better!). The more ideas we generate, the better this project will be, and the faster we can complete it.

Two weeks ago, I noticed some new buildings that Pixel added during a game update. These buildings were not listed in the Wikia, so I decided to enter them. HHowever, the numerous inconsistencies in the building tables bothered me so much that I began to study how to create a consistent format. The end result of unknown hours of study is this proposal.

...and I still haven't entered those new buildings. Let's work together to create a solution so we won't be annoyed by missing buildings. ;-) 