Cloudinary App Installation Guide

Cloudinary is an assets management tool for websites and mobile applications covering everything from uploading, storage, optimization, and delivery.

Contentstack Marketplace lets you install the Cloudinary application 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 Cloudinary in Contentstack Marketplace
3. Use Cloudinary 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. In the left-hand side primary navigation, click Settings. Then, go to Account, and scroll down to see the cloud name.
      
   3. Click Access Keys in the left navigation panel to view the API Key.
      
   4. Save the Cloud Name and API Key; you will need it while configuring your Cloudinary app in Contentstack.

2. Install and Configure Cloudinary in Contentstack Marketplace

   Follow the steps to install the application in Contentstack.

   1. Log in to your Contentstack account.
   2. In the left-hand side primary navigation, click the Marketplace icon to go to the Marketplace. 
      
      
   3. Click Apps from the left panel.
   4. Within the Marketplace, you can see all the available apps. Hover over the Cloudinary app and click Install App.
      
   5. In the popup window, select the stack where you want to install the Cloudinary app, accept the terms and conditions, and click the Install button.
       
   6. On the Configuration screen, enter the following details:
      1. Enter the Cloudinary Cloud Name and API Key retrieved from your Cloudinary Account in step 1.
      2. 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 dropdown appears in which public_id, resource_type, and 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 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 Save in Entry feature is applicable to Cloudinary Custom Fields only.

   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.

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

   8. Click the Save button.
   9. Click Open Stack to start using the Cloudinary application.

3. Use Cloudinary within your Stack

   To use the Cloudinary application 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 application in your entry.

   1. Custom Field
   2. JSON Rich Text Editor field

   Steps to use Cloudinary within the 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 that can be added in the custom field inside Config Parameter, as shown in the following screenshot:
      
      Add an object named as advanced which includes a key named max_limit and its value as the maximum number of assets you want to add, in the following format:
      {"advanced":{"max_limit":3}}
      

   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 can see the Cloudinary app’s custom fields on 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 sections. Select the image file(s) and then click the Insert button to add them to your entry.
      
   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 gets disabled. You cannot add more assets than the preconfigured limit in the Custom field.

   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 Cloudinary within the JSON Rich Text Editor field

   1. In the Content Type Builder page, add JSON Rich Text Editor in your content type by clicking the Insert a field link represented by a + sign. 
   
   2. To add the Cloudinary plugin in JSON RTE, click the Properties icon of JSON RTE, and under Select JSON RTE Plugin(s), choose the Cloudinary app, and then click the Add Plugin(s) button. 
      
   3. After adding the plugin, click Save or Save and Close to save your changes. 
   
   4. To use the Cloudinary app as JSON RTE plugin, create an entry for this content type. 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 sections. Choose one or more media files from the Media Library and then click the Insert button.
      
      The selected asset(s) gets displayed in the JSON RTE editor:
      
      
   7. You can resize the image by adjusting the size from the corners.
   8. Hover over the image to preview, edit, or remove it.
      1. Click the Preview icon to view the image.
      2. Click the Edit icon to edit the image. Make the necessary changes and click the Save button.
      3. Click the Remove icon to remove the selected image.
      
   9. To add inline text to the selected image, follow the steps below:
      1. Drag and resize the image as required.
      
      2. Click the Edit button, choose the right or left alignment, check the Inline Asset checkbox, and then click the Save button.
      
      3. Add the required text next to the image.
         

   The assets you select are referenced within your entry. You can add more assets by following the steps as discussed above, or simply save and publish your entry as it is.