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 Default 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 Default Theme, see Linking in API Documentation (API Admin help).
By default, Simple Dev has three content pages in the user interface:
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 the customization guide.
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:
The Site Admin can upload a revised file in Akana API Platform (default theme).
For instructions, see How do I upload content for Simple Developer theme? (Site Admin Configuration help).
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.
Note: to see the update immediately, you will need to clear cache and refresh the page. Cache is updated automatically every hour.
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 Default 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: Default Theme: Administration > Config > Resources > Content File Manager. From here, there are two approaches to uploading the content:
You can create as much API documentation content as is needed, including:
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:
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 Default Theme: Administration > Config > Resources > Content File Manager, 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 Default 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:
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:
However you choose to structure your files, just use a relative link to the CSS in the <head> tag of your documentation file.
Simple Dev supports most standard file types you might want to use in documentation. For example, it supports the following:
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.
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).
File Manager is not available in the Simple Dev theme. In Default Theme, it is available for two audiences:
For Simple Dev content, the Site Admin can:
For information and procedures for working with File Manager, review the topics in the API Admin content management help under this heading: Using File Explorer.
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 Default 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.
http://{hostname}/#/api/{APIID}/versions/{APIVersionID}/documents/index.htm
<a class= "soa-control-cm-route-link" href="api/{APIID}/documents&doc={filename}.htm">{text for the link}</a>
In Default Theme, when an API is set up, the generated API document is displayed by default when the user goes to the API > Documents 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:
FIrst, go to the API > Documents page in Default Theme. Let's say the page URL is:
You'll need to code a link in the Simple Dev documentation index page (or other page) that looks something like the below (line breaks added for display purposes):
<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 link looks like this:
When the user clicks the link, the generated API documentation is displayed.
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>
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:
Below are the URLs for the default platform content pages:
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>
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>
The approach explained in Link from a platform content page to another content page above applies to links to all main 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>
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>
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>