Datasource

A generic datasource bridge for connecting datatables and controls to structured data providers.

Import

import { Datasource } from "@schukai/monster/source/components/datatable/datasource.mjs";

Source

View source code

Package

@schukai/monster

Since

1.0.0

Purpose and scope

A generic datasource bridge for connecting datatables and controls to structured data providers.

This page documents the Datasource class. Use the Usage examples for a working starting point and the API tab for the complete public contract.

When to use it

Use this module when its focused responsibility matches the surrounding workflow. Prefer its public options, properties, methods and events over reaching into rendered internals.

Datasource

In this example, we introduce the concept of a DataSource in Monster. A DataSource is an object that can hold a data structure, making it versatile for managing data within components. Here, we demonstrate a basic example using a DOM-based DataSource.

In this simple setup, data is embedded as JSON within the DOM, specifically in a <script> tag. In real-world scenarios, however, data typically originates from an API through a REST interface. This means that switching the DataSource from a DOM-based source to an API-based source is straightforward and requires minimal adjustments to the setup—without any changes to the structure of the table itself.

To link a DataSource to a DataTable in Monster, use the data-monster-datasource-selector attribute. This attribute points to the id of the element containing the JSON data within the DOM.

In this example, the data-monster-datasource-selector attribute on the DataTable points to #myDataSourceID, which contains the JSON data embedded in the DOM.

By changing the DataSource to point to a REST API instead of a JSON script tag, the DataTable will be populated with data from the external source, while the internal structure and bindings remain unaffected. This makes Monster a flexible tool for integrating data dynamically, suitable for a range of applications from simple to complex.

Javascript

import "@schukai/monster/source/components/datatable/datatable.mjs";
import "@schukai/monster/source/components/datatable/embedded-pagination.mjs";
import "@schukai/monster/source/components/datatable/filter.mjs";
import "@schukai/monster/source/components/form/button.mjs";
import "@schukai/monster/source/components/form/state-button.mjs";
import "@schukai/monster/source/components/form/confirm-button.mjs";
import "@schukai/monster/source/components/form/button-bar.mjs";
import "@schukai/monster/source/components/form/field-set.mjs";<script type="module">import "@schukai/monster/source/components/datatable/datatable.mjs";
import "@schukai/monster/source/components/datatable/embedded-pagination.mjs";
import "@schukai/monster/source/components/form/button.mjs";
import "@schukai/monster/source/components/form/state-button.mjs";
import "@schukai/monster/source/components/form/confirm-button.mjs";
import "@schukai/monster/source/components/form/button-bar.mjs";
import "@schukai/monster/source/components/form/field-set.mjs";</script>

HTML

<monster-datasource-dom id="myDataSourceID">
    <script type="application/json">
        {
            "dataset": [
                {
                    "id": 1,
                    "name": "John Doe",
                    "street": "Main Street 1",
                    "city": "Berlin",
                    "zipcode": "10115",
                    "country": "Germany",
                    "phone": "+49 30 1234.56",
                    "email": "john.doe@example.com"
                },
                {
                    "id": 2,
                    "name": "Jane Doe",
                    "street": "Second Avenue 2",
                    "city": "Munich",
                    "zipcode": "80331",
                    "country": "Germany",
                    "phone": "+49 89 6543.21",
                    "email": "jane.doe@example.com"
                },
                {
                    "id": 3,
                    "name": "Max Mustermann",
                    "street": "Example Road 3",
                    "city": "Hamburg",
                    "zipcode": "20095",
                    "country": "Germany",
                    "phone": "+49 40 1111.11",
                    "email": "max.mustermann@example.com"
                },
                {
                    "id": 4,
                    "name": "Lena Schmidt",
                    "street": "Hauptstrasse 4",
                    "city": "Cologne",
                    "zipcode": "50667",
                    "country": "Germany",
                    "phone": "+49 221 9876.54",
                    "email": "lena.schmidt@example.com"
                },
                {
                    "id": 5,
                    "name": "Markus Meier",
                    "street": "Ringstrasse 5",
                    "city": "Frankfurt",
                    "zipcode": "60311",
                    "country": "Germany",
                    "phone": "+49 69 4321.98",
                    "email": "markus.meier@example.com"
                }
            ]
        }
    </script>
</monster-datasource-dom>


<monster-datatable data-monster-datasource-selector="#myDataSourceID">
    <template id="row">
        <div data-monster-grid-template="1.2rem" data-monster-head="id" data-monster-replace="path:row.id"></div>
        <div data-monster-grid-template="auto" data-monster-head="name" data-monster-replace="path:row.name"></div>
        <div data-monster-grid-template="3fr" data-monster-head="street" data-monster-replace="path:row.street"></div>
        <div data-monster-head="city" data-monster-replace="path:row.city"></div>
        <div data-monster-head="zipcode" data-monster-replace="path:row.zipcode"></div>
        <div data-monster-head="country" data-monster-replace="path:row.country"></div>
        <div data-monster-head="phone" data-monster-replace="path:row.phone"></div>
        <div data-monster-head="email" data-monster-replace="path:row.email"></div>
    </template>
</monster-datatable>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Explicit Datasource Fetch

This example demonstrates how to manually work with the DataSource. Since we are not using Auto-Init, data must be explicitly fetched by calling the read method.

The method uses the URL defined in the read configuration to query the data. The URL can include various placeholders, such as:

filter: For specific query criteria.
orderBy: For sorting the results.
page: For specifying the page number.

These placeholders must be inserted into the URL, e.g., for the page: ${page}.

Further settings and details can be found in the REST Datasource documentation.

This is a slotted content

Result

Javascript

import '@schukai/monster/source/components/datatable/datasource/rest.mjs';

const restAPI = document.getElementById("Re9Oo")
const codeOutput = document.getElementById("Ui0Ee")


// here we set the page to 4, in this example the page is hardcoded and has no effect
restAPI.setOption('read.parameters.page', "4")


// here we read the data from the API and display it in the codeOutput element
restAPI.read().then((response) => {

    // here we display the data in the codeOutput element
    codeOutput.innerHTML = JSON.stringify(restAPI.data, null, 4)

}).catch((error) => {

    // if there is an error, we log it to the console
    console.error(error)
})<script type="module">import '@schukai/monster/source/components/datatable/datasource/rest.mjs';

const restAPI = document.getElementById("Re9Oo")
const codeOutput = document.getElementById("Ui0Ee")

restAPI.setOption('read.parameters.page', "4")



restAPI.read().then((response) => {
    codeOutput.innerHTML = JSON.stringify(restAPI.data, null, 4)

}).catch((error) => {
    console.error(error)
})</script>

HTML

<monster-datasource-rest style="display: flex;" id="Re9Oo"
                         data-monster-option-read-url="/assets/examples/countries.json?page=${page}">
    This is a slotted content
</monster-datasource-rest>

<strong>Result</strong>

<pre><code id="Ui0Ee"></code></pre>

Stylesheet

/** no additional stylesheet is defined **/

Open in playground

Component Design

Datasource is the shared data and observation contract behind the datatable datasource elements. It owns records, loading state, errors, and update notifications without prescribing a visual presentation.

Extension Contract

Specialized datasources implement transport or storage behavior through the public read and write methods. Consumers should react to datasource events instead of reaching into implementation state.

HTML Structure

Datasource is not registered as a custom element.

JavaScript Initialization

import { Datasource } from "@schukai/monster/source/components/datatable/datasource.mjs";

Exported

Datasource, dataSourceSymbol

Derived from

CustomElement

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomElement.

Option

Type

Default

Description

templates

object

undefined

Template definitions

templates.main

string

undefined

Main template

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomElement.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomElement.

Constructor

constructor()

the constructor of the class

Behavioral methods

read()

Wrapper for the read method of the datasource

write()

Wrapper for the write method of the datasource

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{void}

No description available.

Other methods

data()

Returns

{Object}

Get the data, without proxy

data(data)

Parameters

data {object}: data

set the data with proxy

datasource()

Returns

{Datasource}

Get the base datasource

Events

This component does not fire any public events. It may fire events that are inherited from its parent classes.

The current width of the area is too small to display the content correctly.