1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
---
title: MDN サンプルサーバ
slug: MDN/Tools/Sample_server
tags:
- Advanced
- Draft
- Guide
- MDN Meta
- Site-wide
- Tools
translation_of: MDN/Tools/Sample_server
---
<div>{{MDNSidebar}}</div><div>{{IncludeSubnav("/ja/docs/MDN")}}</div>
<p><span class="seoSummary">MDN の <a href="/ja/docs/MDN/Kuma">Kuma</a> プラットフォームは内蔵の<a href="/ja/docs/MDN/Contribute/Editor/Live_samples">ライブサンプルシステム</a>を提供して単純な（時にはそう単純でない）コードのサンプルをその出力と共にページの中で表示する機能を提供していますが、この機能では許可されていないことがあり、またサーバへの通信を必要とするサンプルもあります。私たちは MDN サンプルサーバを用意し、このような、またその他の問題も合わせて、解決することにしました。</span> この記事は、そのサンプルサーバを利用するためのガイドです。</p>
<h2 id="Possible_use_cases" name="Possible_use_cases">想定するユースケース</h2>
<p>たいていのサンプルは組み込みの <a href="https://developer.mozilla.org/ja/docs/MDN/Contribute/Editor/Live_samples">live sample system</a> で表現できますが、例外もあります。サンプルサーバーの利用が必要となる理由は下記の通りです:</p>
<ul>
<li>サンプルにサーバー上で永続的に実行されるコードが必要、例えば WebSocket サーバーにはサーバーコンポーネントと、サンプルサーバー上のクライアントコンポーネントもあるなど。</li>
<li>MDN wiki のコンテンツでは動かない技術を使ったサンプルや、読み手がコンテンツに集中する能力に影響するようなものは明らかに候補となります; これにはサウンド効果やメディアや大量のアニメーションを再生するものが含まれます。</li>
<li>MDN でホストできないようなリソースにアクセスする必要があるサンプルはサンプルサーバーに置かれます。</li>
</ul>
<h2 id="Referencing_samples" name="Referencing_samples">サンプルへの参照を追加する</h2>
<p>各サンプルのコードは <a href="https://github.com/mdn/samples-server">GitHub で管理されて</a>おり、そのすべてのサンプルの実行可能/使用可能なインストールアクセスを提供するサーバーを持っています。各サンプルには固有の名前があり、リンクされる際には常にその名前のみで参照されます。以下のマクロの1つを使います。</p>
<h3 id="GithubSampleLink" name="GithubSampleLink">GithubSampleLink</h3>
<p>{{TemplateLink("GithubSampleLink")}} は Github にある与えられた名前を持つサンプルのサンプルコードへのリンクを作成します。リンクのテキストとして使用する文字列をオプションで変更することもできます。</p>
<h3 id="GithubSampleFileLink" name="GithubSampleFileLink">GithubSampleFileLink</h3>
<p>{{TemplateLink("GithubSampleFileLink")}} は Github にあるサンプルコードの中の指定された名前のファイルへのリンクを作成します。引数として、サンプルの名前、 リンクしたいファイルへのサンプルコード内での相対パスがあり、オプションでリンクのテキストを指定することもできます。</p>
<h3 id="SampleServerLink" name="SampleServerLink">SampleServerLink</h3>
<p>{{TemplateLink("SampleServerLink")}} はサンプルサーバー上のユーザーインタラクティブなサンプルへのリンクを挿入します。これはユーザーにサンプルへ移動してブラウザー内で遊ぶことができるように使います; これはサンプルがサーバーのみで作られてクライアント側のコードから別の場所から参照する場合には使いません。サンプルの名前と、オプションでリンクの代替テキストを入力として受けます。</p>
<h2 id="高度なサンプルに貢献する">高度なサンプルに貢献する</h2>
<p><a href="https://mdn-samples.mozilla.org/">サンプルサーバー</a>に置かれたサンプルに貢献するには、GitHub の <a href="https://github.com/mdn/samples-server">MDN サンプルサーバーリポジトリ</a>をフォークする必要があります。現在、すべてのサンプルは GitHub の同じリポジトリにあります。</p>
<p>それぞれのサンプルは <a href="https://github.com/mdn/samples-server/tree/master/s"><code>s/</code> ディレクトリー</a>の下に自身のディレクトリーを持っています。新しいサンプルを作るには、そこに適切な名前のディレクトリーを追加します。例えば、ちょっとしたゲームを実装するための Fetch API の使い方を示す例であれぱ、<code>s/fetch-trivia</code> にサンプルを置いても良いでしょう。</p>
<h3 id="Structure_of_an_advanced_sample" name="Structure_of_an_advanced_sample">高度なサンプルの構造</h3>
<p>それぞれのサンプルに一つの必須ファイルがあります (これは皮肉にもまだ使われていませんが、すぐ使われるため入れておいてください): <code>manifest.json</code> というマニフェストファイルで、これはサンプルを説明し、サンプルサーバー自体からと、これをメンテ・使用するツールから使われるメタデータを提供します。その他のすべてはオプションです。もっと詳しく見ていきましょう。</p>
<h4 id="マニフェストファイル_manifest.json">マニフェストファイル: manifest.json</h4>
<p>マニフェストファイルは第一に、サンプルのリストをビルドするのに使われますが、最終的には各サンプルのスタートアップとシャットダウンプロセスを改良することに使われるでしょう。これは次のような JSON オブジェクトです:</p>
<pre class="brush: json line-numbers language-json notranslate"><code class="language-json"><span class="punctuation token">{</span>
<span class="key token">"name":</span> <span class="string token">"WebSocket based chat server with WebRTC video chat support"</span><span class="punctuation token">,</span>
<span class="key token">"docsUrl":</span> <span class="string token">"https://developer.mozilla.org/ja/docs/Web/API/WebRTC_API/Signaling_and_video_calling"</span><span class="punctuation token">,</span>
<span class="key token">"description":</span> <span class="string token">"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."</span>
<span class="punctuation token">}</span></code></pre>
<p>現在オブジェクトには3つの項目があり、<em>すべてが必須です </em>(まだ使用してないですが、すぐ使います):</p>
<dl>
<dt><code>name</code></dt>
<dd>実例の名前です。例の比較的短い名前であるべきです。</dd>
<dt><code>docsUrl</code></dt>
<dd>この例を詳しく扱っている MDN の主なページの URL です。例が複数のページから参照されている場合、「メイン」ページ (または存在するならランディングページ) のアドレスであるべきです。</dd>
<dt><code>description</code></dt>
<dd>実例を説明する長めの文で、これがデモする技術についての情報を含みます。</dd>
</dl>
<h4 id="スタートアップ時にサンプルを動かす_startup.sh">スタートアップ時にサンプルを動かす: startup.sh</h4>
<p>When 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 <code>startup.sh</code>. 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 <a href="https://developer.mozilla.org/ja/docs/Web/API/WebRTC_API/Signaling_and_video_calling">WebSocket chat sample's</a> startup.sh script looks like this:</p>
<pre class="brush: bash line-numbers language-bash notranslate"><code class="language-bash">npm install websocket
node chatserver.js</code></pre>
<p>The first line uses the Node package manager, <code>npm</code>, to install the module named <code>websocket</code>, which provides support for creating and/or talking to <a href="https://developer.mozilla.org/ja/docs/Web/API/WebSocket_API">WebSocket</a> servers.</p>
<p>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.</p>
<h4 id="Node.js_モジュールを使う_package.json">Node.js モジュールを使う: package.json</h4>
<p>To use Node modules in your project, you'll need to add a <code>package.json</code> 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 (<code>npm</code>).</p>
<h4 id="Optional_files" name="Optional_files">オプションのファイル</h4>
<p>You may of course have other files. Obvious candidates are an <code>index.html</code> 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.</p>
<h3 id="Submitting_your_sample" name="Submitting_your_sample">サンプルを投稿する</h3>
<p>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 <a href="https://help.github.com/articles/using-pull-requests/">pull request</a> process.</p>
<h2 id="Tips_and_errata" name="Tips_and_errata">Tips とエラッタ</h2>
<p>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.</p>
<h3 id="Port_numbers" name="Port_numbers">Port numbers</h3>
<p>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!</p>
<h2 id="進行中の作業">進行中の作業</h2>
<p>このページそのもの、そしてここに記述されているサーバについては、作業が継続中です。</p>
|
