Contents


5 insider tips to customize themes in the IBM API Connect Developer Portal

Comments

In IBM® API Connect, you can publish your products and APIs in the Developer Portal for other application developers to use. To provide a coherent and consistent experience for these developers, you can create themes in the Developer Portal to match the look and feel of your organization's existing online presence. By carefully creating themes in the Developer Portal, your API consumers get a solid feel for interacting with your brand.

With Drupal, the innumerable options for configuring themes can make this process of transforming your API Connect Developer Portal seem somewhat daunting at first. By reading the tips and tricks that we learned when working with our clients, you can make clearer decisions about your themes and streamline the development process.

Here is an example of the default Developer Portal, where you start designing and customizing your brand.

Default Developer                     Portal
Default Developer Portal

The basics of a theme

A theme in the Developer Portal is a Drupal 7 subtheme that is inherited from the main API Connect Developer Portal theme. The empty subtheme looks identical to the default Developer Portal in API Connect and is an excellent starting point for transforming appearance.

The theme folder, which is in a compressed file that you upload to the Developer Portal, typically contains the following directories:

  • CSS. This folder contains all of the CSS files for the portal theme. It is typically where any font stylesheets are stored, along with the essential overrides stylesheet.
  • Images. This folder contains all of the images that will be added to pages on the Developer Portal. Upload these images as part of the theme folder, rather than source them from the web.

The compressed file also contains the following default files:

  • favicon.ico. This file, which is a small image file for the fav icon, is normally uploaded as part of the theme folder.
  • Logo. The logo file is an image for the logo that is used on the customized portal. This file is normally uploaded as part of the theme folder.
  • demoThemeName.info. This file is mandatory for any theme and contains metadata and information about the composition of the theme. The themeName in this case must be the name of the theme and must be consistent across several files.
  • template.php and theme-settings.php. These files include the required PHP code to make the theme work. The template.php file is where you add custom PHP methods to extend the site functions.
  • screenshot. This file is a small screen capture of the theme home page to help you identify each theme from the theme selector menu in the GUI.

The name of the theme folder must be the same as the .info file name, which is demoThemeName in this case. In the following example, the openbank_theme theme folder has a corresponding openbank_theme.info file.

Default file structure for the openbank_theme                 folder
Default file structure for the openbank_theme folder

Tip #1. Use the Custom CSS option when developing the overrides.css file

When you create another theme for the Developer Portal, most of the work is in producing the overrides.css file. This file is a stylesheet that overrides the existing styles that are applied to the elements that make up the Developer Portal site. The overrides sheet is where, except for images and PHP methods, all of the visual transformations of the theme are described. The development of this file tends to be iterative, in that changes to a small section of the site are made and their effects are appraised before you continue. After you make some changes, you must deactivate, uninstall, and reinstall the entire theme for the changes to take effect. Although this process is time-consuming, use the custom CSS capability to make it more efficient.

When you need to change the CSS file, use the Custom CSS option, which is available to the administrator of a portal site. By using the Custom CSS mechanism, the changes are applied instantly to the site, making the iterations when you develop this code faster and more efficient.

To access the Custom CSS option:

  1. Click Appearance -> Settings. Then, select your theme from the tabulated list.
  2. Click Extensions, and from the list of extensions, select Custom CSS to enable the option for this theme.
  3. Save the configuration. Then, go to the Custom CSS extension that is now visible in the list of Extensions.
  4. Enter any valid CSS into the text box, and save the configuration again to have it take effect.
Custom CSS added to the Developer Portal
Custom CSS added to the Developer Portal

The Custom CSS overrides every source of style, including the overrides.css file. For this reason, develop small amounts of CSS this way before you transfer the CSS to the overrides.css file. In this way, you can minimize the number of theme reinstallations and be confident that the theme is progressing as expected.

Tip #2. Use the page classes

When you develop themes, you might need to target an element on only one page. We found that the best way to achieve this goal is to start the CSS declaration with the page-specific class, which is found on the body element. Every portal page adds its own specific class to the body, allowing for easy targeting of elements on a page.

For example, if you want to change the background color of all div elements on the product page (but not anywhere else on the site), you can target them by using the following CSS:

.page-product .teaser-mode div {
      background-color: grey;
}

Or, you might want to change the paragraphs on the application page to the color gray:

.page-application .teaser-mode p {
       background-color: gray;
}

You can discover the exact classes on the body element by using your browser's developer tools. When you develop a theme, you are likely to be more specific in identifying each element to style. If you start the declaration with the correct body class, only the specified elements on that page are affected.

Tip #3. Create your own set of classes for custom blocks, and reference the theme in the overrides.css file

When you create custom blocks, especially if the final theme contains many custom blocks, create your own set of classes within the HTML of the blocks. Then, reference these themes in the overrides.css file. By using this approach, you can easily reuse styles between blocks. You can label elements within the HTML of the blocks with CSS classes from the stylesheets in the Developer Portal. However, this method can lead to confusion later if you need to override the existing styles but do not want to change the appearance of certain custom blocks.

We found this tip useful when we created each block as a stand-alone piece of HTML/CSS. When we used the browser to render the code while we developed it, each section of HTML linked to its own stylesheet until the block looked right. After we were satisfied with the HTML and CSS files, we created the block in the Developer Portal and added the CSS file to the overrides.css file.

Tip #4. Extend the Developer Portal functions with custom PHP methods

You might often find it helpful to extend the functions of the Developer Portal for your own use case. You can achieve this goal by creating a Drupal module or by adding your own PHP code to the template.php file within a theme. Creating a custom Drupal module is a larger task than editing the template file. Therefore, if the task is suitably small and self-contained, edit the template file to make any changes to the custom PHP methods.

The possibilities for extension are vast because your custom methods can hinge on any of the Drupal  hooks. Hooks are the basis for the Drupal modular system and follow a systematic style. They are PHP functions that are named moduleName_hookName(), where moduleName is the name of the module, and hookName is the name of the Drupal hook.

For example, one of our clients needed to send the name of the API with their support requests. Because this capability is not available by default in the Developer Portal, the client asked us to write custom PHP functions for them. This task entailed creating two functions: adding a drop-down list of APIs to the form and attaching the API name to the Subject field of the automatically generated email when the form is completed. Both functions were appended to the template.php file.

Adding the list of APIs to the form

The first function that we created uses the form_{formid}_alter hook. In our case, the ID of the form is contact_site_form. This hook is how Drupal knows which forms in the Developer Portal to alter. Each form HTML is labeled with a unique ID. The code performs the following actions:

  • It gets a list of all APIs.
  • It gets the name value of each API and stores these values as $api_array.
  • It adds the 'apiselect' field, to the form, with the values shown in the following example.
  • It calls the validate function that is specified before it sends the form.

This function entails the following configuration:

function demo_theme_form_contact_site_form_alter(&$form, &$form_state, $form_id) {
       // Generate a list of APIs and store them in an array

       // Loop the array and extract the name of each API

       // Store the list of API names in a new array - $api_array

       $form['apiselect'] = array(
             '#type' => 'select',
             '#title' => 'API Dropdown',
             '#options' => '$api_array',
             '#description' => 'Please select an API from the menu below',
             '#weight' => '-10',
             '#required' => TRUE
       )

       $form['#validate'][] = 'demo_theme_contact_site_form_validate';
}

Appending the user's choice to the form submission

The second function that we created uses the concept of form validation, that is, a function that must run against the forms content before it is sent. By creating this trigger, we can manipulate the form data and add the required field. The code appends the value of the 'apiselect' field (created in the first function) to the end of the subject field.

function demo_theme_contact_site_form_validate($form, &$form_state) {

       $form_state['values']['subject'] .= ' ' . $form_state['values']['apiselect'];
}

The combination of the two functions results in requiring all users to select an API before they submit the form (from the TRUE value of the required field). Then, this API name is displayed in the email with the request for support. Now, the support team can use this information to filter, group, or prioritize tickets.

Tip #5. Display the website slogan

Often, you can inject text into the header region of the Developer Portal by using slogans. If the site slogan displayed, you see it as an h2 element in the header region of the page. From here, you can change the slogan as needed by using the CSS.

To display the website slogan below the logo, select Administrator -> Configuration -> System -> Site information. Enter your website slogan in the Drupal administrative panel. Click Save.

Now, when you go back to the home page, you can see the slogan. To change the style and positioning of the slogan, edit the CSS file.

Conclusion

In this article, you learned five tips to help you customize themes in the API Connect Developer Portal. Each tip is based on our experience in customizing the Developer Portal for our clients. To maximize efficiency when you create themes, use these tips with existing knowledge about themes in the Developer Portal topic in IBM Knowledge Center.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1044973
ArticleTitle=5 insider tips to customize themes in the IBM API Connect Developer Portal
publish-date=04192017