Was this helpful?

Use the Drupal Book module to add documentation about your API, such as how-to guides and API reference documents, to your Developer Services portal. The Book module allows you to create the kind of structured, hierarchical content that typically appears in a book. However, you can also use the Drupal Book module to create less formal documents, such as a brief set of instructions or a list of links to additional content such as videos, screencasts, or code downloads. 

Note: Developers will use apps to access resources in your API products. In general, developers will use your developer portal to add those apps. Ensure that your documentation includes instructions for adding apps though your developer portal. You can use Instructions for adding apps as a starting point. Those instructions cover how to add apps through the default developer portal.

The Documentation page is set up with some initial entries organized in various categories such as "Getting Started" and "Tutorials". The page is a starting point for you to edit. In this way you can add you own content entries and organize those entries in the way you want.

Adding the Drupal Book module

You use the Drupal Book module to add structured documentation to your portal.

To enable the Book module:

  1. Log in to your portal as a user with admin privileges.
  2. Select Modules in the Drupal administration menu. The list of all installed Drupal modules appears.
  3. Scroll down the page and select the checkbox next to the Book module.
  4. Save your configuration.

Adding the Documentation home page and book

By default, the Documentation home page is at <siteURL>/documentation on your developer portal. The default Home page of the developer portal contains a link to this page in the box at the top of the Home page:

You can also add a Documentation link to this page in the main menu of the developer portal menu.

However, the Documentation home page does not exist by default, so you must create a new page on the developer portal at the correct URL. If this is the first page you create, it also becomes the parent page for a book and also defines the name of the book. You can then add all subsequent documentation pages to this book.

To add the Documentation home page to your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the title of the document, such as Documentation Home, and the content of the first page.
  4. Click Edit summary to add a Summary.
  5. Click the Menu settings item below the Body section.
  6. Select Provide a menu link, add the link title, and select <Main menu> in the Parent Item.
    This adds a link to the main menu for your Documentation Home page.
  7. Click the Book outline item below the Body section to open the Book drop-down menu. Select <create a new book>.
  8. Click the URL path settings item below the Body section.
  9. Select Generate automatic URL alias, and set the URL alias to documentation.
    By default, the URL of a page is <siteURL>/content/pageName. By setting the URL alias, you set set an explicit URL of the page, in this case to <siteURL>/documentation.
  10. Save the page.
    You should now see a link to the page in the menu bar, and the link in the in the box on the home page should now work.

Adding a page to a book

As you add pages to your book, links are automatically added to the Documentation home page, if it is the parent page of the book. In addition, links are added to the bottom of each basic page to navigate from page to page.

To add a page to a book:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the page title and the content of the first page.
  4. Click Edit summary to add a Summary.
  5. Click the Book outline item below the Body section to open the Book drop-down menu. Select the book you created with the Documentation Home page.
  6. Save the page.
    You should now see a link to the page on the Documentation Home page.

Editing a documentation page

To edit a page:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Navigate to the page in the developer portal. For example, select Documentation in the developer portal navigation menu.
  3. Select the Edit tab on the page.
  4. Open a visual editor by selecting Filtered HTML in the Text Format drop-down menu below the Body section.
    You should see the content of the Documentation page displayed in the editor.
  5. Edit the page as necessary.

  6. Click Save.

Displaying any documentation page

To display the content of a document:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Books in the Drupal administration menu.
  3. Select the document you want to view from the Book list.
    The first page of the document opens. Pages that follow the first page are displayed as topics in the topics list.

Rearranging the order of pages

You can change the sequence of pages in a book . You can also make a page subordinate in level to another page.

To rearrange pages in a book:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Books in the Drupal administration menu.
  3. Click "edit order and titles" in the row for the pertinent book.
    A list of titles opens, showing the pages in the book.
  4. Click the Title (+) icon that corresponds to the page that you want to move. Drag the icon up or down in the title list. You'll see the sequence of pages change. Drop the icon at the appropriate point in the title list.
  5. Move the icon to the right, to make the page a subtopic of the topic above it.
  6. Click Save basic pages.

Editing footer pages

The footer for the portal contains three social icons for Twitter, Facebook, and LinkedIn and links with the following URLs:

  • Privacy Policy to the URL <siteURL>/privacy-policy
  • Terms & Use to the URL <siteURL>/terms-use
  • Contact pages to the URL <siteURL>/contact-us

Edit these pages to add your own content.

If these pages do not exist, create them:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Content > Add content > Basic page in the Drupal administration menu.
  3. Enter the title of the document, such as Privacy Policy, and the content of the page.
  4. Click Edit summary to add a Summary.
  5. Click the Book outline item below the Body section to open the Book drop-down menu. Select <none>.
  6. Click the URL path settings item below the Body section.
  7. Select Generate automatic URL alias, and set the URL alias to privacy-policy.
    By default, the URL of a page is <siteURL>/content/pageName. By setting the URL alias, you set set an explicit URL of the page, in this case to <siteURL>/privacy-policy.
  8. Save the page.
  9. Repeat this process for the Terms & Use and Contact pages. 

To edit the content of a footer page, such as the Privacy Policy, Terms of Use, or Contact Us page, in your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Navigate to the page by clicking its link in the footer. For example, click the Privacy Policy link.
  3. Click the Edit tab in the page to open the editor.
  4. Change the contents of the Privacy Policy page as appropriate.
  5. Click Save.
  6. Repeat this process for the Terms & Use and Contact pages.

To edit the social icons, such as the Twitter, Facebook, and LinkedIn icons, in your developer portal:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Structure > Blocks in the Drupal administration menu.
  3. Scroll down the Blocks page until you see the Site-wide Default Footer block.
  4. Select the configure link corresponding to the Site-wide Default Footer block.
  5. In the Custom Content area, right-click on a social icon and select Edit Link from the pop-up menu. Or, delete the icon from the Custom Content area to remove it.
  6. Select Save block to save your changes.

Adding JavaScript to a portal page

You can add JavaScript to any portal page. The easiest way to add JavaScript is to edit the page, and then:

  1. Select Full HTML as the Text Format.
  2. Select the Source button to edit the HTML source code for the page.
  3. Add your JavaScript to the page. For example, to pop up an alert box when the page loads, add the following code:

    <script language="JavaScript">
        alert('Welcome to my page!');
    </script>

The Full HTML text format can be configured to limit the HTML tags allowed on the page. For example, it can be configured to prohibit the use of the <script> tag. To determine the settings of the Full HTML text format, select Configuration > Content authoring > Text formats > Full HTML in the Drupal administration menu. If the Limit allowed HTML tags checkbox is selected, then check the allowed HTML tags in the Filter processing order area of the page.

Some considerations on using JavaScript:

  • If you are going to reference a JavaScript file, don't do it in the source code of a node because that creates a static link. Instead use PHP code so you can create a dynamic link. In that way, if the location of the JavaScript file changes, you do not have to update all of the portal pages that reference it.
  • If you want to include a JavaScript file, add it to the portal theme. Or, if it is part of a Drupal module, add it to the module.
  • You can also use the Drupal drupal_add_js function to add JavaScript in Drupal. For more information, see https://api.drupal.org/api/drupal/includes!common.inc/function/drupal_add_js/7.

Checking for broken links

It's good practice to check your content for broken links. By default, the developer portal is set up to check various types of pages for broken links. For example, links are checked in basic pages, articles, blog entries, and forum topics.

To add to or remove page types from the link check:

  1. In the Drupal administration menu select Configuration > Link checker.
  2. Select the checkboxes for the page types in which you want links checked. Uncheck the checkboxes for the page types in which you don't want links checked.

Configuring search

The developer portal provides a built-in search engine implemented by Apache Solr, which uses the Apache Lucene search library. This is the search engine for the site itself, which the user accesses through the search box in the upper-right corner of all portal pages.

External search engines, such as Google, can also index your portal. The developer portal lets you control whether or not external search engines can index your portal.

Configuring Apache Solr

You can configure Apache Solr to control the content types to index, to force an index, and to perform additional configuration tasks.

To configure Apache Solr:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. In the Drupal administration menu select Configuration > Search and metadata > Apache Solr search.
  3. Use this page to configure Apache Solr.

Disabling Google indexing

It's also good practice to index your content, and make it available to search engines. By default, your content is indexed by the Google indexer. However, you have the option of disabling Google indexing. You might want to do this if your developer portal is not ready for public use and so you don't want your content to be publicly searchable.

To disable Google indexing:

  1. Log in to your portal as a user with admin or content creation privileges.
  2. Select Modules in the Drupal administration menu.
  3. Select the Meta tags section to expand the section.
  4. Uncheck the Meta tags checkbox.
  5. Click Save configuration.
  6. In the Drupal administration menu select Configuration > Search and metadata > Metatag.
  7. Select Override operation for the Global type.
  8. Click the Advanced section to open it.

  9. Check the checkbox for Prevent search engines from indexing this page.
  10. Click Save.

Notice that there are other search-engine related options in the Advanced section of the Global page. For example, you can check a checkbox to prevent search engines from following links on a page. Check one or more of these checkboxes as appropriate.

Instructions for registering apps

As mentioned earlier, it's important that your documentation include instructions on how developers can register their apps though your developer portal. You can use the following instructions as a starting point — these instructions cover how to register apps through the default developer portal.

To register an app through the default developer portal:

  1. Select  My apps below your username in the login menu. This displays the My apps page.
  2. Click the Add  (+)  new app  icon. This displays the Add app page.

    Add app icon

  3. Enter appropriate values in the Add app page:
    App name Provide a unique App Name for your app.
    Callback URL

    Provide the callback URL to which the OAuth call should return. By default, this value is required even if your APIs do not use OAuth. If your APIs do not use OAuth, enter a dummy value such as my.site.com.

    Alternatively, you can select Configure > Dev Portal Settings in the Drupal administration menu to configure the portal to not require the Callback URL. On the Dev Portal Settings page, scroll down to the Callback URL Handling section to make your selection. However, this setting applies to all apps so you should only do this if none of your API products use OAuth.

    Product Select the API product from the drop-down list to gain access to that product.
  4. Click Create App. This will register the app and generate the API key for the app.

Learning more about the Drupal Book module

The Drupal Book module has more functionality than described here. The Drupal community maintains a Community Documentation page that includes more complete information about using the Book module. There are also some good videos that demonstrate the use of the Book module. One of them is Book Module Demo for Drupal & Drupal Gardens.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)