MDN の Kuma プラットフォームは内蔵のライブサンプルシステムを提供して単純な（時にはそう単純でない）コードのサンプルをその出力と共にページの中で表示する機能を提供していますが、この機能では許可されていないことがあり、またサーバへの通信を必要とするサンプルもあります。私たちは MDN サンプルサーバを用意し、このような、またその他の問題も合わせて、解決することにしました。 この記事は、そのサンプルサーバを利用するためのガイドです。
たいていのサンプルは組み込みの live sample system で表現できますが、例外もあります。サンプルサーバーの利用が必要となる理由は下記の通りです:
各サンプルのコードは GitHub で管理されており、そのすべてのサンプルの実行可能/使用可能なインストールアクセスを提供するサーバーを持っています。各サンプルには固有の名前があり、リンクされる際には常にその名前のみで参照されます。以下のマクロの1つを使います。
{{TemplateLink("GithubSampleLink")}} は Github にある与えられた名前を持つサンプルのサンプルコードへのリンクを作成します。リンクのテキストとして使用する文字列をオプションで変更することもできます。
{{TemplateLink("GithubSampleFileLink")}} は Github にあるサンプルコードの中の指定された名前のファイルへのリンクを作成します。引数として、サンプルの名前、 リンクしたいファイルへのサンプルコード内での相対パスがあり、オプションでリンクのテキストを指定することもできます。
{{TemplateLink("SampleServerLink")}} はサンプルサーバー上のユーザーインタラクティブなサンプルへのリンクを挿入します。これはユーザーにサンプルへ移動してブラウザー内で遊ぶことができるように使います; これはサンプルがサーバーのみで作られてクライアント側のコードから別の場所から参照する場合には使いません。サンプルの名前と、オプションでリンクの代替テキストを入力として受けます。
サンプルサーバーに置かれたサンプルに貢献するには、GitHub の MDN サンプルサーバーリポジトリをフォークする必要があります。現在、すべてのサンプルは GitHub の同じリポジトリにあります。
それぞれのサンプルは s/ ディレクトリーの下に自身のディレクトリーを持っています。新しいサンプルを作るには、そこに適切な名前のディレクトリーを追加します。例えば、ちょっとしたゲームを実装するための Fetch API の使い方を示す例であれぱ、s/fetch-trivia にサンプルを置いても良いでしょう。
それぞれのサンプルに一つの必須ファイルがあります (これは皮肉にもまだ使われていませんが、すぐ使われるため入れておいてください): manifest.json というマニフェストファイルで、これはサンプルを説明し、サンプルサーバー自体からと、これをメンテ・使用するツールから使われるメタデータを提供します。その他のすべてはオプションです。もっと詳しく見ていきましょう。
マニフェストファイルは第一に、サンプルのリストをビルドするのに使われますが、最終的には各サンプルのスタートアップとシャットダウンプロセスを改良することに使われるでしょう。これは次のような JSON オブジェクトです:
{
"name": "WebSocket based chat server with WebRTC video chat support",
"docsUrl": "https://developer.mozilla.org/ja/docs/Web/API/WebRTC_API/Signaling_and_video_calling",
"description": "Uses Node.js to set up a WebSocket-based chat server, and provides a web page you can use to join the chat. Adds a feature to start a video call with another chat participant."
}現在オブジェクトには3つの項目があり、すべてが必須です (まだ使用してないですが、すぐ使います):
namedocsUrldescriptionWhen the sample server starts up or samples are restarted, each sample's base directory is scanned to see if there's a shell script file named startup.sh. If the file exists, it is executed, so that the sample has the opportunity to install support files, run any scripts, and start up any server processes that are needed to support the sample. For example, the WebSocket chat sample's startup.sh script looks like this:
npm install websocket
node chatserver.jsThe first line uses the Node package manager, npm, to install the module named websocket, which provides support for creating and/or talking to WebSocket servers.
The second line actually starts up the server process, which is implemented as a JavaScript script which is started up and run in the background.
To use Node modules in your project, you'll need to add a package.json file, which lists information about your sample but also includes a list of dependencies, so that those dependencies can be installed for you by the Node package manager (npm).
You may of course have other files. Obvious candidates are an index.html file so that users that browse to your sample see some content, style sheets, support HTML and JavaScript files, images and other media, and so forth.
Once you've finished and tested your sample, you will want to submit it so that it can be tested and eventually installed onto the production sample server. This is done using the standard Github pull request process.
Because the sample server itself is still a work in progress, there are quirks and issues with how samples work. Here are some tips that will help you avoid some of the worst potential problems.
If your sample needs to use a network port, you will have to take care not to inadvertently use one that's already being used by another sample (or by a system service on the server). At some point in the future, there will be an entry in the sample manifest for requesting a port number, so that the system will allocate them and keep track of which are used and which are not. But until then, be careful not to step on any toes!
このページそのもの、そしてここに記述されているサーバについては、作業が継続中です。