Build an admin form

• Add MishkaGervaz.Resource to the resource. See Get Started.
• Have a create, an update and a read action, on the resource or named on the domain. A form with any field needs all three.

The identity name is what MishkaGervaz.Resource.Info.Form.component_id/1 returns. Declare it, and mount the form with that id. Gervaz does not require the id, because the page that mounts the form chooses it.

form do
  identity do
    name :tag_form
  end
end

route is optional. Gervaz stores it, and the built-in form does not redirect with it.

The three form actions usually come from the domain. See How domain defaults work. In edit mode the form fetches the record with the read action. If a field reads a relationship, preload it by role, so that the master and tenant forms load different relationships. The blog post form does this for its collections, tags and bloggers:

source do
  preload do
    master [:master_collections, :master_tags, :master_bloggers]
    tenant [:tenant_collections, :tenant_tags, :tenant_bloggers]
  end
end

The read action of a preloaded relationship must set required?: false on its pagination, because a preload passes no page. Gervaz reports a violation when it compiles.

In the common case a field takes its type from the Ash attribute when you give none: a string is :text, a number is :number, a boolean is :checkbox, a date is :date and a datetime is :datetime. A string or atom attribute with constraints one_of: becomes a :select whose options Gervaz builds from the constraint. A long string, a UUID, a list and a map infer other types. Form fields DSL lists them all. Write options yourself to translate the labels, as the status field below does.

fields do
  field :title, :text do
    required true

    ui do
      label fn -> dgettext("mishka_gervaz", "Title") end
      placeholder fn -> dgettext("mishka_gervaz", "Post title") end
    end
  end

  field :status do
    options fn ->
      [
        {dgettext("mishka_gervaz", "Draft"), :draft},
        {dgettext("mishka_gervaz", "Published"), :published},
        {dgettext("mishka_gervaz", "Scheduled"), :scheduled}
      ]
    end

    ui do
      label fn -> dgettext("mishka_gervaz", "Status") end
    end
  end

  field :content, :textarea do
    required true

    ui do
      label fn -> dgettext("mishka_gervaz", "Content") end
      rows 8
    end
  end
end

A select draws an empty choice ahead of its options. The choice is labeled with ui placeholder when you set one. A required field or one with a default has no empty choice. Otherwise the choice reads "Select...".

Fields take these behavior options in the body, and presentation options in ui:

• required, readonly, visible and restricted gate the field. readonly, visible and restricted take a boolean or a function of the state.
• show_on :create or show_on :update shows the field in one mode.
• virtual true marks a field that is not an attribute of the resource. default is stored with the field, and the built-in form uses it for one thing: a select with a default has no empty choice. Pass starting values with the defaults assign of the mount.
• ui holds label, placeholder, description, icon, debounce, span, rows, autocomplete, add_label, remove_label, disabled_prompt and extra. The options class, wrapper_class and step are accepted, and the Standard form template does not read them.

A field the action neither accepts nor takes as an argument is drawn read-only and left out of the save. A value that is always written left to right, such as a slug, an address or a token, says so with ui do extra %{dir: "ltr"} end.

A :relation field chooses related records. mode, display_field, search_field, min_chars and page_size work as they do on a table filter, except that a function display_field of two arguments is ignored by a form field. value_field stores another attribute of the chosen record in place of its id. The permissions field of a post stores permission names, and picks several:

field :permissions, :relation do
  resource MishkaCmsCore.Accounts.Permission
  display_field :name
  search_field :name
  value_field :name
  mode :search_multi
  page_size 15

  ui do
    label fn -> dgettext("mishka_gervaz", "Permissions") end
  end
end

A many-to-many relation that is not an attribute of the form's resource is a virtual field. It needs a source for its choices, which is a resource, options or options_source. load scopes the choices and is optional. derive_value reads the current choices off the record in edit mode. A virtual field has no attribute to read, so without derive_value the field opens empty when you edit. depends_on names the field it follows.

field :collection_ids, :relation do
  virtual true
  resource MishkaBlog.Collection
  display_field :name
  search_field :name
  mode :search_multi
  depends_on :site_id

  load fn query, state ->
    site_id =
      if state.master_user? do
        Map.get(state.field_values, :site_id)
      else
        Map.get(state.current_user, :site_id)
      end

    Ash.Query.filter_input(query, %{site_id: site_id})
  end

  derive_value fn record ->
    cols =
      cond do
        is_list(Map.get(record, :master_collections)) -> record.master_collections
        is_list(Map.get(record, :tenant_collections)) -> record.tenant_collections
        is_list(Map.get(record, :collections)) -> record.collections
        true -> []
      end

    Enum.map(cols, &to_string(&1.id))
  end

  ui do
    label fn -> dgettext("mishka_gervaz", "Collections") end
  end
end

When a parent changes, Gervaz empties every field that depends on it, directly or down the chain. A value picked under the old parent is never saved, and a required dependent left empty is refused. On a :relation field, include_nil adds a labeled empty choice, such as the "New Language Group (auto-generate)" choice of the tags form. A picked include_nil parent arrives as "__nil__", not as nil.

A :nested field edits an embedded resource or a constrained map column as repeatable rows. The rows are nested_field entities, which accept a narrower set of types: :text, :textarea, :number, :checkbox, :date, :datetime, :select, :hidden, :toggle, :range, :json, :key_map and :key_list.

field :seo_tags, :nested do
  ui do
    label fn -> dgettext("mishka_gervaz", "SEO Tags") end
    add_label fn -> dgettext("mishka_gervaz", "+ Add SEO Tag") end
    remove_label fn -> dgettext("mishka_gervaz", "Remove") end
  end

  nested_field :tag, :select do
    options [{"title", "title"}, {"meta", "meta"}, {"link", "link"}]

    ui do
      label fn -> dgettext("mishka_gervaz", "Tag") end
    end
  end

  nested_field :attrs, :json do
    ui do
      label fn -> dgettext("mishka_gervaz", "Attributes") end
    end
  end

  nested_field :content, :textarea do
    ui do
      label fn -> dgettext("mishka_gervaz", "Content") end
      rows 3
    end
  end
end

When the keys of a map are known and few, draw one control per key instead of asking for JSON. A :key_map edits one map, and a :key_list edits a list of maps with rows the reader adds and removes. Each key is a keyword list with a :name and, optionally, :type, :label, :placeholder and :options. The component form of the page builder declares a slot's options and attributes this way:

nested_field :opts, :key_map do
  options [
    [name: :required, type: :toggle, label: dgettext_noop("mishka_gervaz", "Required")],
    [name: :doc, type: :text, label: dgettext_noop("mishka_gervaz", "What goes in it")]
  ]

  ui do
    label fn -> dgettext("mishka_gervaz", "Options") end
  end
end

A blank key is left out of the stored map, and a toggle left off is left out too, so "not set" stays distinct from "set to nothing". Gervaz reports a nested_field outside a :nested field when it compiles.

Groups put fields in named sections and set the grid. A field may sit in one group. A field in no group still draws, but a wizard step can reach it only through a group. ui do columns N end sets the grid of one group, and layout do columns N end sets the default grid for the form.

groups do
  group :basic_info do
    fields [:site_id, :name, :slug, :language]

    ui do
      label fn -> dgettext("mishka_gervaz", "Basic Information") end
      columns 2
    end
  end

  group :organization do
    fields [:language_group_id, :parent_tag_id]

    ui do
      label fn -> dgettext("mishka_gervaz", "Organization") end
      columns 2
    end
  end
end

The tag form draws its groups in a two-column grid.

The example shows two groups. The real tag form has more under them: Details, which holds Description, and a last group of one-column fields for SEO Tags and Permissions.

restricted true on a field, a group or a button limits it to master users. The tags form shows the site field to masters only, and only when a tag is created:

field :site_id, :relation do
  restricted true
  required true
  show_on :create
  display_field :name
  search_field :name
  mode :search
end

To close a whole mode, use source.access. The permissions form lets only masters create and update:

source do
  access :create, restricted: true
  access :update, restricted: true
end

access :update, false closes a mode for everyone, and then its action need not exist. A denied mode leaves the form without fields.

The labels of the create, update and cancel buttons usually sit on the domain. A resource declares a submit section only where it differs, and the buttons merge one by one. See How domain defaults work.

A notice in the layout draws a banner at a position. The page form of Mishka CMS shows help after the group that holds the field it explains, and only while that field is on the form:

layout do
  notice :permissions_help do
    position {:after_group, :access}
    show_when fn state -> Enum.any?(state.static.fields, &(&1.name == :permissions)) end

    render fn assigns ->
      ~H"""
      <MishkaCmsCore.CoreComponents.tip id="pb-permissions-help" class="mt-2.5 mb-4">
        {dgettext(
          "mishka_gervaz",
          "Who may open this page; empty means everyone. If the page shows records, leave it empty: each record's own Permissions are used."
        )}
      </MishkaCmsCore.CoreComponents.tip>
      """
    end
  end
end

Valid positions and bindings are listed in Form groups and layout DSL.

• Split a form into steps: a wizard or tabs.
• Add file uploads to a form: a dropzone and existing files.
• React to table and form events with hooks: before_save and on_validate.
• Form fields DSL: every option of a field.