State files

  • 6 minutes to read

A state file is the result of saving all objects loaded in the Design Editor, i.e. its state. A state contains all information on the product, including images, user changes, fonts, colors, etc. These states also contain rendering settings and the Design Editor's configuration. You may think of them as an internal design format of Customer's Canvas.

The Design Editor does not automatically clean up the state files. They are kept forever, until you delete these files manually or through the Web API. The only exception is when you enable the Demonstration mode. In this case, state files of anonymous users will be automatically removed when the session expires.

Creating State Files

State files are created every time you call Editor.saveProduct to save a product or Editor.finishProductDesign to render a print file and generate URLs that link to hi-res and proof images. By default, state files have unique names that look like aaaaaaaa-bbbb-cccc-xxxx-yyyyyyyyyyyy.st. When using these methods, you can also specify user-friendly names up to 36 symbols long.

For example, you can save a product as follows:

// Save your product to the t-shirt.st state file.
// Note, if a file with the same name already exists, it will be overwritten.
editor.finishProductDesign({stateId: "t-shirt"})
    .then(function (result) {
        // Verify a state ID and a user ID.
        stateId = result.stateId;
        userId = result.userId;
        // Get links to hi-res outputs.
        hiResOutputUrls = result.hiResOutputUrls;
        console.log("User " + userId + " successfully saved the product " + stateId);
        console.log(hiResOutputUrls);
    })
Warning

In this example, we defined the name of the new state file. You can pass this parameter for any user other than the master and default user.

By default, product states are saved in the ..\userdata\<someUserId>\states\ folder for every user. The ..\userdata\ folder contains states and images for all your users. The someUserId value is determined when you load the Design Editor.

let iframe = document.getElementById("editorFrame");
// For example, define an empty page as a product.
let productDefinition = { surfaces: [{ width: 800, height: 600 }] };
// Set the ID of the user who will create state files.
let config = { userId: 'someUserId' };
// Load the Design Editor.
CustomersCanvas.IframeApi.loadEditor(
    iframe, 
    productDefinition,
    config
);

You can change the default location for user images and states through the UserDataFolder parameter in AppSettings.config. You can move state files between folders of different users, rename them, or back them up.

Note

By default, images are embedded into the .st file. It makes the state file self-contained - you can easily copy it to a backup drive, restore, or even move it to another Design Editor instance. However, such files can become pretty large. To avoid this, you can enable a space-saving mode by setting the StateFileStorageEnabled to true in AppSettings.config. In this mode, state files are saved in the .sto format, when all images are stored in the ..\userdata\StateFileCache\ folder and state files have only links to the files in this folder. As a trade-off, you will have to copy this cache folder during the backup procedures or migration to another Design Editor instance.

Loading State Files

If you open the state folder, you will see a lot of state files. How do you pick the right one? To load a state, you should know its name (i.e. the state ID). You can get the state name when a Promise object returned by the Editor.saveProduct or Editor.finishProductDesign is resolved. The state ID, along with other information about the state, is passed to the successful resolution callback.

// Save a product.
editor.saveProduct()
    .then(function (result) {
        // Get a state identifier and a user identifier.
        stateId = result.stateId;
        userId = result.userId;
        console.log("State was saved successfully. Its id is " + stateId);
        ...
    })
    .catch(function (error) {
        ...
    });
...
// Now, you can load the previously saved product.
CustomersCanvas.IframeApi.loadEditor(iframe, stateId, { userId: userId });

Now, let's see how you can get a list of state files through the Web API.

Web API for Manipulating State Files

You can use our REST API to manipulate state files. For example, you can get a list of a user's state files by using the following request.

// Define the ID of the user who created state files.
const userId = "default";
// Pass the user ID to the StateFiles controller.
const url = `https://localhost:44300/api/users/${userId}/states`;
fetch(url).then(response => {
    return response.json();
}).then(json => {
    // Output state file names to the console.
    json.forEach(st => {
        console.log(st.stateId);
    });
});

Webhooks for Loading and Saving State Files

The Design Editor also allows you to implement custom HTTP callbacks triggered by saving, loading, and deleting the state files in the editor. In this case, you can organize external storage for state files. To enable such webhooks, you need to define ExternalStatePushUrl, ExternalStatePullUrl, and ExternalStateDeleteUrl in AppSettings.config.

Master User

Imagine that you want to create templates in Customer's Canvas format, rather than use PSD/IDML. For example, you may want to create templates in a cloud account of Customer's Canvas using a Template Editor app, download them and put them to Design Editor. Or maybe you would like to implement a workflow when certain user's designs are published using API.

As you can find out from the state file storage folder structure explained above, you need to have a folder corresponding to a user so that you could save state files. However, if you save the state files under a specific user folder, they are not available to other users. How do you make their work available to all users of your site?

To provide a template for all of your users, the specified state file must be located in the master user folder. The master user is a special user whose resources, such as images or state files, are accessible to every user in your system. When a user sets a state file to load, the Design Editor first looks for the state in the state folder of this user, and if it cannot be found there, the master user folder is checked.

A default location of a master user folder is ..\userdata\masteruser\states\. Just put a state file to this folder and provide its name in the same way as you do for the regular designs. Design Editor will recognize it as a public design and load it.

If you like, you can override the master user name with a MasterUserId parameter specified in AppSettings.config. You may want to change the MasterUserId parameter if a user named masteruser already registered on your system.

Default User

In addition to the master user, there is another special user type - the default user. It is used when Design Editor cannot identify the user, for example, if you did not specify the user ID in the editor configuration.

The name of this user is defined in the DefaultUserId parameter in AppSettings.config. By default, it is set to default. Accordingly, the folder where the states and uploads of such a user are located in ..\userdata\default\ . As for the master user, the name of the default user is reserved, there should not be a user with this name in your system.

We recommend that you always specify the user. Otherwise, you may encounter behavior when different users upload their files and see the uploads of your previous users. Due to the separation of users, you can determine who created a particular design.

Was this page helpful?
Back to top Copyright © 2001–2022 Aurigma, Inc. All rights reserved.