Web SDK - Overview

The Catalyst Web SDK has the javascript methods which helps you to access the Catalyst Components from your client web application.

Prerequisites

Authentication

Zoho Catalyst provides a straightforward authentication mechanism for users to access the Catalyst REST APIs and our SDKs. In order to use the catalyst components from your client application, it is mandatory to integrate the authentication mechanism provided by Catalyst.

Initialize SDK

Catalyst authentication can be integrated with your application, by including the following javascript code snippet to your application. Get your Catalyst project_Id from General settings and zaid from Environments settings.

Copied<script src="https://js.zohostatic.com/catalystclient/1.0.0/catalystWebSDK.js"></script>
<script>            
	let cred = new catalystCredential();
	cred.loadFromJSON({
	    project_Id: 560000xxxxxxxxx,
	    zaid: 1001xxxxxxx
	                 });
	catalyst.initApp(cred, {});
	catalyst.auth.signIn("your element id here....");
</script>

Note:

  1. While designing your application login page, please include the above code snippet and replace the "your element id here" with the id of the div where you want to load the login form.
  2. It is necessary to include this code snippet in all of your pages, as the scope of the catalyst object is limited to any individual page. It allows you to access the javascript SDK methods.

Instance Objects

It is always effective to minimize the API access whenever not required. In case, you need an API reference which should not actually fire the API, but should refer the component in your code for subsequent access, then Catalyst WebSDK provides that facility.

For example, the following code will not fire an API call to refer a specific file component,

Copiedcatalyst.file.folderId(folder_id).fileId(file_id);

However, the following code will actually fire an API call to delete a file from a selected folder,

Copiedcatalyst.file.folderId(folder_id).fileId(file_id).delete();

Note: Promises are returned with a specified object after firing the actual API call. Therefore, .then() is handled only after the actual API calls. The API calls cannot be used with dummy objects that don't fire an API.

Responses and Exceptions

All the responses are returned as JSON objects containing data, status codes, and status messages. A developer can track the responses easily from these objects.

Exceptions

The faulty behaviors of the application output are called exceptions or errors. The Zoho Catalyst Web SDK  throws 3 types of errors called appET, ServerET, and  DeveloperET.  These errors define whether faulty behavior is caused by application code, server error, or something else.

Code the Client Application

  1. Open your system's terminal and create an empty resource directory.
  2. Initialize catalyst and select the client option.
  3. Select the project you created ,to deploy the client application.
  4. A boiler plate client code will be generated as shown below,
  5. Open it in your text editor, whose structure looks like the one shown below,

Note: The location where the boiler plate code (client folder and catalyst.json) is generated, is the project's home location.

The following table describes the list of files and their purposes in your resource directory,

S.NoFiles/PackagesPurpose
1client (folder)The folder that has the static files(js, css, html,etc) of your client application.
2client-package.jsonA json file that has the configuration information of your client application

Structure of client-package.json

Copied{
    "name": "SampleApp",
    "version": "1.0.0",
    "description": "This is my sample app",
    "homepage": "index.html",
    "login_redirect":"home.html"
}

Here are the attributes of client-package.json,

Key NameDescription
nameName of your client application
versionVersion of your client application. Refer to Web Client Hosting help page for detailed information about Client application version management.
descriptionA short description about the current version you are going to deploy.
homepageThe landing page of your application, say index.html .
login_redirectThe page to be redirected after the login page. It should be mandatory if you integrate Catalyst Authentication in your application. Refer to User Management and Authentication API help pages for details.

You can code your web application's UI elements, java script files and CSS in the appropriate files given in the Client folder.

Deploy the Client Application

You can deploy the client application using Catalyst CLI. Refer to the Deploy Resources help page for detailed help.

  1. Open your system's terminal.
  2. From the Project's home location, deploy your client app using the command:
Copiedcatalyst deploy --only client
  1. Once deployed , you will get an URL endpoint with which you can access your client application.