SurveyCTO フォームおよびデータセット作成

SurveyCTO は XLSForm および ODK 標準に基づくモバイルデータ収集プラットフォームであり、プラットフォーム固有の拡張機能と相違点があります。このスキルは、遭遇する可能性のある 4 つの定義ファイルタイプに対する SurveyCTO ドメイン専門知識を提供します:

1. XLSForm フォーム定義 (.xlsx) — 調査インストルメント
2. データセット定義 (.xml) — サーバーデータセット構造と発行ルール
3. Data Explorer ワークブック定義 (.xlsx) — 監視ダッシュボード
4. フィールドプラグインバンドル (.fieldplugin.zip) — 単一フィールドのレンダリングを引き継ぐカスタム HTML/CSS/JS

高レベルの方向づけについては、まず references/overview.md をお読みください。

SurveyCTO ファイルの識別

ファイルタイプ	形式	識別方法
XLSForm	.xlsx	survey、choices、settings という名前のワークシート
データセット定義	.xml	ルート要素 <dataset> と子要素 <definition>
Data Explorer ワークブック	.xlsx	summaries、settings、global_filters、global_exclusions という名前のワークシート
フィールドプラグインバンドル	.fieldplugin.zip	ルートに manifest.json、template.html、style.css、script.js を含む zip。フィールドの appearance から custom-<name> として参照

XLSForm 開始点

ツールを選択する前に、コードを書く前に、さらに読む前に:

• 新規フォーム → ステップ 1 は常に assets/xlsform-template.xlsx から出力パス (例えば Unix シェルで cp assets/xlsform-template.xlsx <output_path>) への厳密なファイルコピーです。テンプレートはこのスキルの assets/xlsform-template.xlsx にバンドルされています (スキルのルートディレクトリからの相対パスで解決)。その後、以下のツール選択ルールに従い、コピーされた ファイルをアップロードまたは開きます。
• 既存フォーム → ユーザーのワークブックをそのまま読み込みます。再生成しないでください。
• 決して .xlsx をゼロから作成しないでください。このルールは利用可能なツールに関わらず適用されます。MCP のみの要件ではなく、フォールバック除外はありません。アンチパターン: ワークブックをゼロから構築 を参照して、回避すべき特定のツールと慣用句をご確認ください。

このルールはこのスキルで最も見落とされやすいステップです。openpyxl.Workbook()、新しいパスに対する pandas.ExcelWriter、新しいファイルを作成するための libreoffice --headless、またはゼロから XLSX バイトを書き込むコードを呼び出そうとしている場合は、代わりにテンプレートをコピーしてください。

利用可能なツール

このスキルは特別なツールなしで完全に使用可能です。ここと同じ文書のリンク先に組み込まれた十分な SurveyCTO 知識があれば、ユーザーをアドバイスしたり、散文で編集を説明したり、フォームについて推論したりするのに十分です。追加のツールがある場合は、以下の優先順位で使用してください。

XLSForm 作業用のツール選択ルール: SurveyCTO MCP サーバーツールが接続されている場合、自明でない XLSForm 検査、編集、検証、および エクスポート には必ずそれらを使用する必要があります。SurveyCTO MCP ツールが利用可能な場合、汎用の bash、python、openpyxl、LibreOffice、またはスプレッドシート ツールを主な作成パスとして選択しないでください。汎用ツールは、MCP ツールが利用できない、接続されていない、または回復不可能なエラーを返す場合の フォールバック のみです。

SurveyCTO MCP サーバー (利用可能な場合は推奨)

SurveyCTO MCP サーバー は、このドメイン用に構築された機能を持つパブリック認証不要の MCP サーバーです (XLSForm セッション検査/編集/エクスポート および SurveyCTO ナレッジベース検索)。エンドポイント: https://assistant-be.surveycto.net/mcp (Streamable HTTP、ステートレス、認証不要)。ユーザーが XLSForm を編集している場合や SurveyCTO の事実上の質問をしている場合にサーバーが接続されていないときは、それが存在することを言及して、インストールを支援することを申し出ます。主張しないでください。

SurveyCTO MCP ツールを使用する前に、references/mcp.md をお読みください。MCP 使用には必須です。ツール署名、パッチセマンティクス、並行ルール、エラーハンドリング、または制限を推測しないでください。

推奨ワークフロー

1. 任意の MCP ツール呼び出し前に: references/mcp.md をお読みになり、不確定な場合は get_surveycto_mcp_capabilities を呼び出して、現在のツール リストと入門トピックを確認してください。作業に XLSForm が含まれる場合は、最初に references/xlsform.md も読んでいる必要があります。前提条件: XLSForm リファレンスを読む をご覧ください。
2. 事実上の SurveyCTO の質問: kb_search → 返された URL を回答に引用してください。
3. 新しい XLSForm を作成: 以下の ワークフロー: 新規フォーム作成 に従ってください。これは標準的なシーケンスであり、テンプレートファースト ルールを強制します。
4. 既存の XLSForm を検査または編集:
   1. ユーザーのワークブックを読み込みます (再生成しないでください)。新規アップロードの場合は start_xlsform_session、既存の session_id を再開する場合は get_xlsform_summary を使用してください。
   2. パッチを適用したり行をページングしたりする前に、form_summary から開始インベントリを取得してください。 既存の列名、選択肢リスト (特に yesno などの再利用可能なもの)、設定値、および警告に注意してください。メモリから綴りや値を想定しないでください。
   3. xls_get_rows / xls_get_row を使用して、変更しようとしている行を検査します。並列呼び出しは問題ありません。
   4. xls_apply_patches — すべての関連編集を 1 回の呼び出しにバッチします。リスキーな変更の場合は、フルバッチで validate_only=true を使用してください。change_setting 経由で設定を更新し、edit_row ではなく。大規模バッチの場合は return_form_summary=false と include_details=false を設定します。
   5. export_xlsform → download_url またはリソース リンクをユーザーに手渡してください。実ワークブックの場合は format="base64" を避けてください。フォームが custom-<name> appearance を参照している場合は、アップロード時に SurveyCTO コンソールでマッチする .fieldplugin.zip ファイルをアタッチするようユーザーに通知してください 。このスキルと MCP サーバーはローカルファイルのみを編集します。
   6. TTL 期限切れまでセッションを開いたままにするのが一般的です。明示的なクリーンアップについてのみ end_xlsform_session を呼び出してください。

汎用スプレッドシート/xlsx ツール

SurveyCTO MCP ツールが利用できない場合、または回復不可能な方法で失敗した場合にのみ、汎用 xlsx、Excel、Python/openpyxl、LibreOffice、またはスプレッドシート ツールを使用してください。これらのツールは .xlsx ファイルをセルごとに読み書きできますが、SurveyCTO フォームセマンティクス、MCP セッション並行性、またはサーバーサイド数式再計算を理解していません。汎用ツールを使用する必要がある場合は、MCP ツールが利用できないか失敗したため フォールバック していることをユーザーに明確に伝えてから、以下の XLSForm .xlsx ファイルの操作 セクションの編集ルールに従ってください。

Web フェッチ

URL をフェッチできる場合、最も信頼できるライブソースは:

• docs.surveycto.com — 製品ドキュメント
• support.surveycto.com — サポートセンター記事
• www.surveycto.com — サイト/マーケティングコンテンツ

現在の製品の動作を確認する際は、バンドルされた入門書よりもこれらを優先してください。

ファイルツールがまったくない場合

それでも支援できます: 散文で編集を説明してください ("survey ワークシートに type=integer、name=age、label=Age in years、constraint=. >= 0 and . <= 120 の行を追加")、式を説明したり、ロジックをデバッグしたり、ユーザーの案を以下のルールに対して検証したりできます。ユーザーは変更を自分で適用できます。

知識質問の権限階層

ユーザーが SurveyCTO 製品の動作、慣例、またはドキュメントについて質問する場合、この順序でソースを優先してください:

1. MCP kb_search / get_surveycto_primer (利用可能な場合) — 現在、索引付け、権威あり。
2. docs.surveycto.com、support.surveycto.com、www.surveycto.com のライブ web フェッチ (フェッチ可能な場合)。
3. references/ のバンドルされた入門書 — 安定した要約、ライブドキュメントより遅れる可能性があります。
4. 一般的な XLSForm/ODK 知識 — SurveyCTO が場所によって相違している (= vs ==、index() vs position()、choice-label() vs jr:choice-name()、relevance 列名、select_multiple 用 selected() など) という明示的な警告付きでのみ。

重要な場合は、どのレベルから回答しているかを引用してください。

XLSForm 概要

XLSForm は 3 つのワークシートを持つ XLSX ワークブックです:

• survey — すべての質問、グループ、リピート、および計算は 1 行
• choices — select_one および select_multiple フィールド用選択肢リスト
• settings — フォーム全体の設定 (タイトル、ID、バージョン、言語、暗号化)

キー列 (survey ワークシート)

列	目的
type	フィールドタイプ: text、integer、decimal、select_one [list]、select_multiple [list]、note、calculate、date、geopoint、image、begin group、end group、begin repeat、end repeat など
name	一意の変数名 (スペース/句読点なし); エクスポート列になります
label	プロンプト テキスト (翻訳用 label:Language をサポート)
relevance	行が表示される時期を制御するスキップロジック式
constraint	検証式 (. = 現在の値)
calculation	calculate フィールド用式
choice_filter	選択フィールド用選択肢をフィルター処理する式
appearance	表示オプション (minimal、quick、likert、field-list など)
repeat_count	リピートグループの繰り返し数

キー列 (choices ワークシート)

列	目的
list_name	選択肢リスト名 (select_one [list] / select_multiple [list] で参照)
value	選択肢の保存されたコード
label	表示テキスト (翻訳用 label:Language をサポート)

コア機構

• ${fieldname} は式内の別のフィールドの値を参照します。
• . は現在のフィールドの提案値を参照します (制約で使用)。
• グループ (begin group / end group) はフィールドを組織します。グループの relevance はすべてのコンテンツを制御します。
• リピート (begin repeat / end repeat) はブロックを繰り返します。repeat_count は番号を設定します。
• フィールド名はフォーム全体で一意である必要があります。

完全なリファレンス: references/xlsform.md。

SurveyCTO 式規約

SurveyCTO は、いくつかのプラットフォーム固有の規約を持つ XPath のような式を使用します。常にこれらを標準 ODK 同等物の代わりに使用してください:

これを使用 (SurveyCTO)	これでなく (ODK/XPath)	コンテキスト
=	==	等値比較
index()	position()	現在のリピートインスタンス番号
choice-label()	jr:choice-name()	選択肢ラベルテキストを取得
relevance 列	relevant 列	スキップロジック列名
div	/	式での除算演算子

選択フィールド規約

• select_one の場合: ${field} = 'value' と selected(${field}, 'value') の両方が機能します。
• select_multiple の場合: 常に selected() を使用してください。= 演算子は複数選択に対して機能しません。

文字列リテラル

文字列リテラルにはシングルクォートを使用してください: ${field} = 'yes'

例外: 文字列にシングルクォートが含まれている場合は、ダブルクォートを使用してください: if(${yesno} = 1, "a string with 'quotes' in it", "no quotes")

一般的な式パターン

スキップロジック (relevance): ${consent} = 'yes'

範囲を持つ制約: . >= 0 and . <= 120

生年月日から計算された年齢: int((today() - ${dob}) div 365.25)

条件付き値: if(${gender} = 'female', 'F', 'M')

アタッチされたデータセットからデータをプル: pulldata('households', 'head_name', 'hhid', ${household_id})

ランダム割り当て (一度だけ計算): once(if(random() < 0.5, 'treatment', 'control'))

完全な式リファレンス: references/expressions.md。ライブドキュメント: Using expressions in your forms。

XLSForm .xlsx ファイルの操作

このセクションは、どのファイルツールパスを使用しているかに関わらず適用されます (SurveyCTO MCP サーバー、汎用 xlsx ツール、またはユーザーが適用するための散文説明)。ルールは同じです。適用メカニズムのみが異なります。MCP ツールが接続されている場合、このセクションを使用して編集を計画および検証しますが、xls_apply_patches と export_xlsform を使用して編集を適用します。

前提条件: XLSForm リファレンスを読む

*任意の XLSForm 作業 — 作成、編集、デバッグ、または XLSForm に関する質問への回答 — を開始する前に、references/xlsform.md をお読みください。 これは、どのツール パス (MCP、汎用 xlsx ツール、または散文のみ) を使用しているか、タスクがどのくらい簡単に見えるかに関わらず、必須です。SurveyCTO 固有の列規約、多言語構造、グループ/リピート ルール、および一般的な ODK 知識と異なる式構文をドキュメント化しています。一般的な ODK メモリに頼らないでください。リファレンスを読んだ後も不明な点がある場合は、先に進む前に kb_search (または docs.surveycto.com のライブドキュメント) を使用してください。

一般的な ODK メモリが一貫して間違うため、事前に言及する価値がある既知の頻出な問題があります: 多言語フォームでは、デフォルト言語はサフィックスなしの列に入ります (label、hint、constraint message など) および追加の言語はサフィックス付き列に入ります (例: label:Spanish)。デフォルト言語をサフィックス付き列に入れてベースを空白のままにすると、フォームはサイレントに破損します。その他の相違点は references/xlsform.md でドキュメント化されています。読んでください。

重要: 常にテンプレートから開始

すべての新しい XLSForm は、assets/xlsform-template.xlsx のバンドルテンプレートから開始 する必要があります。

テンプレートの使用方法:

1. assets/xlsform-template.xlsx から出力パスへの厳密なファイルコピーを作成します (例えば、Unix シェルで cp assets/xlsform-template.xlsx <output_path>; assets/ をスキルのルートディレクトリから相対的に解決)。ファイルを再生成しないでください。
2. MCP ツールが利用可能な場合、コピーされたファイルをアップロード URL フローを使用して start_xlsform_session に渡し、xls_apply_patches で編集を適用します。
3. MCP ツールが利用できない場合、コピーされたファイルを開いて、その場で編集してください。既存のワークシートにコンテンツを追加します。

以下をしないでください:

• ゼロから新しい .xlsx ファイルを作成しないでください。
• 新しいワークシートを作成し、自分で構造を構築しないでください。
• テンプレートからワークシートを削除し、再作成しないでください。
• フォームを "適切に" "再構築" しないでください。テンプレートが適切な開始点です。

アンチパターン: ワークブックをゼロから構築

新しいフォームについて以下のいずれかを実行しないでください:

• from openpyxl import Workbook; wb = Workbook() (または survey/choices/settings シートを追加する新しいワークブックオブジェクトを構築するその他のコード)
• 既存のテンプレートコンテンツを含まないパスに対する pandas.ExcelWriter(<new_path>) または pandas.DataFrame.to_excel(<new_path>)
• 非テンプレートソースから開始する libreoffice --headless --convert-to xlsx
• XLSX バイトを直接書き込む (zipfile + xl/worksheets/*.xml)

これらは技術的に有効ですが使用不可能なフォームを生成します: 条件付き書式なし、help-survey/help-choices/help-settings シートなし、caseid 行なし、隠し監査計算なし、再利用可能な yesno 選択肢リストなし、自動更新 version 式なし、色分けされた行スタイルなし。ユーザーは手作業で Excel 作業をやり直す必要があります。代わりに assets/xlsform-template.xlsx をコピーしてください。MCP ツールが利用できない場合、openpyxl にフォールバックしても、これは真実です。フォールバックは ゼロからの作成 ではなく 編集 用です。

ワークフロー: 新規フォーム作成

これらのステップを順番に実行してください:

1. assets/xlsform-template.xlsx から出力パスへの厳密なファイルコピーを作成します。新しいワークブックオブジェクトを作成したり、ワークシートを生成したり、別のソースから変換したりしないでください。
2. フォームコンテンツを設計する前に、references/xlsform.md をお読みください。 これは必須です。後で混乱した場合のルックアップではなく。列規約、多言語構造、グループ/リピート ルール、および式構文はすべて、一般的な ODK 知識と異なる SurveyCTO 固有の詳細があります。前提条件: XLSForm リファレンスを読む をご覧ください。
3. MCP ツールが利用可能な場合は、references/mcp.md をお読みなり、その後、start_xlsform_session 経由でコピーされたファイルをアップロードします。MCP が利用できない場合、入手可能な最高のスプレッドシート/XLSX ツール でコピーされたワークブックを直接開きます。
4. 編集する前に、開始構造を完全に読みます。MCP を使用する場合は、返された form_summary を使用します。MCP なしの場合は、ワークシートを直接検査します。次の追加位置、既に存在する正確な列名、既存の再利用可能な選択肢リスト、および現在の設定値に注意してください。
5. 関連編集を 1 回のバッチで適用します。MCP を使用する場合、単一の xls_apply_patches 呼び出しと change_setting を form_id、form_title、default_language に使用してください。MCP なしの場合、コピーされたワークブックの既存ワークシートに直接書き込みます。
6. 結果をエクスポートまたは保存します。MCP を使用する場合、export_xlsform を使用し、download_url をユーザーに手渡してください。ユーザーに、アップロード時に SurveyCTO コンソールで必要な .fieldplugin.zip ファイルをアタッチするよう通知してください。

テンプレートが必須である理由: 条件付き書式ルール、ヘルプワークシート、列ヘッダー、スターター メタデータ フィールド、数式ベースのバージョン管理、および事前にフォーマットされた行が含まれており、プログラムでは確実に再作成できません。テンプレートをスキップすると、技術的には有効ですが、人間が Excel で編集するのに苦しいファイルが生成されます。

テンプレートは以下を提供します:

• 正しい列ヘッダーとスターター メタデータ フィールド (隠し監査計算と caseid 行を含む) を備えた survey ワークシート
• ヘッダーと yesno 選択肢リスト付きの choices ワークシート
• ヘッダーと自動更新 version 式付きの settings ワークシート
• リファレンスドキュメント付きの help-survey、help-choices、help-settings ワークシート
• フィールドタイプ別に行を色分けする条件付き書式ルール

編集ルール (すべてのパスに適用)

• 既存のすべてのワークシートを保持してください 。テンプレートまたは既存のフォーム内に存在する help-survey、help-choices、help-settings およびその他のシートを含める。
• 既存のフォーマットを保持してください 。条件付き書式、列幅、またはセルスタイルをクリアまたは上書きしないでください。
• データを含むまたは含む行にのみ書き込んでください。 コンテンツの下の未使用行にタッチしないでください。既に空のセルをクリアするために空の文字列または None を書き込まないでください。
• 既存のデータの後に新しい行を追加してください。 固定のスターター行数を想定しないでください。テンプレートにはいくつかの事前入力されたメタデータおよび計算行 (隠し監査計算と caseid 行を含む) が付属しており、既存のフォームは任意の数の行を持つ可能性があります。MCP を使用する場合、add_row は自動的に追加されます。行インデックスを計算する必要はありませんが、form_summary (counts.n_rows または survey_preview_rows の最大 excel_row) から、または必要な場合は xls_get_rows をページングして導出できます。MCP なしの場合は、survey (および choices) でスキャンして、最初の行を見つけます。これにより、type/list_name および周囲の列がすべて空になり、そこに追加します。
• settings の version セルを上書きしないでください 。自動更新式が含まれています。(MCP サーバーの export_xlsform はこれを自動的に再計算します。)
• デフォルトではプレーンラベルを使用してください。 SurveyCTO はラベル、ヒント、ノート、またはメッセージで Markdown をレンダリングしません。プレーンテキストを優先してください。単純なインライン HTML のみを使用してください (実質的に助けになる場合)。ラベル、ヒント、メッセージフォーマット を参照してください。

編集ワークフロー

1. 正しいベースから開始してください — テンプレートをコピー (新規フォーム) または既存ワークブックをロード。
2. パッチを書く前に references/xlsform.md をお読みください。 これは既存のフォームの編集と同じくらい新しいフォームに適用されます。列名、式構文、または多言語規約について一般的な ODK メモリに頼らないでください。前提条件: XLSForm リファレンスを読む を参照してください。
3. 既存の構造を読んでください 。何があるかを知るために。
   • MCP 利用可能: start_xlsform_session でアップロード、その後返された form_summary をスターティング概要として使用。概要が提供するより多くの詳細が必要な場合のみ xls_get_rows を呼び出してください。
   • MCP なし: すべての 3 つのシートを開いて読みます。
4. 編集を計画してください 。追加/変更する行と セル値を特定します。
5. 適用 — 適切な行と列に セル値を書き込みます。
   • MCP 利用可能: xls_apply_patches。
   • MCP なし: セルを直接書き込みます。
6. 下記のチェックリストに対して検証します。
7. 保存 / エクスポート — MCP 利用可能の場合、export_xlsform は式の再計算を実行してファイルを返します。MCP なしの場合、ワークブックを保存し、利用可能な最高の再計算パスを使用します。

一般的な操作

• フィールドを追加: survey の次の空行に type、name、label (最低限) を書き込みます。グループとリピートに対して正しい位置に配置します。
• 選択肢リストを追加: choices に list_name、value、label 行を書き込みます。list_name が select_one/select_multiple タイプで参照されているものと一致することを確認してください。
• グループを追加: begin group 行と同じ name でマッチする end group 行。それらの間にフィールドを配置します。
• リピートを追加: begin repeat / end repeat 行。マッチング name 。必要に応じて repeat_count を設定します。
• スキップロジックを追加: ターゲット行の relevance 列に式を書き込みます。
• 制約を追加: constraint に式を書き込みます (現在値には . を使用); ユーザー向けメッセージを constraint message に書き込みます。
• 計算を追加: type=calculate、一意の name、calculation 内の式を持つ行。
• 設定を更新: MCP を使用する場合、change_setting を form_title、form_id、default_language に使用します。MCP なしの場合、これらの値を settings の行 2 に書き込みます。version はそのままにしておきます。

検証チェックリスト

編集後に確認してください:

• すべての name 値はフォーム全体で一意です
• name にスペースまたは特殊な句読点が含まれていません
• すべての begin group に一致する end group (同じ name) があります
• すべての begin repeat に一致する end repeat (同じ name) があります
• グループとリピートは適切にネストされています (重複なし)
• すべての select_one [list] / select_multiple [list] は choices に存在するリストを参照しています
• すべての選択肢リストは value と label を持つ少なくとも 1 行を持っています
• 式の ${fieldname} 参照は存在するフィールドをポイントしています
• 式は SurveyCTO 規約を使用しています (== ではなく =、position() ではなく index() など)
• ラベル、ヒント、ノート、メッセージはプレーンテキストまたはシンプルなインライン HTML フラグメントを使用しており、Markdown ではなく
• settings に form_title と form_id があります
• フォーム内のすべての custom-<name> appearance には、ユーザーがアタッチする対応する <name>.fieldplugin.zip があります
• フォームをユーザーに返すとき、SurveyCTO コンソールのアップロード時にすべての必須 .fieldplugin.zip をアタッチするようユーザーに明確に通知してください。 スキルと MCP サーバーはローカルファイルのみを編集します。アップロードやアタッチは行いません

データセット XML 定義

データセット定義は <dataset> ルート要素を持つ XML ファイルです。列構造、フォーム添付、および発行ルールを定義します。

キー要素

要素	目的
<id>	pulldata() および search() 呼び出しで使用されるデータセット ID
<title>	表示名
<datasetType>	SERVER、CLIENT、または REPORT
<fieldNames>	コンマ区切り列名/順序
<formLinks>	事前読み込みのためこのデータセットをアタッチするフォーム
<dataLinks>	発行ルール (フォームからの着信、ファイルへの発信)
<caseManagementOptions>	ケース管理表示とワークフロー設定
<uniqueRecordField>	アップサート用の一意キーとして使用される列

クリティカルな注記

• 要素名は 大文字小文字を区別します (例: otherUserCode、otherUsercode ではなく)。
• <formLinks> および <dataLinks> 内のフォームは、定義をアップロードする前にデプロイする必要があります。
• <showColumnsWhenTable> にはコンマ区切り文字列ではなく、複数の <columnNames> 子要素が含まれています。

完全なリファレンス: references/datasets-xml.md。

Data Explorer ワークブック定義

Data Explorer ワークブックは 4 つのワークシート付き XLSX ファイルです: summaries、settings、global_filters、global_exclusions。

summaries ワークシートは可視化を定義します。各行は type (text、categorical、numeric、temporal、scatterplot、crosstab など) と field 参照を持つサマリーです。グループは、マッチング label 値を持つ begin group / end group を使用します。

完全なリファレンス: references/data-explorer.md。

フィールドプラグイン

フィールドプラグインは、単一のフォームフィールドのレンダリングを引き継ぐ .fieldplugin.zip バンドル (zip ルートで HTML/CSS/JS) です。プラグインは text、integer、decimal、select_one、select_multiple フィールドでのみサポートされており、SurveyCTO Collect (Android)、SurveyCTO Collect for iOS、Web フォーム内で実行されます。

フィールドプラグインを使用する場合

ネイティブフィールドタイプとアピアランスをデフォルトとしてください。プラグインは実際のコスト (添付管理、バージョンバンプ、アグレッシブなキャッシング、クロスプラットフォーム (Android/iOS/Web) テスト) を追加するため、必要な動作または UX をネイティブフィールドが配信できない場合にのみそれらに向かってください。この順序で決定してください:

1. ネイティブフィールドとアピアランスを最初に。 ほとんどのニーズは組み込み type/appearance 組み合わせで満たされます。
2. フィールドプラグインカタログ からそのまま使用してください。 維持されたカタログプラグインが既に必要なことを実行している場合、何を作成せずにアタッチしてください。
3. 既存のプラグインをカスタマイズしてください。 最も近いカタログプラグインまたは SurveyCTO baseline-* リポジトリを GitHub からダウンロード (Code → Download ZIP)、またはユーザーが Git に快適な場合はクローン/フォークしてから、バンドルルートの 4 つのファイルを編集します。
4. バンドルテンプレートから開始。 assets/field-plugin-template/ は意図的に最小限のテキストのみのスケルトン です。オフラインの開始点または最小読み取り表面に便利ですが、baseline-text が提供するいくつかの動作を省略しています (バンドルテンプレートが省略する内容 を参照)。必要な場合は、これらを手動で追加してください。

エージェント動作ルール: フォームがプラグインから利益を得る可能性がある場合、トレードオフ (追加の複雑性 対 機能/UX 獲得) を提示し、プラグイン依存性をユーザーに確認してから追加してください。ユーザーが明示的にプラグイン使用を指示していない限り、custom-<name> アピアランスを単独で追加したり、.fieldplugin.zip ファイルをアタッチしたりしないでください。

フォーム内の既存プラグインを使用

1. フォームに .fieldplugin.zip をアタッチします (Form Designer → Attachments、または XLSForm をアップロードするときの通常のフォーム添付として)。
2. フィールドで、appearance を custom-<filenamestem> に設定します 。zip ファイル名の前の部分 (例: myplugin.fieldplugin.zip → custom-myplugin) — オプショナルで (key=value, …) パラメータ。

作成 (ユーザーがプラグインを構築したい場合)

上記の決定順に従ってください。具体的に:

• 推奨開始ポイント: 最も近い SurveyCTO ベースラインプラグイン (フィールドタイプ用: baseline-text、baseline-integer、baseline-decimal、baseline-select_one、baseline-select_multiple) — または密接に関連するカタログプラグイン — を GitHub の Code → Download ZIP ボタンから ZIP としてダウンロードしてから、カスタマイズしてください。ユーザーが Git ワークフローを優先する場合、クローンまたはフォークは同じくらい機能します。そうでない場合、Git ツールは必要ありません。
• 最小/オフライン代替: assets/field-plugin-template/ をコピーしてください。これはオリジナルコードであり、baseline-text のコピーではなく、複数のベースライン動作を意図的に省略しています (メディアレンダリング、ラベル/ヒント内の HTML エンティティアンエスケープ、標準 numbers/numbers_decimal/numbers_phone アピアランス処理、ソフトキーボード呼び出し、読み取り専用デフォルト placeholder フォールバック、空の値の表示)。完全なリストについては references/field-plugins.md をご覧ください。
• バンドルルートの 4 つのファイルを編集してください: manifest.json、template.html、style.css、script.js。{{{LABEL}}} および {{{HINT}}} に常にトリプルブレース Mustache を使用してください (HTML を含む可能性があります)。
• <name>.fieldplugin.zip として再パッケージしてください。すべてのファイルを zip ルートに (サブディレクトリはアップロード時にフラット化されます)。再アップロードするたびに manifest.version をバンプしてください。

テスト

• ローカル高速ループ: assets/field-plugin-test-harness/ に validate.mjs (静的チェック) と preview.html (編集可能なフィクスチャと スタブ化されたホストブリッジに対してプラグインをレンダリングする単一のセルフコンテイドブラウザハーネス) が付属しています。ハーネスはエージェント UI でのインライン HTML/JS アーティファクトとして機能します (それがサポートしている場合)。テキストエリアにプラグインソースを事前入力し、プラグインの進化に伴い更新します。
• 最終検証: フォームデザイナーのテストビューのインプロダクト フィールドプラグインコンソール 。デプロイ前に必須。ローカルハーネスのスタブは、実際の Android/iOS/Web フォームランタイムの完全な代替ではありません。

その他のすべてについて — 完全なマニフェストスキーマ、フォーム API (フィールドプロパティ、ランタイム CSS クラス、提供/呼び出し JS 関数)、パラメータとメタデータモデル、Android のみの意図と電話 API、および一般的な落とし穴 — references/field-plugins.md をご覧ください。

一般的なパターン

カスケード選択

別のフィールドの選択に基づいて 1 つのフィールドの選択肢をフィルター処理します:

1. choices で、子リストに filter 列 (例: region) を追加します。
2. survey で、子フィールドの choice_filter を設定します: region = ${region}。

pulldata() を使用した事前読み込みデータ参照

1. ルックアップデータを含む CLIENT データセットを作成します。
2. データセット定義の <formLinks> を使用してフォームにアタッチします。
3. calculation で pulldata('dataset_id', 'column_to_return', 'lookup_column', ${key_field}) を使用します。

事前読み込みデータからの動的選択リスト

1. CLIENT データセットを作成してフォームにアタッチします。
2. survey で、type を select_one listname に設定し、appearance を search('dataset_id') に設定します (またはより特定的な検索式)。
3. choices で、listname に 1 行を追加し、value と label にはデータセットのリテラル値ではなく列名を含めます。

search() 構文パターンについては references/xlsform.md を参照してください。

リピートグループからのランダムサンプリング

1. リピート内: calculation フィールド (計算 = once(random()))。
2. リピート外: rank-index(1, ${random_calc}) はランダムに選択されたインスタンスのインデックスを返します。

カスタムフィールドプラグインを使用

プラグインをフォームに追加する前に、追加の複雑性が獲得された機能の価値があることをユーザーに確認し、フォームをアップロードするときに .fieldplugin.zip を自分でアタッチする必要があることを思い出させてください。

フォームに .fieldplugin.zip をアタッチしてから、フィールドに appearance を custom-<filenamestem> に設定します (プラグインが期待するパラメータを持つ)。<filenamestem> は zip ファイル名の前の部分です (例: phonenumber.fieldplugin.zip → custom-phonenumber)。manifest.json 内の name フィールドは人間が読める表示名であり、アピアランスをドライブしません。

type	name	appearance
text	phone	custom-phonenumber(country='US', placeholder=${default_format})

パラメータ値はプラグインが読み込まれる前にフォームによって評価されるため、${field} 参照と完全な SurveyCTO 式が機能します。プラグインでは、fieldProperties.PARAMETERS のインデックスの代わりに getPluginParameter('country') でパラメータを読み取ります。完全なリファレンス: references/field-plugins.md。

フォームデータをデータセットに発行

データセット XML で、以下を持つ <dataLink> を追加してください:

• <dataLinkClass>FORM</dataLinkClass>
• <dataLinkType>INCOMING</dataLinkType>
• <linkObjectId>form_id</linkObjectId>
• フォームフィールドをデータセット列にマップする JSON を持つ <fieldMap>

一般的な問題のデバッグ

症状	可能性のある原因	修正
フォームはアップロードされません	name 値の重複	name 列の重複をスキャン
フォームはアップロードされません	バランスの取れていないグループ/リピート	すべての begin/end ペアをチェック
フィールドは表示されません	不正な relevance 式	構文を確認し、参照されたフィールドが存在することを確認
制約は決して成功しません	. vs ${fieldname} の間違った使用	制約では、. は現在のフィールド; ${fieldname} は別のフィールド
選択肢が不足しています	list_name 不一致	select_one [list] は choices の list_name と一致する必要があります
select_multiple ロジックは失敗します	selected() の代わりに = を使用	常に selected(${field}, 'value') を使用してください
日付の比較は失敗します	文字列を日付と比較	ラップしてください: ${field} > date('2024-01-01')
データセットはアップロードされません	参照されたフォームがデプロイされていません	<formLinks> および <dataLinks> 内のすべてのフォームを最初にデプロイ
データセット要素が無視されます	大文字小文字の区別エラー	正確なケース (例: otherUserCode) をチェック
プラグインフィールドが表示されない / custom-<name> が無視される	プラグイン .fieldplugin.zip がアタッチされていない、名前不一致、またはサポートされていないフィールドタイプ	zip を再アタッチしてください。custom-<name> トークンが .fieldplugin.zip ファイル名の語幹 (例: myplugin.fieldplugin.zip → custom-myplugin) と一致することを確認してください。manifest.name ではなく。プラグインは text/integer/decimal/select_one/select_multiple でのみ機能します
プラグイン回答が保存されません	setAnswer が呼び出されていない、またはコンマで結合された select_multiple 値	入力イベントを setAnswer(value) にワイヤしてください。select_multiple の場合、スペース区切りリストを渡してください
プラグイン添付ファイルのランタイムで 404	ファイルは zip 内のサブディレクトリに配置	zip をフラット化 — すべてのファイルをルートに、重複なし

リファレンス

入門書	読む時期
references/overview.md	最初 — 方向付け、ファイルタイプ、どう一緒に適合するか
references/xlsform.md	任意の XLSForm 作業前に必須 — 列規約、式、グループ/リピート、多言語
references/expressions.md	任意の式作業 (relevance、constraint、calculation、choice_filter)
references/datasets-xml.md	サーバーデータセット XML 定義
references/data-explorer.md	Data Explorer ダッシュボード
references/field-plugins.md	フィールドプラグイン作成、パッケージング、フォーム API、テスト

キードキュメントリンク

• Designing forms: core concepts
• Using expressions in your forms
• Grouping and repeating questions
• Using constraints to validate responses
• Implementing skip patterns with relevance
• Introduction to advanced dataset usage
• Working with server dataset XML files
• Advanced use of Data Explorer workbooks
• Using field plug-ins
• Field plug-in developer documentation (GitHub)
• SurveyCTO Support Center