diff --git a/docs/javascript/columns.md b/docs/javascript/columns.md index 23624570..cd691736 100644 --- a/docs/javascript/columns.md +++ b/docs/javascript/columns.md @@ -4,6 +4,12 @@ description: JavaScript API reference for managing columns — create, rename, r # Columns +!!! warning "Columns cannot be created or modified from a SeaTable script" + + Reading columns works in both contexts, but every write method on this page -- *Add Column*, *Rename Column*, *Column Settings* and *Delete Column* -- is only available in the external `seatable-api` client. In a JavaScript script inside a base, `base.insertColumn`, `base.deleteColumn` and the others are `undefined`. + + To create or modify columns from within SeaTable, use a [Python script](../python/objects/columns.md) instead: the Python library supports the full range of column operations in both contexts, including link columns. Alternatively, call the [REST API](https://api.seatable.com/reference/insertcolumn-1) directly. + {% include-markdown "includes.md" start="" @@ -27,7 +33,7 @@ description: JavaScript API reference for managing columns — create, rename, r const column = base.getColumnByName('Table1', 'Name'); ``` -!!! abstract "getColumns" +!!! abstract "getColumns :material-tag-outline:{ title='Scripting only' }" Get all columns of a table. @@ -92,7 +98,7 @@ description: JavaScript API reference for managing columns — create, rename, r ## Add Column -!!! abstract "insertColumn" +!!! abstract "insertColumn :material-package-variant-closed:{ title='External client only' }" Add a new column to a table. @@ -118,7 +124,7 @@ description: JavaScript API reference for managing columns — create, rename, r ## Rename Column -!!! abstract "renameColumn" +!!! abstract "renameColumn :material-package-variant-closed:{ title='External client only' }" Rename a column, identified by its column key. @@ -133,7 +139,7 @@ description: JavaScript API reference for managing columns — create, rename, r ## Column Settings -!!! abstract "resizeColumn" +!!! abstract "resizeColumn :material-package-variant-closed:{ title='External client only' }" ```js base.resizeColumn(tableName, columnKey, newColumnWidth); @@ -144,7 +150,7 @@ description: JavaScript API reference for managing columns — create, rename, r await base.resizeColumn('Table1', 'asFV', 500); ``` -!!! abstract "freezeColumn" +!!! abstract "freezeColumn :material-package-variant-closed:{ title='External client only' }" ```js base.freezeColumn(tableName, columnKey, frozen); @@ -155,7 +161,7 @@ description: JavaScript API reference for managing columns — create, rename, r await base.freezeColumn('Table1', '0000', true); ``` -!!! abstract "moveColumn" +!!! abstract "moveColumn :material-package-variant-closed:{ title='External client only' }" Move a column to the right of the target column. @@ -168,7 +174,7 @@ description: JavaScript API reference for managing columns — create, rename, r await base.moveColumn('Table1', 'loPx', '0000'); ``` -!!! abstract "modifyColumnType" +!!! abstract "modifyColumnType :material-package-variant-closed:{ title='External client only' }" Change the type of an existing column. @@ -182,7 +188,7 @@ description: JavaScript API reference for managing columns — create, rename, r await base.modifyColumnType('Table1', 'nePI', ColumnTypes.NUMBER); ``` -!!! abstract "addColumnOptions" +!!! abstract "addColumnOptions :material-package-variant-closed:{ title='External client only' }" Add options to a single-select or multiple-select column. @@ -198,7 +204,7 @@ description: JavaScript API reference for managing columns — create, rename, r ]); ``` -!!! abstract "addColumnCascadeSettings" +!!! abstract "addColumnCascadeSettings :material-package-variant-closed:{ title='External client only' }" Add cascade settings to a single-select column, limiting child options based on the parent column's selection. @@ -216,7 +222,7 @@ description: JavaScript API reference for managing columns — create, rename, r ## Delete Column -!!! abstract "deleteColumn" +!!! abstract "deleteColumn :material-package-variant-closed:{ title='External client only' }" Delete a column, identified by its column key. diff --git a/docs/javascript/constants.md b/docs/javascript/constants.md index 148d9dc5..6b54a43c 100644 --- a/docs/javascript/constants.md +++ b/docs/javascript/constants.md @@ -10,6 +10,10 @@ When creating or modifying columns, use the `ColumnTypes` constants for type-saf import { ColumnTypes } from 'seatable-api'; ``` +!!! info "External client only" + + `ColumnTypes` comes from the `seatable-api` npm package. There is no `import` in the SeaTable script editor, so these constants are not available there. Since columns cannot be created or modified from a script anyway, this is not a limitation in practice -- see [Columns](columns.md). + ## ColumnTypes | Constant | Column type | diff --git a/docs/javascript/files.md b/docs/javascript/files.md index 9755ab68..41d67cf8 100644 --- a/docs/javascript/files.md +++ b/docs/javascript/files.md @@ -6,6 +6,10 @@ description: Upload files and images to SeaTable from JavaScript using the REST The `seatable-api` npm package does not currently support file or image uploads. To upload files, you need to use the SeaTable REST API directly via `fetch()`. +!!! info "External client only" + + The example on this page runs in Node.js: it reads from the local filesystem and authenticates with an API token. Neither is available in the SeaTable script editor. + ## Upload workflow Uploading a file to SeaTable requires three steps: diff --git a/docs/javascript/index.md b/docs/javascript/index.md index 2d7a54eb..7a800e12 100644 --- a/docs/javascript/index.md +++ b/docs/javascript/index.md @@ -4,7 +4,7 @@ description: Get started with the SeaTable JavaScript API. Use it inside SeaTabl # JavaScript -SeaTable provides a JavaScript API that works in two contexts: inside SeaTable as a script, or externally via Node.js or a frontend application. The core methods (tables, views, columns, rows, links, SQL) are the same in both contexts. Features that are only available in one context are clearly marked on the respective pages. +SeaTable provides a JavaScript API that works in two contexts: inside SeaTable as a script, or externally via Node.js or a frontend application. Many methods exist in both contexts, but the two are **not** identical -- most notably, columns can only be created or modified from an external client. Every method that is limited to one context carries a marker on the respective page. ## Script vs. External Client @@ -15,6 +15,18 @@ SeaTable provides a JavaScript API that works in two contexts: inside SeaTable a | Execution | In the browser | Node.js or frontend app | | `await` required | Only for `query()` and `getLinkedRecords()` | For all calls | | Exclusive features | [Context, Output, Utilities, Filter/QuerySet](scripting-features.md) | [Constants](constants.md) | +| Column management | Read only | Full (create, modify, delete) | + +### Context markers + +Methods that are not available in both contexts are marked in the reference pages: + +| Marker | Meaning | +|---|---| +| :material-tag-outline:{ title='Scripting only' } | Available **only** in scripts inside SeaTable. Calling it from an external client returns `undefined`. | +| :material-package-variant-closed:{ title='External client only' } | Available **only** in the external `seatable-api` client. Calling it in a SeaTable script returns `undefined`. | + +Methods without a marker work in both contexts. ## Installation diff --git a/docs/javascript/links.md b/docs/javascript/links.md index 4d32ef7c..1992d096 100644 --- a/docs/javascript/links.md +++ b/docs/javascript/links.md @@ -69,7 +69,7 @@ Link columns connect rows between tables. Most link operations require the `link ## Update Link(s) -!!! abstract "updateLink" +!!! abstract "updateLink :material-package-variant-closed:{ title='External client only' }" Replace all linked records of a row with a new set. @@ -77,6 +77,10 @@ Link columns connect rows between tables. Most link operations require the `link base.updateLink(linkId, tableName, otherTableName, rowId, otherRowIds); ``` + !!! warning "Different name in scripts" + + In a SeaTable script, this method is called `updateLinks` (plural) -- see below. `base.updateLink` is `undefined` in the script context. + __Example__ ```js base.updateLink('r4IJ', 'Table1', 'Table2', 'BXhEm9ucTNu3FjupIk7Xug', [ @@ -85,7 +89,23 @@ Link columns connect rows between tables. Most link operations require the `link ]); ``` -!!! abstract "batchUpdateLinks" +!!! abstract "updateLinks :material-tag-outline:{ title='Scripting only' }" + + Replace all linked records of a row with a new set. This is the script equivalent of `updateLink`; the parameters are identical. + + ```js + base.updateLinks(linkId, tableName, otherTableName, rowId, otherRowIds); + ``` + + __Example__ + ```js + base.updateLinks('r4IJ', 'Table1', 'Table2', 'BXhEm9ucTNu3FjupIk7Xug', [ + 'exkb56fAT66j8R0w6wD9Qg', + 'DjHjwmlRRB6WgU9uPnrWeA' + ]); + ``` + +!!! abstract "batchUpdateLinks :material-package-variant-closed:{ title='External client only' }" Update links for multiple rows at once. diff --git a/docs/javascript/metadata.md b/docs/javascript/metadata.md index 9525dd94..f3f7a168 100644 --- a/docs/javascript/metadata.md +++ b/docs/javascript/metadata.md @@ -4,7 +4,7 @@ description: Retrieve the complete structural schema of a SeaTable base — tabl # Metadata -!!! abstract "getMetadata" +!!! abstract "getMetadata :material-package-variant-closed:{ title='External client only' }" Get the complete structure of a base -- tables, views, and columns. Does not include row data. diff --git a/docs/javascript/rows.md b/docs/javascript/rows.md index 4de6d3df..7c01d46c 100644 --- a/docs/javascript/rows.md +++ b/docs/javascript/rows.md @@ -27,7 +27,7 @@ description: JavaScript API reference for row operations — query, append, inse const row = base.getRow('Table1', 'M_lSEOYYTeuKTaHCEOL7nw'); ``` -!!! abstract "getRows" +!!! abstract "getRows :material-tag-outline:{ title='Scripting only' }" Get all rows displayed in a view. @@ -42,7 +42,7 @@ description: JavaScript API reference for row operations — query, append, inse const rows = base.getRows('Table1', 'Default View'); ``` -!!! abstract "listRows" +!!! abstract "listRows :material-package-variant-closed:{ title='External client only' }" Get rows with optional sorting and pagination. Particularly useful for large tables. @@ -142,7 +142,7 @@ description: JavaScript API reference for row operations — query, append, inse }); ``` -!!! abstract "insertRow" +!!! abstract "insertRow :material-package-variant-closed:{ title='External client only' }" Insert a row after a specific anchor row. @@ -155,7 +155,7 @@ description: JavaScript API reference for row operations — query, append, inse await base.insertRow('Table1', {'Name': 'Inserted row'}, 'U_eTV7mDSmSd-K2P535Wzw'); ``` -!!! abstract "batchAppendRows" +!!! abstract "batchAppendRows :material-package-variant-closed:{ title='External client only' }" Append multiple rows at once. More efficient than calling `appendRow` in a loop. @@ -208,7 +208,7 @@ description: JavaScript API reference for row operations — query, append, inse base.modifyRows(table, selectedRows, updates); ``` -!!! abstract "batchUpdateRows" +!!! abstract "batchUpdateRows :material-package-variant-closed:{ title='External client only' }" Update multiple rows at once. Each entry specifies a row ID and the data to update. @@ -239,7 +239,7 @@ description: JavaScript API reference for row operations — query, append, inse base.deleteRow('Table1', 'U_eTV7mDSmSd-K2P535Wzw'); ``` -!!! abstract "batchDeleteRows" +!!! abstract "batchDeleteRows :material-package-variant-closed:{ title='External client only' }" Delete multiple rows at once.