Class SxcData

Data Service for an App / Sxc-Instance to get/create data of a specific Content-Type

sxc.data Services of the Sxc Instance

you are here (click to zoom) - discover the stack

A common need in JS is to read/write data from/to the backend.

2sxc 13 introduce new JS APIs for this.

  • data(...) gets a data service to get one or many items of the same type, and also create/update data (this document)
  • query(...) gets a query service to call server-side queries 👉 docs

Note: You can do all what these services do using webApi.fetchJson(...), but this is more convenient.

Tip

You may sometimes find old code which does something like data.on(...) or data.sourceUrl - this is obsolete and will not work any more.

👉 Check out the Js Data and Query Tutorials

Tip

The data format is described here: JSON Data Format used in WebAPI calls (technical)

Get a Data Service

  1. Get the Sxc Instance of the current module
  2. Call .data(contentTypeName) to get the service

Example:

const modId = @CmsContext.Module.Id;
const sxc = $2sxc(modId);
const authorsSvc = sxc.data('Authors');
authorsSvc.getAll().then(authors => console.log(authors));

Data Service Factory Parameters

The data(...) factory just has one parameter: the contentTypeName.

The returned service will always perform actions for this content-type.

Data Service APIs

Data Services always return a modern Promise containing data.

A Data Service has the following commands:

  • getAll() - no parameters, will return an array of all items of this content-type
  • getOne(id) - id is an int - will return a single item of this content-type
  • create(objectWithValues) - objectWithValues is a JS object with keys/values - will create the item and return it
  • create(objectWithValues, metadataFor) - metadataFor creates an item as metadata for something
  • delete(id) WIP
  • delete(guid) WIP
  • update(id, objectWithValues) - performs an update on the targeted item and returns the item. Note that objectWithValues can also just have a few properties, all others will be left as is.

Create Metadata

When using create(..., ...) with two parameters you are creating metadata. The signature of the address-object is

  1. Either a string containing a GUID to an entity (the most common case) - like 31f509f1-e553-4371-bf60-3d5e98937b79
  2. Or a full target identifier with TargetType and the ID as String, Number or Guid - see JSON Data Format used in WebAPI calls (technical)

Tutorial

👉 Js Data and Query Tutorials

History

  1. jQuery based webApi.get(...) etc. introduced in 2sxc 04.00
  2. in 2sxc 4.0 there was also a data object but it had a very different purpose and rarely used
  3. 2sxc 13 created a new data(...) function based on the new fetch as a data service
  4. 2sxc 13 introduced query(...)
Package: Api.Js.SxcJs

Properties

name

Declaration
name: string
Property Value
Type Description
string

Methods

create(Record<string, unknown>)

Create a new entity with the values supplied

Declaration
function create(values: Record<string, unknown>)
Parameters
Type Name Description
Record<string, unknown> values

a simple object containing the values to create
Returns
Type Description
Promise<Record<string, unknown>>

create(Record<string, unknown>, MetadataFor | string)

Create a new entity with the values supplied and also a metadata-for reference

Declaration
function create(values: Record<string, unknown>, metadataFor: MetadataFor | string)
Parameters
Type Name Description
Record<string, unknown> values

a simple object containing the values to create
MetadataFor | string metadataFor
Returns
Type Description
Promise<Record<string, unknown>>

delete(number)

Delete an entity

Declaration
function delete(id: number)
Parameters
Type Name Description
number id

id of the item to delete
Returns
Type Description
Promise<null>

delete(string)

Delete an entity

Declaration
function delete(guid: string)
Parameters
Type Name Description
string guid

GUID of the item to delete
Returns
Type Description
Promise<null>

getAll()

Get all items of this type.

Declaration
function getAll()
Returns
Type Description
Promise<T[]>

getOne(number)

Get the specific item with the ID. It will return null if not found

Declaration
function getOne(id: number)
Parameters
Type Name Description
number id
Returns
Type Description
Promise<T> | null

update(number, Record<string, unknown>)

Update an existing entity with the values supplied

Declaration
function update(id: number, values: Record<string, unknown>)
Parameters
Type Name Description
number id
Record<string, unknown> values
Returns
Type Description
Promise<Record<string, unknown>>