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」です。これらのクラスは、wikiが正しく使うために、対応するコードブロック上になければなりません。幸いにも、各クラスはエディターのツールバーで構文ハイライト機能を使用すると自動的に追加されます。

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

ライブサンプルのマクロ

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

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

多くの場合、 EmbedLiveSampleLiveSampleLink マクロは、追加の作業をほぼ全くすることなくページに追加することができます。サンプルが見出しの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
リンクテキストとして使用する文字列。

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

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

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

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

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

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

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

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

注意: 複数の言語のブロックが独立していて、すべて一緒に連結する場合があるかもしれません。コードの塊りに続いて、動作原理の説明があって、また次の塊り、…という構成ができます。これにより、説明テキストを交えたライブサンプルを利用するチュートリアルなどを作成することがより容易になります。

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

注意: MDNにコンテンツを貼り付ける際には、意図せず不要なスタイルやクラスを取り込む可能性のあるスタイル付きコンテンツ(たとえば、別のサイトからコピーされたコードの構文強調を含む)を貼り付けることを意識してください。こうならないように注意してください。必要に応じて、ソースモードで編集内容を確認し、不要なスタイルやクラスを削除してください(貼り付ける前に確認するか、代わりに「プレーンテキストとして貼り付け」オプションを使用してください)。

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

コードが配置され、各ブロックの言語を識別するように適切に構成されたら、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つの種類があります:

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

注意: ライブサンプルシステムを使用するために更新が必要なサンプルがある記事を見つけた場合は、タグ「NeedsLiveSample」をページに追加してください。

ライブサンプルに変換するサンプルを検索する

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

ライブサンプルのデモ

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

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

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

HTML

この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

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;
}

JavaScript

このコードは非常に簡単です。クリックすると警告が表示されるテキスト「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

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

注意: これは現在、dev-mdcメーリングリスト(このスレッドを参照)に関する議論中で(2016年2月現在)です。どんな入力も歓迎です。このメモが数ヶ月(2016年4月)以降も存続する場合は、このページの更新に関するこのスレッドの最初のメールの著者に連絡してください。

コードブロックの順序
ライブサンプルを追加する場合、コードブロックは最初のものがこのサンプルのメイン言語に対応するようにソートする必要があります。たとえば、HTMLリファレンスのライブサンプルを追加する場合、最初のブロックはHTMLでなければならず、CSSリファレンスのライブサンプルを追加するときはCSSでなければなりません。
見出しの名前付け
曖昧さがない場合(例:サンプルが「Examples」セクションの下にある場合)、見出しは対応する言語の唯一の名前であるHTML、CSS、JavaScript、SVGなど(上記参照)で直接的に表します。「HTMLコンテンツ」や「JavaScriptコンテンツ」のような見出しは使用しないでください。しかし、そのような短い見出しがコンテンツを不明瞭にする場合、より思慮深いタイトルを使用することができます。
「Result」ブロックを使用する
異なるコードブロックの後、EmbedLiveSample マクロを使用する直前に、「Result」ブロックを使用してください(上記参照)。このようにして、この例の意味は、読者とページを解析するツール(スクリーンリーダー、ウェブクローラなど)の両方にとってより明確になります。

 

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

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