---
title: "Tabular Views"
section: "API Reference"
route: /apitabularview
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Tabular Views

Tabular Views are saved table layouts for viewing and editing Entity data. Each one lists the columns to show, and the Entities come from a DataLab query picked when the table is opened.

They are mostly opened through our Tabular View embed, a standalone table you can open on its own or embed in an iframe. Entity tables in Navigator and Operator also offer them as quick column selections.

This article will cover how to manage Tabular View records and descriptions about each column type.

## Data model

Below is the core data model for a Tabular View. You can manage a record without populating the settings.

```typescript
interface ITabularView {
    // Unique ID for the Tabular View.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Limited to 30 characters.
    DisplayName: string;
    // Description of what the Tabular View is for.
    Description?: string;
    // The Tabular View content.
    Settings?: {
        // DataLab query IDs this view can be opened with.
        // If empty, all queries are allowed.
        // If only one is set then the user is not prompted to select one.
        dataLabQueryIds?: number[];
        // The columns to show, in order.
        // See the columns section below for the structure.
        // When empty, an ID and a Name column are shown.
        columns?: IColumn[];
        // Settings for the rows as a whole.
        row?: {
            // Background colour of each row, calculated against the row's Entity.
            // If unset then the default colour is used.
            // This must resolve into a css colour string to be valid.
            bgColor?: IField[];
        };
    };
    // What the requesting user can do with this record.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

## Columns

Every column has a name and a type. The type dictates what the column shows and which other settings are relevant.

```typescript
interface IColumn {
    // Unique ID for the column within this Tabular View.
    // This is used to remember the column's width, so keep it the same when the column is edited.
    id?: string;
    // Column title.
    // NAME, LOD, MEDIA and ATTACHMENT columns have a default title when this is empty.
    name: string;
    /**
     * The kind of column.
     *
     * Attribute = an attribute value that can be edited in the table.
     * Text = an attribute value that is read only.
     * Name = the Entity's name, as calculated by its Entity Type.
     * Calculator = a value calculated against the Entity. See the Columns: Calculation section below.
     * LOD = the Entity's representations.
     * Media = the Entity's photo attachments.
     * Attachment = the Entity's other attachments.
     */
    type: "ATTRIBUTE" | "TEXT" | "NAME" | "CALCULATOR" | "LOD" | "MEDIA" | "ATTACHMENT";
    // Path to the attribute to show. Used by ATTRIBUTE and TEXT columns.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    // You can list several paths separated by commas, the first one with a value is shown.
    // An ATTRIBUTE column with several paths is read only.
    attrPath?: string;
}
```

Here is a small example with a name column, an editable attribute and the Entity's photos.

```typescript
{
    DisplayName: "Asset register",
    Settings: {
        dataLabQueryIds: [4],
        columns: [
            {
                id: "k2m9x7d1q4ab",
                name: "Name",
                type: "NAME"
            },
            {
                id: "p8r3t6w2z5cd",
                name: "Condition",
                type: "ATTRIBUTE",
                attrPath: "\"inspection\"/\"condition\""
            },
            {
                id: "f1h4j7l0n3ef",
                name: "Photos",
                type: "MEDIA"
            }
        ]
    }
}
```

## Columns: Calculation

A calculation column shows a value worked out per Entity, such as a colour, an icon or a progress bar, instead of a raw attribute.

Calculated settings use the same calculator as Entity Styles. Each one is an array of calculator items, and the first item that resolves with a value is applied. An item can be a fixed value, an attribute value, a gradient or a mapping. You can read about each item type in the [Style calculator](/apientitystyles#apientitystylescalculator) section.

```typescript
// These settings are added to IColumn when the type is "CALCULATOR".
interface ICalculatorColumn extends IColumn {
    type: "CALCULATOR";
    /**
     * What the calculated value is shown as.
     *
     * Color = a swatch of the resulting colour.
     * Number = the resulting number.
     * Text = the resulting text.
     * Progress Bar = a bar filled from the min to the max value.
     * Font Awesome Icon = an icon, where the value resolves to a font-awesome class. Eg: "fas fa-check".
     */
    calcType: "COLOR" | "NUMBER" | "TEXT" | "PROGRESS_BAR" | "FONT_AWESOME_ICON";
    // The value to calculate.
    calcValue: IField[];
    // Min and max of the progress bar. Only used by PROGRESS_BAR.
    // Default is 0 and 100.
    calcProgressBarMin?: IField[];
    calcProgressBarMax?: IField[];
    // Icon colour for FONT_AWESOME_ICON, or the filled part of the bar for PROGRESS_BAR.
    color?: IField[];
    // Cell background for FONT_AWESOME_ICON, or the empty part of the bar for PROGRESS_BAR.
    bgColor?: IField[];
}

// A calculator item. See the Style calculator section in Entity Styles for each type.
interface IField {
    value: IGradientValue | IMappingValue | string | number;
    // 0 = Color, 1 = Input, 2 = Gradient, 3 = Mapping, 4 = TagColor, 5 = RandomColor.
    // An Input item reads an attribute when its value is a variable. Eg: "${address/city}".
    type: number;
}
```

Here is a progress bar column that fills by an inspection score out of 10, turning red below 4.

```typescript
{
    id: "s5u8v1y4b7gh",
    name: "Score",
    type: "CALCULATOR",
    calcType: "PROGRESS_BAR",
    // Input item reading the 'inspection/score' attribute.
    calcValue: [
        {
            type: 1,
            value: "${inspection/score}"
        }
    ],
    calcProgressBarMin: [{ type: 1, value: 0 }],
    calcProgressBarMax: [{ type: 1, value: 10 }],
    color: [
        // Mapping item on the same attribute, with a fallback colour.
        {
            type: 3,
            value: {
                field: "\"inspection\"/\"score\"",
                values: [
                    {
                        fieldValue: "0-4",
                        appliedValue: "rgba(255, 45, 45, 0.8)"
                    }
                ]
            }
        },
        {
            type: 0,
            value: "rgba(0, 119, 255, 0.7)"
        }
    ]
}
```

## Requesting records

You can request a list of all Tabular Views or an individual one. Both include the settings JSON.

### Get a list of Tabular Views

```http
GET https://{accountId}.api.nextspace.host/ui.tableviews
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
interface IResponse {
    // Array of Tabular View records.
    // See the data model above for the record structure.
    Items: ITabularView[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.tableviews";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get Tabular View by ID

```http
GET https://{accountId}.api.nextspace.host/ui.tableview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Tabular View to get. |

**Response**

```typescript
// The response is the Tabular View record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.tableview/{view_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Create and update records

You can create a record by performing a POST request to the same URL as the GET. If you specify the ID as '0' then it'll create a new record and return it. If you specify an existing ID then it'll update the record and return it.

When updating, only the properties you include are changed. Settings are replaced as a whole, so send every column rather than only the ones that changed.

### Create or update Tabular View

```http
POST https://{accountId}.api.nextspace.host/ui.tableview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Tabular View to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Tabular View JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "DisplayName": "My new Tabular View",
    "Settings": {
        "columns": [
            {
                "name": "Name",
                "type": "NAME"
            }
        ]
    }
}
```

**Response**

```typescript
// The response is the Tabular View record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.tableview/{view_id}";
const method = "post";
const token = "your-token";
const body = {
    "DisplayName": "My new Tabular View",
    "Settings": {
        "columns": [
            {
                "name": "Name",
                "type": "NAME"
            }
        ]
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete a record

We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds.

### Delete Tabular View

```http
DELETE https://{accountId}.api.nextspace.host/ui.tableview/{view_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{view_id}` | path | yes | The ID of the Tabular View to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ui.tableview/{view_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apitabularview
