Applying a modified content type template

You can apply a modified content type template to override a default content type template in the Developer Portal. For example, you can override the product content type template to change its layout.

Before you begin

You must have administrator access to complete this task.

You must also have a custom sub-theme, and a copy of an existing template that you want to update. For information about how to create a sub-theme, see Creating a sub-theme.

To obtain a copy of an existing template, you can download a copy from the following locations on GitHub: Note that you must copy the template to your sub-theme, and then modify the content. Do not modify the content that is stored on GitHub.

About this task

You can override the Developer Portal core templates by creating a custom sub-theme, and then adding your modified templates to the sub-theme folder. A sub-theme inherits all of the settings of its parent theme, apart from the settings that are overridden, such as by applying modified templates. After you have applied a modified content types template, these changes take precedence over the default content types template. The Developer Portal templates are formatted as Twig template files. The following levels are examples of where you can use templates:
  • html.html.twig - the template for Developer Portal HTML pages
  • page.html.twig - the body of Developer Portal HTML page
  • node.html.twig - the template for all of the content nodes
  • comment.html.twig - the template for all of the comment nodes
  • search-result.html.twig - the template for search results
  • node--product.html.twig - the template for nodes that use the Product content type
  • node--product--teaser.html.twig - the template for the previews for the Product content type
For more information about Twig templates, see Working with Twig templates and Debugging Twig templates on the Drupal documentation website.

Modifying Twig templates allows very fine-grained control over the structure of pages. However, it also means you might miss new features and defect fixes that are made to the original templates, as your Developer Portal is using your overrides instead of the originals. So, if you override a template, it is your responsibility to check the templates in the latest API Connect releases, and to ensure that any equivalent changes that are needed to your overrides to maintain functional equivalence are made.

Important:

Directly editing any API Connect theme files is not permitted or supported, as edited versions of these files are overwritten when a fix pack or iFix is installed.

Procedure

To override a default content type template:

  1. Apply the modifications that you require to the default template that you obtained.
    Warning: Although the ability to override templates is supported, if you override a template they are your responsibility. Templates can be from multiple sources and compatibility with an earlier version is not ensured. You must check the templates in the latest API Connect release to check whether you need to make equivalent changes to your overrides to maintain functional equivalence.
  2. Create a directory in your custom sub-theme, and name it templates.
  3. Add your modified template to the templates directory.
    Note: The modified template file name must be identical to the original name of the template file that it is overriding.
  4. Log in to the Developer Portal UI as an administrator.
  5. If the administrator dashboard is not displayed, click Manage to display it.
  6. Install your custom sub-theme onto the Developer Portal by clicking Appearance > Install new theme on the administrator dashboard.
  7. Click Choose file, select your sub-theme, and then click Install.
  8. Click Install newly added theme, find your new theme in the list of Uninstalled themes, and click Install and set as default to set your new custom sub-theme as the default theme for your site.
    Your new theme, which contains the modified template file, is now set as the default theme, and is listed in the Installed themes section.

Results

You successfully modified and applied a template to override a default content type template in the Developer Portal.