Cloudinary App Installation Guide

Cloudinary is a comprehensive media management platform that helps streamline the process of uploading, storing, managing, and delivering digital media content. With its robust capabilities for optimizing and transforming images and videos on-the-fly, it ensures they are delivered efficiently across various devices and platforms.

Cloudinary's powerful APIs and user-friendly interface enable developers and content creators to seamlessly integrate media management into their workflows, enhancing performance and user experience.

The Contentstack Marketplace lets you install the Cloudinary app and use it within your stack to refer media files from your Cloudinary account.

Prerequisites

• Cloudinary account
• Contentstack account
• Access to the Contentstack Organization/Stack as the Owner/Admin

This step-by-step guide explains how to install and configure Cloudinary within your stack.

Steps for Execution

1. Get your credentials from Cloudinary
2. Install and Configure the Cloudinary app in Marketplace
3. Use the Cloudinary app within your Stack

1. Get your Credentials from Cloudinary

   To get your Cloud Name and API Key from Cloudinary, follow the steps given below:

   1. Log in to your Cloudinary account.
   2. On the left-hand side primary navigation, click the Settings gear icon. Then, go to Account under the Account settings panel and scroll down to see the cloud name.
   3. Click API Keys from the left navigation panel under Product environment settings to view the API Key.
   4. Save the Cloud Name and API Key; you will need it while configuring your Cloudinary app in Contentstack in step 2.

      Note: To view the restricted assets, you need to configure the Access Control Key in step 2. Please contact the Cloudinary Support team to get this credential.

2. Install and Configure the Cloudinary App in Marketplace

   To install the app, log in to your Contentstack account and follow the steps:

   1. From the left-hand side primary navigation, click the Marketplace icon.
   2. Click Apps from the left panel.
   3. Within the Marketplace, you can see all the available apps. Hover over the Cloudinary app and click Install.
   4. In the pop-up window, select the stack where you want to install the Cloudinary app, accept the Terms of Service, and click the Install button.
   5. On the Configuration screen, enter the following details:
      1. Cloud Name and API Key: Enter the Cloudinary Cloud Name and API Key retrieved from your Cloudinary Account in step 1.
      2. Advanced Settings: In the Advanced Settings option, click the Enable Access Control toggle button to view the restricted assets. Enable this option and add the Access Control Key which you have received from the Cloudinary Support team in step 1.
      3. Choose the Cloudinary Keys to Save in Entry: Choose how to save the data fetched from the Cloudinary account in Contentstack entries. If you select the All Fields option, you can select only a limited number of assets in the entry. For Custom Fields, you can search and add specific Cloudinary Fields you want to save in entries.

         Warning: When you change the settings from All Fields to Custom Fields, and vice versa, any existing assets will follow the old configuration settings, whereas newly added assets in the entry will store the data according to the updated configuration settings.

         

         If you select Custom Fields then the Cloudinary Keys drop-down appears in which public_id, resource_type, type, format, version, secure_url, width, height, access_control, id, and derived[0].secure_url Cloudinary Keys options are selected by default. If you want to create a new key, click the + New Key Field option.

         

         In the Add Cloudinary Key Path modal, enter the Cloudinary Key Path and click the Create or Create and Apply button to create a new key.

         

         You can map nested or complex structures in the following manner:

         1. While mapping nested fields, you must specify the object and its field using the dot(.) notation.

            For example, Object.age for accessing the age field within the object.

         2. While mapping arrays, use indexing.

            For example, Array[1] for accessing the second value of an array.

         You can use the above rules to create mapping rules for complex structures that include objects and arrays. All Cloudinary fields are supported through this feature.

         Example: Cloudinary Object

         {
            "public_id": "mens_nyfw_banner_efpxor",
            "resource_type": "image",   
            "tags": ["mensignal", "womenwear"],
            "metadata": { "product_id": "0" },
         }
         eg: tags[1] and metadata.product_id 
         

      Note: The Choose the Cloudinary keys to Save in Entry feature is applicable to Cloudinary Custom Fields only.

   6. Click the Save button.
   7. On the UI Locations tab, you can see the predefined app locations. You can use the toggle button corresponding to each UI location to enable or disable it based on your requirements.

      Note: The app requires at least one UI location to be enabled, otherwise you will not be able to save your app configuration settings.

   8. If the webhook is enabled for your app, you can view the webhook logs under the Webhook tab.

      Additional Resource: For more information on UI locations and webhooks, please refer to the Installed Apps guide.

   9. Click Open Stack to start using the Cloudinary app.

3. Use the Cloudinary App within your Stack

   To use the Cloudinary app within an entry of your stack, follow the steps given below:

   1. Go to your stack and click the Content Models icon in the left navigation panel, and click the + New Content Type button.
   2. Create a content type by adding relevant details as displayed below:

   There are two ways to use the Cloudinary app in your entry.

   1. Custom field
   2. JSON Rich Text Editor field

   Steps to use the Cloudinary App as a Custom Field

   1. In the Content Type Builder page, add a Custom field in your content type by clicking the Insert a field link represented by a + sign.
   2. Under Select Extension/App, select Cloudinary and click the Proceed button.

      Change the Display Name of the custom field to your choice, for example, Cloudinary Custom Field. Optionally, you can add Help Text and Instruction Value for your custom field. This adds the Cloudinary app in the custom field.

      
   3. Under the Advanced Properties tab, you can set the maximum number of assets, folder path, and resource type that can be added in the custom field inside Config Parameter, as shown in the following screenshot:

      As seen in the above screenshot, we have added an object, named advanced, which includes the following keys in the given format:

      • max_limit: Holds the maximum number of assets you want to add. In our example, it is 5.
      • path: Holds the path of the folder which is, by default, selected to choose products.
      • resource_type: Holds the type of assets you want to add. In our example, we want to add images only.
      {
          "advanced": {
              "max_limit":5,
              "cloudinary": {
                  "folder": {
                      "path":"demo_assets/sample",
                      "resource_type":"image"
                  }
              }
          } 
      }
      

      Additional Resource: You can add more optional parameters within the Cloudinary object. For detailed description of these optional parameters, refer to the Cloudinary Media Library Widget documentation.

   4. After adding the app, click Save or Save and Close to save your changes.
   5. To use the Cloudinary app, create an entry for this newly created content type. To do this, in the left navigation panel, navigate to the Entries page, click + New Entry to create a new entry for the above content type, and then click Proceed.

      You will see the Cloudinary app added as a custom field in your entry page as shown below:

      
   6. Click the + Choose Asset(s) button to select assets from your Cloudinary account.
   7. If you are not logged into your Cloudinary account, it will ask you to enter your credentials. Once you do that, you are directed to your assets section. Then, select the image file(s) that you want to add and click the Insert button.

      Note: If you have set the Config Parameter in the Custom Field Advanced Properties, you will directly land to the selected folder.

      You can also add transformed assets. Transformed Assets are the files (such as images, videos, etc.) that have been modified or processed using Cloudinary's extensive transformation capabilities. These transformations can include resizing, cropping, format conversion, applying effects, watermarking, and more.

      Select the image, click the three ellipses, then click Open from the list, you can see several transformed options under the Templates heading. You can create a new template or select the transformed asset and click the corresponding Insert button to add it to the Custom field.

      

      You can also add restricted assets in the Custom field.

      

      Note: To successfully add and view private images to the Custom field, make sure to configure the Access Control Key in step 2.

      The assets you insert are referenced within your entry in the thumbnail view, by default.

      

      To change the assets view, select List from the drop-down menu as shown in the following screenshot:

      

      The assets you insert get referenced within your entry in the list view.

      

      Note: Once you add the maximum number of assets, as defined in config parameter, the Choose Assets button becomes disabled. You cannot add more assets than the preconfigured limit in the Custom field.

      When the Access Control Key is no longer served, the private assets become restricted to the user.

      
   8. Hovering over the image will allow you to reorder, preview, or remove it.
      1. To reorder the image, hover over it and select the Reorder icon. This will allow you to drag and reorder the image to your desired position.
      2. To preview the image, hover over it and select the Preview icon. You will be able to view the image in a new tab.
      3. To delete the image, hover over it and select the Remove icon.

      Thumbnail View

      

      List View

      
   9. Once you have added the assets, Save and Publish your entry.

   Steps to use the Cloudinary App as a JSON RTE Plugin

   1. In the Content Type Builder page (while creating the content type), add JSON Rich Text Editor in your content type by clicking the Insert a field link represented by a + sign.
   2. Under Select JSON RTE Plugin(s), select Cloudinary, and then click Add Plugin(s).

      To add the Config Parameter in the JSON RTE field, click the gear icon on the app plugin selector page.

      

      You can set the maximum number of assets, folder path, and the resource type that can be added in the JSON RTE field inside, as shown in the following screenshot:

      As seen in the above screenshot, we have added an object, named advanced, which includes the following keys in the given format:

      
      • path: Holds the path of the folder which is, by default, selected to choose products.
      • resource_type: Holds the type of assets you want to add. In our example, we want to add images only.
      {
          "advanced": {
              "cloudinary": {
                  "folder": {
                      "path":"demo_assets/sample",
                      "resource_type":"image"
                  }
              }
          } 
      }
      

      Additional Resource: You can add more optional parameters within the Cloudinary object. For detailed description of these optional parameters, refer to the Cloudinary Media Library Widget documentation.

      This adds Cloudinary in the JSON Rich Text Editor.

      
   3. After adding the app in a JSON Rich Text Editor field, click Save or Save and Close to save your changes.
   4. To use the Cloudinary app as a JSON RTE plugin, create an entry for this content type. To do this, in the left navigation panel, navigate to the Entries page, click + New Entry to create a new entry for the above content type, and then click Proceed.

      You will see the Cloudinary app icon inside the JSON RTE field in your entry page as shown below:

      
   5. Click the Cloudinary app icon to open the selector page or Media Library.
   6. If you are not logged into your Cloudinary account, it will ask you to enter your credentials. Once you do that, you are directed to your assets section. Choose one or more media files from the Media Library folder and then click the Insert button.

      Note: If you have set the Config Parameter in the Custom Field Advanced Properties, you will directly land to the selected folder.

      You can also add transformed assets. Transformed Assets are the files (such as images, videos, etc.) that have been modified or processed using Cloudinary's extensive transformation capabilities. These transformations can include resizing, cropping, format conversion, applying effects, watermarking, and more.

      Select the image, click the three ellipses, then click Open from the list, you can see several transformed options under the Templates heading. You can create a new template or select the transformed asset and click the corresponding Insert button to add it to the JSON Rich Text Editor field.

      

      You can also add restricted assets in the JSON Rich Text Editor field.

      

      Note: To successfully add and view private images to the JSON Rich Text Editor field, make sure to configure the Access Control Key in step 2.

      The selected asset(s) gets displayed in the JSON Rich Text Editor:

      

      Note: Once you add the maximum number of assets, as defined in config parameter, the Choose Assets button becomes disabled. You cannot add more assets than the preconfigured limit in the JSON Rich Text Editor field.

      When the Access Control Key is no longer served, the private assets become restricted to the user.

      
   7. To resize the image, drag the corner of the image and adjust the size as required. Hover over the image to view the following options:
      1. Click the Preview icon to view the image.
      2. Click the Open in Cloudinary icon to open the image in Cloudinary.
      3. Click the Edit icon to edit the image. Make the necessary changes and click the Save button.
      4. Click the Remove icon to remove the selected image.
      

      Additional Resource: You can use alignment and inline asset features to edit the asset placement within the JSON Rich Text Editor field.

   8. After adding the asset(s), Save and Publish your entry.