Other macros

In contrast to the macros listed in Commonly-used macros, the macros documented in this article are used infrequently or only in specific contexts, or are deprecated.

Special contexts

These macros are used only with particular contexts, such as a specific API reference.

• jsapixref links to a page in the JSAPI Reference.
• XPCOMxref links to a page in the XPCOM reference. You can specify the name of an XPCOM function, class, component, or interface (although for the latter, you should use Interface instead). This macro will find the page and create a link to it, wherever it is in the XPCOM reference subtree.
• npapi links to the Gecko Plugin API Reference.
• interface can be used when linking to XPCOM interfaces.
  Example: {{interface("nsIIOService")}} results in: nsIIOService.
• interface-method can be used to link to a method of a Mozilla interface in case the target interface is documented according to the current guidelines.
  Example: {{interface-method("nsIFeedResult", "registerExtensionPrefix")}} results in: nsIFeedResult.registerExtensionPrefix(). You can also use interfacemethod which does the same thing.
• ifmethod and ifattribute let you create a link to a particular method or attribute (respectively) on a Mozilla interface that's been created using our standard format for interface documentation. For example, {{ifmethod("nsIAutoCompleteSearch","stopSearch")}} shows up as nsIAutoCompleteSearch.stopSearch(). Note that for ifattribute, id="..." must be added explicitly in the target, since attributes do not have headings.
• Interwiki makes it easy to create interwiki links. Currently it supports linking to Wikipedia and Wikimo. The first parameter is the name of the wiki ("wikipedia" or "wikimo"), and the second is the path of the article. For example, {{interwiki("wikipedia", "Firefox")}} shows up as Firefox. This template auto-detects the page language and directs to the same language on Wikipedia, for example.
• RFC creates a link to the specified RFC, given its number. The syntax is simply: {{RFC(number)}}. For example, {{RFC(2616)}} becomes RFC 2616.

XPCOM Interface reference summaries

Every article in the XPCOM interface reference should start with the interface summary block, which is created using IFSummary. This creates a uniform, standard format block at the top of the page with basic information about the interface. The template accepts up to 7 parameters, but requires only the first four. The parameters are, in order:

Path of the IDL file defining the interface

This is used to create a link to the interface's IDL on MXR so the reader can refer to it if they wish.

Parent interface

This is the name of the interface upon which the interface being document is based. This will be turned into a link to that interface in the interface reference and displayed.

scriptable/not scriptable

A string indicating whether the interface is scriptable or not. You must use either "scriptable" or "not scriptable" (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.

Last changed in what Gecko version

This is a string indicating the version of Gecko in which the interface was last changed. Should be a string in standard Gecko version format, such as "1.9" or "1.9.2" or even "1.9.1.6".

Summary Optional

A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus template (which now calls through to this one). You should always provide this.

Version introduced Optional

If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline showing the availability of the interface in contrast to the history of Gecko, in graphical format.

Version deprecated Optional

If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.

Version obsoleted Optional

Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.

Examples:

{{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9", "Provides assorted network utility functions, as well as functions to parse URLs.", "1.1", "1.8.1", "1.9.2")}}

{{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9", "Provides assorted network utility functions, as well as functions to parse URLs.", "1.1")}}

{{IFSummary("netwerk/base/public/nsIIOService.idl", "nsISupports", "scriptable", "1.9.1")}}

If your summary is more complex and needs to include non-plaintext content, you can use IFSummaryStart and IFSummaryEnd to bracket your summary content.

Landing page components

We have an assortment of macros that can be used to automatically generate the contents of landing pages. Here they are.

Article lists divided by topic

We have an advanced macro that generates a menu of subpages, divided up into groups by topic area; this macro is called SubpageMenuByCategories, and it accepts as input a JSON array of tags and section names that correspond to those tags. Given that information, it pulls all subpages of the page on which the macro was invoked and produces a list of those pages, sorted into subheadings of the specified names, with each section's contents selected by the tags found on the articles.

Sections are listed in the order in which they're specified, and within each section, articles are sorted alphabetically.

Articles with the tag "Featured" are presented in special boxes at the top of the list; you should try to avoid having more than three of these.

The JSON input looks like this, for example:

{{SubpageMenuByCategories('[{"tag": "Overview", "name": "Overviews"}, {"tag": "Guide", "name": "Guides"}, {"tag": "Example", "name": "Sample code"}]')}}

This will split up the output among the headings "Overviews" (items found with the tag "Overview", "Guides" (items with the tag "Guide"), and "Sample code" (items with the tag "Example").

Community information boxes

Each top-level landing page, and some others, should have information about how to contact community related to that topic. The CommunityBox macro creates this for you. Its syntax:

{{CommunityBox(communityName, mailingListName, newsgroupName, ircChannelName, extraLinksString)}}

The IRC channel name and extra links string parameters are both optional.

The extra links string is a specially-formatted string for specifying the additional links that appear in the right-hand column of the box, below the IRC channel information. Its format:

heading|url|text|description||heading|url|text|description...

You may specify as many additional links as you need to (although you should try to keep this down to a scant handful, to avoid making the box unwieldy).

For example:

{{CommunityBox("UberSuperTech", "dev-ubersupertech", "dev.tech.ubersuper", "devmo", "MDN|https://developer.mozilla.org/|The MDN web site|Visit the Mozilla Developer Network||Mozilla|https://www.mozilla.org/|Mozilla's web site")}}

Lists of subpages

• ListSubpages generates an unordered list of links to all the immediate children of the current page; useful for automatically generating tables of contents for sets of documentation.
• LandingPageListSubpages outputs a two-column definition list of all immediate subpages of the current page, with their titles as the <dt> and their SEO summary as the <dd>. This makes it easy to automatically generate reasonably attractive landing pages.
• NavListWithPrioritizedPages generates an ordered list formatted properly for use in a zone navigation sidebar (or quicklinks). As input, you can specify zero or more page slugs that should be pulled out of the main list and instead inserted at the top of the list, in the given order. All remaining pages are placed in the list alphabetically. One level of subpages is included.
• APIListAlpha builds a list of the current page's subpages, formatted as a list of API terms, divided up by first letter. There are three parameters. The first is 0 if you want to include all top-level subpages or 1 to leave out subpages with "." in their names. The second and third let you add text to display as part of the name in each link. This can be used to add "<" and ">" for element links, or to add "()" at the end of lists of method names.
• SubpagesWithSummaries constructs a definition list of all the immediate children of the current page. There is no other formatting done. You can get a two-column list ready for use as a multi-column landing page using LandingPageListSubpages.
• SubpagesWithTags constructs a two-column definition list of all subpages (down several levels) of the specified page which also have one or more of the specified tags.

  Syntax:

  {{SubpagesWithTags(rootPage, tagList)}}

  rootPage

  The path of the page whose children are to be scanned. This may be omitted or null to default to the current page.

  tagList

  A comma-delineated string listing the tags that to match against. Any pages under rootPage which has one or more of these tags will be included in the resulting list. For example, "build, introduction" will include in the list any pages tagged either "build" or "introduction". Pages which also have the tag "Important" get sorted to the top of the list (sorted alphabetically relative to other such tagged pages).

• NeedsReviewWithTags. This template produces a list of articles for which the specified review flag is set. You may specify zero or one review types, as well as an optional list of tags to match against, and a Boolean value indicating whether or not to look across all locales or just the user's current locale.

  Syntax:

  {{NeedsReviewWithTags(reviewtype, tagList, allLocales)}}

  reviewtype

  One of "editorial", "technical", or "kumascript". This can also be an empty string if you want all review types to be included.

  tagList Optional

  If present, this is a comma-delineated string listing the tags that must match before an article will be included in the resulting list. For example, "Mobile,Non-standard" will only include articles tagged with both "Mobile" and "Non-standard". You may omit this parameter, or provide an empty string, to match all pages. Pages which also have the tag "Important" get sorted to the top of the list (kept alphabetically amongst each other).

  allLocales Optional

  If present, this is an integer value; if 0, only the user's current locale is included in the list. If this has any other value, all locales are included in the output.

Quicklinks

We have some macros specifically designed to create quicklinks:

• The MakeSimpleQuicklinks macro creates a flat list of links in the quicklinks box. Simply give it a set of paths to destination pages as its input arguments. Each link's text is the page title, and each link has a tooltip derived from the page summary.
• QuickLinksWithSubpages creates a set of quicklinks comprised of the pages below the current page (or specified page, if one is given). Up to two total levels of depth are generated.

Infrequently used

• outdated can be used to flag pages that are known to be (or might be) horribly outdated. The template is followed by an optional parameter, which can be used to provide details. For example: {{outdated("It was last updated in 1999.")}} gives you this:

  Warning: The content of this article may be out of date. It was last updated in 1999.

• disambig is used on the few disambiguation pages we have. Do not use this macro on Glossary disambiguation pages; use the GlossaryDisambiguation macro instead.
• block-title can be used to create bolded text which visually serves as a title for a block in a page, does not appear in the auto-generated table of contents, and can act as a link target just as headings do. The syntax is: {{block-title(title)}}, where title is whatever you want displayed. title also serves as the target for links to the section you are titling. block-title is meant for use in titling Template:sidenotes, tables, images, and code blocks, particularly in places where you'll be referring to the item more than once or in places not close to the item itself.
• ref and endnote can be used to implement footnotes to articles. The footnote "number" is created using {{ref("something")}}, where something should be some suitably descriptive word for whatever is being mentioned in the footnote. Then, at the end of the document, insert  {{endnote("something")}} Blah blah, text for first footnote to create a numbered list for the footnotes' information.
• OptimizeImagesNote macro returns text that explains that we encourage the use of image optimization software to improve page load times on MDN by making image files load as fast as possible, along with a link or links to tools we recommend for the purpose. Since image uploads are discussed in several places, this macro lets us quickly update all of the places that do so at once.  By default, this macro returns HTML for a standard Note box. Specifying a non-zero parameter (such as {{OptimizeImagesNote(1)}}), you can get back just the text suitable for use in a paragraph.
• ReleaseChannelInfo is used to create the standard header at the top of "Firefox X for developers" pages for a given channel; it takes four parameters: the Firefox version, the Gecko version, a string indicating an expected release date, and the name of the channel on which the release can currently be downloaded.
• InsertFeedLinkList outputs a list of links from an RSS feed. Its parameters configure the output significantly:
  • Feed URL
  • Maximum number of entries to include in the output
  • The heading level to use for the name of the feed, or 0 to leave that heading out
  • Class name to use when building the list; this will be applied to the <ul> element.
  • List type; this is an integer value. 0 produces a simple bullet list, while 1 outputs a header for the page title followed by a paragraph with a byline in it.
  • The heading level to use for the items in the list when using list type 1.

Transclusion

Transclusion is the embedding of part or all of one page into another. Exercise caution when using this macro, to ensure that the transcluded content makes sense in the context of the page it is embedded into.

Page lets you embed some or all of a specific page into a document. It accepts five parameters:

1. The URI of the page to transclude. For example, "/en-US/docs/Project:MDN/About".
2. The name of the section within the page to transclude. This can be specified either as the title string or as the ID of a block to copy over. If not specified, the entire article is transcluded. Optional
3. The revision number of the page version to transclude. This feature is not currently implemented, but would allow including text from specific versions of an article. Unimplemented
4. A Boolean value indicating whether or not to show the heading of the top-level section being transcluded. This is useful if you wish to specify your own heading. The default value is false, meaning the heading is not included by default. Optional
5. The heading level to use as the top heading level. This adjusts the outermost first-discovered level of the transcluded content to the specified number, and all other headings correspondingly. This lets you include content that has its own headings but adjust them to match the heading level at which you're including them. If you don't specify this value, the headings are not adjusted. Unimplemented

Example without heading

{{Page("/en-US/docs/MDN/About", "About Mozilla")}}

Result:

Whether you want to learn more about who we are, how to be a part of Mozilla or just where to find us, you've come to the right place. To find out what drives us and makes us different, please visit our mission page.

Example with heading

{{Page("/en-US/docs/MDN/About", "About Mozilla", 0, 1)}}

Result:

About Mozilla

Whether you want to learn more about who we are, how to be a part of Mozilla or just where to find us, you've come to the right place. To find out what drives us and makes us different, please visit our mission page.

Creating new badges

Icon badges

We have the ability to create attractive icon-based badges to flag compatibility issues. This is done using IconBadge, which accepts five parameters:

1. The text to display in the badge next to the icon.
2. Class name for the background in the circle containing the icon. This background should include the icon to display.
3. Class name for the background in the text area of the badge.
4. Tooltip text. The tooltip doesn't currently draw but will eventually. Optional

For example:

{{IconBadge("Privileged", "privilegedBadge", "Only available to certified apps on Firefox OS.")}}

Results in: Privileged

Other badges

We also have badges that don't have icon bubbles. The generic template for this is SimpleBadge, which accepts three parameters:

1. Text to display in the badge.
2. Name of a CSS class to use as the background for the badge.
3. (Optional) Text to display in a tooltip when hovering over the badge.

Deprecated

These macros have been replace by other ways of doing the same thing, and should no longer be used. If you find them in existing articles, please replace them.

Linking

• The anch macro inserts a link to an anchor. {{Anch("top")}} produces <a href="#top">top</a> (top). You can also add a second parameter which contains replacement text to display as the link text. {{anch("Other badges", "you can use other badges")}} produces this result: you can use other badges. The idea was to create a template that allows easy linking to other sections in a document. Replacement: Use the Anchor toolbar button in the Editor interface. This isn't really a "replacement" and there's some discussion about whether this is truly deprecated at this time.
• The SectionOnPage macro creates a phrase that links to both the name of a section and the article containing that section. For example, {{SectionOnPage("/en-US/docs/Mozilla/Firefox/Releases/21", "Changes for Web developers")}} outputs the following: "Changes for Web developers" in Firefox 21 for developers.
• The manch inserts a link to a method within the current interface; this is intended only for use in interface documentation pages. {{manch("foo")}} produces <code><a href="current/path#foo">foo()</a></code> (foo()).
• The Link macro inserts a link to the specified page on MDN, using the page's title as the visible string to click on, and the tooltip picked up from the page's SEO summary.
• The LinkItem macro inserts a link to a specified URL, with the indicated text as the visible string to click on. The link automatically picks up as its tooltip the summary of the target page. This differs from Link in that you must specify the title.
• The LinkItemDL macro inserts a link to a specified URL, with the indicated text as a <dt> which is also the link. The <dd> element contains the specified page's summary.
• funcref creates links to global functions (usually C++) documented on top-level pages. However, such pages are no longer created at the top-level of MDN.
• Pref inserts a link to the entry in the Preference reference for the specified preference.
• spec inserts a link to a specification. Replacement: Use Spec2 or SpecName instead.
• source allows you to link to a Mozilla source code file without having to type a long MXR URL using this syntax: {{Source("browser/Makefile.in")}}. This gives you: browser/Makefile.in. The text of the link is the path provided; if you want different text, then just provide a second parameter, like so: {{Source("browser/Makefile.in", "the browser/ Makefile.in")}}, which produces the browser/ Makefile.in. Note that the link will be to the very latest version of the file in bleeding-edge code.
• Source_cvs works just like source, except it links to the CVS repository instead of the newer mozilla-central one.
• Include inserts an #include "headername.h" reference that links to the specified file in MXR. This is used in pages that want to have a heading at the top of the page telling you how to include the appropriate header file for the interface being described. For example, {{Include("mozilla/CondVar.h")}} results in:

  #include "CondVar.h"

• LXRSearch can be used to create an LXR search URL.

Boilerplate

• SeeDOMInterface inserts a blurb of text explaining that a specified interface implements a given DOM interface. Use this to create simple stub pages for Gecko interfaces that simply implement standard interfaces in the DOM. For example: {{SeeDOMInterface("nsIDOMHTMLFormElement", "HTMLFormElement")}} looks like this: The nsIDOMHTMLFormElement interface implements the DOM HTMLFormElement interface. See that page for details.
• DocPlanHelpUs inserts boilerplate text asking for help with an upcoming or ongoing documentation project, including offering information on how to get involved and where to find basic contribution information.

Code samples

The following macros were used prior to the implementation of the built-in live sample system in Kuma, and should be replaced by uses of EmbedLiveSample or LiveSampleLink.

• LiveSample lets you create a button linking to a sample file; these samples were sent to Eric Shepherd for uploading. These were used on Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.
• CSSLiveSample lets you create a button linking to a sample in the CSS Reference; these samples were sent to Eric Shepherd for uploading. These were used on CSS Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.
• DOMLiveSample lets you create a button linking to a sample in the DOM Reference; these samples were sent to Eric Shepherd for uploading. These were used on DOM Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.
• HTMLLiveSample lets you create a button linking to a sample in the HTML Reference; these samples were sent to Eric Shepherd for uploading. These were used on HTML Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.
• SVGLiveSample lets you create a button linking to a sample in the DOM Reference; these samples were sent to Eric Shepherd for uploading. These were used on SVG Reference pages when linking to live, standalone sample pages. The template accepts one parameter, the name of the HTML file to link to.
• JSFiddleLink lets you easily create a button linking to a sample on the jsFiddle web site. These should NOT be used to replace in-line samples, or MDC-uploaded samples, but to offer access to secondary examples readers can experiment with. The template accepts one parameter, the ID tag of the jsFiddle item to link to.

Organizational

• LockedPage inserts a mark bar across the page that provides an explanation for why a page is locked. This macro is obsolete because Kuma doesn't support locking pages.
• jsapi_ref_header was used to create breadcrumbs for the JSAPI referenced; this is now done by Kuma, not by a macro.

Formatting

• Note inserts a specially-formatted "note" block into the article's text. This is intended to call out an interesting or important fact. Replacement: Use the Note box style in the Editor toolbar.
• warning inserts a specially-formatted "warning" block. WarningStart and WarningEnd define the start and end of warning block that needst to contain other macro calls .Replacement: Use the Warning box style in the Editor toolbar.

Version indicators

The following macros are deprecated because this information should be contained in the Browser Compatibility table of the article.

• gecko_minversion_header indicates the minimum Gecko version for a feature.
• Gecko  inserts the text "Gecko versionnumber" into the text, but adds a tooltip to the text that, when the user hovers over it, displays the corresponding versions of Firefox, Thunderbird, and SeaMonkey.
• fx_minversion_header  and fx_minversion_section indicate the minimum Firefox version for a feature.
• tb_minversion_header, tb_minversion_section, and tb_minversion_inline indicate the minimum Thunderbird version for a feature.
• js_minversion_header and js_minversion_inline indicate the minimum JavaScript version for a feature.
• MobileOnlyHeader inserts an "Available only for mobile Firefox" header box.  MobileOnlyInline inserts a inline indicator. These indicate the version of Gecko as of which the interface is still only available for mobile. 
• PlatformOnlyInline: this aims to replace the MobileOnlyInline with a more generic and therefore more useful one. The one-argument version simple states "Platform only", e.g. Firefox OS Only. The two argument version states a platform and a version number, e.g. Firefox OS 2.0 Only
• dom_level indicates the minimum DOM version for a feature.
• renamed_inline inserts an in-line "renamed" mark to indicate that an API has been renamed.
• unimplemented_inline inserts an in-line "unimplemented" mark to prevent the use of, for example a function, method or property which is not yet implemented. Replacement: Use the Browser Compatibility table to indicate this information.
• unimplemented_inline_webkit inserts an in-line "unimplemented" mark to prevent the use of, for example, a function, method or property which is not yet implemented. Replacement: Use the Browser Compatibility table to indicate this information.
• gecko_callout_heading includes a Gecko version-specific call-out box.
• fx_minversion_note creates a note about a minimum version of Firefox; GeckoMinVersionNoteStart and GeckoMinVersionNoteEnd can be used to wrap text inside a box labeled as pertaining to a given version of Gecko and later; specify the version as the sole parameter to the "start" macro.
• tb_minversion_note creates a note about a minimum version of Thunderbird.
• js_minversion_note creates a note about a minimum version of JavaScript.

• h1_gecko_minversion, h2_gecko_minversion, and h3_gecko_minversion let you insert headers (h1, h2, and h3) that include at the right end of the line a badge indicating the Gecko version (and corresponding app versions) that the section applies to.