Live samples

この記事は翻訳作業中です。

MDNは、記事に表示されているサンプルコードを、実際に見ている実行可能なサンプルに変換することをサポートしています。 これらのライブサンプルには、HTML、CSS、およびJavaScriptを任意の組み合わせで含めることができます。 「ライブ」サンプルはインタラクティブではありません。 ただし、実際にコードサンプルによって生成されるため、サンプルの表示出力はサンプルのコードと正確に一致します。

ライブサンプルシステムの仕組み

ライブサンプルシステムは、グループ内のすべてのコードを集め、1つのHTMLファイルにマージし、そのHTMLを<iframe>にレンダリングします。
ライブサンプルは2つの部分で構成されています。

  • コードブロックのグループ
  • コードブロックの結果を表示する(フレームまたはリンクを作成する)マクロ

このコンテキストでは、コードブロックの「グループ」は、見出しまたはブロック要素(<div>など)のIDによって識別されます。

  • IDがブロック要素に属する場合、そのグループは、そのIDが使用される囲むブロック要素内のすべてのコードブロックを含む。
  • IDが見出しに属する場合、その見出しの後ろで同じ見出しレベルの次の見出しの前にあるすべてのコードブロックがグループに含まれます。
    指定された見出しの小見出しのコードブロックはすべて使用されていることに注意してください。
    これがあなたが望む効果でない場合は、代わりにブロック要素にIDを使用してください。

このマクロでは、特別なURLを使用して、http://url-of-page$samples/group-idgroup-id はコードが配置されている見出しまたはブロックのID)という特定のグループのサンプルコードを取得します。
結果として得られるフレーム(またはページ)は、サンドボックスで保護されており、技術的にはWeb上で動作するものすべてを行う可能性があります。
もちろん、実際の問題として、コードはそのページの要点に貢献しなければなりません。
MDN上で実行されているランダムなものは、エディタコミュニティによって削除されます。

注意: ライブサンプルの出力を表示するには、マクロを使用する必要があります。
MDNのエディタは、セキュリティを確保するために<iframe>要素の直接使用を取り除きます。

サンプルのコードを含む各<pre>ブロックには、HTML、CSS、またはJavaScriptコードのいずれかを示すクラスがあり、それぞれ "brush:html"、 "brush:css"、 "brush:js" です。
これらのクラスは、対応するコードブロック上になければなりません。
幸いにも、各クラスはエディタのツールバーで構文ハイライト機能を使用すると自動的に追加されます。

ライブサンプルシステムには多数のオプションが用意されており、一度に少しずつ見ていきます。

ライブサンプルのマクロ

ライブサンプルを表示するために使用できるマクロは2つあります。

  • EmbedLiveSampleはライブサンプルをページに埋め込みます。
  • LiveSampleLinkはライブサンプルを新しいページに開くリンクを作成します。

多くの場合、EmbedLiveSample または LiveSampleLinkマクロは、余計な作業をほぼ全くすることなくページに追加することができます。
サンプルが見出しのIDで識別されるか、IDを持つブロックに含まれていれば、マクロを追加するだけでその作業を行う必要があります。

EmbedLiveSample マクロ

 {{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}}
block_ID
必須:コードを描画する見出しまたは囲みブロックのID。
適切なIDであるかどうかを確認する最善の方法は、ページの目次のセクションのURLを見ることです。
width
作成する<iframe>pxで指定された幅で
これはオプションで、省略すると、合理的なデフォルト幅が使用されます。
特定の幅を使用する場合は、heightパラメータも指定する必要があります。
height
作成する<iframe>pxで指定された高さです。
これはオプションで、省略すると、合理的なデフォルトの高さが使用されます。
特定の高さを使用する場合は、widthパラメーターも指定する必要があります。
どちらか一方しか使用しない場合は、デフォルトのフレームサイズが使用されます。
screenshot_URL
ライブサンプルの外観を示すスクリーンショットのURL。
これはオプションですが、新しいテクノロジが動作しないユーザーのブラウザに対して役立つ可能性があるため、サンプルがブラウザでサポートされている場合のサンプルを確認できます。

新しいテクノロジが動作しないユーザーのブラウザに対して、ブラウザが対応している場合のサンプルを確認できるため、役立つ可能性があります。

このパラメータを含めると、ライブサンプルの横に適切な見出しが付いたスクリーンショットが表示されます。
page_slug
サンプルが入っているページのスラグ。
これはオプションで、指定されていない場合は、マクロが使用されている同じページからサンプルが引き出されます。
 {{LiveSampleLink(block_ID, link_text)}}
block_ID
コードを描画する見出しまたは囲みブロックのID。
正しいIDであるかどうかを確認する最善の方法は、ページの目次のセクションのURLを見ることです。
link_text
リンクテキストとして使用する文字列。

ライブサンプルシステムを使用する

以下のセクションでは、ライブサンプルシステムの一般的な使用例をいくつか説明します。

In all of these cases, to see the results of the live sample, you must click Save Changes in the editor (which takes you out of edit mode). Because of the reflexive, Inception-like nature of live samples, the Preview Changes functionality is not able to display live samples.

これらのすべてのケースでライブサンプルの結果を表示するには、エディタでSave Changesをクリックする必要があります(編集モードから離れます)。
ライブサンプルにはインセプションのように再帰的な性質があるため、Preview Changes 機能でライブサンプルを表示することはできません。

スニペットをライブサンプルにする

よく使用されるケースの1つは、既にMDNに表示されている既存のコードスニペットを実際のサンプルに変換することです。

コードサンプルを準備する

最初のステップでは、コードスニペットを追加するか、既存のサンプルをコンテンツやマークアップの観点からライブサンプルとして使用できるようにします。
コードスニペットは、まとめて実行可能な完全な例を構成する必要があります。
たとえば、既存のスニペットにCSSのみが表示されている場合は、操作するCSSのスニペットを追加する必要があります。

それぞれのコードは<pre>ブロックにあり、各ブロックはブロックごとに言語ごとに適切にマークされていなければなりません。
ほとんどの場合、これは既に行われていますが、コードの各部分が正しい構文で構成されていることを確認することは、常に二重チェックの価値があります。
ツールバーのPREアイコンの隣には、MDNが構文強調表示を行うさまざまな言語のドロップダウンメニューアイコン(ツールヒント:構文ハイライター)があります。
構文の強調表示のためにブロックの言語を設定することで、ライブサンプルシステムの目的のための言語と関連付けられます。

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.

Note: When pasting content into MDN, please be aware that if pasting styled content (including, for example, syntax highlighting in code being copied from another site) that you may be bringing along unwanted and unneeded additional styles or classes. Please be careful not to do this; if necessary, review your edit in source mode to remove these unnecessary styles and classes (or check it before pasting, or use the "Paste as plain text" option instead).

ライブサンプルマクロを挿入する

Once the code is in place and properly configured to identify each block's language, you need to insert the macro that creates the iframe.

  1. Click the Insert Live Code Sample iFrame button in the toolbar; it looks like this: . This opens a dialog box for configuring your live sample frame:
  2. Under Document, enter the title of the article that contains the sample you wish to embed. By default, it's the article you're currently editing, but you can choose an article elsewhere on MDN, too. This makes it possible to reuse samples on multiple pages if needed. (If you type new text in this field, a menu of partially matching pages appears; select the title of the page you want.)
  3. In the Sections in Document menu, select the section in the article that contains the code blocks of the sample you want to embed.
  4. Click the OK button to generate and insert the macro call that creates the sample frame for you. The macro call looks something like this:
    {{ EmbedLiveSample('Live_sample_demo') }}

新規ライブサンプルを追加する

If you're writing a new page, and want to insert code that you want to present as a live sample, even more of the work can be done for you by the editor! 

  1. Click the Insert Code Sample Template button in the toolbar, which looks like this: . This presents a simple dialog asking you to name your live sample:
  2. Enter the title of the sample; this is used as the heading for the sample. Make sure that your title makes sense within the context of the page you're on.
  3. Click OK. A new heading with the title you entered is created, with sub-headings and empty code blocks for HTML, CSS, and JavaScript.
  4. Delete any headings and code blocks you don't need.
  5. Enter the code that makes up your sample in the appropriate code blocks
  6. Check conventions

サンプル検索を使う

As mentioned above, the Sample Finder is activated by clicking the Insert Live Code Sample iFrame icon. Unfortunately the the Sample Finder may produce a macro that is NOT usable without editing. There are two problem areas that should be carefully checked and edited if necessary.

  1. Document field. This field will search as you type and present a list of documents that match your string. But the list presented will NOT include the sub-page. For example, say you are working on the subpage for Negative under the main page @counter-style. The Sample Finder search will not find Negative but will find the main page @counter-style. When @counter-style is selected the field background turns green. See below for the issue this creates.
  2. Sections in Document. The pull-down menu Sections in Document may not show the section that you need. Just pick one, say Examples, and it can be fixed with a simple edit.

Here is what the Sample Finder produced:

{{ EmbedLiveSample('Examples', '', '', '', 'Web/CSS/@counter-style') }}

This macro will not work. The block_ID is Examples and it should be Example in this case (check the source ID for this section to verify which block_ID you need to use. Similarly the page_slug is @counter-style and it should be @counter-style/negative. These corrections can be done directly in the page with Edit active.

After editing the macro now looks like this:

{{ EmbedLiveSample('Example', '', '', '', 'Web/CSS/@counter-style/negative') }}

This edited macro will work correctly. If the macro is working correctly you will see the Open in CodePen button. A thumbnail of the example should appear above the Open in CodePen button. If the button is there but there isn't a thumbnail, just wait a few minutes. It may take some time for the server to generate it.

更新が必要なサンプルを検索する

When looking for existing samples to update, there are three main kinds of updating you may wish to do:

  • Turn an existing non-live example snippet into a live sample.
  • Correct bugs in an existing live sample.
  • Improve an existing live sample, or update a sample based on technology changes.

Note: If you find an article that has samples in need of being updated to use the live sample system, please add the tag "NeedsLiveSample" to the page.

live サンプルに変換するサンプルを検索する

MDN has lots of older examples that don't yet use the live sample system. Our goal is to update most or all of these to be live samples. This will improve consistency and usability. You will almost certainly find many of these as you use MDN on a daily basis; however, how can you find them if you're specifically looking for them to update? Unfortunately, there's not an easy way to do that. But there are some guidelines you can follow to help track them down:

Live サンプルのデモ

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!</div>
</div>

CSS

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

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

#item {
  width: 100%;
  font-weight: bold;
  text-align: center;
  font-size: 2em;
}

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!');
}

結果

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

ライブサンプルに関する取り決め

Note: This is currently (Feb. 2016) under discussion on the dev-mdc mailing list (see this thread). Any input is welcome. If this note persists after some month (Apr. 2016), please reach the author of the first email in this thread for updating this page.

コードブロックの順序
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.
見出しの名前付け
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.
"Result" ブロックを使用する
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).

 

ドキュメントのタグと貢献者

 このページの貢献者: nakano348, Uemmra3
 最終更新者: nakano348,