User:Xover/Template guidelines

Draft.

User:Inductiveload comments in green.

User:CalendulaAsteraceae comments in orange.

Guidelines for templates with a goal of making them consistent, intuitive, and robust.

Calling conventions

• All templates should use a consistent calling convention so that users don't have to look up every little detail every time they're used
• Block (start—stop) templates should all use either one of /s+/e, /begin+/end, {{mytemplate start}}, or {{mytemplate begin}}; or possibly all of them should support all modes.
  • Also /m for "mid" templates like {{hi/m}}
  • Less work in the long run to pick one convention and redirect existing uses but not require four redirects for every block template. I like the /s + /e + /m convention.
• Block templates should never rely on generic {{div end}}, even if the end template is just a redirect to it
• Block-model templates should prefer start+stop calling and actively discourage 1= calling
• Templates that support both start+stop and 1= calling should use redirects and docs to present itself as multiple templates
  • Having trouble interpreting this one. If a template had {{mytemplate/s}} and {{mytemplate/e}} and then {{mytemplate}} used them like below, would that be what you want?

    {{mytemplate/s}}
    {{{1|}}}
    {{mytemplate/e}}
    

    • Yup, that's it. Keep the two in sync and reduce maintenance. For a lot of block-modelled templates /s+/e should really be the default, but the logic currently lives in the 1= variant, meaning /s has to be kept manually in sync (which means a lot of them are not currently in sync).
    • Oh, and we can do div/span tricks here: if we're called without a {{{1}}} we're in /s+/e mode, if there is a {{{1}}} we're being called inline. Things like {{italic block}} doesn't need to be a separate template, just a "polymorphic" one.
• The calling model should tell you whether you get a div (block) or a span (inline) HTML element
• Inline templates should use inline elements (e.g. span) and actively discourage use on a block of content
• Inline and block-based templates should exist in concert, so if you need fine text you look at docs for fine text and it tells you about the inline and block variants and explains when to use both; and both should of course have consistent parameters and behaviour where there isn't an inherent reason to diverge

Block based templates should always start and end with a newline between the container tags and the content

• This is because otherwise the MediaWiki parser's p-wrapping will produce wildly inconsistent results. Note this is, I think, phab:T134469

Inline based templates should never emit any newlines that weren't fed into it

• This is because if it is used in a context where newlines matter it will be impossible for the user to compensate, but without it there are any number of ways they can add it if they need it

All templates should have documentation (/doc) and use {{documentation}}

Related templates should be connected together through navboxes

A core set of templates everyone should know and prefer should exist

• These should have a well-written Help: page that we actively maintain
• These could beneficially have their CSS in common.css or a default gadget
  • Could they? TemplateStyles is de-duplicated and stripped. Also core CSS needs replicating to Mediawiki:Epub.css, TS does not. Downside: TS CSS is repeated in every section of an EPUB.
    • Could, not should. There are some things that are hard to do in TS, and there are some things that it would be convenient to use global CSS to keep in sync (and for standardisation). We still don't want global CSS as a rule of thumb, but this is to say it's an option in special cases. We just need to design it properly if and when we do so.
  • All other templates can still use TemplateStyles of course
  • Core templates by definition are so much used that making everyone load them on all pages is reasonable
  • Core templates are also so stable that needing an interface admin to edit them is reasonable

We should document common problems and their solutions

• Particularly p-wrapping
• Particularly the need for escaping inside 1= templates (which we should have much fewer of)

We need to actively curate template documentation to have it a little more standard

We should also more actively (and support with helper templates) document use of Lua modules, TemplateStyles, and div vs. span, and redirects (aliases)

Tracking categories are a thing and we should use lots of them

• But be clear on whether they track something we don't want or just track something to track it

We should encourage use of core helper templates and modules like namespace detect and category handler (and module arguments, yesno, and no globals; coding conventions essentially)