Customizing the theme

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

A theme is a collection of files that defines the look and feel of a site. The Developer Services portal is initially defined with a default theme, which you can customize. This allows you to select your preferences for the look and feel of your portal. More specifically, you can change the color of links, backgrounds, text, and other theme elements. You can also change the welcome message that appears on the front page of your developer portal.

You can customize the theme through the developer portal UI, or by writing code in a custom theme file to override the default theme file.

Depending on your version of the developer portal, you will have several themes to choose from:

Theme Description

Apigee Responsive theme

Based on Bootstrap 3, the default theme for later releases of the portal. This theme supports devices with widths from 768 pixels to 1400 pixels. All Bootstrap 3 features are available in this theme.

Note: To use the Apigee Responsive theme, ensure that the Bootstrap 7.x-3.0 theme is enabled.

Apigee DevConnect theme

The default portal theme previous to the Apigee Responsive theme.

Existing portals can be upgraded to the new Apigee Responsive theme but must first ensure that all blocks, templates, and other content is compatible with Bootstrap 3, and that the Bootstrap 7.x-3.0 theme is enabled.

Apigee Base theme

A parent theme to the Apigee DevConnect theme and not intended to be used on its own.

Setting the default theme

If your portal is still using the older Apigee DevConnect theme, you might see a warning in the form:

"Apigee DevConnect theme" is out of date 

You can use the following procedure to set the default theme for the portal. You should always test a new theme first on a non-production system before deploying the theme to production.

To set the default theme:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Appearance in the Drupal administration menu. The list of enabled themes appears.
  3. For the theme that you want to use as the default, select Set default.
    To use the Apigee Responsive theme, ensure that the Bootstrap 7.x-3.0 theme is enabled on that page as well.
  4. Save the configuration.

Customizing the Apigee Responsive theme

This section describes how to configure the Apigee Responsive theme, including:

  • Customizing modal forms
  • Customizing general settings

To customize modal form support:

The portal uses the Drupal Bootstrap Modal forms sandbox module to display Drupal forms as modals. The login and register forms by default function as modals. You can disable this functionality to have those forms appear as individual pages instead.

  1. Log in to the developer portal as a user with admin privileges.
  2. Select Configuration > User interface > Bootstrap Modal forms in the Drupal administration menu.
  3. Enable or disable modal support for forms.
  4. Select Save configuration.

To customize the general settings of the Apigee Responsive theme:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Appearance in the Drupal administration menu. The list of enabled themes appears.
  3. In the Apigee Responsive (default theme) area of the page, select Settings (do not select the Settings button at the top of the page).
  4. The settings page for the Apigee Responsive theme appears.
  5. The following table describes the areas on that page that you can use to configure the theme. If you change any of these settings, select Save configuration.

    Area Section Description

    Bootstrap settings

    Components

    Control the display of breadcrumbs, the position of the main menu (called the Navbar in the settings), and the display of region wells:

    • Breadcrumbs: Hide/show breadcrumb, turn on/off the Home link inside the breadcrumb.
    • Navbar: Change the position of the Navbar (main menu) to fixed/static/normal positions, making the layout more dynamic.
    • Region wells: Add a well class to any region on the site to add a darker background to the region.

    JavaScript

    Control the display of anchors, popovers, and tooltips:

    • Anchors: Fix anchor positions, and enable smooth scrolling.
    • Popovers: Popovers add small overlays of content to any element. Enable/disable popovers and configure how popovers are used.
    • Tooltips: Configure how tooltips are used. You can force each tooltip to display on the right, left, top, or bottom of each form element, and set other display options.

    Advanced

    Controls how the portal uses BootstrapCDN to update the Bootstrap theme files. You can disable the reliance of the portal on BootstrapCDN, but you then must provide your own implementation of the Bootstrap framework.

    DevConnect Settings

    Set the welcome message, the default colors, and the size of the logo that appears in the main menu.

    Override Global Settings

    Toggle display

    Enable and disable the display of different areas of the portal.

    Logo image settings

    Specifies the image displayed in the main menu.

    Shortcut icon settings

    Specifies the image displayed in the address bar of a browser or for a bookmark to the portal.

Customizing the Apigee DevConnect theme

The Apigee DevConnect theme is the default portal theme for older releases of the portal, and can be upgraded to the new Apigee Responsive theme. However, you must first ensure that all blocks, templates, and other content is compatible with Bootstrap 3 before performing the upgrade.

To customize the general settings of the Apigee DevConnect theme:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Appearance > Apigee DevConnect theme > Settings in the Drupal administration menu. This displays the initial settings for the theme. Color settings are specified as hexadecimal values.

  3. Change the settings to suit your preference.
    For example, add or change the welcome message or change the header background color. The header background color is initially set to something close to orange (#FF4300). You can change it to another color such as blue (#0000FF).
  4. When you are done changing the settings, click Save.

Customizing a theme by creating a sub-theme

All of the files and assets that define the default themes shipped with the portal are in the profiles/apigee/themes directory under the portal installation directory. This directory is at /var/www/html/profiles/apigee/themes if you installed the portal in the default location.

To edit a theme to modify the look and feel of the site, do not modify the theme files under profiles/apigee/themes directly. If you do, your changes will be overwritten the next time you upgrade the portal.

Instead, create a sub-theme of the theme that you want to modify by copying the default theme files to the /sites/all/themes directory. For instructions on sub-themes, see the Drupal documentation at https://www.drupal.org/node/225125.

The Drupal documentation specified above has detailed information about creating a sub-theme, but the general steps are listed below for creating a sub-theme of the Apigee Responsive theme:
  1. Copy the profiles/apigee/themes/apigee_responsive/apigee_responsive_starterkit folder to the /sites/all/themes folder.
  2. Rename the apigee_responsive_starterkit folder to YOUR_THEME_NAME.
  3. Rename the apigee_responsive_starterkit.info file to YOUR_THEME_NAME.info.
  4. Rename the css/apigee_responsive_starterkit.css to css/YOUR_THEME_NAME.css.
  5. Rename the js/apigee_responsive_starterkit.js to YOUR_THEME_NAME.js.
  6. Edit YOUR_THEME_NAME.info file and replace the following lines:

    stylesheets[all][] = css/apigee_responsive_starterkit.css
    scripts[] = js/apigee_responsive_starterkit.js


    with:

    stylesheets[all][] = css/YOUR_THEME_NAME.css
    scripts[] = js/YOUR_THEME_NAME.js
  7. Change the name of the theme in YOUR_THEME_NAME.info file from Apigee Responsive Starter Kit to YOUR THEME NAME.
  8. If you want to add a new screenshot for your theme then replace the existing screenshot.png file.
  9. If you want to add a new logo to your theme then replace the exiting logo.png file.
  10. If you want to add a new favicon to your theme replace the existing favicon.ico file.