Live samples - The MDN project 编辑

MDN supports turning sample code displayed in articles into running samples the reader can look at in action. These live samples can include HTML, CSS, and JavaScript in any combination. Note that "live" samples are not interactive; however, they do ensure that the output displayed for a sample matches the code of the sample exactly, because it is actually generated by the code sample.

How does the live sample system work?

The live sample system gathers up all the code in a group, merges it into one HTML file, and then renders that HTML in an <iframe>. A live sample therefore consists of two pieces:

• A group of code blocks
• The macro call that (creates the frame or the link that) displays the result of the code blocks

A "group" of code blocks, in this context, is identified by the ID of a heading or a block element (such as a <div>).

• If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. 
• If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element instead.

The macro uses a special URL to fetch the sample code for a given group, for example https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_samples_/Cylon_Eye. The general structure is https://url-of-page_samples_/group-id, where group-id is the ID of the heading or block where the code is located.

The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community.

Note: You must use the macro for presenting the live sample's output. MDN's editor will strip out any direct use of the <iframe> element in order to ensure security.

Each <pre> block containing code for the sample has a class on it that indicates whether it's HTML, CSS, or JavaScript code; these are "brush: html", "brush: css", and "brush: js". These classes must be on the corresponding blocks of code so that the wiki can use them correctly; fortunately, these are added for you automatically when you use the syntax highlighter features in the editor's toolbar.

The live sample system has lots of options available, and we'll try to break things down to look at them a bit at a time.

Live sample macros

There are two macros that you can use to display live samples:

• EmbedLiveSample embeds a live sample into a page
• LiveSampleLink creates a link that opens the live sample in a new page

In many cases, you may be able to add the EmbedLiveSample or LiveSampleLink macro to pages with little or no additional work! As long as the sample can be identified by a heading's ID or is in a block with an ID you can use, adding the macro should do the job.

EmbedLiveSample macro

 {{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}

If the heading is translated, its ID is automatically updated to match the translated text. Therefore, you must change the value of block_ID in the macro call in the translated article, in order for the macro to work properly.

block_ID

Required: The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page (by clicking the "Source" button in the editor toolbar). Note: In a translated page, if the heading has been translated, the ID is automatically translated, too, and you must use the translated ID in order for the macro to work properly.

width

The width of the <iframe> to create, specified in px. This is optional; a reasonable default width will be used if you omit this. Note that if you want to use a specific width, you must also specify the height parameter.

height

The height of the <iframe> to create, specified in px. This is optional; a reasonable default height will be used if you omit this. Note that if you want to use a specific height, you must also specify the width parameter. If you use only one of them, the default frame size is used.

screenshot_URL

The URL of a screenshot that shows what the live sample should look like. This is optional, but can be useful for new technologies that may not work in the user's browser, so they can see what the sample would look like if it were supported by their browser. If you include this parameter, the screenshot is shown next to the live sample, with appropriate headings.

page_slug

The slug of the page containing the sample; this is optional, and if it's not provided, the sample is pulled from the same page on which the macro is used.

LiveSampleLink macro

 {{LiveSampleLink(block_ID, link_text)}}

block_ID

The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page (by clicking the "Source" button in the editor toolbar). Note: In a translated page, if the heading has been translated, the ID is automatically translated, too, and you must use the translated ID in order for the macro to work properly.

link_text

A string to use as the link text.

Using the live sample system

The sections below describe a few common use cases for the live sample system.

Turning snippets into live samples

One common use case is to take existing code snippets already shown on MDN and turn them into live samples.

Prepare the code samples

The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their mark-up. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on.

Each piece of code must be in a <pre> block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. This is done with a class on the <pre> element of brush:language-type, where language-type is the type of language the block contains, e.g. html, css, or js.

Note: You may have more than one block for each language; they are all concatenated together. This lets you have a chunk of code, followed by an explanation of how it works, then another chunk, and so forth. This makes it even easier to produce tutorials and the like that utilize live samples interspersed with explanatory text.

So make sure the <pre> blocks for your HTML, CSS, and/or JavaScript code are each configured correctly for that language's syntax highlighting, and you're good to go.

Live sample demo

This section is the result of using the live sample template button to create not only the main heading ("Live sample demo"), but also subheadings for our HTML, CSS, and JavaScript content. You're not limited to one block of each; in addition, they don't even need to be in any particular order. Mix and match!

You may choose to delete any of these you wish; if you don't need any script, just delete that heading and its <pre> block. You can also delete the heading for a code block ("HTML", "CSS", or "JavaScript"), since these are not used by the live sample macro.

Now that the template has been inserted, we can put in some code, and even some explanatory text.

HTML

This HTML creates a paragraph and some blocks to help us position and style a message.

<p>A simple example of the live sample system in action.</p>
<div class="box">
  <div id="item">Hello world! Welcome to MDN</div>
</div>

CSS

The CSS code styles the box as well as the text inside it.

.box {
  width: 200px;
  border-radius: 6px;
  padding: 20px;
  background-color: #ffaabb;
}

#item {
  font-weight: bold;
  text-align: center;
  font-family: sans-serif;
  font-size: 1.5em;
}

JavaScript

This code is very simple. All it does is attach an event handler to the "Hello world!" text that makes an alert appear when it is clicked.

var el = document.getElementById('item');
el.onclick = function() {
  alert('Owww, stop poking me!');
}

Result

Here is the result of running the code blocks above via{{EmbedLiveSample('Live_sample_demo')}}:

Here is a link that results from calling these code blocks via {{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}:

Live sample demo link

Conventions regarding live samples

Orders of code blocks

When adding a live sample, the code blocks should be sorted so that the first one corresponds to the main language for this sample (if there is one). For example, when adding a live sample for the HTML Reference, the first block should be HTML, when adding a live sample for the CSS Reference, it should be CSS and so on.

Naming of headings

When there is no ambiguity (e.g. the sample is under a "Examples" section), headings should be straightforward with the sole name of the corresponding language: HTML, CSS, JavaScript, SVG, etc. (see above). Headings like "HTML Content" or "JavaScript Content" should not be used. However if such a short heading makes content unclear, one can use a more thoughtful title.

Using a "Result" block

After the different code blocks, please use a last "Result" block before using the EmbedLiveSample macro (see above). This way, the semantic of the example is made clearer for both the reader and any tools that would parse the page (e.g. screen reader, web crawler).