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

• Catalyst CLI (Refer CLI Installation)
• Catalyst project (Refer Catalyst Projects)
• Any text editor(Xcode or Sublime)

Authentication

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 code snippet given below in your application. This script allows you to access the JavaScript methods of Catalyst Web SDK.

This initializes the Web SDK and refers to an init.js file which will automatically populate the essential details of your project, such as the Project ID which is your project’s unique ID and ZAID which is the project’s key.

These values are automatically populated based on the environment that you are working on. That is, if this script is called from the Development environment URL of your app, the appropriate ZAID value is populated.

    

        
copy
        

            

        
    
    

         <script src="https://static.zohocdn.com/catalyst/sdk/js/4.0.0/catalystWebSDK.js"></script>
<script src="/__catalyst/sdk/init.js"></script>
<script>
catalyst.auth.signIn("your element id here....");
</script>

    

You can build the sign-in form of your application as an iFrame using this code snippet. You must however add this code snippet in all of your pages. This initialization script is required in all pages because the scope of the catalyst object is limited to a single page.

The code contains the line: catalyst.auth.signIn(“Your elementID here”); . The elementID can be the ID of any HTML element or div element in your application’s login page. You should replace this with the elementID of your application’s login and implement this in the page that contains the user login.

You can now create a division in the same page for your iFrame as: <div id=“Your elementID here”> </div>. This will span the iFrame for user login in the same page.

For example, if your elementID is “login”, your code will look like this:

• In the Web SDK Initialisation script: catalyst.auth.signIn(“login”);
• In the body of your page: <div id=“login”></div>

Manage Environment Variables

You can manage the environment variables through code using the following Catalyst methods:

• To set the environment variable:
  

    
  
        
  copy
        
  
            
  
        
    
    
  
         catalyst.setCatalystEnv(keyName,value)
    
  

• To get the environment variable:
  

    
  
        
  copy
        
  
            
  
        
    
    
  
         catalyst.getCatalystEnv(key)
    
  

• To delete the environment variable:
  

    
  
        
  copy
        
  
            
  
        
    
    
  
         catalyst.deleteCatalystEnv(key)
    
  

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.

    

        
copy
        

            

        
    
    

         catalyst.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,

    

        
copy
        

            

        
    
    

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

    

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 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.

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

Structure of client-package.json

    

        
copy
        

            

        
    
    

         { 
"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:

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:

Once deployed , you will get an URL endpoint with which you can access your client application.