Storage

The schmuckliCloud service provides different kind of services. Therefore, all the services are splitted in to different packages, so that you only have to install these packages, which you want to use in your project. In this documentation, it's all about the storage package.

Getting started

To get started, first you have to install the package via the command line terminal in your app, where the package.json file is already located.

npm i schmucklicloud_storage

If you want to use the unpacked version, please use:

<script src="https://unpkg.com/schmucklicloud_storage/dist/min.js" type="text/javascript"></script>

Initialization (with npm)

Now you have to create an instance, where you can connect to the schmuckliCloud service. To do that, import first the package with the class.

import { sCStorage } from "schmucklicloud_storage";

After that, create a new instance from the class sCStorage and pass the APP_ID and APP_SECRET inside of it. You can get the two strings via the schmuckliCloud console.

var reference = new sCStorage('YOUR_APP_ID', 'YOUR_APP_SECRET');

You are now ready to go with start building apps on top of the schmuckliCloud service.

Initialization (without npm)

If you are using the unpacked version of the library, you don't have to import the package anymore, since you already mapped it in the script tag. The difference between the npm version is instead, that you have to use the namespace 'schmuckliCloud', if you want to access the constructor.

var reference = new schmuckliCloud.sCStorage('YOUR_APP_ID', 'YOUR_APP_SECRET');

Now you're all set and can start building amazing apps.

Selecting buckets and datasets

Before you can insert, update and getting data from the service, you also have to define a bucket and a dataset, which should always be used for the future requests.

Just simply use the following two methods, to set the two properties.

reference.setBucket(12); //Set here the number of the bucket, not the name
reference.setDataset("abc"); //Set there the name of the dataset

Notice: You can also change between the buckets and datasets as you want. But in most cases you only need to set them once.

Inserting new data

If you want to save new data for example from a form to the storage, use the insert function on the reference object.

reference.insert("container_name", {
    column_1: "value_1",
    column_2: "value_2"
}).then(function(response) {
  if (response.isOK) {
    //The data has been saved to the database
  } else {
    //There was an expected error
  }
}).catch(function(error_response) {
  //There was an error while the operation
});

In the first parameter, you have to provide a container name, which is defined in the bucket. As a second argument you now can pass all the data in a key-value pair object. The keys provide the column name, the values their matching values.

Updating exisiting data

To update exising data, you can use the update method on the reference object:

reference.update("container_name", 34, {
    column_1: "value_1",
    column_2: "value_2"
});

Like in the insert method the first parameter provides the container name. The second parameter provides the item id, which should be updated. The third parameter is again the data object with the key-value system. If you not define a column, this column will also not be updated in the backend.

Deleting data

If you have to delete some data in the storage, then you might will use the delete function on the reference object.

reference.delete("container_name", 34);

The first parameters is as always the container name. The second parameters again defines the item id. You can get it when you retrieve the data as described below.

Operation returns

All the function above do also return a Promise, which can be fetched, as soon as the requests has been finished. Here is an example, how the promise can be handeled:

reference.insert("my_fancy_container", {
    name: "cloud",
}).then(function(response) {
  if(response.isOK){
    //Everything was fine and further actions can be done.
  } else {
    //There was something wrong. Output of the error message in the browser console.
    console.error(response.message);
  }
});

Fetching data

Get all data

To fetch data from the storage, you can use one of these three functions. The first function is when you just want to display all the rows in a specific container.

reference.getAll("container_name", "asc").then(function (response) {
  if (response.isOK) {
    response.data.forEach(function (row) {
      console.log(row.id) //Can be used to update and delete data (row set id)
      console.log(row.data.name + " " + row.data.link) //Fetch the columns by using the data object.
    });
  }
});

The first parameter, which you have to provide is the container name. It will then just display all the data in that specific container with the predefined dataset. As a second argument, you can optionally sort all the entries. Currently it is only supported to order the row.id. Other sorting mechanism has to be done on the client side.

Get data, filtered on the backend

The second function is used, if you want to filter data on the server-side, which boosts up the performance on the client. For that use the function get and provide the parameters:

reference.get("container_name", [
  {
    "column": "name", //Define the column which should be the indication of the filter
    "operator": "==" //Checkout the different operators
    "value": "cloud" //Searching value, which has to match
  }
], "desc").then(function (response) {
  if (response.isOK) {
    response.data.forEach(function(row){
      console.log(row.id) //Can be used to update and delete data
      console.log(row.data.name + " " + row.data.link) //Fetch the columns by using the data object.
    });
  }
});

As the above getAll function, you provide first a container. Then you can pass an array of objects. These objects contains information about the filters. A filter is constructed always the same. In the first attribute, you define the name of the column. In the operator property, you define with which operator, it should filter the value. Last but not least, the value property filters the filter according to this value.

Advanced usage of get and getAll functions

You also have the ability to limit the results as you know it from other database languages. As third and fourth on the getAll function and fourth and fifth parameters on the get you can also now define the start and limit number. The start counts from the index 0. The limit number count the occurences of and will stop showing the other results after it has exceeded the limit number.

storage.getAll("container_name", "asc", 2, 5). then(function (response) {
  if (response.isOK) {
    console.log(response.data.length); //Output: 5 (only if there are equal or more rows available)
    console.log(response.data); //Showing now the five items starting from the third position.
  }
});

Get data by the ID

The third function to fetch data is called getById. This function allows you to simply get just one rowset of the given ID in a container.

storage.getById("container_name", 123).then(function (response) {
  if (response.isOK) {
    console.log(response.data.id); // The row set id
    console.log(response.data.data); //A single object of your data
  } else {
    console.error(response.message);
  }
});

To use the function provide as a first parameter again the container name. Define then in the second parameter the ID you want. Please note that you will not get an array of data in this function and you can directly access the data from response.data.data.