「TsumeCompe.js」の使い方

1. はじめに
   1. このツールはWebサーバにアップロードして使用する。
      PC等のローカル環境では動作しない。
   2. 任意のファイルがアップロード可能なWebサービスであれば、ブログツール等でも利用できる（はず）。
   3. 必要に応じて、ダウンロードしたサンプルファイルや、サンプルのアップロード例もご参照。
      • ダウンロードしたファイルの中にある「SampleFiles」フォルダのファイル一式で、動作サンプルとなっている。
      • 「SampleFiles」フォルダごと、Webサーバにアップロードし、index.htmlを閲覧して動作を確認できる。
      • ツールの本体は「SampleFiles」フォルダにある「tsumecompe.js」である。
2. 設置方法
   1. 解答集約にGoogleフォームを利用する場合の設置方法を説明する。
      （formからの送信を受け付ける機能があるサービスであれば、Googleフォーム以外でも利用できる）
   2. ここから面倒な説明が続くが、formとHTMLは１度作成すればコピーして繰り返し使用できるので、少々ご辛抱頂きたい。
      また、Googleフォームの使い方の基本的説明は割愛する。
   3. Googleフォームを作る
      1. Googleフォームの作成には、サンプル用に作成したフォームも参考。
      2. フォームに設定する項目は、次のとおり。
         • 氏名
         • 居住地
         • 重複チェック
         • 問題の回答欄（問題の個数（以上）設定する）
         いずれも「記述式テキスト」を選択。
      3. 「送信」ボタンで、フォームのリンクURLを取得する。
   4. HTMLファイルを作る（Googleフォームに合わせて設定する）
      1. HTMLの作成には、サンプル用に作成したHTMLも参考。
         （ブラウザの右クリック等で、ソースコードを確認する）
      2. HTML5（正確にはHTML5が廃止された2021年時点のHTML Living Standard）の文法で作成する。
         古い規格では、正常に動作しない場合がある。
      3. ツールの処理範囲を<div>...</div>などで規定し、その範囲内にツールの処理対象になるタグを置く。
         • formタグ：１つだけ置く。Googleフォームに送信するデータ
           • formタグの範囲内に、送信する項目となるinputタグ、selectタグを置く。
           • 氏名のIDは「name」、居住地のIDは「place」に設定する。
           • 重複チェック欄は、ツールが自動入力する。
             inputタグ、type="hidden"（非表示）、idは"answer0"に設定する。
           • 問題回答欄は、ツールが自動設定する。問題の個数（以上）置く。
             inputタグ、type="hidden"（非表示）、idは"answer1"、"answer2"...に設定する。
         • buttonタグ：１つだけ置く。解答送信ボタン
         • canvasタグ：問題の数だけ置く。盤面を表示する場所
         • selectタグ（問題の番号をvalueで設定したもの）：１つ。タッチデバイスでの問題選択用
         • 何も文字列を含まないdivタグ（<div></div>）：任意の個数。ツールからのメッセージを表示する場所
           divタグが１つでスタイルの指定がなければ、上端合わせでsticky表示になる（Ver 1.1）
         • scriptタグ：ツールのファイルへの参照。処理範囲の最後に置く
      4. HTMLのformタグに、Googleフォームと連携させる設定をする。
         • formタグのactionには、Googleフォームの「送信」ボタンで取得したURLの、末尾の「/viewform...」を「/formResponse」に変更して設定する。
         • formタグの範囲内のinputタグ、selectタグに、Googleフォームに合わせたnameを設定する。
           • Googleフォームでは、name要素は「entry.（数値）」の形式とする。
             数値部分がGoogleフォームの各入力項目と連携するので、実際に作成したGoogleフォームに合わせて設定する。
           • サンプルのフォームを例にすると、フォームのソースコードの下の方に「"氏名",null,0,[[1009657845,null,0]」とある。
             これに合わせて、氏名欄のinputタグのname要素は「entry.1009657845」とする。
           • 他の入力欄も同様に、name要素を設定する。
         • 以上の操作は、HTML作成支援ツールを利用して自動作成できます。
   5. 問題ファイルの作成
      1. 問題ファイルは、適宜のツール（柿木将棋IXなど）を使用してcsaファイルで作成する（kifファイルやbodファイルは不可）。
         
      2. 初形局面のみで、詰手順は入力しない（詰手順が入っている場合は、ツールが警告表示する）。
         詰手順が入力されている既存ファイルから作成する場合は、詰手順を削除する。
      3. コメント（csaフォーマットでの「'*」）に半角数値を設定すると、「詰手数」として表示する。
      4. 問題ファイルをエラーチェックをしていない。エディタ等で修正する場合は注意。
   6. 設定ファイルの作成
      1. 設定ファイルはテキストファイルで、ファイル名は「0.csa」。
         （設定ファイルはcsaとは無関係だが、サーバ側の設定で都合が良いため（後述）拡張子csaを既定値としている）
         １行に１つ、設定を記入する。
      2. 使用できる設定は現在のところ、「shokyu」「ippan」の２種類（サンプルのファイルは「shokyu」）。
         「shokyu」では、王手の判定をする。「ippan」では王手の判定をしない。
         どちらかの設定が必要。
   7. CSSについて
      1. サンプルのCSSを付けているが、あまり凝ったことはしていないので、必要に応じて追加設定をする。
      2. CSSの設定以外に、ツールが設定しているスタイルは次のとおり。
         • 問題の盤面サイズ（canvasタグのheightとwidth）：横20ピクセル:縦31ピクセルの倍数で、画面サイズから自動設定
         • 問題選択ボタン：タッチデバイスで右下固定表示、タッチデバイス以外で非表示
         • z-index：問題選択ボタン=2、盤面=1（問題選択ボタンを盤面より表面に表示するため）
      
      以上で、基本的な材料は完成である。
      サーバの同じディレクトリにアップロードして、動作を確認してみる。
3. 動作の概要
   ツールの動作は、概要次のとおり。
   1. 解答者がWebページを閲覧すると、重複チェック値（時刻と乱数から単純生成した文字列）をcookieに設定する。
      cookieが設定済の場合は、値を再利用する。
   2. 氏名欄および居住地欄が必須項目で、両方の入力を待つ。
      （氏名の記入漏れを防ぐための仕様）
   3. 氏名欄と居住地欄の両方が空欄でなくなると、設定ファイル（0.csa）を読み込む。
      読み込みが失敗したときは、5秒後にリトライする。
   4. 設定ファイルの読み込みが成功すると、問題ファイルを非同期（ファイルの順不同）で読み込む。
      読み込みが失敗したときは、5秒後にリトライする。
   5. 問題ファイルの読み込みが成功すると、問題の盤面を表示し、解答者の操作が可能になる。
   6. 解答者の操作に応じて、手順の文字列を生成する。
   7. 解答者が送信ボタンをクリックすると、formの各answerに値を設定し、Googleフォームに送信する。
4. 解答手順の文字列
   解答手順は、次の規則で生成される文字列となる。
   1. １つの着手は「xy駒XY」の形式。
      
      • xy: 移動先の位置（半角数字2文字）
      • 駒: 移動先での駒の漢字1文字
        移動先での駒なので、例えば「角成」と「馬」はどちらも「馬」で表記。
        「と」=と金、「杏」=成香、「圭」=成桂、「全」=成銀の略記を使用。
      • XY: 移動元の位置（半角数字2文字）
        駒打ちのときは00。
   2. 着手と着手の間を、半角スペース1文字空ける。
5. オプション設定
   
   scriptタグのdata要素で、デフォルトの設定から変更できる。《クリックして開く》

   1. 開始時刻の指定（start）
      指定の時刻以前に閲覧したときに問題を表示しない。
      時刻の指定方法は、次の３とおりのいずれか。
      
      • "yyyy,mm,dd,hh,mm,ss"の形式の日本時間で指定する。省略した値はゼロになる。
        （例）data-start="2024,4,13,13,30"で、日本時間2024年4月13日13時30分00秒を開始時刻に指定。
      • "yyyy-mm-ddThh:mm:ss"の形式の日本時間で指定する。
        （例）data-start="2024-04-13T13:30:00"で、日本時間2024年4月13日13時30分00秒を開始時刻に指定。
      • "yyyy-mm-ddThh:mm:ss.mmmTZD"の形式で指定する。
        （例）data-start="2024-04-13T13:30:00.000+09:00"で、UTCと時差9時間（日本時間）の2024年4月13日13時30分00秒を開始時刻に指定。
      開始時刻設定の詳細《クリックして開く》

      • 開始時刻を設定したときの動作は次のとおり。
        1. デバイスの時計を5秒間隔で確認する。
        2. 開始時刻まで10秒未満になると、通常動作と同様に設定ファイルの読み込みを開始する。
      • data-startは端末の時刻なので、サーバの時刻と同じとは限らない。
        このため、開始時刻判定はあまり厳密にはしていない。
        
      • 問題ファイルはWebサーバ上のテキストファイルなので、ブラウザで閲覧できてしまう。
        開始時刻以前に閲覧させない方法として、例えば.htaccessを用いてサーバ側でアクセス規制をすることが考えられる。
        .htaccessが使用できる場合の設定例
        （サーバ時刻が2024年4月13日13時29分50秒より前のときは、（任意の1文字）.csaファイルの代わりに空のファイル（設定ファイルとして無効なもの。この場合はdummy.txt）にリダイレクトする）

        			RewriteEngine On
        			RewriteCond %{TIME} <20230413132950
        			RewriteRule .\.csa dummy.txt [R=302,L]
        			

        （この指定方法が使えるので、設定ファイルの拡張子を.csaとしている）
      • サーバ側で可能な設定（サーバの時刻指定方法が日本時間かUTCか、なども含め）は、各サービスの説明書などで確認すること。
   2. 終了時刻の設定（end）
      指定時刻になると送信ボタンを押せなくなる。時刻の指定方法は、開始時刻と同じ（data-endで指定）。
   3. 設定ファイルのファイル名（config）
      設定ファイルのファイル名の指定する（0.csa以外のファイル名を使用できる）。
      （例）data-config="example.txt" は、設定ファイル名をexample.txtにする。
      省略時は0.csa（data-config="0.csa" を指定したのと同じ）。
   4. 問題ファイルの開始値および拡張子指定（file）
      問題番号を1以外から表示させるときの指定。問題のファイル名を1.csa以外の番号から開始できる。
      拡張子も変更できる。開始値は正の数（ゼロは不可）。
      （例）data-file="5.txt" は、最初の表示が第5問になり、ファイル拡張子がtxtになる。
      このとき、第5問に対応する問題ファイルは"5.txt"、formの回答欄に設定するidは"answer5"、configの指定が無い場合は設定ファイルの拡張子も変更になる点に注意。
      数値のみを指定した場合は、開始値のみ設定し拡張子はcsaのまま。
      数値以外の文字列を指定した場合は、文字列を拡張子とし開始値は1のまま。
      省略時は1.csa（data-file="1.csa" を指定したのと同じ）。
   5. formタグ内の項目のid名称（idprefix）。id名称を"answer～」以外に指定できる。
      （例）data-idprefix="kaito" は、id名を"kaito1"、"kaito2"...にする。
      省略時はanswer（data-idprefix="answer" を指定したのと同じ）。
   6. 必須入力項目のid設定と入力案内メッセージの設定（required）
      （入力案内メッセージは必須項目の未入力時に表示するもので、デフォルトは「氏名・居住地を入力して下さい。」「氏名・居住地を入力して、開始時刻をお待ち下さい。」である。）
      必須項目とするidをカンマ区切りで指定し、その後に「:」で区切って入力案内の「氏名・居住地」部分を置き換える文字を指定する。
      （例）data-required="name,age:氏名と年齢" は、必須項目のidをname、ageに、入力案内を「氏名と年齢」に設定する。
      省略時は、nameとplaceが必須入力項目で、入力案内は「氏名・居住地」（data-required="name,place:氏名・居住地" を指定したのと同じ）。
      なお、必須項目以外の入力項目（例えば、感想やアンケート項目）はツールの動作には関係ないため、オプション設定と関係なく自由に設定できる。
   7. cookieのパス指定（cookie）
      data-cookie="/"は、ルートディレクトリ以下でcookieを共有する。"/"以外の指定は無効。
      （例）example.comドメインのWebページで、data-cookie="/" は、example.com/ 以下でcookieを共有する。
      省略時は、該当ページと同じディレクトリだけで有効。
      指定が空文字列のとき（data-cookie="" のとき）は、cookieを使用しないで（重複チェック値を生成しないで）動作する。
6. 重複チェックについて
   1. このツールは、解答を他ドメインに送信する前提であるため、ツールで検出できない送信先での不具合に備え、解答の再送を許容する。
      （送信ボタンを1度しかクリックできない設定にすると、一時的な不具合のときに解答者の判断では再開できなくなる）
      ネットワークの遅延などを解答者が不具合と判断し送信ボタンを複数回クリックするケースに備え、重複解答の除去の手助けとなるよう、重複チェック値を生成して解答と併せて収集する。
   2. 重複チェック値は、アクセス時刻ミリ秒と乱数から単純生成した数字列であり、個人情報やデバイス固有情報は含まない。
      一意な値である保証はないが、実用上は十分である。
   3. 重複チェック値はブラウザのcookieに記録するが、cookie自体はブラウザの操作で削除できるため、意図的な複数回解答を防止する効果はない。
7. cookieについて
   1. 他のユーザとドメインを共有するサービスで、cookieのパス（前述のdata-cookie="/"）を指定する場合は、他のユーザからアクセス可能であることに留意する。