ウィザード

フォームの入力を、戻るボタンと次へボタンで移動する複数のページに分ける

ウィザードとは

ウィザード は、1 つのフォームを一連のページに変えます。各ページは subform から表示され、ユーザーは 戻る ボタンと 次へ ボタンで移動します。検証はページごとに行われ、ステップに optional が付いていない限り、現在のステップが有効になるまで先に進めません。

すべてのウィザードの最後には、読み取り専用の 確認ページ が自動的に追加されます。各ステップと収集した値が一覧表示されるため、ユーザーは送信前に内容を確認できます。確認ページは YAML では宣言 しません。タイトルは現在のロケールから取得されます。

送信すると、 すべてのステップで収集した値が 1 つの extravars のペイロードにまとめられ、ユーザーが 1 つの大きなフォームに入力した場合とまったく同じように、基になる playbook、テンプレート、ワークフローに送信されます。

wizard を持つフォームには独自の fields は不要ですが、 enableForChat は設定できません。また、 subform 自体が wizard を持つことはできません。 起動時の検証 は、ウィザードの起動をステップごとにチェックします。

wizard とワークフローの違いと、両者の組み合わせ方については、FAQ の項目 ウィザードとワークフローの違いは何ですか? を参照してください。

フォームレベルのプロパティ

ウィザードは、1 つのフォームレベルのプロパティで有効にします。

属性 説明
wizard
array
バージョン 6.4.0 で追加

Wizard steps (form-layer)

Turn a form into a multi-page wizard.
Where steps splits the execution into multiple jobs, wizard splits the input of a single form into multiple pages.
Each wizard step references a subform and is rendered as its own page with Back / Next navigation. A read-only review page is appended automatically as the last step — you do not declare it in YAML.
See the Wizard page for all step properties and examples.

例:

1) Three-step wizard

name: Provision host
type: ansible
roles:
  - default
playbook: provision.yml
wizard:
  - subform: basics
    title: Basics
  - subform: network
    title: Network
    defaultModel: net
  - subform: advanced
    title: Advanced
    optional: true
    when: $(__parent__.basics.kind) === 'vm'

2) Wizard mapped one-to-one onto multistep (defaultModel + key)

name: Provision and verify host
type: multistep
roles:
  - default
wizard:
  - subform: basics
    title: Basics
    defaultModel: basics      # wraps fields under `basics`
  - subform: network
    title: Network
    defaultModel: network     # wraps fields under `network`
steps:
  - name: Create host
    type: ansible
    playbook: create_host.yml
    key: basics                # receives only the basics payload
  - name: Configure network
    type: ansible
    playbook: configure_network.yml
    key: network                # receives only the network payload

ウィザードのステップのプロパティ

Each wizard step references a subform and is rendered as its own page with Back and Next navigation. The user must validate one step before moving to the next; data from earlier steps is available in later steps via __parent__.

Review step is automatic. A read-only summary page that lists every step’s input is appended as the last page of the wizard. You do not declare it in YAML — its title is taken from the active locale (“Summary” / “Samenvatting” / “Zusammenfassung” / …).

Wizard vs Multistep. steps splits the execution into multiple sequential jobs (each step is its own playbook/template). wizard splits the input of a single form into multiple pages — only one job runs at the end. The two can be combined: a type: multistep form can also have a wizard: block to gather its extravars across pages.

属性 説明
basic
subform
string / 必須

Subform reference
a valid subform name

The name of a type: subform form to render on this wizard page. The subform’s fields become this step’s inputs.

例:

1) Reference a subform

wizard:
  - subform: basics
  - subform: network
name
string

Step namespace key
alphanumeric + dash + underscore

The key under which this step’s values are exposed to later steps via $(__parent__.<name>.<field>).
Defaults to the value of subform when omitted.
Set this explicitly when you reuse the same subform multiple times in the same wizard, or when you want a stable key independent of the subform name.

例:

1) Override the namespace

wizard:
  - subform: address
    name: shipping
  - subform: address
    name: billing
title
string

Page title in the stepper
free text

Title shown in the wizard stepper and at the top of the page.
Defaults to the subform’s description, or to the step’s name if no description is set.

例:

1) Custom title

wizard:
  - subform: basics
    title: Tell us about your host
help
string

Help text shown on this page
free text (markdown supported)

Help text rendered on the wizard page. Defaults to the subform’s own help when omitted.
showHelp
boolean

Show help on load
true, false

When true, the help block is expanded by default when the user lands on this page. Falls back to the subform’s showHelp when omitted.

既定値:
false
defaultModel
string

Wrap this step's output under a prefix
a model path (dot notation allowed)

Wraps every field of this step under the given object key in the final extravars payload. Useful when you reuse a generic subform and want its values namespaced.
Without defaultModel, fields are merged into the top level of the extravars (still grouped per step under __parent__ for cross-step references).

例:

1) Wrap network fields under `net`

wizard:
  - subform: network
    defaultModel: net

# The subform has fields `hostname` and `ipv4`.
# Final extravars contain:
#   net:
#     hostname: ...
#     ipv4: ...
workflow
when
expression

Conditionally show this step
a JavaScript expression returning truthy/falsy

When the expression evaluates falsy, the step is hidden entirely — the user never sees it and its values are not collected.
The expression has access to all earlier steps via __parent__.<stepname>.<field>. Steps after a hidden one are renumbered automatically.
Note: when is purely about visibility; it is unrelated to optional, which is about whether the user is allowed to skip a visible step.

例:

1) Only show when kind is "vm"

wizard:
  - subform: basics       # has a `kind` enum field
  - subform: advanced
    when: $(__parent__.basics.kind) === 'vm'
optional
boolean

Allow skipping this step
true, false

When true, the user can press Next even if the step’s fields are not (yet) valid, and Submit is allowed without ever visiting this step.
The step is still shown in the stepper — use when if you want to hide it altogether.

既定値:
false

例:

1) Optional advanced page

wizard:
  - subform: basics
  - subform: advanced
    optional: true
例

1) Minimal wizard (review page is auto-added)

- name: Provision host
  type: ansible
  roles:
    - default
  playbook: provision.yml
  wizard:
    - subform: basics
    - subform: network

- name: basics
  type: subform
  fields:
    - name: hostname
      type: text
      required: true

- name: network
  type: subform
  fields:
    - name: ipv4
      type: text

2) Cross-step reference and namespace prefix

wizard:
  - subform: basics
    title: Basics
  - subform: network
    title: Network
    defaultModel: net          # wraps network fields under `net`

# In the `network` subform you can reference fields
# from the `basics` step like this:
#   default: $(__parent__.basics.hostname).local

ウィザードとワークフローを組み合わせる

ウィザードは ワークフロー フォームの上に重ねられます。ウィザードの各ステップの defaultModel が、対応するワークフローノードの extra_vars_key と一致する場合、各 playbook やテンプレートは、それぞれのウィザードのページの値だけを受け取ります。

FAQ には、具体的な例と、まとめられた extravars の構成が記載されています: ウィザードとワークフローの違いは何ですか?（組み合わせ（ワークフローの上にウィザード） のセクション）。

非推奨の multistep フォーム上のウィザードも同じように動作し、 extra_vars_key の代わりにステップの key を使います。

関連項目

関連するページと FAQ の項目: