Customize Your Content Portal

You can modify the Content Portal look, feel, and behavior by using your own CSS and JSON files.

Prepare your sitemap for Content Portal customizations. See Prepare a Sitemap for Content Portal Customizations.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Content Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Content Portal instances are instantaneous.

If you want to edit your existing Content Portal customizations, see Edit the Existing Content Portal Customizations.

Prepare a Sitemap for Content Portal Customizations

You prepare a sitemap for Content Portal customizations by adding a <sitemeta> element to the sitemap. You can find more information on sitemaps in Content Portal Layout and Navigation.

There is a portal_configuration folder created within the __configuration folder in the content library that stores your config.json and {file_name}.css files for the portal configuration and styling.

  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. In the content library right-click the sitemap that you want to modify and select Dock.
  3. In the left pane, ensure that all map elements are shown:
    1. Click the cog icon.
    2. Under Show Elements, select All.
    All elements option
  4. Right-click the TITLE element and select Insert element after > sitemeta.
    Inserting sitemeta element

Customize the Content Portal Settings

You can add a custom logo, footer, title, and more by overwriting the default Content Portal settings.

Prepare your sitemap for Content Portal customizations. See Prepare a Sitemap for Content Portal Customizations.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Content Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Content Portal instances are instantaneous.

Prepare the configuration file.
  1. In the __configuration folder, create a folder called portal_configuration.
  2. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  3. Right-click on config.json file and click the Edit Source button to open the file in the Source Editor.
    For more information, see Content Portal Configuration Reference.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the config.json file onto the SITEMETA element.
    Inserting the config.json file
    The config.json file is added as a DATA element.
    sitemeta element
  3. In the left pane, hover over config.json and click the wrench icon.
  4. In the pane that appears, in the name field, enter config
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Content Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Customize the Content Portal Style

Overwriting the default Content Portal style enables you to customize its look and feel.

Tip:

The following procedure assumes that you will be updating and maintaining your CSS customizations directly in Heretto CCMS.

If you want to maintain your CSS code on a server external to Heretto CCMS, you can add the following code to the config.json file to call and apply the CSS.

"stylesheets": ["your-server-url/custom.css"]
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Content Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Content Portal instances are instantaneous.

Keep the following guidelines in mind when styling your Content Portal:

  • Avoid using negative values for margin and padding properties.
  • Avoid using percent values. Try using flex or flex-basis properties.
  • If you use percent values, the value should a base 8 root percent.

    For example, you can use: 100%, 50%, 25%, 6.25%, 3.125%.

  • Use flex for general layout properties.
  • Use grid for specific use cases like lists and items that need to be fixed to a certain number.
Prepare the configuration file.
  1. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  2. Add custom CSS for styling your Content Portal.
    While developing the custom.css file, you'll need to get CSS selectors. For more information, see Get CSS Selectors for Portal Styling.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the custom.css file onto the SITEMETA element.
    Inserting the custom.css file
  3. In the left pane, hover over custom.css and click the wrench icon.
  4. In the pane that appears, in the name field, enter stylesheets
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Content Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Get CSS Selectors for Portal Styling

The DITA elements are rendered as HTML elements with classes that you can use to define CSS selectors.

In Google Chrome™ or Mozilla Firefox, access the Content Portal instance that you want to style.
  • To inspect a particular element, right-click the rendered DITA element and do one of the following:
    • For Google Chrome™, select Inspect.
    • For Mozilla Firefox, select Inspect Element.
    Figure 1. Rendered Note Element.
    The following example (from Google Chrome™ and Mozilla Firefox respectively) shows that:
    • The note DITA element is rendered as a div HTML element with the note and note_note classes
    • You can use the .note CSS selector to style all note DITA elements

    CSS element with classes example

    Inspect tool example
  • To quickly inspect different elements, do one of the following:
    • For macOS, press Cmd > Shift > C and hover over different elements.
    • For Windows, press Ctrl > Shift > C and hover over different elements.
    Figure 2. Live Inspection in Firefox
    Live inspection

Customize the Content Portal Behavior

To extend the default Content Portal behavior or add custom features, you can implement your own JavaScript code.

Prepare your sitemap for Content Portal customizations. See Prepare a Sitemap for Content Portal Customizations.
Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Content Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Content Portal instances are instantaneous.

Prepare the configuration file.
  1. Upload the config.json, scripts.js, or CSS file into the __configuration/portal_configuration folder in the content library.
    Important: Do not upload empty files into Heretto CCMS.
  2. To open the file, right-click on scripts.js file and click the Edit Source button to open the file in the Source Editor.
Add the configuration file to your sitemap.
  1. In the content library double-click on the sitemap that you want to modify to open it in the Content Editor.
  2. Drag and drop the script.js file onto the SITEMETA element.
    INserting script.js file
    The script.js file is added as a DATA element.
    sitemeta element
  3. In the left pane, hover over script.js and click the wrench icon.
  4. In the pane that appears, in the name field, enter scripts
  5. If needed, clear the scope field by clicking the corresponding trash icon.
  • Verify the configuration changes by opening your Content Portal in a web browser.
    Tip: If you still cannot see your edits, try clearing your web browser cache.

    If you use Mozilla Firefox, see How to clear the Firefox cache.

    If you use Google Chrome™, see Clear cache & cookies.

Edit the Existing Content Portal Customizations

You can edit the Content Portal configuration files directly in Heretto CCMS.

Note: Your content library may contain multiple sitemaps associated with different portal instances such as production (public) or staging (internal) instances. We recommend keeping the sitemaps associated with production (public) Content Portal instances on distinct branches different than the default “master” branch.

Any configuration, style, behavior, or content changes that you make to the sitemaps associated with your Content Portal instances are instantaneous.

  1. In your content library, navigate to the following folder __configuration/portal_configuration.
  2. Right-click the config.json, custom.css file, or script.js file and select Open in Source Editor .
  3. Make changes to the file.
  4. Click Save.
Verify the configuration changes by opening your Content Portal in a web browser.
Tip: If you still cannot see your edits, try clearing your web browser cache.

If you use Mozilla Firefox, see How to clear the Firefox cache.

If you use Google Chrome™, see Clear cache & cookies.

Upload Files to the Content Library

You can upload images and other allowed file types to the content library.

  • If you want to upload a large number of files, compress these files to a ZIP archive.
    Tip: Uploading files compressed to a single ZIP archive is quicker than uploading multiple files without compressing them first.

    By default, when you upload a ZIP archive to the content library, Heretto CCMS unzips the archive retaining its folder structure. If needed, you can also upload a ZIP archive to the content library without unzipping it.

    Uploaded files must be under 100MB in size.

  1. In the content library, navigate to the folder where you want to upload your files and click the Upload icon.
  2. If you selected any files that already exist in the content library folder and you don't want to overwrite them, clear the corresponding Overwrite files with the same names check box.
  3. If you selected any ZIP files that you do not want to be automatically unzipped, clear the corresponding Unzip check box.
  4. Click Upload Files.