Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

wizards

/wizards

Zbiera dane wejściowe przed operacją w oknie dialogowym, wykorzystując tymczasowy obiekt w modelu i akcję niestandardową.

Repozytorium
claude-plugins ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Zbiera dane wejściowe przed operacją w oknie dialogowym, wykorzystując tymczasowy obiekt w modelu i akcję niestandardową.

Oryginalny opis (EN)

Collect input or a selection before an operation with a transient PO opened as a dialog: declared in model JSON only (`StateBehavior: 8`), returned from a custom action's `Execute` via `GetPersistentObject(..., isNew: true)`, `ActionLabels` in `OnNew`, the work run in `OnSave` after `CheckRules`; plus the two-pass `RetryAction`/`RetryResult` and the bulk-assign carrier. PROACTIVE: invoke when the user needs a popup/dialog/wizard before an action, a bulk assign, or mentions transient PO, RetryAction, ActionLabels. Not for the button itself (see /vidyano:custom_actions).

Jak działa

  1. When to use
  2. 1 — Declare the dialog in model JSON
  3. 2 — The action that opens it
  4. 3 — Seed defaults and relabel Save in OnNew
  5. 4 — Run the operation in OnSave
  6. Refreshing the client
  7. Variant — the lighter RetryAction / RetryResult confirm-and-apply
  8. Variant — multi-select bulk assign
  9. Declaring the rights
  10. Checklist
Sekcje z nagłówków SKILL.md, w oryginale · 267 linii, 2 033 słów
Podgląd SKILL.md
---
name: wizards
description: "Collect input or a selection before an operation with a transient PO opened as a dialog: declared in model JSON only (`StateBehavior: 8`), returned from a custom action's `Execute` via `GetPersistentObject(..., isNew: true)`, `ActionLabels` in `OnNew`, the work run in `OnSave` after `CheckRules`; plus the two-pass `RetryAction`/`RetryResult` and the bulk-assign carrier. PROACTIVE: invoke when the user needs a popup/dialog/wizard before an action, a bulk assign, or mentions transient PO, RetryAction, ActionLabels. Not for the button itself (see /vidyano:custom_actions)."
user-invocable: true
---

# Wizards & Multi-Step Dialogs

Some operations need input before they can run. Recalculating a month needs to know *which* month. Bulk-assigning people to a department needs the department. None of these is a record the user is creating — there is nothing to persist. What you want is a small modal form that collects a parameter (or a selection), runs a domain operation when the user confirms, then refreshes the screen.

A wizard is built from pieces you already know: a custom action returns a **transient** PersistentObject — a PO declared only in model JSON, with no backing C# entity — and the framework opens it as a dialog. The PO is never stored. Its `OnSave` hook is simply *where the real work runs* once the user has filled the form and pressed the (relabelled) Save button. The key shift from an ordinary New flow: **the dialog PO is a form, not a record.**

Not for: the toolbar button itself and its right (`/vidyano:custom_actions`), the general `OnNew`/`OnSave` pipeline of a *real* record (`/vidyano:lifecycle_hooks`), or a paste-a-list intake dialog (`/vidyano:imports`).

## When to use

The user needs a popup/dialog/wizard to collect a parameter or selection before an action, a confirm-then-apply prompt, or a bulk-assign over selected rows — or mentions a transient PO, `StateBehavior 8`/`OpenAsDialog`, `GetPersistentObject`, `RetryAction`/`RetryResult`, `ActionLabels`, or `QueueClientOperation`.

The flow is always the same:

1. A custom action's `Execute` returns the transient PO → the framework opens it as a modal dialog.
2. `OnNew` seeds defaults and relabels the Save button to a verb.
3. The user fills the form and clicks the verb.
4. `OnSave` validates, runs the domain operation, and refreshes the client.

The worked example below: an action on a `Company` that recalculates a chosen month's headcount.

## 1 — Declare the dialog in model JSON

The dialog has no backing entity, so it lives entirely in model JSON. Two fields make it behave as a dialog: `"StateBehavior": 8` (`OpenAsDialog`) renders it as a modal popup instead of a full page, and `"NewBreadcrumb"` sets the header text:

```json
{
  "PersistentObject": {
    "SchemaName": "Acme",
    "Type": "RecalculateMonth",
    "NewBreadcrumb": { "en": "Select month" },
    "StateBehavior": 8,
    "Attributes": [
      {
        "Name": "Month",
        "Offset": 10,
        "DataType": { "$ref": "DataType:Date" },
        "DataTypeHints": "DisplayFormat={0:y}",
        "Label": { "en": "Month" }
      }
    ],
    "Queries": []
  },
  "Queries": [],
  "Reports": []
}
```

Attribute `Required`/`NotEmpty` rules belong here too — `CheckRules` (step 4) enforces them server-side. If the PO type happened to carry queries you don't want, suppress them at open time with `ignoreQueries: true`. The dialog type and its attributes are model changes: run a schema synchronize (in CronosCore repos, `/dcg:synchronize`) so `Types.RecalculateMonth` and `AttributeNames.RecalculateMonth.*` exist before the C# below compiles.

## 2 — The action that opens it

The action is a `/vidyano:custom_actions` whose `Execute` returns the transient PO. Because the returned PO's `StateBehavior` is `OpenAsDialog`, the framework pops it as a modal:

```csharp
namespace Acme.Service.CustomActions;

public partial class RecalculateMonth : CustomAction<AcmeContext>
{
    // The action lives on a Company grid/record; the dialog gathers one parameter (a month).
    public override PersistentObject? Execute(CustomActionArgs e) =>
        Manager.Current.GetPersistentObject(Types.RecalculateMonth, e.Parent?.ObjectId, isNew: true, targetContext: Context);
}
```

The second argument is the **parent ObjectId** — the id of the record the action was invoked on. The framework stamps it onto the transient PO's `ObjectId`, which is how `OnSave` later knows *which* `Company` to recompute. On a grid there is no parent, so `e.Parent` is null and `ObjectId` comes through empty — branch on that to recompute for one company versus all of them. Assert placement at the top of `Execute` with `e.EnsureParent(Types.Company)` or `e.EnsureQuery()`.

## 3 — Seed defaults and relabel Save in OnNew

`OnNew` on the dialog's `*Actions` partial runs as the transient PO is created. Give parameters sensible defaults and — importantly — relabel the Save button. The user is triggering an operation, not saving a record, so the button should read as a verb:

```csharp
namespace Acme.Service.Actions;

public partial class RecalculateMonthActions
{
    public override void OnNew(PersistentObject obj, PersistentObject? parent, Query? query, Dictionary<string, string>? parameters)
    {
        base.OnNew(obj, parent, query, parameters);

        var today = Manager.Current.Today;
        obj[AttributeNames.RecalculateMonth.Month].SetValue(new DateTime(today.Year, today.Month, 1));
        obj.ActionLabels[ActionNames.Save] = "Recalculate";   // verb instead of "Save"
    }
}
```

`ActionLabels[ActionNames.Save]` is the lever — set it to `"Run"`, `"Assign"`, `"Recalculate"`, whatever names the operation. `OnNew` is also where you seed an attribute's selectable `Options` at runtime if a field's choices depend on context.

## 4 — Run the operation in OnSave

When the user presses the verb, `OnSave` fires. There is nothing to persist about the PO itself — this hook is simply *where the operation runs*. **Always call `CheckRules(obj)` first and return early if it fails** — that is what enforces the attribute `Required`/`NotEmpty` rules declared in model JSON (they are NOT applied automatically here). Then read the parameter, load the real aggregate from `ObjectId`, do the work, and save the *domain* changes:

```csharp
public partial class RecalculateMonthActions
{
    // A form, not a record: no base.OnSave here — it would run SaveNew on a PO with no backing entity.
    public override void OnSave(PersistentObject obj)
    {
        if (!CheckRules(obj))
            return;

        var month = (DateTime)obj[AttributeNames.RecalculateMonth.Month];
        var companyId = obj.ObjectId;                          // the source record id; empty when opened from a grid

        RecomputeHeadcount(Context, month, companyId);         // the real domain operation
        Context.SaveChanges();

        Manager.Current.QueueClientOperation(RefreshOperation.Query(QueryNames.CompanyHeadcountPeriods));
    }

    // Shared with the scheduled job, which calls it headlessly with no dialog.
    public static void RecomputeHeadcount(AcmeContext context, DateTime month, string? companyId)
    {
        var companies = string.IsNullOrEmpty(companyId)
            ? context.Companies.ToArray()
            : [context.Session.Load<Company>(companyId)];

        foreach (var company in companies)
            company.Headcount = context.Employees.Count(emp => emp.Company == company.Id && emp.StartDate <= month);
    }
}
```

`obj.ObjectId` here is the **source record's** id (the parent passed into `GetPersistentObject`), not an id belonging to the dialog. Load the aggregate from it with `Context.Session.Load<Company>(obj.ObjectId)` when you need the full entity. Keep the real work in a **shared/static method** so the dialog and any scheduled job run identical logic.

## Refreshing the client

The operation mutated data the user is looking at, so tell the client to refresh — `QueueClientOperation` queues a refresh that runs once `OnSave` returns:

```csharp
// Refresh a grid the operation touched.
Manager.Current.QueueClientOperation(RefreshOperation.Query(QueryNames.CompanyHeadcountPeriods));

// Or refresh the parent record itself after mutating it.
Manager.Current.QueueClientOperation(new RefreshOperation(e.Parent));
```

Inside `OnSave` (or `OnAddReference`) you can also call `obj.QueueQueryRefresh(QueryNames.CompanyHeadcountPeriods)` directly on the PO — same effect, fewer keystrokes. Refresh the query when a grid changed; refresh the parent PO when you wrote values back onto it.

## Variant — the lighter RetryAction / RetryResult confirm-and-apply

When the dialog is a single confirm-and-apply — no separate save round-trip, often just an option button or two — `RetryAction`/`RetryResult` is lighter. It needs only the dialog PO type; you write **no `OnSave` at all**. The catch is that it is a **two-pass protocol**: `Execute` runs twice.

```csharp
public partial class ChangeOrderDiscount : CustomAction<AcmeContext>
{
    public override PersistentObject? Execute(CustomActionArgs e)
    {
        e.EnsureParent(Types.Order);

        // First pass: no answer yet — pop the dialog with Apply / Cancel buttons and return.
        if (Manager.Current.RetryResult is null)
        {
            var dialog = Manager.Current.GetPersistentObject(Types.ChangeOrderDiscountDialog, isNew: true);
            Manager.Current.RetryAction("Change order discount", "Enter the new discount percentage.", dialog, "Apply", "Cancel");
            return null;
        }

        // Second pass: the framework re-invoked Execute with the user's answer.
        var result = Manager.Current.RetryResult;
        if (result.Option == "Apply")
        {
            var percent = (decimal)result.PersistentObject[AttributeNames.ChangeOrderDiscountDialog.Percent];
            var order = Context.Session.Load<Order>(e.Parent!.ObjectId);
            order.DiscountPercent = percent;
            Context.SaveChanges();

            Manager.Current.QueueClientOperation(new RefreshOperation(e.Parent));
        }

        return null;
    }
}
```

On the **first pass** `RetryResult` is null, so you call `RetryAction(title, message, dialogPO, "Option1", "Option2")` and **return `null`** — the framework shows the modal with those named buttons. When the user answers, the framework **re-invokes `Execute`**; now `RetryResult` is non-null and carries `.Option` (the button pressed) and `.PersistentObject` (the filled-in dialog). Branch on `.Option`, do the work, refresh. Ideal for a confirm-then-apply where the whole operation fits in the action and there is no separate dialog `*Actions` class.

## Variant — multi-select bulk assign

The transient-dialog pattern extends to bulk operations: the user multi-selects grid rows, the action collects them, and the dialog asks for the *one* thing the operation still needs — a target. The only new wrinkle is carrying the selection into the transient PO.

The selected rows arrive on `e.SelectedItems` — each `QueryResultItem` exposes `.Id` (the document id) and `.GetValue(...)` for any column. The idiomatic carrier is a **newline-joined id string in a hidden `MultiLineString` attribute**; pair it with a read-only attribute holding human-readable names so the user can verify the selection:

```csharp
public partial class AssignToDepartment : CustomAction<AcmeContext>
{
    public override PersistentObject? Execute(CustomActionArgs e)
    {
        e.EnsureQuery();

        var personIds   = e.SelectedItems!.Select(si => si.Id!);
        var personNames = e.SelectedItems!.Select(si => si.GetValue(AttributeNames.Person.FullName)!);

        var dialog = Manager.Current.GetPersistentObject(Types.AssignToDepartment, isNew: true, ignoreQueries: true, targetContext: Context)!;

        // Selection ride-along: ids in a hidden carrier, names in a read-only display attribute.
        dialog[AttributeNames.AssignToDepartment.People].SetValue(string.Join('\n', personIds));
        dialog[AttributeNames.AssignToDepartment.Display].SetValue(string.Join('\n', personNames));

        return dialog;
    }
}
```

`ignoreQueries: true` keeps the dialog clean by suppressing any grids the PO type might carry. Use `SetOriginalValue(...)` instead of `SetValue(...)` for the hidden carrier when you want to seed it without flagging the attribute dirty. For a soft conflict, surface it non-blockingly with `dialog.AddNotification(text, NotificationType.Warning)`.

`OnSave` splits the carrier back into ids, loads the target, and folds the selection in. **Filter against what the target already has** before appending — that keeps re-running the wizard idempotent, so you never create duplicate links:

```csharp
public partial class AssignToDepartmentActions
{
    public override void OnSave(PersistentObject obj)   // again: no base.OnSave on a transient form
    {
        if (!CheckRules(obj))
            return;

        // The framework auto-splits the newline-joined MultiLineString back into a string[];
        // cast directly — do NOT ((string)...).Split('\n').
        var personIds  = (string[])obj[AttributeNames.AssignToDepartment.People]!;
        var department = Context.Session.Load<Department>((string)obj[AttributeNames.AssignToDepartment.Department]!);

        var existing = department.Members.Select(m => m.Person).ToArray();
        foreach (var personId in personIds.Where(id => !existing.Contains(id)))
            department.Members.Add(new DepartmentMember { Person = personId });

        Context.SaveChanges();
    }
}
```

A heavier alternative exists when you want the framework's built-in reference-picker grid rather than a pre-collected selection: `AddReference(QueryNames.SelectPeople_Items)` opens a selection grid and the chosen rows arrive in `OnAddReference(parent, entities, query, selectedItems)`. To survive a confirm round-trip (an `AddReference` followed by a `RetryAction`), stash the in-flight selection in `Manager.Current.User.Profile["key"]` and read it back with `.Profile["key"].FromServiceString<T>()`. Reach for the simpler transient-PO carrier above unless you specifically need that built-in picker grid.

## Declaring the rights

A wizard needs **two** security rights, not one — forgetting the first makes the button appear but do nothing:

- `New/<Schema>.<TransientPO>` — so the user is allowed to open the dialog PO (e.g. `New/Acme.RecalculateMonth`).
- `<ActionName>/<Schema>.<SourceType>` — the per-action right that makes the button visible on the source query/record (e.g. `RecalculateMonth/Acme.Company`).

Grant **both** to the action's group in `security.json`.

## Checklist

- [ ] Dialog declared in model JSON only — `"StateBehavior": 8`, `"NewBreadcrumb"`, attribute `Required`/`NotEmpty` rules; no backing C# entity; schema synchronized so `Types.*`/`AttributeNames.*` resolve.
- [ ] `Execute` returns `GetPersistentObject(Types.X, e.Parent?.ObjectId, isNew: true, targetContext: Context)`; `ignoreQueries: true` to suppress grids; assert with `EnsureParent`/`EnsureQuery`.
- [ ] `OnNew`: seed defaults, `obj.ActionLabels[ActionNames.Save] = "<verb>"`.
- [ ] `OnSave`: `if (!CheckRules(obj)) return;` FIRST, load aggregate from `obj.ObjectId`, run a **shared static** operation, `Context.SaveChanges()`, then `QueueClientOperation` / `QueueQueryRefresh`; no `base.OnSave`.
- [ ] Confirm-and-apply alternative: `if (Manager.Current.RetryResult is null) { RetryAction(...); return null; }`, then branch on `.Option` and read `.PersistentObject`; no `OnSave`.
- [ ] Bulk assign: ids in a hidden `MultiLineString`, cast back with `(string[])obj[attr]!` (no manual `Split`), filter against existing members.
- [ ] Rights: BOTH `New/<Schema>.<TransientPO>` and `<ActionName>/<Schema>.<SourceType>` in `security.json`.

## Verify

1. Build; run a schema synchronize (in CronosCore repos, `/dcg:synchronize`) so `Types.RecalculateMonth` resolves, and grant both rights.
2. As a member of the group, the action button shows on the `Company` record; clicking it opens a modal with the `NewBreadcrumb` header, the seeded default and the verb in place of Save.
3. Clear a required field and press the verb: the model-JSON rule message appears and RavenDB Studio shows nothing changed.
4. Fill it in and press the verb: the dialog closes, the refreshed grid shows the recomputed rows, and Studio has no collection named after the dialog type.
5. Negative: without the `New/<Schema>.<TransientPO>` right the button is visible but the dialog never opens; grant the right and retry.

## Related skills

- `/vidyano:custom_actions` — the action that opens the dialog; action rights and button visibility.
- `/vidyano:lifecycle_hooks` — the `OnNew`/`OnSave` save pipeline and `CheckRules`.
- `/vidyano:imports` — a paste-a-list intake wizard is the ingestion cousin of the bulk-assign shape.

Wersje

W bazie nie ma innych skilli o nazwie wizards.

Migawka bazy z 13.11.2026 · wersja paczki 65f125e3de35 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95custom_actions
    Tworzy akcję własną Vidyano, czyli operację po stronie serwera na pasku narzędzi lub w menu kontekstowym, z prawami w security.json.
  • 95business_rules
    Waliduje dane wejściowe w aplikacji Vidyano na właściwej warstwie: reguły atrybutów, sprawdzenia między polami i blokady usuwania.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.