Card item layout

A Card Surface can arrange its items in one, two, or three columns depending on the space available inside its current container. Column span lets a configurator say how many of those columns an item should use without creating separate layouts for a Drawer and a Details page.

Use a wider span for content such as a description, Markdown narrative, address, text block, or alert that needs reading space. Moltaro does not widen an item automatically because of its field type or renderer; the saved Card configuration is the source of that presentation decision.

Configure a Card item

1. Open Constructor > Entity Explorer and select the Entity Definition.
2. Open Surface library, then select or create the Card Surface.
3. In Card items, edit a Field, Text block, or Alert item.
4. Choose Column span and save the item.
5. Save the Card Surface, then verify it in every Runtime screen that selects that Card, especially Drawer and Details.

Card items do not have a fixed Column setting. They keep their row-major order from SortOrder and flow into the available columns. A wider item may use the remaining space in a row or cause the next item to wrap to a new row. Form layout is different: Forms keep their own fixed Column and Column span settings against an authored Form column count.

Card display options

The Display block at the top of the Card Surface editor holds two options for the whole Card. Both are off by default, so an existing Card looks the same until you change them.

• Field labels: Beside the value shows a label column next to each value, which saves height when values are short (codes, dates, statuses, names). Moltaro uses it only where the item’s cell is about 350 px wide or more; on phones and in narrow Drawers the label stays above the value. Long text, Markdown and child-table fields always keep the label above.
• Hide empty fields leaves out fields that would read “Not set” when the record is read: no value, blank text, an empty list, an amount field without an amount or an address with nothing in it. false and 0 are values and stay visible; fields the reader may not see keep their restricted state. A Card tab whose fields are all empty is not shown. Edit forms still show every field.

In the API these are the Card configuration properties LabelPlacement (0 Above, 1 Beside) and HideEmptyFields. In Entity YAML they are CardLabelPlacement and CardHideEmptyFields, written only when not default.

How the responsive span works

The accepted authored values are 1 through 3. A configuration with no authored value (null in the API) behaves as 1; the visual editor therefore shows the effective value 1 for existing null items.

At runtime Moltaro uses the smaller of the authored span and the number of columns that currently fit the Card:

effective span = min(ColumnSpan ?? 1, current Card column count)

Column span	Narrow Card (1 column)	Medium Card (2 columns)	Wide Card (3 columns)
unset or 1	1	1	1
2	1	2	2
3	1	2	3

The Card’s container width, not only the browser or device width, determines the current column count. The same saved value can therefore appear as one column in a narrow Drawer and as several columns on a full Details page.

Practical choices:

• use 1 for compact facts that can share a row;
• use 2 when an item should fill a two-column Card but may share a wider row;
• use 3 when an item should fill the row in every current Card layout.

A valid value above the current responsive column count is clamped to the available width. Values 0, negative values, and values above 3 are invalid.

Upgrade behavior

When an installation adopts this three-column contract, persisted Card values above 3 are normalized to 3, which preserves their current full-row rendering. Form item spans are not changed. Package and YAML sources must use 1, 2, or 3 before they are applied again.

Drawer and Details behavior

Card Tabs group items in configuration. In Details and Drawer, several groups appear as stacked, collapsible subsections. In the Card designer, enable Collapsed by default for a group that should start closed. Groups start expanded when this setting is off. A single expanded group renders directly; a single group configured collapsed keeps its disclosure button. Hide empty fields can remove empty groups. Hosts with a tab strip ignore the collapse setting.

While a record remains open, your expand/collapse choices survive data refreshes and editing. Reopening the record or selecting another Card returns to the configured defaults. A host layout section’s CollapsedByDefault controls that outer section independently.

For API and YAML configuration, set CollapsedByDefault: true on the relevant entry in Tabs. Omission means expanded; YAML export omits the false default. In a .NET package, use card.Tab("additional", "Additional information").CollapsedByDefault(). Package Card settings seed newly created surfaces; later package updates preserve the administrator’s configuration unless it is explicitly reset.

The span belongs to the reusable Card Surface, not to its host. Drawer, Details, and other screens that render the selected ordinary Card use the same clamp rule. They may still show different results if they select different Card Surfaces or provide different container widths.

This setting does not reconfigure the generated Boards Board data section. Change an ordinary Card Surface only when its content and hosts are the target.

Configuration API workflow for developers and agents

All routes below are relative to the installation’s WORKSPACE_API_BASE_URL, never to https://moltaro.com. The caller needs the Admin or Configurator role. Public JSON property names are PascalCase.

Read the options response before presenting or sending a value:

GET /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/card-surfaces/configuration/options

Its Data.SupportedColumnSpans value is the server-authoritative list:

{
  "Data": {
    "SupportedColumnSpans": [1, 2, 3]
  },
  "Errors": [],
  "Warnings": [],
  "Success": true
}

Then use a read-modify-write-read workflow:

GET /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/card-surfaces/{surfaceKey}/configuration
PUT /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/card-surfaces/{surfaceKey}/configuration
GET /api/workspace/admin/entity-definitions/{entityDefinitionId}/ui/card-surfaces/{surfaceKey}/configuration

PUT replaces the complete Card configuration

Preserve the current Tabs, every Items entry, LabelRules, LabelPlacement, and HideEmptyFields; change only the intended item’s ColumnSpan. Sending only the abbreviated fragment below would remove the omitted configuration.

The following JSON is an item fragment for explanation, not a complete request:

{
  "Items": [
    {
      "Id": "description",
      "SortOrder": 30,
      "ColumnSpan": 3
    }
  ]
}

After PUT, GET the configuration and verify the exact authored value. Entity Definition YAML export/import also preserves ColumnSpan exactly. Do not translate Card span into a fixed Column, infer width from the field type, or send a breakpoint-specific map.

Generated operation references:

• Get Card configuration options
• Get Card configuration
• Replace Card configuration

An invalid value returns the stable code moltaro.ui.card.item.columnSpan.invalid. See Errors and responses for the standard error envelope and recovery rules.

Related documentation

• UI surface library explains reusable Table, Card, and Form Surfaces.
• Runtime screens explains how Drawer and Details select a Card Surface.
• Display fields explains calculated read-time values that can be shown on Cards.