Template:Service awards/doc

Basic usage
This template allows users to show service awards. To display it, place on the relevant page where the item in italics is replaced by the relevant value. These parameters are required, and should not be omitted.

The template takes four required parameters:


 * year – Starting year
 * month – Starting month
 * day – Starting day of month
 * edits – Number of user edits

Display format
The format parameter is used to specify the type of template displayed. Most users will want to use one of the standard format values. There are also some special formats that allow you to put together your own custom format.

Custom formats
You can create your own format by combining the name, description and image of an award in any way you like. The format parameter values shown below allow you to fetch these parts of an award on their own. Transclude the template multiple times to fetch multiple elements, arranged how you like.

For example:

Image alignment
Use the align parameter to specify the location of the template. It can only be used with the medal, book, ribbon, ribbon2 and smlribbon formats.

Image size
For the image-with-caption award formats, the size parameter specifies whether to include the frame and caption, and/or change the image size. The frame and caption are shown by default for the image awards, but are omitted for ribbons. Userboxes have a separate frame and caption that the size parameter does not control. The size parameter is ignored for the ribbon format, though it works for the ribbon2 and smlribbon formats.

Small ribbons default to 72 pixels wide; other ribbons default to 120 pixels wide. The image on userboxes defaults to 45 pixels wide. The default width for the image formats depends upon the award.

Some example uses of size=:
 * size=NNpx : Display the image at the specified width, selecting the best height to maintain the image proportions.
 * size=xNNpx : Display the image at the specified height, selecting the best width to maintain the image proportions.

For the topicon format, the size parameter specifies the width of the top icon. Any non-numeric characters are ignored. The height is capped to 20 pixels by the top icon template. The default of 48px results in an image that is 48 pixels wide by 20 pixels tall. Set this to 20px to keep the top icon the same width as a standard 20px×20px top icon.

Caption customisation
The caption on the template can be customised using these parameters. The caption has two auto updating sections: one for the editor's title and one for the editor's award. The three caption parameters specify the text either side of these auto updating sections and the punctuation parameter specifies what punctuation character to use at the end of the caption.

Example:

Gives:

Note: the caption and punctuation parameters will have no effect on the ribbon formats and therefore these parameters should be left out (not blank) if one of these formats is selected.

Technical details
Internally, this template uses the following sub-templates:
 * /compose: Displays an award as described by various parameters.
 * /core: Displays the award for the specified level (0-22) by calling /compose with the appropriate parameters. Edit this template to change the template names or text displayed for each award.
 * /select: Determines which level of award to display, based on the length of service and number of edits. Edit this template to change the award requirements.

Template Data
{	"params": { "edits": { "label": "Edits", "description": "Number of user edits", "example": "2000000", "type": "number", "required": true },		"day": { "label": "Day", "description": "Starting day of the month", "example": "15", "type": "number", "required": true },		"month": { "label": "Month", "description": "Starting month", "example": "1", "type": "number", "required": true },		"year": { "label": "Year", "description": "Starting year", "example": "1995", "type": "number", "required": true },		"size": { "label": "Size", "description": " Size of image (##px, x##px)", "example": "72px", "type": "string" },		"align": { "label": "Align", "description": "Alignment of image (left, center, or right)", "example": "left", "type": "string", "suggestedvalues": [ "left", "center", "right" ]		},		"format": { "label": "Format", "description": "Type of template desired (medal, ubxmedal, book, ubxbook, ribbon, ribbon2, smlribbon, topicon)", "example": "medal", "type": "string", "suggested": true, "suggestedvalues": [ "medal", "ubxmedal", "book", "ubxbook", "book", "ribbon", "ribbon2", "smlribbon", "topicon" ]		},		"caption1": { "label": "Caption 1", "description": "First part of message shown", "example": "This editor is", "type": "string" },		"caption2": { "label": "Caption 2", "description": "Second part of message shown", "example": "and is entitled to display this ", "type": "string" },		"caption3": { "label": "Caption 3", "description": "Third part of message shown", "type": "string" },		"punctuation": { "label": "Punctuation", "description": "Punctuation at end of message", "example": ".", "type": "string" },       "noinc": { "label": "No Incremental Awards", "description": "Incremental awards are not shown where they are available (Topicons)", "type": "boolean" },		"nocat": { "label": "No Categories", "type": "boolean" }	},	"paramOrder": [ "year", "month", "day", "edits", "format", "align", "caption1", "caption2", "caption3", "punctuation", "size", "noinc", "nocat" ],	"description": "Display a Service Award automatically based on editor's starting date and number of edits." }