Content Development Guidelines for Simple Dev Theme

Manage content pages for Simple Developer theme (Simple Dev).

Simple Dev content pages are displayed in Simple Dev, but must be uploaded by the Site Admin in Hermosa Theme.

Simple Dev has its own set of content pages that will display to all users. This document provides information specific to Simple Dev for writing, uploading, and managing Simple Dev content, and information about coding links for documentation in Simple Dev.

For information about coding links in Hermosa Theme, see Linking in API Documentation (API Admin help).

Table of Contents

Simple Dev Theme:

Coding Links in Simple Dev Theme:

Simple Dev Theme:

What are the content pages in Simple Dev?

By default, Simple Dev has three content pages in the user interface:

  • Documentation page:
    • Filename: content/documentation/index.htm.
    • URL: {hostname}/#!documentation
    • Accessed: Via the Documentation link, center of top menu bar.
  • Help page:
    • Filename: content/help/index.htm.
    • URL: {hostname}/#!help
    • Accessed: Via the Help link, right of top menu bar.
  • Welcome page:
    • Filename: content/welcome/index.htm.
    • URL: {hostname}/#!welcome
    • Accessed: By clicking the logo at the top left.

See also: What is the folder structure for content in Simple Developer Theme? below.

You can, of course, create additional pages in the existing folders, or create new custom pages, as needed. This document includes general information on modifying and formatting existing pages and on creating additional pages within the same folder structure. To add custom pages to the user interface, or modify existing user interface pages, refer to Detailed Customization Document.

What is the folder structure for content in Simple Developer theme?

Simple Developer theme, by default, includes three content files/folders, as explained in What are the content pages in Simple Dev? above.

In the file system, these are represented by a structure of three subfolders in the main /content/ folder which is shared by both themes:

  • content/documentation/index.htm
  • content/help/index.htm
  • content/welcome/index.htm

Where do I upload revisions for the Simple Dev content pages?

The Site Admin can upload a revised file in Akana API Platform (Hermosa Theme).

For instructions, see How do I upload content for Simple Developer theme? (Site Admin Configuration help).

What is the customization ZIP file and how do I use it?

A customization ZIP file is available to help you get started with customizing your content. You can upload the ZIP file in File Manager and view examples of linking, and other instructions, or you can unzip to your local drive and use those files as a basis for further customization.

To get a copy of the customization file, contact Technical Support.

To update the Simple Developer customization ZIP file

  1. Log in as a Site Admin and go to the Admin section.
  2. Go to More > Admin >File Manager.
  3. In the Content section, click File Manager. The File Manager window opens at the content folder.
  4. Click Upload a Zip Archive.
  5. Go to the location of the ZIP file and upload it. The content is automatically unzipped as part of the upload process.
  6. Test by viewing in Simple Developer theme.

    Note: to see the update immediately, you will need to clear cache and refresh the page. Cache is updated automatically every hour.

Where do I upload API documentation for Simple Dev?

In the Simple Dev user interface, the Documentation link gives access to the default location for API documentation.

In the content folder structure, it is in the /documentation subfolder: content/documentation/index.htm. The Site Admin can upload the documentation in Hermosa Theme in the same way as any other content. For full instructions, see How do I upload content for Simple Developer theme? (Site Admin Configuration help). Brief instructions: Hermosa Theme: More > Admin > File Manager. In the Content section, click File Manager. From here, there are two approaches to uploading the content:

  • ZIP file: Zip all the documentation files into one zip file named documentation.zip, and upload it from the Content folder. The documentation folder is created automatically, and the files are placed in that folder.
  • Individual file uploads: Create a documentation folder if there isn't one (exact name and case as given here). Change directory into the documentation folder, and from there, upload the files individually.

You can create as much API documentation content as is needed, including:

  • Adding files
  • Adding assets such as images
  • Adding links
  • Adding CSS definitions and referencing the CSS from your files

It's a good idea to keep the basic folder structure and build on that, keeping index.htm as the main entry page. For example, let's say you have three APIs on the platform. You could:

  • Create a subfolder for each API, so you can keep the three sets of files separate.
  • Keep one API-specific main page in the root /documentation folder. Link from the main index page to the API-specific pages, and from there to the content in each subfolder.
  • Create a separate /styles subfolder and keep your CSS file in there, linking to it with relative links from your content files. Alternatively, if you want different styles for each API project, you could store a separate CSS file for each API in the applicable folder—or have a style subfolder for each API.

Depending on the number of assets you have, you might want one assets folder for all API documentation files, or might prefer to have an assets subfolder for each API. The only constraints are file type (see What file types are supported for content in Simple Dev? below).

For Simple Dev theme, the Site Admin must upload the files in Hermosa Theme: More > Admin >File Manager. In the Content section, click File Manager. Upload the files in a folder below the content folder. The Site Admin must use or create a folder named documentation (so the path is content/documentation). As soon as the files are uploaded in Hermosa Theme, they are immediately visible in Simple Dev theme. Just log in and click the Documentation page to view the API documentation.

Coding of links in Simple Dev essentially follows HTML standard for coding of links, with one or two differences.

The sections below explain each type of link, with examples.

To experiment with working examples of each link type, upload the customization ZIP file. See What is the customization ZIP file and how do I use it? above.

Refer to the following topics:

How do I use CSS with my Simple Dev pages?

The platform comes with some default styles for documentation. You can add or customize styles via CSS in the platform in the same way you would anywhere else.

Simply create a custom stylesheet (CSS) file, upload it to the platform, and reference it via relative links in the <head> tag of your files, following the basic content folder structure: see What is the folder structure for content in Simple Developer theme?

For example, if you want to use the same styles for all your platform content pages, you might choose to add a new subfolder in the Content folder, and store your custom CSS in there:

/content/styles/acmepaymentscorp.css

To reference this CSS file in your platform Welcome page, you'll just need an extra line in the <head> tag of your Welcome page, with the relative path to your CSS file:

<link href="../styles/acmepaymentscorp.css" rel="stylesheet" type="text/css" />

If you have several APIs on your platform, you might choose to have different styles for each API. You could set up a folder structure in your /content/documentation folder, and store the CSS file for each project in the same folder, such as this:

  • content/documentation/API_1/api_1.css
  • content/documentation/API_2/api_2.css
  • content/documentation/API_3/api_3.css

However you choose to structure your files, just use a relative link to the CSS in the <head> tag of your documentation file.

What file types are supported for content in Simple Dev?

Simple Dev supports most standard file types you might want to use in documentation. For example, it supports the following:

  • Standard HTML files: htm, html
  • Image files: gif, png, jpg
  • PDF files: pdf
  • Flash files: swf
  • ZIP archive files: zip. Note that if you want to offer a ZIP file in your documentation--for example, to include an SDK—you must upload it as a single file. If you choose Upload a Zip Archive, File Manager unzips the files.

For more information, see Can I add other types of content to my API documentation?

If you want to use a file type that isn't listed above, test to see whether it is supported.

How do I manage my content assets in Simple Dev?

Managing your content assets in Simple Dev is the same as in any other file structure. Just organize your assets and refer to them by relative links.

For example, you might choose to create a subfolder for all your documentation assets:

/content/documentation/assets

All files in the documentation folder, or any subfolders you create, can refer to those assets by simple relative links, in the same way as the references to the CSS stylesheets (see How do I use CSS with my Simple Dev pages? above).

How do I use File Manager?

File Manager is not available in the Simple Dev theme. In Hermosa Theme, it is available for two audiences:

  • API Admins managing API content for Hermosa Theme
  • Site Admins managing site content for Hermosa Theme or both site and API content for Simple Dev

For Simple Dev content, the Site Admin can:

  • Upload individual files
  • Upload a ZIP file
  • Create folders
  • Navigate up and down the file structure

For information and procedures for working with File Manager, review the topics in the API Admin content management help under this heading: Using File Manager.

Are there any limitations to HTML coding in Simple Dev?

There is one known limitation to HTML coding in Simple Dev: If an uploaded document has expandable/collapsible sections, those sections do not resize when viewed in the platform (this issue exists in all themes).

In Hermosa Theme, users viewing API documentation first choose the API and version, and then view the documentation. The context is already set, and the user interface shows the version-specific API documentation automatically.

In Simple Developer theme, the user interface is completely different, and the API and version are not selected when viewing the documentation. In addition, the API-specific files and folders are not displayed in the user interface in the same way.

You'll need to follow a specific procedure to make sure that from the main API documentation page in Simple Dev you link to the index page for the correct API and API version.

Follow the steps below.

To set up a link from the Simple Dev API documentation index page to the documentation index page for a specific API version

  1. Log in to Hermosa Theme as the Site Admin, Business Admin, or API Admin, so you have visibility of the API documentation files.
  2. Go to the API list and choose the API.
  3. From the left menu, choose Documentation, and view the documentation index page. If the page name is index.htm, the path will be something like the below:

    http://{hostname}/#/api/{APIID}/versions/{APIVersionID}/documents/index.htm

  4. Save the path and make a note of the APIID. You'll need this to set up the link from your Simple Dev documentation page to your API-specific doc index page.
  5. In the main documentation page for Simple Dev, in the source file (outside the platform) set up the link to the API-specific index page, making sure you assign the soa-control-cm-route-link class to the tag. Use the following structure:

    <a class= "soa-control-cm-route-link" href="api/{APIID}/documents&doc={filename}.htm">{text for the link}</a>

  6. Upload the updated Simple Dev documentation page. For instructions, see Where do I upload API documentation for Simple Dev?
  7. Test. When you click the link in the Simple Dev documentation page, the API-specific index page is displayed. From there, Simple Dev users can click through to view the rest of your API documentation.

In Hermosa Theme, when an API is set up, the generated API document is displayed by default when the user goes to the API > Documentation page. However, in Simple Dev theme, since there is no API-specific documentation page, this doesn't happen.

You can make the generated API doc for a specific API available in Simple Dev theme by coding a link from the main Documentation index page, or another page in Simple Dev, using the syntax shown below.

To do this you'll need to:

  1. Get the APIID and APIVersionID.
  2. Write the Simple Dev link, incorporating the APIID and APIVersionID.
  3. Apply the soa-control-cm-route-link class on the link.
  4. Include the script references in the <head> tag to support the soa-control-cm-route-link class. See How do I add the <script> tag in the head of my HTML file below.

First, go to the API > Documentation page in Hermosa Theme. Let's say the page URL is:

http://acmepaymentscorp.com/acmepaymentscorp/#/api/74e6caf2-99cb-41b5-aff0-68c56c2c3853.acmepaymentscorp/versions/6a42934e-70d5-4ab2-918b-eb2988cf5da0.acmepaymentscorp/documents

You'll need to code a link in the Simple Dev documentation index page (or other page) that looks something like the example below:

<p><a class="soa-control-cm-route-link" href="apis/74e6caf2-99cb-41b5-aff0-68c56c2c3853.acmepaymentscorp/versions/6a42934e-70d5-4ab2-918b-eb2988cf5da0.acmepaymentscorp/documents">Link to the dynamic doc page</a></p>

To the user, the above looks like a normal link, with the text Link to the dynamic doc page.

When the user clicks the link, the generated API documentation is displayed.

How do I add the <script> tag in the head of my HTML file

If you're using certain doc features, you'll need to include a <script> tag in the head of your HTML file to provide additional functionality. Then, you can use tags within the document to add these doc features to your API documentation or other documentation on the platform.

The special classes that require a <script> tag referencing the tag_lib.min.js file are:

  • soa-control-cm-route-link

In the <head> tag of your HTML document, add the lines of code shown below. The last line references the tag_lib.min.js file.

<html lang="en" xmlns:soa="http://soa.com">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<!-- The css files below are needed for the inline testing feature to be displayed correctly -->
    <link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/> 
    <link rel="stylesheet" type="text/css" href="/resources/style/base.css"/> 
    <!--[if lte IE 9]>
    <link rel="stylesheet" href="/resources/style/ie.css">
    <![endif]-->
<!-- The script files below are needed for the inline testing feature to work correctly -->
    <script language="javascript" src="config.js" type="text/javascript"></script>
    <script language="javascript" src="/ui/apps/atmosphere/123/resources/console/SOA/console/common/tag_lib/dist/tag_lib.min.js"type="text/javascript"></script>

Notes:

When you reference reset.css, as in the above example, you must also define styles in your custom css. For more information, see What are reset.css and base.css and why would I use them?

If you need to add compatibility for users of IE9 and below, you can include a conditional comment to an additional stylesheet. For details and an example, see How do I make sure my API documentation is rendered correctly for users of Internet Explorer 9 and below?

Coding Links in Simple Dev Theme:

Use the standard # coding as shown below.

Coding of the link:

<p>For more information, see <a href="#section_2">Section 2</a>.</p>

Coding of the destination content:

<a name="section_2"></a><h4>Section 2</h4>

Use a standard <a href> link with the filename, as shown below.

For more information about the ACME Payments API, see 
<a href="index_pmt_api.htm">ACME Payments API: Overview</a>.</p>

Use a standard <a href> link with the relative path and the filename, as shown below.

<p>For more information about security with the ACME Payments API, see 
<a href="api_payments/acmepaymentsapi_security.htm">Security</a>.</p>

Use a standard <a href> link with the relative path and the filename, as shown below.

<p>For an overview of the ACME Payments API, see 
<a href="../index_pmt_api.htm">ACME Payments API: Overview</a>.</p>

How do I link from a platform content page to another content page in Simple Dev?

Normally, when coding a relative link to another file, you must include the full filename, including extension, and take into account folder names that you might need to reference in going up or down the folder structure from one folder to another, as in the examples shown above.

When coding a link to a platform user interface page or main platform content page, you don't need to do that. Instead, you'll need to do two things:

  • Reference the page's unique name
  • Apply this class on the link: soa-control-cm-route-link

Below are the URLs for the default platform content pages:

  • {hostname}/#!help
  • {hostname}/#!documentation
  • {hostname}/#!welcome

For example, let's say you want to link from the Welcome index page to the Help index page. All you need to do is reference the unique name, help, as follows:

<p>For more information about using the platform, visit the 
<a class="soa-control-cm-route-link" href="help">Simple Dev Help Page</a>.</p>

How do I link from a platform UI page to a content page in Simple Dev?

The approach explained in Link from a platform content page to another content page above applies to links to all main platform content or UI pages.

Let's say you want to link from the Forum page to the Documentation index page.

First, look at the Documentation page in the browser. The URL is: {hostname}/#!documentation.

All you need to do is reference the unique name, documentation, with the soa-control-cm-route-link class on the link, as follows:

<p>For more information about using the platform APIs, visit the 
<a class="soa-control-cm-route-link" href="documentation">Documentation Page</a>.</p>

How do I link from a content page to a platform UI page in Simple Dev?

The approach explained in Link from a platform content page to another content page above applies to links to all main platform content or UI pages.

Let's say you want to link from the platform help page to the Forum page.

First, look at the Forum page in the browser. The URL is: {hostname}/#!forum.

All you need to do is reference the unique name, forum, with the soa-control-cm-route-link class on the link, as follows:

<p>For discussions and other information, visit the 
<a class="soa-control-cm-route-link" href="forum">Forum Page</a>.</p>

How do I link to a content page in a platform subfolder in Simple Dev?

The approach explained in Link from a platform content page to another content page above applies to links to all main platform content or UI pages. However, if you want to link to an additional content page, either in the same folder as a main content page or in a subfolder, you will need to use the relative path.

You might need to do this to link to a specific help page that's supplementary to the main help page, or a specific API documentation page.

As an example, let's say you want to link from the platform help page to the overview page for a specific API, which is stored in a subfolder in the documentation section. The file name and location are as follows:

\content\documentation\api_payments\index_api_payments.htm

Since it isn't a main platform page, you'll need to use a relative path based on the file and folder structure within the /content folder.

So the link would look something like the below:

<p>For information about using the Payments API, visit the 
<a href="../documentation/api_payments/index_api_payments.htm">Payments API Home Page</a>.</p>

When coding a link to an external site, document, or other file, first test the link yourself in the browser. Include target="_blank" as shown below so that the site or document opens in a new browser tab or window rather than replacing the existing one.

<p>For more information, visit <a href="http://acmepaymentscorp.com/api" target="_blank">http://acmepaymentscorp.com/api</a>.</p>

How do I link to another API documentation file in the documentation folder in Simple Dev?

If you have multiple documentation files in the documentation folder and want to link directly to one of them without using a relative link, you can code the link using the &doc= parameter, as shown in the example below.

<a class="soa-control-cm-route-link" href="documentation&doc=another_api_doc_file.htm">Another API Doc File</a>

In the platform, normally the content within the main window cannot be bookmarked. However, you can add special coding to your link and the resulting URL can be shared.

You'll need to add the following class to your link:

soa-control-cm-doc-jump-link

Examples are shown below for two scenarios:

An example is shown below of how you'd code the link.

<a class="soa-control-cm-doc-jump-link" href="#jump_to_section">Section Title</a>

And how you would code the destination, standard HTML:

<h5 id="jump_to_section">Section Title</h5>

When the user clicks the link, the link goes to the destination location, and the URL changes. The resulting URL can be copied and shared and will work consistently.

Examples are shown below of how you'd code the link.

Link to a specific location in a different file in the same folder: 

<a class="soa-control-cm-doc-jump-link" href="File2.htm#section_1">Link to Section 1 in File 2</a>

Link to a specific location in a different file in the parent folder: 

<a class="soa-control-cm-doc-jump-link" href="../File2.htm#section_1">Link to section in File 2 in parent folder</a>

Link to a specific location in a different file in a subfolder: 

<a class="soa-control-cm-doc-jump-link" href="subfolder/File2.htm#section_1">Link to section in File 2 in subfolder</a>

You might have a dynamic document page that's written using an MVC web application framework such as AngularJS.

JavaScript MVC framework, or AngularJS. Normally you couldn't share this type of link as a bookmark.

However, you create a link that can be shared as a bookmark by adding the following class to your link:

soa-control-cm-doc-route-link

An example is shown below of how you'd code the link.

<a class="soa-control-cm-doc-route-link" href="#/completed">Completed</a>