Content Development Guidelines for Simple Developer Theme

Manage content pages for Simple Developer theme (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.

Table of Contents

  1. What are the content pages in Simple Dev?
  2. What is the folder structure for content in Simple Developer Theme?
  3. Where do I upload revisions for the Simple Dev content pages?
  4. What is the customization ZIP file and how do I use it?
  5. Where do I upload API documentation for Simple Dev?
  6. How do I code links in Simple Dev?
  7. How do I use CSS with my Simple Dev pages?
  8. What file types are supported for content in Simple Dev?
  9. How do I manage my content assets in Simple Dev?
  10. How do I use File Manager?
  11. Are there any limitations to HTML coding in Simple Dev?
  12. In Simple Dev, how do I set up links to documentation for a specific API?

What are the content pages in Simple Dev?

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.

Back to top

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:

Back to top

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

The Site Admin can upload a revised file in Community Manager (default theme).

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

Back to top

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 to the platform (Default Theme) as a Site Administrator.
  2. Navigate to Administration > Config > Resources.
  3. In the Content section, click File Manager to access the Content folder.
  4. Click Upload a Zip Archive.
  5. Navigate 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.

Back to top

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 Default Theme in the same way as any other content. For instructions, see How do I upload content for Simple Developer theme? (Site Admin Configuration help).

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).

Back to top

How do I code links in Simple Dev?

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.

Link types include:

Link to another location in the same document

Use the standard # coding as shown below.

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

Link to a content file in the same folder

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>

Link to a content file in a subfolder

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>

Link to a content file in a parent folder

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>

Link from a platform content page to another content page

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>

Link from a platform UI page to a content page

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>

Link from a content page to a platform UI page

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>

Back to top

Link to a content page in a platform subfolder

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>

Link to an external site or document

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> 

Link to another API documentation file in the documentation folder

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>

Back to top

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:

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

Back to top

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:

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.

Back to top

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).

Back to top

How do I use File Manager?

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 Manager.

Back to top

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.

Back to top

In Simple Dev, how do I set up links to documentation for a specific API?

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.

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 into Default 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 Documents, and view the documentation index page. If the page name is index.html, 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.

Back to top