Brandfolder App Installation Guide

Brandfolder is a cloud-based and customizable digital asset management platform many brands use to organize all digital assets in one place. Marketers and creatives use this platform to readily organize, control, create, distribute, and measure all their digital assets.

Contentstack Marketplace lets you install the Brandfolder app and use it within your stack to fetch and display digital assets from the Brandfolder account within your entries.

Prerequisites

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

Follow this step-by-step guide to install and configure Brandfolder within your stack.

Steps for Execution

1. Retrieve credentials from your Brandfolder account
2. Install and configure the Brandfolder app in Marketplace
3. Use the Brandfolder app within your stack

1. Retrieve Credentials from your Brandfolder Account

   To get the API Key for Brandfolder, log in to the Brandfolder account (as an Owner or Admin) and follow the steps given below:

   Note: If you already have a guest account, log in to the Brandfolder account (as a Guest), or create a new one.

   1. To create a guest account, navigate to your workspace, click the horizontal ellipses, and select Manage Users.
   2. You are redirected to the All Users > User Management section. Under the Invite tab, fill in the details and click Send invitations. You will get an invitation email.
   3. Click the Accept Invitation button in your email to go to the guest account dashboard.
   4. Now, click the username dropdown in the top-right corner, and navigate to My Profile.
   5. Click Integrations in the left panel and copy the API Key.

2. Install and Configure the Brandfolder App in Marketplace

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

   1. Navigate to the “App Switcher” icon in the top-right corner and click Marketplace.
   2. Click Apps from the left panel.
   3. Within the Marketplace, you can see the available apps. Hover over the Brandfolder app and click Install.
   4. In the pop-up window, select the stack where you want to install the Brandfolder app, accept the Terms of Service, and click the Install button.
   5. On the Configuration screen, you can add multiple configurations for Brandfolder. To do so, follow the steps given below:
      1. Click the + New Configuration button to add new configuration details.
      2. In the Add Configuration modal, enter the configuration Name and click Add.
      3. Enter the Brandfolder API Key retrieved from your Brandfolder account in step 1.
      4. Set as Default: To set this configuration as the default, click this checkbox.

         Alternatively, click the vertical ellipsis on the top-right side of the configuration section, then select Set as Default from the menu.

         

         Note: At least one app configuration should be selected as the default.

         Similarly, you can add multiple configurations by following the steps discussed above.

      5. To delete the configuration, click the vertical ellipsis and select Delete Configuration.

         In the Confirm Deletion modal, add the configuration name and click Delete.

         
      6. For an existing user, the credentials will be added as the default configuration, and named as legacy_config.

         Warning:

         • legacy_config is a reserved keyword and you cannot use it in adding new configurations.
         • If you delete the legacy_config configuration, data loss may occur and you will not be able to access the products and categories from the related accounts.
      7. Legacy Settings: Legacy Settings allow you to use the Brandfolder Extension. To enable the extension, simply toggle the Enable Extension Support option. If this toggle is enabled, you will be able to get the asset JSON data similar to the Brandfolder Extension.

         Note: If the extension is enabled, All Fields and Custom Fields option cannot be accessed to save the Brandfolder keys within the entry.

      8. Choose the Brandfolder Keys to Save in Entry: Choose how to save the data fetched from Brandfolder in Contentstack entries.
         1. If you select the All Fields option, you can select only a limited number of assets in the entry.
         2. With Custom Fields, you can search and add specific Brandfolder fields that you want to save in entries.
         

         If you select Custom Fields, then the Brandfolder Keys drop-down appears. By default, id, name, url, assetId, filename, extension, sizeInBytes, dimensions, and apiDto.attributes.cdn_url keys are selected. If you want to create a new key, click the + New Key Field option.

         

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

         
   6. After adding the configuration details, 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.

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

   8. Click Open Stack to start using the Brandfolder app.

3. Use the Brandfolder App within your Stack

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

   1. Navigate to the stack dashboard, click Content Models in the header, then New Content Type. From the dropdown, select Create New.
   2. Create a content type by adding relevant details as displayed below:
   3. There are two ways to use the Brandfolder app in your entry:
      1. Custom Field
      2. JSON Rich Text Editor field

   Use the Brandfolder App as a Custom Field

   1. In the Content Type Builder page, add a Custom field by clicking the Insert a field link represented by a + sign.
   2. Under Select Extension or App, select Brandfolder and click the Proceed button.

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

      

      Additional Resource: To set the configuration object, refer to the Set Advanced Config Object in Custom Field section.

   3. After adding the app, click Save or Save and Close to save your changes.
   4. To use the Brandfolder app, create an entry for this newly created content type. Navigate to Entries in the header, click + New Entry to create an entry within the same content type, and click Proceed.

      You can see the Brandfolder app’s custom fields on your entry page as shown below:

      
   5. Click + Choose Asset(s) button.
   6. Choose the Collection to select the asset from your Brandfolder account to add them to your entry.

      You can add the Brandfolder assets in two ways:

      1. Hover over the image, click the three ellipses icon, and then click Place to add the asset to your custom field from the Brandfolder selector page.
      2. Hover over the image and click View Details.

         Go to Placement options and click Place to add the asset to your custom field from the Brandfolder selector page.

         

         You can edit the File Type, Width, and Height of the image before placing it.

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

      

      Note: You can select only one asset at a time to add to your entry.

      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.

      
   7. 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 allows 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 can view the image in a new tab.
      3. To delete the image, hover over it and select the Remove icon.

      Thumbnail View

      

      List View

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

   Set Advanced Config Object in Custom Field (Optional)

   While adding the Brandfolder app in the custom field in step 3, you can set the configuration parameter if you have added multi-configuration details during app installation in step 2.

   Under Advanced properties, you can set the Config Parameter for all entries of a particular content type.

   

   The key:value passed in the configuration object overrides the default app configuration settings.

   • Configuration Object: In case you want to use a different Brandfolder configuration for any custom field within the same stack, you need to specify the configuration name in the Config Parameter.

     {
       "config_label": [
         "Configuration-2"
       ]
     }

   • Locale Based Configuration Object (Optional): To add a locale-based configuration, add a locale parameter to the additional configuration object which specifies the locale value (for example: en-us) as the object key and the configuration object as the value to the locale.
     {
       "config_label": [
         "Configuration-2"
       ],
       "locale": {
         "en-us": {
           "config_label": [
             "Configuration-3"
           ]
         },
         "fr-fr": {
           "config_label": [
             "Configuration-1"
           ]
         }
       }
     }

   • Max Limit: You can set the maximum number of assets that can be added in the Custom field. In our example, it is 5.
     {
       "advanced": {
         "max_limit": 5
       }
     }

   • Asset Validations: Only those assets will be added in the custom field that satisfy the advance config constraints for size, height, and width.
     {
       "advanced": {
         "size": {
           "max": 10,
           "min": 5
         },
         "height": {
           "max": 10,
           "min": 5,
           "exact": 25
         },
         "width": {
           "max": 10,
           "min": 5,
           "exact": 25
         }
       }
     }

   Use the Brandfolder app as a JSON RTE Plugin

   1. In the Content Type Builder page, add a JSON Rich Text Editor field by clicking the Insert a field link represented by a + sign.
   2. Click inside the Select JSON RTE Plugin(s) field to open the Select Plugin modal.
   3. Select Brandfolder from the available options and click Add Plugin(s).

      This adds Brandfolder in the JSON Rich Text Editor.

      

      Additional Resource: To set the configuration object, refer to the Set Advanced Config Object in JSON RTE Plugin section.

   4. After adding the app in a JSON Rich Text Editor field, click Save or Save and Close to save your changes.
   5. To use the Brandfolder app, create an entry for this content type. To do this, navigate to the Entries page, click + New Entry, select the content type you created above, and then click Proceed.

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

      
   6. Choose the Collection to select the asset from your Brandfolder account to add them to your entry.

      You can add the Brandfolder asset(s) in two ways:

      1. Hover over the image, click the three ellipses icon, and then click Place to add the asset to your JSON Rich Text Editor field from the Brandfolder selector page.
      2. Hover over the image and click View Details.

         Go to Placement options and click Place to add the asset to your JSON Rich Text Editor field from the Brandfolder selector page.

         

         You can edit the File Type, Width, and Height of the image before placing it.

      The assets you select are added to your entry.

      

      Note: You can select only one asset at a time to add to your entry.

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

      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.

   Set Advanced Config Object in JSON RTE Plugin (Optional)

   While adding the Brandfolder app in the JSON RTE Plugin in step 3, you can set the configuration parameter if you have added multi-configuration details during app installation in step 2.

   To add the Config Parameter in the JSON RTE field, click the gear icon on the app plugin selector page. You can set the following validation for the JSON RTE field:

   

   In case you want to use a different Brandfolder configuration for any JSON RTE field within the same stack, you need to specify the configuration name in the Config Parameter.

   Configuration Object (Optional):

   {
     "config_label": [
       "Configuration-2"
     ]
   }