Wikipedia:Wikipedia Signpost/Templates/Voter/Documentation: Difference between revisions

Browse history interactively

← Previous edit

Content deleted Content added

VisualWikitext

Inline

Latest revision as of 16:13, 9 January 2021

This template uses Lua:

Module:Signpost poll

Parameters

This template is a proposal for an in-wiki polling apparatus for weekly use by the Signpost. The parameters are as follows:

{{Wikipedia:Wikipedia Signpost/Templates/Voter
| image = <!-- An image for the top-right corner of the sidebar; defaults to the Signpost logo. -->
| question = <!-- Question under consideration in the poll. -->
| option1 = <!-- Name of the first option, as reported in the legend and in the vote button. Defaults to the test poll. -->
| option1color = <!-- Color of the first option choice; defaults to #006699, Foundation blue. -->
| option2 = <!-- Name of the second option, as reported in the legend and in the vote button. Defaults to the test poll. -->
| option2color = <!-- Color of the first option choice; defaults to #339966, Foundation green. -->
| option3 = <!-- Optional. Where the votes for option two will be collected. Defaults to the test poll. -->
| option3color = <!-- Color of the first option choice; defaults to #990000, Foundation red. -->
| votepage = <!-- The page at which all of the votes will be accrued. -->
| min_votes = <!-- The minimum number of votes that must accrue before the template begins to display results. Defaults to 10. -->
| break = <!-- If this parameter is non-empty the votebar is split into two to better accommodate lengthier poll options. -->
| overlay = <!-- overlay image; defaults to File:Foundation Logo Transparent.svg. -->
| expiry = <!-- The number of days after which the poll is closed; defaults to 14 days. -->
}}

question: Question under consideration in the poll. (required)
votepage: Page that the votes will be stored on (required). If in doubt, choose poll location/Votes.
option1: Name of the first option, as reported in the legend and in the vote button. Defaults to Yes.
option1color = Color of the first option choice; defaults to , Foundation blue.
option2: Name of the second options, as reported in the legend and in the vote button. Defaults to No.
option2color: Color of the second option choice; defaults to , Foundation green.
option3: Optional. Name of the third options, as reported in the legend and in the vote button. No default.
option3color: Optional. Color of the third option choice; defaults to , Foundation red (if the third option is enabled at all).
minimum: Minimum number of votes that must accrue before the poll will display the visualization; before this many votes are made the poll will tell readers that X more votes are needed based on the size of the deficit. Defaults to 10.
break: Set to "yes" to break columns between the buttons to allow longer button names. If this is not set, the template will try and auto-detect a sensible value.
expiry: The number of days after which the poll is closed; defaults to 14 days (two publication cycles). Note that is this defined from the day that you create the template not from the day that you actually publish the article!
header: Text that goes in the poll header. The default is "Signpost poll".
icon: Changes the image that is displayed in the top-right corner of the poll. As used in the Signpost other images are not recommended.
overlay: Overlay on the stacked bar chart which produces the template's fancy visualization. By default this is File:Foundation Logo Transparent.svg, a transparent version of the Wikimedia Foundation's logo. With some basic vector editing skills such images are easy to make; requirements for a working overlay are:
- Square image; the transparent Foundation logo is a vector SVG with native resolution of 1050x1050.
- Canvas whitespace; The bar chart is not displayed wherever the image canvas is explicitly white.
- Transparent logo; this is where the chart will be displayed.

Test cases

For test-cases see here.

@@ Line 1: / Line 1: @@
+{{important|1=Do not transclude this template directly! Use {{tl|Signpost filler poll}} instead; for documentation see [[Wikipedia:Wikipedia_Signpost/Newsroom/Style#More on layout|our style guidelines]].}}
-== Setting up a poll ==
+{{Lua|Module:Signpost poll}}
+== Parameters ==
 This template is a proposal for an in-wiki polling apparatus for weekly use by the ''Signpost''. The parameters are as follows:
@@ Line 5: / Line 8: @@
 {{Wikipedia:Wikipedia Signpost/Templates/Voter
 | image = <!-- An image for the top-right corner of the sidebar; defaults to the Signpost logo. -->
-| question = <!-- Title of the poll. -->
+| question = <!-- Question under consideration in the poll. -->
-| option_one = <!-- Name of the first option, as reported in the legend and in the vote button. Defaults to the test poll. -->
+| option1 = <!-- Name of the first option, as reported in the legend and in the vote button. Defaults to the test poll. -->
-| option_one_color = <!-- Color of the first option choice; defaults to #006699, Foundation blue. -->
+| option1color = <!-- Color of the first option choice; defaults to #006699, Foundation blue. -->
-| option_one_vote_collection_page = <!-- Where the votes for option one will be collected. Defaults to the test poll. -->
+| option2 = <!-- Name of the second option, as reported in the legend and in the vote button. Defaults to the test poll. -->
-| option_two = <!-- Name of the second option, as reported in the legend and in the vote button. Defaults to the test poll. -->
+| option2color = <!-- Color of the first option choice; defaults to #339966, Foundation green. -->
-| option_two_color = <!-- Color of the first option choice; defaults to #339966, Foundation green. -->
+| option3 = <!-- Optional. Where the votes for option two will be collected. Defaults to the test poll. -->
-| option_two_vote_collection_page = <!-- Where the votes for option two will be collected. Defaults to the test poll. -->
+| option3color = <!-- Color of the first option choice; defaults to #990000, Foundation red. -->
+| votepage = <!-- The page at which all of the votes will be accrued. -->
+| min_votes = <!-- The minimum number of votes that must accrue before the template begins to display results. Defaults to 10. -->
 | break = <!-- If this parameter is non-empty the votebar is split into two to better accommodate lengthier poll options. -->
+| overlay = <!-- overlay image; defaults to File:Foundation Logo Transparent.svg. -->
+| expiry = <!-- The number of days after which the poll is closed; defaults to 14 days. -->
 }}
 </pre>
+* '''question''': Question under consideration in the poll. (required)
-Setting up a poll requires ''at least'' two additional pages be created: one for collecting <code>option_one</code> votes and the other for collecting <code>option_two</code> votes, the pages in question in parameters <code>option_one_vote_collection_page</code> and <code>option_two_vote_collection_page</code>.
+* '''votepage''': Page that the votes will be stored on (required). If in doubt, choose <code>''poll location''/Votes</code>.
+* '''option1''': Name of the first option, as reported in the legend and in the vote button. Defaults to <code>Yes</code>.
-To simplify the process a tool-assisted procedure has been created for this purpose, as follows:
+* '''option1color''' = Color of the first option choice; defaults to {{legend inline|#006699}}, Foundation blue.
+* '''option2''': Name of the second options, as reported in the legend and in the vote button. Defaults to <code>No</code>.
-# First of all come up with a succinct title for your poll. For instance if your poll question is "Jimbo Wales: yay or nay?", you might want to title your poll "Jimbo Wales". If it is instead the example question used here, "Do you believe that pending changes are the future when it comes to Wikipedia version control?", you could title it "Pending Changes".
+* '''option2color''': Color of the second option choice; defaults to {{legend inline|#339966}}, Foundation green.
-# Second, think of what your poll options should be. Which one should go first? Which one should go second? In the case of simple Yes/No polls, that orientation is standard, but otherwise the choice is yours.
+* '''option3''': Optional. Name of the third options, as reported in the legend and in the vote button. No default.
-# To create the <code>option_one_vote_collection_page</code>, type the name of the page you are creating into the box below, replacing <code>{POLL TITLE}</code> with your poll title from step one and <code>{OPTION_ONE}</code> with the name of your first vote option from question two, and follow the instruction displayed once you hit the "Create" button. You may want to open this page in a second tab as hitting the button will take you away from this page.<br/><inputbox>
+* '''option3color''': Optional. Color of the third option choice; defaults to {{legend inline|#990000}}, Foundation red (if the third option is enabled at all).
-type=create
+* '''minimum''': Minimum number of votes that must accrue before the poll will display the visualization; before this many votes are made the poll will tell readers that X more votes are needed based on the size of the deficit. Defaults to 10.
-break=no
+* '''break''': Set to "yes" to break columns between the buttons to allow longer button names. If this is not set, the template will try and auto-detect a sensible value.
-width=100
+* '''expiry''': The number of days after which the poll is closed; defaults to 14 days (two publication cycles). Note that is this defined from the day that you create the template ''not'' from the day that you actually publish the article!
-default=Wikipedia:Wikipedia Signpost/Templates/Voter/Issues/{POLL TITLE}/{OPTION_ONE}
+* '''header''': Text that goes in the poll header. The default is "''Signpost'' poll".
-buttonlabel=Create option one vote gathering page
+* '''icon''': Changes the image that is displayed in the top-right corner of the poll. As used in the ''Signpost'' other images are not recommended.
-editintro=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Counter EditIntro
+* '''overlay''': Overlay on the stacked bar chart which produces the template's fancy visualization. By default this is [[:File:Foundation Logo Transparent.svg]], a transparent version of the Wikimedia Foundation's logo. With some basic vector editing skills such images are easy to make; requirements for a working overlay are:
-preload=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Counter Preload
+**Square image; the transparent Foundation logo is a vector <code>SVG</code> with native resolution of <code>1050x1050</code>.
-</inputbox>
+**Canvas whitespace; The bar chart is not displayed wherever the image canvas is explicitly white.
-# To create the <code>option_two_vote_collection_page</code>, follow the same procedure but with reference to your second poll option this time:<br/><inputbox>
+**Transparent logo; this is where the chart ''will'' be displayed.
-type=create
-break=no
-width=100
-default=Wikipedia:Wikipedia Signpost/Templates/Voter/Issues/{POLL TITLE}/{OPTION_TWO}
-buttonlabel=Create option two vote gathering page
-editintro=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Counter EditIntro
-preload=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Counter Preload
-</inputbox>
-# '''Non-step''': The templates will automatically configure the page for the text that will be preloaded into users' input when they vote. For instance, if I am a reader voting in the poll and I hit the <code>Yes</code> vote button, I naturally expect a corresponding text input to be created for me to save. In order to reduce the workload on pollsters and to reduce the amount of subpages that uses of the poll template will generate, this text input has been reduced to a simple reused string: <code>Voting for option 1.</code>, <code>Voting for option 2.</code>, and so on. <!-- http://en.wikipedia.org/w/{PAGE_LINK}?action=edit&section=new&nosummary=true&preload=User:Resident_Mario/Voter/Setup/Preload2&preloadparams%5b%5d={VOTE_VALUE} -->
-# Finally it is time to set up a page for the poll itself. To do so use the following input to create the template, preferably at the same {POLL_TITLE} you used in steps 3 and 4:<br/><inputbox>
-type=create
-break=no
-width=100
-default=Wikipedia:Wikipedia Signpost/Templates/Voter/Issues/{POLL TITLE}
-buttonlabel=Create poll template
-editintro=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Poll EditIntro
-preload=Wikipedia:Wikipedia Signpost/Templates/Voter/Setup/Poll Preload
-</inputbox>
-# '''Optional''': Try voting to make sure that everything works!
-Once all of this done, no further action is required: the templates handles vote counting, inputting, and display automatically.
-== How? ==
+== Test cases ==
+For test-cases see [[Wikipedia:Wikipedia Signpost/Templates/Voter/testcases|here]].
-From a technical perspective this is made possible through two key technical <s>uses</s> abuses:
-* The use of a Lua script to track the number of times a specific string has been inputted into a page: credit on this front to [[User:Mr. Stradivarius|Mr. Stradivarius]].
-* The use of a <code>CommentTitle</code> input box and preloaded text to present the user with ready-made input that only needs to be saved in an aesthetically appealing way.
-Other technical invocations:
-* The use of parser functions to turn vote numbers into percentages, and from there into a stacked bar chart.
-* The use of absolute positioning and image transparency to overlay a visually appealing graphic onto said chart.
-* The use of absolute positioning to quietly hide the section title bar included in the <code>CommentTitle</code> input form (admit it; until you read this you didn't realize it was missing, did you?).
+{{clear}}
-== To do ==
-* <s>Add built-ins and preloads for semi-automating the poll setup procedures, particularly when it comes to vote counting.</s>
-* <s>Add a capacity to return to the previous page after voting.</s>
-* Rigorous testing and bug-fixing.
-* Add a capacity for closing the poll after a certain amount of time has elapsed.
-* Add a capacity for not visualizing poll results until a certain minimum number of votes have accrued.
-* Add a capacity for a third and maybe fourth polling option.