Apigee Developer Portal - Drupal - How to Improve User Experience of Apigee SmartDocs Landing Page

Hello Everyone,

SmartDocs is one of the differentiating factors when it comes to API Documentation in Apigee Edge. It gives you many features out of the box including Search, RBAC, Templating, Customization etc.

I would like to take this opportunity to share with the community how you can improve the User Experience of the SmartDocs landing page from a simple list of API Models to much more visible API Catalog with search & filter capabilities using out of the box configuration & a little bit of css customization.

In this article, You are going to see how to change the SmartDocs landing page in detail.

What do you see when you navigate to /apis page in out of the box Developer Portal ? You will see the list with couple of SmartDocs API models out of the box. More or less similar to below screenshot.

5229-5210-screen-shot-2017-06-28-at-25412-pm.png

Let's see how to categorize above API Models, Improve Visual & User Experience of above page step by step.

Prerequisites :

Developer Portal Code Base Access. If you have an Apigee-hosted devportal, you need pantheon access. If you are hosting your own devportal, you should have codebase access to the portal.

Step 1 :

Install Drupal contributed module better_exposed_filters in sites/all/modules/contrib folder.

If you are using drush, run the commands below, inside developer portal source code.

drush dl better_exposed_filters-7.x-3.4
drush en better_exposed_filters 

If you are not sure how to use drush,

  • download module 7.x version zip from above link, extract the zip, place the folder inside sites/all/modules/contrib folder.
  • Push the code to pantheon repo if you are in cloud.
  • Navigate to "admin/modules"
  • Search for Better Exposed Filters module, Enable the module.

Step 2 :

Let's create some test API models. Let's take a scenario of Banking UseCase & create the API Models & See how it works. Let's create following API Models.

  • Savings Account APIs
  • Current Account APIs
  • Car Loans APIs
  • Home Loans APIs
  • Term Deposits APIs
  • Recurring Deposits APIs
  • OAuth Authentication APIs
  • Payments APIs
  • Fund Transfer APIs
  • Car Insurance APIs
  • Health Insurance APIs

I am sure, There might be many more. Having these many API Models sometimes need categorization & ability to filter the API Catalog.

Let's delete the default hello & pet store API Models & Add above API models using some random OpenAPI Spec.

  • Navigate to Content => SmartDocs as Developer Portal Administrator or using direct link "admin/content/smartdocs/models"
  • Delete the existing smartdoc models, Hello world & Petstore.
  • Add new models with above names & some random.
  • Click on import, Use sample OpenAPISpec to render smartdocs.

5226-5211-screen-shot-2017-06-28-at-32206-pm.png

  • Render and publish nodes

  • Repeat same for all above API model names. You should see list of API models in admin screen like below when you naviate to "admin/content/smartdocs/models" page.

5227-5212-screen-shot-2017-06-28-at-33042-pm.png

Step 3 :

Add ability to categorize, API models by leveraging out of the box taxonomy concepts in Developer Portal.

  • Navigate to Structure => Taxonomy => Add Vocabulary or "admin/structure/taxonomy/add"
  • Create vocabulary called, "SmartDocs Models Categories"

  • Add Terms , Use Add Terms link next to above created vocabulary.

  • Add terms below,
    • Accounts
    • Loans
    • Payments
    • Authentication
    • Insurance

Step 4 :

Reference the above vocabulary in SmartDocs Models vocabulary as a new field.

  • Navigate to Structure => Taxonomy => SmartDocs Models => Manage Fields or URL "admin/structure/taxonomy/smartdocs_models/fields"
  • Add a new field called, "Model Category", See the settings below. Click Save.

  • Choose vocabulary reference as "SmartDocs Models Categories". Click Save.

  • Make it Required Field, Set number of values to unlimited, Save Settings.

Let's add one more field called Model Image, which will be used to upload a pic that will get displayed in the SmartDocs APIs landing page.

  • Add New Field, "Model Image", See settings below, Click Save.

  • Upload default Image, Use Image below, Click Save Field Settings. Next screen, Scroll to bottom, Click Save Settings.

5230-5213-api1.jpg

Step 5 :

Update the SmartDocs API Models with categories & an image.

  • Navigate to "admin/structure/taxonomy/smartdocs_models"
  • Click on Edit Link next to SmarDocs API Model Term
  • Choose category, Upload relevant image, Click Save

  • Repeat same for other API models.

Step 5 :

Create an image style to auto resize uploaded images.

  • Navigate to "admin/config/media/image-styles/add" to add a new image style. Name it as "Smartdocs 400x243". Click on create new style.
  • Select Resize, Click Add

  • Update width as 400, height as 243
  • Click Add Effect
  • Click Update Style.

Step 6 :

Add some custom css to theme the view.

  • Create a new subtheme of Apigee Responsive theme to have custom css files. If you already have a subtheme, you can skip this line item.You can find instructions here. Make sure the sub theme is enabled & set default in your developer portal (admin/appearance).
  • Create a new file called "apicatalog.css" inside sites/all/themes/{YOURTHEME}/css folder
  • Paste below css in above created file, save the file.
.view-smartdocs-models .view-filters {
    float: left;
    width: 170px;
    min-height: 750px;
}

.view-smartdocs-models .form-control {
    border: none;
    box-shadow: none;
}

.form-type-bef-checkbox {
    clear: both;
}

.form-type-bef-checkbox input {
    float: left;
    width: 15px;
}

.form-type-bef-checkbox label {
    float: left;
    margin-top: 11px;
    margin-left: 15px;
}

.view-smartdocs-models ul {
    list-style: none;
}

.view-smartdocs-models ul li {
    float: left;
    width: 230px;
    padding: 10px;
    border-bottom: 6px solid #c8c9c7;
    box-shadow: 0 0 3px 0 rgba(0,0,0,.35);
    margin-top: 10px;
    margin-left: 10px;
    min-height: 150px;
    cursor: pointer;
}

.view-smartdocs-models .views-field.views-field-name {
    margin-top: 15px;
    text-align: center;
}

.view-smartdocs-models .bef-checkboxes label {
    color: #666;
    font-size: 13px;
    font-weight: normal;
}

.view-smartdocs-models label[for=edit-field-model-category-tid]
{
    font-size: 16px;
}

.view-smartdocs-models .views-field-field-model-image-fa-icon {
    text-align:center;
    margin-top:20px;
}
  • Update the sites/all/themes/{YOURTHEME}/YOURTHEME.info file with below line,
stylesheets[all][] = css/apicatalog.css
  • Clear all drupal caches.

Step 7 :

We are almost there, It's time to update the view. Navigate to APIs (/apis) page as Administrator.

  • Hover on the view, You will small wheel icon on top right hand. Click on Edit View.

  • Click on Unformatted List, Change it to HTML LIST, Click Apply -> Apply

5231-qv8urfxc0bn-1.png

  • Click on Arrow next to Add in Fields section, Click ReArrange, Select Term Description to remove, Apply.

  • Click on Add button in Fields Section above, Search for image, Select Model Image, Click Apply

  • Click Apply & Continue, In next screen, Uncheck Create a label, Choose Image Style Smartdocs 400x243, Link Image to Content, Click Apply button.
  • Rearrange Fields , Click on arrow next to Add in Fields Section, Drag the image field above Display Name, Click Apply.

  • Let's add the filter now, Remember the SmartDocs Model category field you have created earlier ?
  • Click on Add next to Filter Criteria Section. Search Category, Select field_model_category, Click Apply => Apply and Continue in next screen.

  • Choose DropDown, Click Apply (all displays).
  • Click on Just Added, Taxonomy Term : Model Category,

  • Choose Expose filter, Change label to "API Catalog"

  • Choose Allow Multiple Selection, Click Apply.

  • Expand Advanced Section, Change Use Ajax to Yes.

  • Click on Exposed Form Style - Basic, Change it to Better Exposed Filters, Click Apply

  • Click on Settings next to Taxonomy term, Change the setting to DropDown.

  • Click on BEF Settings link next to Exposed Form : Better Expose Filter, In popup, Choose, AutoSubmit, Select Exposed Filter as Checkboxes / Radio buttons, Click Apply

  • Click on Paged, 10 items, Change it to 0

  • Click on Save button on top to save the view.

  • New look of Smartdocs landing page should be up & running.

Some reference links in Developer Portal to work with content,

  • To add new categories that you see in left side bar, "admin/structure/taxonomy/smartdocs_models_categories"
  • To update images of models & categories, "admin/structure/taxonomy/smartdocs_models", Click edit next to model.

Hope it's helpful. Any feedback / suggestions / Queries ? Please use comments below.

Comments
DChiesa
Staff

Sweet, Anil!

Hey, here's a tip I used recently. I wanted to allow a "all/none" checkbox or button in the categories list. And I wanted to remove the "Reset" button. Like this:

5612-api-product-catalog-one-change.png

I found that BEF allows us to remove the reset and add the "all / none". Do that in the UI, under advanced settings like this:

5613-bef-uncheck-check.png

And then add this to the .CSS:

/* ================================================================== */
/* style the anchor inserted by BEF like a bootstrap button */
.bef-select-all-none > a.bef-toggle {
    background-color: #009FD0;
    background-image: -moz-linear-gradient(center top , #00A4D7, #0197C6);
    background-repeat: repeat-x;
    border-color: rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.1) rgba(0, 0, 0, 0.25);
    border-radius: 4px;
    box-shadow: 0 0 0 0 rgba(0, 0, 0, 0) inset, 0 0 5px 0 rgba(255, 255, 255, 0.3);
    color: #FFFFFF;
    cursor: pointer;
    display: inline-block;
    font-size: 13px;
    font-weight: normal;
    line-height: 24px;
    margin-bottom: 0;
    padding: 4px 10px;
    text-align: center;
    vertical-align: middle;
}


.bef-select-all-none > a.bef-toggle:active {
    background-color: #0197C6; /* 1 151 198 */
}
/* ================================================================== */

anilsr
Staff

Awesome @Dino , + 1, Power of Drupal Modules 🙂

surik-babu
Participant II

5771-picture2.png

How can we do better user experience for product list selection for App creation.

Please provide me step to implement my use case

Not applicable

How would you include the taxonomy term inside the Smart Doc so it automatically selected the term for you?

In other words so you did not have to come back and edit the published rendered node manually w the term of your choice.

anilsr
Staff

@James Chandler , Welcome to Apigee Community !

Rendered Node ( SmartDocs API Page) is automatically connected to Smartdocs Model Taxonomy. It happens automatically when you create a Smartdoc model & upload your spec.

We just manually map the Smartdoc Models to one more high level category called Smartdoc Model Categories to group Smartdoc Models ( Think Smartdocs Models as API Products which lists APIs part of it).

Not applicable

Thanks Anil!

One question though, the way it automatically went to 'loans' for example. Was that because of the title we gave it? Confused because we used the same Swagger JSON every time.

Say I did want to add a new taxonomy with for example US State and I followed the same instructions and AM also using everything in this tutorial. How would I put the 'US State' tag inside the swagger doc for drupal to automatically map it to the state?

Version history
Last update:
‎06-29-2017 07:42 PM
Updated by: