ライブサンプル

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

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

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

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

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

このマクロでは、特別な URL を使用して、http://url-of-page$samples/group-id (group-id はコードが配置されている見出しまたはブロックの ID) という特定のグループのサンプルコードを取得します。

結果として得られるフレーム (またはページ) はサンドボックスで保護されており、技術的にはウェブ上で動作するものすべてを行う可能性があります。もちろん、実際の問題として、コードはそのページの要点に貢献しなければなりません。MDN 上で実行されているランダムなものは、エディターコミュニティによって削除されます。

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

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

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

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

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

EmbedLiveSample マクロ

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

block_ID

必須: コードを描画する見出しまたは囲みブロックの ID。適切な ID であるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。注記: 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される block_ID の値を変更しなくていけません。 【訳注: 日本語では見出し要素には name 属性を追加して英語版と同じ ID となるようにしています。】

width

作成する <iframe> の幅で、px で指定します。これはオプションで、省略すると合理的なデフォルト幅が使用されます。特定の幅を使用する場合は、height パラメーターも指定する必要があります。

height

作成する <iframe> の高さで、px で指定します。これはオプションで、省略すると合理的なデフォルトの高さが使用されます。特定の高さを使用する場合は、width パラメーターも指定する必要があります。どちらか一方しか使用しない場合は、デフォルトのフレームサイズが使用されます。

screenshot_URL

ライブサンプルの外観を示すスクリーンショットの URL。これはオプションですが、新しいテクノロジが動作しないユーザのブラウザに対して役立つ可能性があるため、サンプルがブラウザーでサポートされている場合の様子を確認できます。このパラメータを含めると、ライブサンプルの横に、適切な見出し付きのスクリーンショットが表示されます。

page_slug

サンプルが入っているページのスラグ。これはオプションで、指定されていない場合はマクロが使用されている同じページからサンプルが引き出されます。

LiveSampleLink マクロ

 {{LiveSampleLink(block_ID, link_text)}}

block_ID

コードを引っ張ってくる見出しまたは囲みブロックの ID。正しいIDであるかどうかを確認する最善の方法は、ページの目次のセクションの URL を見ることです。注記: 見出しが翻訳されている場合、その ID 属性が自動的に翻訳されたテキストに合わせてアップデートされます。そのため、マクロ内で呼び出される block_ID の値を変更しなくていけません。【訳注: 日本語では見出し要素には name 属性を追加して英語版と同じ ID となるようにしています。】

link_text

リンクテキストとして使用する文字列。

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

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

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

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

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

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

HTML、CSS、JavaScript コードの <pre> ブロックがそれぞれの言語の構文強調表示に対して正しく設定されていることを確認してください。

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

コードが配置され、各ブロックの言語を識別するように適切に構成されたら、iframeを作成するマクロを挿入する必要があります。

1. ツールバーのコードサンプルの iFrame を挿入ボタン () をクリックします。
   ライブサンプルフレームを設定するためのダイアログボックスが開きます
   
2. ドキュメントに埋め込みたいサンプルが含まれている記事のタイトルを入力します。
   デフォルトでは現在編集中の記事ですが、MDN の別の場所で記事を選択することもできます。これにより、必要に応じて複数ページのサンプルを再利用することができます。(このフィールドに新しいテキストを入力すると、部分的に一致するページのメニューが表示され、必要なページのタイトルを選択します)
3. ドキュメント内のセクションメニューで、埋め込みたいサンプルのコードブロックを含む記事のセクションを選択します
4. OKボタンをクリックして、サンプルフレームを作成するマクロ呼び出しを生成して挿入します。マクロ呼び出しは次のようになります
   {{ EmbedLiveSample('Live_sample_demo') }}

新しいページを作成していて、ライブサンプルとして提示したいコードを挿入したい場合は、さらに多くの作業をエディターで行うことができます！

1. ツールバーのコードサンプルテンプレートを挿入ボタン () をクリックします。
   ライブサンプルに名前を付けるよう求める簡単なダイアログが表示されます。
   
2. サンプルのタイトルを入力します。これはサンプルの見出しとして使用されます。このタイトルがページの文脈の中で意味が通ることを確認してください。
3. 入力したタイトルの新しい見出しが、HTML、CSS、およびJavaScript用のサブ見出しと空のコードブロックとともに作成されます。
4. 必要のない見出しやコードブロックを削除してください。
5. 適切なコードブロックでサンプルを構成するコードを入力します。
6. 取り決めを確認します。

前述のように、サンプルファインダーは、コードサンプルの iFrame を挿入アイコンをクリックするとアクティブになります。残念なことに、サンプルファインダーは編集しないと使用できないマクロを生成することがあります。必要に応じて慎重にチェックして編集すべき 2 つの問題エリアがあります。

1. ドキュメントフィールド。このフィールドは入力時に検索され、入力した文字列にマッチするドキュメントのリストが表示されます。しかし、提示されたリストにはサブページは含まれません。たとえば、メインページの @counter-style の下にある Negative のサブページで作業しているとします。サンプルファインダーでの検索では Negative は見つかりませんが、メインページの @counter-style が検索されます。@counter-style を選択すると、フィールドの背景が緑色に変わります。このことによる問題については以下を参照してください。
2. ドキュメントのセクション。ドキュメント内のプルダウンメニューのセクションに、必要なセクションが表示されないことがあります。例のように、ただ一つ選択して簡単な編集をすることで修正することができます。

サンプルファインダーは次のようになりました。

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

このマクロは動作しません。block_ID が Examples となっていますが、この場合は Example でなければなりません。(このセクションのソース ID を調べて、使用する必要のある block_ID を確認してください。) 同様に page_slug が @counter-style になっていますが、@counter-style/negative となるべきです。これらの修正は、編集ページで直接行うことができます。

編集すると、マクロは次のようになります。

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

この編集されたマクロは動作します。マクロが正常に動作している場合は、Open in CodePen ボタンが表示されます。この例のサムネイルは、Open in CodePen ボタンの上に表示されます。ボタンがあるがサムネイルがない場合は、少し待ってください。サーバーがこれを生成するには時間がかかることがあります。

既存のサンプルを探して更新する場合は、更新の主な 3 つの種類があります:

• 既存の非ライブサンプルスニペットをライブサンプルに変換。
• 既存のライブサンプルのバグを修正。
• 既存のライブサンプルを改善、または、技術の変化に基づいてサンプルを更新。

MDN にはライブサンプルシステムをまだ使用していない古いサンプルがたくさんあります。私たちの目標は、これらのほとんどまたはすべてをライブサンプルに更新することです。これにより、一貫性とユーザビリティが向上します。MDN を日常的に使用するときには、これらの多くがほぼ確実に見つかるでしょう。しかし、あなたが特にそれらを更新しようと探している場合、それらを見つけることができますか？残念ながら簡単な方法はありません。ですが、それらを追跡するのに役立つガイドラインがいくつかあります：

• まず、「NeedsLiveSample」というタグが付けられたこのページのリストを見てみましょう。これらは、ユーザーが更新が必要とマークしたページです。ライブサンプルを使用するように更新する必要のあるページが表示されてもすぐに修正する時間がない場合は、このタグを自分で追加する必要があります。
• JavaScript ガイド、HTML ドキュメント、CSS リファレンスなどのサンプルが含まれている可能性のあるドキュメントツリーを参照してください。
• 「example」や 「sample」のような用語を検索し、更新するページがないか、検索結果を調べます。

このセクションは、ライブサンプルテンプレートボタンを使用してメイン見出し (「ライブサンプルデモ」) だけでなく、HTML、CSS、および JavaScript コンテンツのサブ見出しも作成した結果です。それぞれのブロックに限定されませんし、さらに、特定の順序である必要はありません。

削除したいものを削除することもできます。スクリプトが必要ない場合は、その見出しとその <pre> ブロックを削除してください。コードブロック (HTML、CSS、または JavaScript) の見出しは、ライブサンプルマクロでは使用されないため、削除することもできます。

テンプレートが挿入されたので、いくつかのコード、さらには説明テキストを挿入することができます。

この HTML は、メッセージの配置とスタイルに役立つ段落とブロックを作成します。

<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 コードは、ボックスとその内部のテキストのスタイルを設定します。

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

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

このコードは非常に簡単です。クリックすると警告が表示されるテキスト「Hello world!」にイベントハンドラーをアタッチするだけです。

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

下記は {{EmbedLiveSample('Live_sample_demo')}} を通じて、上のコードブロックを実行した結果です。

下記は {{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}} を通じて、これらのコードブロックを経由して呼び出される結果のリンクです。

Live sample demo link

コードブロックの順序

ライブサンプルを追加する場合、コードブロックは最初のものがこのサンプルのメイン言語に対応するようにソートする必要があります。たとえば、HTML リファレンスのライブサンプルを追加する場合、最初のブロックは HTML でなければならず、CSS リファレンスのライブサンプルを追加するときは CSS でなければなりません。

見出しの名前付け

曖昧さがない場合 (例: サンプルが「Examples」セクションの下にある場合)、見出しは対応する言語の唯一の名前である HTML、CSS、JavaScript、SVG など (上記参照) で直接的に表します。「HTML コンテンツ」や「JavaScript コンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。

「Result」ブロックを使用する

異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「Result」ブロックを使用してください (上記参照)。このようにして、この例の意味は、読者とページを解析するツール (スクリーンリーダー、ウェブクローラーなど) の両方にとってより明確になります。