> For the complete documentation index, see [llms.txt](https://craig-branscom.gitbook.io/marble-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://craig-branscom.gitbook.io/marble-docs/contract-standard/marble-layers/frames.md).

# Frames

## What is a Frame?

A frame is a pre-built set of properties that can be assigned to an item all at once. Frames are created and updated by group managers.

{% hint style="info" %}
Note the **Frames Layer** requires the **Tags** and **Attributes** Layers as dependencies.
{% endhint %}

## Table Breakdown

**Table Name:** `frames`

**Table Scope:** `self`

| Name                | Type                 | Example                                    | Description                                  |
| ------------------- | -------------------- | ------------------------------------------ | -------------------------------------------- |
| frame\_name         | name                 | testframe                                  | Frame name identifier (Primary Key).         |
| group               | name                 | testgroup                                  | Group managing the frame.                    |
| default\_tags       | map\<name, string>   | \[{"key": "tag1", "value": "tag1content"}] | A map of default tag names and content.      |
| default\_attributes | map\<name, int64\_t> | \[{"key": "attr1", "value": 4}]            | A map of default attribute names and points. |

#### Additional Indices

`bygroup`

## Create a Frame

To create a new frame call the `newframe()` action.

**Required Authority:** `group.manager`

### Action Parameters

| Name                | Type                 | Example                                    | Description                                 |
| ------------------- | -------------------- | ------------------------------------------ | ------------------------------------------- |
| frame\_name         | name                 | testframe                                  | The name of the frame.                      |
| group               | name                 | testgroup                                  | The name of the group.                      |
| default\_tags       | map\<name, string>   | \[{"key": "tag1", "value": "tag1content"}] | The default tags to apply to an Item.       |
| default\_attributes | map\<name, int64\_t> | \[{"key": "attr1", "value": 4}]            | The default attributes to apply to an Item. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} newframe '[ ... ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble make frame ...
```

{% endtab %}
{% endtabs %}

## Apply a Frame

To apply a frame to an Item call the `applyframe()` action.

**Required Authority:** `group.manager`

### Action Parameters

| Name        | Type      | Example   | Description                                                                                                                                                                                                    |
| ----------- | --------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| frame\_name | name      | testframe | The name of the frame to apply to the Item.                                                                                                                                                                    |
| serial      | uint64\_t | 5         | The serial number of the Item being applied the frame.                                                                                                                                                         |
| overwrite   | bool      | true      | When true, will overwrite any existing tags or attributes on the Item of the same name. When false, these tag and attribute name collisions will skip the frame defaults and leave the existing data in place. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} applyframe '[ ... ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble ...
```

{% endtab %}
{% endtabs %}

## Quick Build an Item

Frames offer a special action called `quickbuild()` that will mint a new item, apply a frame, and then apply frame default override values - all at once. This is a preferred method for rapid complex item creation.

**Required Authority:** `group.manager`

### Action Parameters

| Name                 | Type                 | Example                                        |                                                            |
| -------------------- | -------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| frame\_name          | name                 | testframe                                      | The name fo the frame to quick build.                      |
| to                   | name                 | testaccountb                                   | The name of the account to receive the newly built Item.   |
| override\_tags       | map\<name, string>   | \[{"key": "tag1", "value": "overridecontent"}] | The set of tag overrides to override frame defaults.       |
| override\_attributes | map\<name, int64\_t> | \[{"key": "attr1", "value": 3}]                | The set of attribute overrides to override frame defaults. |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} quickbuild '[ ... ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble ...
```

{% endtab %}
{% endtabs %}

## Remove a Frame

To remove a frame call the `rmvframe()` action.

**Required Authority:** `group.manager`

### Action Parameters

| Name        | Type   | Example            | Description                      |
| ----------- | ------ | ------------------ | -------------------------------- |
| frame\_name | name   | testframe          | The name of the frame to remove. |
| memo        | string | "frame not needed" | An optional memo field.          |

### Examples

{% tabs %}
{% tab title="Cleos" %}

```
cleos push action {account} rmvframe '[ ... ]' -p {manager}
```

{% endtab %}

{% tab title="Marble CLI" %}

```
marble remove ...
```

{% endtab %}
{% endtabs %}