Customization

Customization Overview

The customization feature provides you options to customize the Developer Portal UI to suit your needs. This feature allows you to completely customize the portal to establish your brand among your consumers. As administrators and API providers, who set up their portal to offer APIs, you would want your portal to be unique and recreate your brand by tailoring the portal the way you want. Customization helps you to achieve this.

Customization could involve changing logos, organizing available blocks or other UI components, based on your priority and marketing strategy. Developer Portal comes with a WYSWYG UI that allows you to preview your customization and proceed accordingly.

Developer Portal offers different levels of options to perform customization. They include:

This section describes the feature and detailed procedures for customizing Developer Portal.

Customization based on themes

Developer Portal allows you to perform the customization through themes. The Themes feature under the Administration section provides you the options that you can use to specify your customization.

You can create themes, perform required customization, and activate the theme to apply the customization. You can create any number of themes and customize each of them differently. However, you can have only one theme activated for a portal at a time.

Managing Themes

Theme contains all information about the UI appearance and they determine the look and feel of the UI. So, you should create a theme, specify your changes and apply it to customize the UI. The high level steps are:

You can have more than one theme and apply them according to your requirements. However, you can have one theme activated at a time.

How do I create a theme for customizing the Developer Portal UI?

You can create a theme from scratch or clone one from an existing theme.

This use case starts when you want to create a theme for customizing your portal UI and ends when you have successfully created the theme.

In this example, you create a theme named Dark theme.

Before you begin:

Ensure you have the API Administrator privilege.

To create a theme

  1. Click the menu options icon from the title bar.

  2. Select Administration, and click Manage themes.

  3. Click Create theme.

  4. Provide Dark theme in the Name field.

  5. Provide 1.0 in the Version field.

  6. Click Create.

    The new theme appears in the Manage themes page.

Alternative steps:

Next steps:

Customize pages

Developer Portal pages include multiple sections. Sections include different objects like headings, text, images, links, tags, and icons.

The Pages section provides you options to select a page and customize its sections or add a new page. From the Pages section, you can:

The screen indicates the options available for customizing the Developer Portal pages.

How do I customize a block on a page?

You can divide a page into multiple blocks and customize the blocks individually to transform the page.

This use case begins when you want to customize a block and ends when you have completed customization.

In this example, the first image in the Welcome page of the theme Theme1 is modified.

Before you start

Ensure that you have created a theme or have a theme to customize.

To customize a block

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and select Welcome.

    The Welcome page appears with the corresponding editing options for each of the blocks.

  3. Move your mouse pointer over the first image on the Welcome page and click the edit icon .

  4. Click Browse and select the required image.

  5. Click Save.

    Your changes are saved.

Alternative steps:

  1. In Step 3, move your mouse pointer over a block for customization options. The options to customize the block appear in the Layout configuration section of the right pane. For information on the customization fields, see Customization fields.

  2. When the focus is set on a component, click of the component to shift focus to the parent component.

    When you select a parent component for editing, press Esc to clear the selection, before selecting any other component.

Next steps:

Customization fields

This section lists the fields that are used to customize the blocks on a page.

Layout configuration options for page alignment
Field Description
Direction Specifies the direction of text in a block.
Available options are:
  • Row. Aligns components in a horizontal fashion like a row.
  • Column. Aligns components in a vertical fashion like a column.
Main axis Specifies the option to determine how the components in page must be distributed between and around the main axis of the page.
Available options are:
  • Start. Aligns components from the start of the block.
  • Center. Aligns components towards the center of the block.
  • End. Aligns components towards the bottom portion of the block.
  • Space around. Distributes components evenly. Components have a half-size space on either end. Aligns the paragraphs in a block allowing space around each paragraph.
  • Space between. Distribute components evenly The first item is flush with the start, the last is flush with the end
Tip: You can try the options, check results, and select
Cross axis Specifies the option to determine how the components in page must be distributed between and around the cross axis of the page.
Available options are:
  • Stretch. Stretches and aligns components to fill the block.
  • Center. Aligns components towards the center of the block.
  • Start. Aligns components from the start of the block.
  • End. Aligns components towards the bottom portion of the block.
Minimum height Specifies the minimum height of a component.
It prevents the used value of the height property from becoming smaller than the value specified value.
Width Specifies the width of the page.
Flex basis Specifies the initial minimum width of the page.
Layout configuration options for headings
Field Description
Is display string a property key or plain text? Specifies the type of text displayed as heading.
Select one of these options:
  • Text. To display plain text and provide the text to be displayed.
  • Key. To display localization text and provide the required key.
Type Specifies the heading level. The value ranges from H1 to H6.
Layout configuration options for images
Field Description
Has context? Specifies if you insert an image using context.
If you enable this, provide the JSON representation of the image that has to be inserted in the Source field. For example
{
'icon' : '...'
}
${icon}
The value of icon is retreived from the JSON provided in the field.
Browse Allows you to select an image from your device.
Alt text Provide the alt text for the image.
Height (in pixels) Provide the height of the image in pixels.
Width (in pixels) Provide the width of the image in pixels.
Layout configuration options for buttons and icons
Field Description
Icon button Specifies whether the button is an icon.
Icons customization options
Size Specifies the size of the icon.
Available options are small, medium, large, and extra small.
Note: You can try these options, check the preview, and select the required type.
Icon Allows you to select an icon from the list of default icons such as Save, Close and so on.
Tooltip Provide the tooltip that must appear for the icon.
Button customization options
Button type Specifies the style of button. Available options are Primary, Secondary, Tertiary, and Emphasis.
Note: You can try these options, check the preview, and select the required type
Size Specifies the size of the icon. Available options are small, medium, and large.
Note: You can try these options, check the preview, and select the required type.
Is display string a property key or plain text? Specifies the type of text displayed on the button. Select one of these options:
  • Text. To display plain text and provide the text to be displayed.
  • Key. To display a localization text and provide the required key.
Layout configuration options for Tags
Field Description
Value Provide the text, as comma separated values, that must appear on tags.
Field Description
Type Specifies the type of link.
Available options are Internal and External.
Target link Provide the required link.
Is display string a property key or plain text? Specifies the type of text displayed as link. Select one of these options:
  • Text. To display plain text and provide the text to be displayed.
  • Key. To display a UI label and provide the required key.
Layout configuration options for text editor and HTML enabled
Field Description
Configure the value Provide the custom text or HTML code.
Layout configuration options for web components
Field Description
Name Select the name of the web component.
Element name Select the required element name.

How do I add a new block and component?

Page is made of multiple blocks. You can add new blocks or customize the available blocks as per your requirements.

This use case starts when you want to add a block and ends when you have added it.

In this example, you add a new heading component to the Home page of the theme Theme1.

Before you start

Ensure that you have created a theme or have a theme to customize.

To add a block and components

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and select Home.

    The Home page appears with the corresponding editing options for each of the blocks.

  3. Move your mouse pointer top-right corner of the page and click the add icon .

  4. Select Heading from the Component section.

  5. Move your mouse pointer over the new block and click the edit icon .

  6. Provide the heading text in the Layout configuration section.

  7. Click Save.

    Your changes are saved.

Alternative steps:

You can select one of the following layouts or components for your new block from the Layout and Components sections respectively:

Note
This table lists only the default layouts. This section will also include the custom layouts to allow you select them. You can create custom layouts from the Layouts section.

Next steps:

How do I move blocks in a page?

You can move blocks within a page and cannot move across pages.

This use case starts when you want to move a block and ends when you have saved your changes.

In this example, you move down the three headings above the images in the Welcome page of the theme Theme1.

Before you start

Ensure that you have created a theme or have a theme to customize.

To move a block:

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and select Welcome.

    The Welcome page appears with the corresponding editing options for each of the blocks.

  3. Move your mouse pointer over the image heading and click .

  4. Repeat for the other two headings.

  5. Click Save.

    Your changes are saved.

Next steps:

How do I remove a block from a page?

This use case starts when you want to remove a block and ends when you have removed.

In this example, you remove the breadcrumbs section from the API gallery page of the theme, Theme1

Before you start

Ensure that you have created a theme or have a theme to customize.

To remove a block

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and select API gallery.

    The API gallery page appears with the corresponding editing options for each of the sections.

  3. Move your mouse pointer over the breadcrumbs section and click

    The block is deleted from the page.

  4. Click Save.

    Your changes are saved.

Next steps:

How do I add a page?

You can create links to access the page from any other page or top navigation bar.

This use case starts when you want to add a page and ends when you have added the page.

In this example, you add a new page Page1, in the theme, Theme1.

Before you start

Ensure that you have created a theme or have a theme to customize.

To add a page

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and click Add.

  3. Provide the page name, Page1 in the Name field.

    The page is added.

  4. Click Save.

    Your changes are saved.

Next steps:

How do I assign access to a custom page?

When you add a custom page, all users can access the page. You can assign or remove permissions, to certain users, for a custom page by selecting the required privilege, community, groups, or individual users. For information on adding a custom page, see How do I add a page?

You can assign permission to:

Permission assigned to Description
Community All members of the community. That is, the users and the groups that are the part of the community will have permission to access the page.
Group Users of the group will have permission to access the page.
Privilege Users with the selected privilege will have permission to access the page.
Users Specified users will have permission to access the page.

Users who are not assigned permission for a custom page cannot access the page. However, the users with the Administrators privilege can access custom pages irrespective of the permissions specified at the page level.

Note
When you migrate a custom page from Developer Portal 10.11, it is accessible as it was in the 10.11 version. You can assign permissions to the required users based on your requirements.

This use case starts when you have to allow only certain users to access a custom page and ends when you have restricted the access.

In this example, you allow access to the page Page1, only to the users who are part of the Developers community.

Before you start

Ensure that you have created a custom page and added links to access the same.

To assign access to a custom page

  1. From the Manage themes page, click the customize icon next to Theme1.

  2. Select Pages and click Page1.

  3. Click the assign permission icon.
    The Update permission page appears.

  4. Select Developers from the Communities field.

  5. Click Save.
    The assigned permission is saved.

  6. Click Save.
    The changes are saved.

Alternative steps:

  • Select the required groups, users, or select the privilege, in Step 4, to who you want to assign access to the custom page.
  • Next steps:

  • Modify the permissions of a custom page anytime by clicking the .
  • Click the activate icon next to theme in the Manage themes screen to activate the changes.
  • Customize UI Components

    The Components section is used to customize the default UI components of Developer Portal. They include:

    Before you begin the following use cases:

    Ensure that you have created a theme or have a theme to customize.

    How do I add a new item to the top navigation bar

    The top navigation bar of Developer Portal includes links to the API gallery and API packages pages by default.

    You can customize this section to:

    This use case starts when you want to add a new item to the top navigation bar and ends when you have added.

    In this example, you add the link to Dashboard page in the top navigation page for the theme, Theme1.

    To add a new item in the top navigation bar

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components and click Top navigation.

    3. Click Add navigation.

    4. Select Text from the Is display string a property key or plain text? field and provide API analytics.

    5. Select Internal and provide the page link in the Enter the target like given below:

      analytics/user

    6. Click Ok.

    7. Click Save.

      Your changes are saved and the new item appears in the top navigation bar.

    Alternative steps:

    Next steps:

    How do I customize the top navigation bar?

    This use case starts when you want to customize the top navigation bar and ends when you have completed the customization.

    In this example, you modify the API gallery as API catalogue for the theme, Theme1.

    To customize the top navigation bar

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components and click Top navigation.

    3. Click the edit icon next to API gallery.

    4. Select Text and provide API catalogue in the Enter the text field.

    5. Click Ok.

    6. Click Save.

      Your changes are saved.

    Next steps:

    How do I customize the Sign up page?

    The Sign up page includes the following fields, by default:

    You can add new fields in the registration form to get more details from your users. You cannot edit or remove the existing default fields. However, you can move them up or down to change their order of appearance in the registration form.

    In this example, you add the field, Address in the Sign up page for the theme, Theme1.

    To customize the Sign up page

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components from the left pane and select the Registration form.

    3. Click Add a field.

    4. Select Text from the Field Type list.

    5. Select Text from the Label section.

    6. Provide Address in the Name field.

    7. Select Medium from the Size list.

    8. Select the Required check box to indicate that the field is mandatory for user registration.

    9. Click Add.

      The new field appears.

    10. Click Save.

      Your changes are saved.

    Alternative steps:

    1. In Step 4, add any of the following types of fields in the Sign up page. Select the required option from the Field Type list:

      • Password. To add a field that allows users provide their password.

      • Select. To add a field with options in a drop-down list.

      • Checkbox. To add a field with options as check boxes.

      • Radio. To add a field with options as radio buttons.

    2. In Step 5, select the type of label to be displayed for the field from the Label section:

      • Text, if the value entered in the field must appear as they are.

      • i18N, if the value is in other languages. You can use English or any language that is supported by i18N standards.

    3. Select the Auto focus check box to display the cursor in the new field by default.

    4. Optional. If you have selected Select, Checkbox, Radio in the Field type drop-down list, click Add new option and provide the possible options.

    5. Select the edit icon next to the field that you want to edit.

      You cannot edit the default fields.

    6. Use the move up icon and the move down icon buttons next to a field to modify its position.

    7. Click the delete icon next to a field to removed it.

      You cannot remove default fields.

    8. Select or clear the check box next to a field name to include or remove it respectively from the sign up page.

    Next steps:

    APIs, along with their details, are displayed as grids in API gallery. Each grid has an API and its details. You can customize the layout and details of the API grid to suit your requirements.

    This use case starts when you want to customize API grid and ends when you have saved the changes.

    In this example, you edit the image displayed in the API grid for the theme, Theme1

    To customize API grid

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components from the left pane and select the API default box.

    3. Move your mouse pointer over the image icon and click the edit icon .

    4. Click Browse and select the required image.

    5. Click Save.

      Your changes are saved.

    Alternative steps:

    Next steps:

    How do I customize the package grid?

    API packages, along with their details, are displayed as grids in the API packages page. Each grid has a package and its details. You can customize the layout and details of the grid to suit your requirements.

    This use case starts when you want to customize API package grid and ends when you have saved the changes.

    In this example, you remove the image component in the package grid for the theme, Theme1

    To customize API package grid

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components from the left pane and select the Package default box.

    3. Move your mouse pointer over the image and click the delete icon .

    4. Click Save.

      Your changes are saved.

    Alternative steps:

    Next steps:

    How do I customize the API details pane?

    You can customize the entries displayed in the left pane of the API details screen to suit your requirements.

    This use case starts when you want to customize the API details pane and ends when you have saved your customization.

    In this example, you change the text Introduction to API Overview for the theme, Theme1.

    To customize the API details pane

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components from the left pane and select the API details side bar.

    3. Move your mouse pointer over the component and click the edit icon .

    4. From the Layout configuration section, select Text.

    5. Provide API Overview in the Enter the key field.

    6. Click Save.

      Your changes are saved.

    Alternative steps:

    Component Description
    Global search Inserts search box that allows users to search for API resources.
    Stage chooser Inserts option that allows users to choose the required API stage.
    Version chooser Inserts option that allows users to choose the required API version.
    Comment streams Inserts the comments stream section.
    API Nav Item Inserts link to the configured page. Click next to the component and configure the required page in the Layout configuration section.

    Next steps:

    How do I customize the plans grid?

    API subscription plans, along with their details, are displayed as grids in the API packages details page. Each grid has a plan and its details. You can customize the layout and details of the grid to suit your requirements.

    This use case starts when you want to customize the plans grid and ends when you have saved your customization.

    In this example, you remove the image component in the plans grid for the theme, Theme1

    To customize the API plan grid

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Components from the left pane and select the Plan default box.

    3. Move your mouse pointer over the image and click the delete icon .

    4. Click Save.

      Your changes are saved.

    Alternative steps:

    Next steps:

    Customize Labels

    The Properties section is used to add custom labels on the Developer Portal UI such as:

    In addition, you can also view the labels available in the UI based on the following categories:

    How do I add new UI labels?

    You can add new labels and use them in place of existing labels or use them in the new blocks that you add to your theme.

    This use case starts when you want to add a new UI label and ends when you have added labels.

    In this example, you add a new label, Request pending for the theme, Theme1.

    Before you start

    Ensure that you have created a theme or have a theme to customize.

    To add new labels in the UI

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Properties and select Custom.

    3. Click the Click here link.

      The Add property screen appears.

    4. Provide admin.label.request.pending in the Key field.

    5. Select US from the Language list.

    6. Provide Request pending in the Value field.

    7. Click the add icon .

      The label is added.

    8. Click Save.

      Your labels are saved and appear in the Properties screen.

    Alternative steps:

    Next steps:

    Customize Color Schemes

    The Themes section is used to customize the color schemes used in general and in different blocks of a page.

    You can customize the colors and font size, in general, in the UI.

    You can customize the color scheme used in:

    How do I customize the color scheme used in a screen?

    This use case starts when you want to customize the color scheme used in UI.

    In this example, you modify the primary color of the application in general for the theme, Theme1

    Before you start

    Ensure that you have created a theme or have a theme to customize.

    To customize the color schemes

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Theme from the left pane and select General.

    3. Select Color from the Select module list.

    4. Select a color using the color slider.

    5. Click Save.

      Your changes are saved.

    Alternative steps:

    Next steps:

    How do I customize the text and icon displayed in browser header?

    This use case starts when you want to customize the text and icon (thumbnail) displayed on browser header.

    In this example, you modify the text in browser header as Developer portal for the theme, Theme1.

    Before you start

    Ensure that you have created a theme or have a theme to customize.

    To customize the browser header

    1. From the Manage themes page, click the customize icon next to Theme1.

    2. Select Theme and select Title and Fav Icon.

    3. Provide Developer Portal in the Title field.

    4. Click Save.

      Your changes are saved.

    Alternative steps:

    Next steps:

    Customization using Web components

    Web components are a set of web platform APIs that allow you to create new custom, reusable, encapsulated HTML tags to use in web pages.

    You can use web components to add customized components and widgets to your portal.

    The high level workflow of using web components for UI customization is as follows:

    You can create web components using TypeScript or JavaScript. If you create your component in TypeScript, you must first compile it to JavaScript for registering it with Developer Portal.

    The web component can be created by extending the following example:

    
        
    
    export abstract class AbstractPortalElement extends HTMLElement {
        private context: ContextModel;
        
        abstract render(): void | Promise<any>;
        
        setContext(context: ContextModel) {
         this.context = context;
         this.render();
    }
    protected getData(): any {
        if (this.context && this.context.getData) {
         return this.context.getData();
        
         }
        
    }
    protected navigate(path: string): void {
        if (this.context && this.context.navigate) {
         this.context.navigate(path);
        }
    }
    protected getLocaleString(key: string): string {
        if (this.context && this.context.getLocaleString) {
         return this.context.getLocaleString(key);
        }
        return key;
     }
    }
    
    

    The methods in the above class definition include the following:

    Method Description
    setContext(context: ContextModel) {
    this.context = context;
    this.render();
    }
    Developer Portal invokes this method to access the context data.
    protected getData(): any {
    if (this.context && this.context.getData) {
    return this.context.getData();
    }
    }
    This methods returns the context data.
    protected navigate(path: string): void {
    if (this.context && this.context.navigate) {
    this.context.navigate(path);
    }
    }
    This method is used to navigate to the given page.
    protected getLocaleString(key: string): string {
    if (this.context && this.context.getLocaleString) {
    return this.context.getLocaleString(key);
    }
    return key;
    }
    This method is used to retrieve the i18N key for a given value.
    export class ContextModel {
    getData: () => any;
    navigate: (path: string) => void;
    getLocaleString: (key: string) => string;
    }
    This method registers custom-elements with component definitions.

    Web components considerations

    Remember the following points when creating web components:

    Customization example

    This use case is about an example scenario where a page is customized for a portal that exposes APIs for mobile applications.

    For example, to customize the Welcome page like seen below.

    1. Create a theme. For information on creating themes, see How do I create a theme for customizing the Developer Portal UI?

    2. From the Manage themes page, click the edit icon next to the theme you created.

    3. Select Pages from the left pane and select the page you want to customize.

      The selected page appears with the corresponding editing options for each of the blocks. For example, let us customize the Welcome page.

      For example, let us remove the three blocks in the page and add four panels with images and headings.

    4. Click the delete icon next to the blocks to remove them.

    5. Click the add icon to add new blocks.

    6. Select Composite 3. The new block with one horizontal and three vertical panels appear.

    7. Click Component and select Image.

    8. Click the edit icon next to the image, click Browse from the editing options, and select the required image.

    9. Similarly, add a heading component and edit the component to give a required heading.

    10. Repeat the steps to add images and headings.

    11. Click Save to save your changes and activate the theme to see the customized Welcome page.