Skip to content
MoltaroMoltaroMoltaro Docs

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

Section titled “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.

How the responsive span works

Section titled “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 spanNarrow Card (1 column)Medium Card (2 columns)Wide Card (3 columns)
unset or 1111
2122
3123

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.

Drawer and Details behavior

Section titled “Drawer and Details behavior”

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

Section titled “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

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:

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.

Section titled “Related documentation”