A column of a grid: which value of a row it shows, how, and what a person may do with it.

A grid makes its columns from its :col slots (see Masu.Components.data_grid/1):

<:col field={:name} />
<:col field={:total} type={:decimal} label="Total" width={140} />
<:col :let={order} field={:status} type={:enum}>
  <.badge status={order.status} />
</:col>

Types

The type says how the browser formats a value, in the grid's locale, how a filter reads the value it is given, and where the cell aligns:

• :text (the default) and :enum, as they are;
• :integer, :number and :decimal, as numbers, aligned to the end of the cell. A decimal goes to the browser as a string, so no digit is lost on the way;
• :date, :datetime and :time;
• :boolean, as a check mark.

A column with an inner block is rendered by it, on the server, for each row that the browser shows; the type still says how it sorts and filters.

filters, a list of Masu.Filter operators, limits a column's filters to those: the operators the app runs, in a controlled grid (on_query) whose app's queries have fewer than Masu (as a source's Masu.Source.filters/2 does). Masu adds :between for a column that has :gte and :lte.

type={:auto} is a column whose type the grid learns from its values, in the first block of rows of its source: integers make an :integer column, Decimals a :decimal one, Dates a :date one, and so on; values of several types, or of none of these, make it :text. The grid keeps the type until its source changes. A column whose rows are a query tool's results, of no types, takes it.

Rows as lists

field={2} reads the value at that place of a row that is a list (from 0): a query tool's rows, which come as lists of values in the order of its columns. Its key is the place as a string unless given.

Fields of related rows

field={[:customer, :name]} reads a field of a related row: a path of the row's associations (or keys of maps in it) to a field. Its key is the path joined with dots ("customer.name") and its label the path in words ("Customer name") unless given. An Ecto source sorts, filters, searches and groups by it in the database, with a join; a list follows the path in each row. The column is read-only.

A path through several related rows (a has_many or many_to_many: [:tags, :name]) is a column of many values: a list of the values of the rows that are loaded. It does not sort or group; it filters by "has any of" (:in), "has all of" (:all_of), "has none of" (:none_of), "has none" (:is_nil) and "has some" (:not_nil). The source says whether a path is of many values (an Ecto source from its associations, a list from its rows); many={true} says so for a source of your own.

Editing

In a grid that edits, values lists the values of an :enum column, which its editor offers (a schema's Ecto.Enum field has them unless given); decimals shows a :decimal or :number column with that many digits after the point, whatever the value has.

editor gives the column an editor of your own, in place of the one of its type; see editor/0 and the Editors of your own guide.

Layout

width is the column's width in pixels, of its type unless given, and at least min_width (48 unless given), the narrowest a person resizes it to.

grow makes the column take the room the columns leave in a grid wider than them, from its width up: a title or a description, rather than empty room after the last column. grow={2} takes twice the share of a grow column. A grid narrower than its columns scrolls sideways, and a column that grows is its width there. A person who resizes the column gives it their width, and it grows no more (in a view, too); see Masu.Layout.

hidden starts the column hidden (a person shows it from the columns menu), and pinned={:start} or pinned={:end} keeps it in view while the others scroll sideways. See Masu.Layout.

Totals

aggregate={:sum} totals the column in the row of each group and in a row of totals at the bottom of the grid; see Masu.Group.