Commonly-used macros

Cette page présente un grand nombre de macros à usage général créées pour une utilisation avec MDN. Pour avoir des informations sur l'utilisation de ces macros, voir Utilisation des macros et Utiliser les liens macros . Voir les autres macros pour avoir des informations sur les macros qui sont rarement utilisées, ou utilisées dans des contextes spécifiques, ou obsolètes. Il y a aussi une liste complète de toutes les macros MDN.

Voir aussi le Guide style CSS pour l'utilisation des styles disponibles.

Linking

Création d'un lien hypertexte unique

En général, vous ne devez pas utiliser des macros pour créer des liens arbitraires. Utilisez le Lien dans l'interface de l'éditeur pour créer des liens.

• La macro Glossary crée un lien vers une entrée du glossaire MDN. Cette macro accepte un paramètre obligatoire et deux optionnels:
  1. Le nom d'un terme (comme "HTML").
  2. Le texte à afficher dans l'article au lieu du nom du terme (ce qui devrait être rarement utilisé). Facultatif
  3. Si ce paramètre est spécifié et est non nul, le style personnalisé normalement appliqué aux liens glossaire n'est pas appliquée. Facultatif

  Examples:

  • {{Glossary("HTML")}} yields HTML
  • {{Glossary("CSS", "Cascading Style Sheets")}} yields Cascading Style Sheets
  • {{Glossary("HTML", "", 1)}} yields HTML

Liens vers des pages avec références

Il existe différentes macros pour des liens vers des pages dans les zones de référence spécifiques MDN.

• cssxref links to a page in the CSS Reference. Example: {{cssxref("cursor")}}, results in: cursor.
• domxref links to pages in the DOM reference; if you include parentheses at the end, the template knows to display the link to look like a function name. For example, {{domxref("document.getElementsByName()")}} results in document.getElementsByName() while {{domxref("Node")}} results in Node.
• event links to pages in the DOM Event reference, for example: {{event("change")}} results in change.
• HTMLElement links to an HTML element in the HTML Reference.
• htmlattrxref links to an HTML attribute, either a global attribute description if you only specify the attribute name or an attribute associated with a specific element if you specify an attribute name and an element name. For example, {{htmlattrxref("lang")}} will create this link: lang.  {{htmlattrxref("type","input")}} will create this link: type.
• jsxref links to a page in the JavaScript Reference.
• SVGAttr links to a specific SVG attribute. For example, {{SVGAttr("d")}} creates this link: d.
• SVGElement links to an SVG element in the SVG Reference.

Liens vers des bugs et des IRC

• Bugs
  • bug allows you to link to a bug on bugzilla.mozilla.org easily using this syntax: {{Bug(123456)}}. This gives you: bug 123456.
  • WebkitBug inserts a link to a bug in the WebKit bug database. For example, {{WebkitBug(31277)}} inserts WebKit bug 31277.
• IRCLink inserts a link to the specified IRC channel, complete with a tooltip that says that's what it does and that an IRC client is needed.

Aides à la navigation pour les guides multi-pages

Previous, Next, and PreviousNext provide navigation controls for articles which are part of sequences. For the single-way templates, the only parameter needed is the wiki location of the previous or next article in the sequence. For PreviousNext, the two parameters needed are the wiki locations of the appropriate articles. The first parameter is for the previous article and the second is for the next article.

Exemples de code

Live samples

• EmbedLiveSample lets you embed the output of a code sample on a page, as described in Live samples.
• LiveSampleLink creates a link to a page containing the output of a code sample on a page, as described in Live samples.

Fichiers exemples attachés

• Embed_text template lets you embed an attached text file into the body of your article. This is helpful if you want to have code snippets that are both downloadable but also displayed within the article's content. You may optionally specify a language for syntax highlighting; if you don't specify one, the text is embedded unformatted. The first parameter is the filename of the attachment to embed; the second, if provided, is the language for the syntax highlighter to apply, such as "javascript", "svg", or "cpp".
• EmbedSVG embeds an attached XML file as an SVG image, in place on the page. Specify the filename of the attached SVG file. You can use this in tandem with Embed_text to show the source and then the rendered output of the same file.

Génération de sidebar (barre latérale)

Modèles pour presque toutes les grandes collection de pages. Ils permettent généralement de revenir à la page principale de référence/Guide/tutoriel et de mettre l'article dans la catégorie appropriée.

• CSSRef generates the sidebar for CSS reference pages.
• HTMLRef generates the sidebar for HTML reference pages.
• APIRef generates the sidebar for Web API reference pages.

La mise en forme à usage général

Inline indicators for API documentation

optional_inline and ReadOnlyInline are used in API documentation, usually when describing the list of properties of an object or parameters of a function.

Usage: {{optional_inline()}} or {{ReadOnlyInline()}}. Example:

isCustomObject Lecture seule

Indicates, if true, that the object is a custom one.

parameterX Facultatif

Blah blah blah...

Noting why a page has no specification table

Most Web documentation pages have specification tables to indicate where the API is specified. However, some API terms do not have specifications for some reason; perhaps the API predates formal specifications, or the API is browser-specific and thus has no specification.

Regardless, it's important that we be able to indicate when this is the case, so we place explanatory text in lieu of the table. In order to help tools understand this is going on, you need to wrap that text using the WhyNoSpecStart and WhyNoSpecEnd macros, like this:

{{WhyNoSpecStart}}Not part of any specification; this API is Firefox OS specific.

These macros are just a guide for automated tools and have no visible effect on rendered content.

Status and compatibility indicators

Inline indicators with no additional parameters

Non-standard

non-standard_inline inserts an in-line mark indicating the API has not been standardized and is not on a standards track.

Syntax

{{non-standard_inline}}

Examples

• Icon:

Experimental

experimental_inline inserts an in-line mark indicating the API is not widely implemented and may change in the future.

Syntax

{{experimental_inline}}

Examples

• Icon:

Inline indicators that support specifying the technology

In these macros the parameter (when specified) should be one of the strings "html", "js", "css", or "gecko", followed by the version number.

Deprecated

deprecated_inline inserts an in-line deprecated mark to discourage the use of an API that is officially deprecated. Note: "Deprecated" means that the item should no longer be used, but still functions. If you mean that it no longer works at all, use the term "obsolete."

Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Syntax

{{deprecated_inline}} or {{deprecated_inline("gecko5")}}

Examples

• Icon:
• Badge: Obsolète depuis Gecko 5

Obsolete

obsolete_inline inserts an in-line obsolete mark to prevent the use of, for example, a function, method or property which is officially obsolete. {{ js_obsolete_inline("1.8.5") }} is equivalent to {{ obsolete_inline("js1.8.5") }}. Same is true for js_obsolete_header.

Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Syntax

{{obsolete_inline}} or {{obsolete_inline("js1.8.5")}}

Examples

• Icon:
• Badge: Obsolète depuis JavaScript 1.8.5

Template badges

These macros are mostly used on the WebAPI page. See Creating new badges for information on creating a new badge.

Privileged

PrivilegedBadge is used in Firefox OS documentation to indicate Privileged APIs.

Syntax

{{PrivilegedBadge}}

Example

Avec privilèges

Page or section header indicators

These templates have the same semantics as their inline counterparts described above. The templates should be placed directly underneath the main page title (or breadcrumb navigation if available) in the reference page. They can also be used to mark up a section on a page.

• non-standard_header: {{Non-standard_header()}}

  Non standard
  Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

• SeeCompatTable should be used on pages that provide a "Browser compatibility" section. Example: {{SeeCompatTable()}}

  Cette fonction est expérimentale
  Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
  Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

• deprecated_header: {{deprecated_header()}}

  Obsolète
  Cette fonctionnalité a été supprimée des standards du Web. Bien que quelques navigateurs puissent encore la supporter, elle est en cours d'éradication. Ne l'utilisez ni dans d'anciens projets, ni dans de nouveaux. Les pages et applications Web l'utilisant peuvent cesser de fonctionner à tout moment.

• deprecated_header with parameter: {{deprecated_header("gecko5")}}

  Obsolète depuis Gecko 5 (Firefox 5 / Thunderbird 5 / SeaMonkey 2.2)
  Cette fonctionnalité a été supprimée des standards du Web. Bien que quelques navigateurs puissent encore la supporter, elle est en cours d'éradication. Ne l'utilisez ni dans d'anciens projets, ni dans de nouveaux. Les pages et applications Web l'utilisant peuvent cesser de fonctionner à tout moment.

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).
• obsolete_header: {{obsolete_header()}}

  Obsolète
  Cette fonctionnalité est obsolète. Bien qu'encore supportée par des navigateurs, son utilisation est découragée pour tout nouveau projet. Évitez de l'utiliser.

• obsolete_header with parameter: {{obsolete_header("gecko30")}}

  Obsolète depuis Gecko 30 (Firefox 30 / Thunderbird 30 / SeaMonkey 2.27 / Firefox OS 1.4)
  Cette fonctionnalité est obsolète. Bien qu'encore supportée par des navigateurs, son utilisation est découragée pour tout nouveau projet. Évitez de l'utiliser.

  Don't use the parameter in any browser-agnostic area (HTML, APIs, JS, CSS, …).

Indicating that a feature is available in web workers

The AvailableInWorkers macro inserts a localised note box indicating that a feature is available in a Web worker context.

Version information macros

These macros are used to indicate that content is relevant only to specific versions of a product.

• gecko_minversion_inline: For example: Nécessite Gecko 100.9
• fx_minversion_inline: For example: Firefox 100.9

These macros are not shown when the specified version is lower than current gecko release.

• gecko_minversion_inline(9.9):
• fx_minversion_inline(9.9):

Macros used on special pages

Download buttons

DownloadButton inserts a green "Download" button into the page. It accepts two parameters:

1. The URL of the destination link
2. The text for the button itself

For example, {{DownloadButton("https://nightly.mozilla.org/", "Download Nightly")}} results in: Download Nightly

FirefoxChannelLink inserts a link to download a specific Firefox channel. The link can be either textual or the channel's icon. The idea behind this macro is that it provides an easy way to link to download Firefox without having to deal with potentially changing "best sources" for these downloads, and lets you use icon buttons without worrying about the icon changing. We can just update the macro and all places using the icons will be updated.

It accepts these parameters:

1. The name of the channel. This is a case-insensitive string, and must be one of "nightly", "aurora", "beta", or "release" (the last one can also be "firefox").
2. The icon size, in pixels. The width of the icon will be set to this, with the height horizontally adjusted to match. If this is zero, the link will be presented as a textual link instead.
3. The text for the link. You can leave this parameter out if you specify an icon size, thereby asking for your link to be an icon.

For example, {{FirefoxChannelLink("aurora", 96)}} results in:

And {{FirefoxChannelLink("beta", 0, "Download Firefox Beta")}} results in: Download Firefox Beta