Other macros - The MDN project 编辑

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.
• 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: {{RFC(number)}}. For example, {{RFC(2616)}} becomes RFC 2616.

Landing page components

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

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.

Quicklinks

We have some macros specifically designed to create quicklinks:

• The MakeSimpleQuicklinks macro creates a flat list of links in the quicklinks box. 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.
• 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:

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

Example with heading

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

Result:

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

Creating new 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("/wiki/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.
• LXRSearch can be used to create an LXR search URL.

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 boxstyle in the Editor toolbar.
• warning inserts a specially-formatted "warning" block. WarningStart and WarningEnd define the start and end of warning block that needs to contain other macro calls .Replacement: Use the Warning boxstyle 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. 
• 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.