Portal Configuration

The look and feel for the entire developer portal can be customized to match your own branding. A standard CSS stylesheet is available to provide an easy starting point for your customizations.

In this HowTo you will add your own CSS customizations, and reload it to put your new styling changes live.

There is a default stylesheet, screen.css. This is quite a large and complex stylesheet. Rather than extend this, it is better to create your own stylesheet for any of your own customizations to overwrite the defaults. You create a new stylesheet the same way you create a page (just remember to choose an appropriate MIME content type, in the advanced page settings).

It is important that the selected Layout is blank. Otherwise the page layout HTML will obscure the CSS rules.

Then in each of your layout templates (or in a partial in case you have a common HEAD section), after the link to screen.css, you add the link to your custom css e.g.

<link rel="stylesheet" href="/stylesheets/custom.css" />

Now enjoy the beauty of your own unique branding!

The look and feel for the entire developer portal can be customized to match your own branding. You have complete control over every element of the portal in order to make it as easy as possible for developers to learn how to use your API. A successful API portal will turn concepts into working apps in no time at all!

By the end of this section you should be familiar with the use of our CMS. We will guide you through it’s structure, usability and functionality.

Let’s start our guide with a general overview of the CMS. As you probably have seen (if you have already taken a look at system), the system consists of a few elements:

  • Horizontal menu in the Portal Admin console with access to
    • Content, Redirects and Changes.
  • The main area containing details of the sections above.
  • The CMS mode which is accessible through the preview option.

We will describe each of the section in more detail.

This is the most important part of the Admin's view of the CMS system. Let’s describe it in more detail.

The Content section shows all the site structure and hierarchy and gives also the editing functionality within the same page. This means that it gives the possibility to manage the site structure and the pages and other assets stored in it. The portal's hierarchy is displayed in a form of a directory tree.

The image above shows a sample view of one of the pages inside the Contents section. As you can see it displays all the files (pages, images, stylesheets, javascripts etc.) preserving the site’s path hierarchy (as before, sections are functionally equal to directories).

On the right hand side you can see the edit page view. Here we can see the pages name (and indicates if its a standard or built-in page) and a button to add a new element to the content (page, layout, partial, section, file, portlet). Below we can choose the layout which the page will be using, and you can also toggle the liquid tags functionality. The following part is the text editor, supporting code highlighting, tabulations, line numeration and much more. The tab buttons ‘Draft’ and ‘Published’ switch between the Draft and Published version of the edited document. Following icons list the document’s versions and open a pop-up edit window respectively.

To edit page content, you just choose the desired layout, set few additional options like content type and the URL path and then input the code in HTML, Markdown or Textile.

Another important functionality in this view is the "Preview" button. You can choose if you want to preview the published or the draft version of the page. Clicking the button redirects you to the CMS mode. In this mode you can see the live(or draft) rendered version of the page with a dark-grey vertical bar on the right hand side. This bar contains links to page, layout and partials edit (this we will cover in the next section of the guide) views of the CMS. Moreover it allows you to swtich between the Draft and Published views.

Another functionality of the Content section, which applies also to the next parts of the guide, is the Filter. It is not only a search field, but it also allows to limit the elements shown to only e.g. stylesheets, javascripts or any other specific types.

These sections manage the templates and the reusable parts of the page. Their functionality is similar, so we will cover it in the same step.

Layouts section consists of definitions of the templates used by pages. Layout is a the main, static (in the way, that it remains the same on all the pages using the same layout) part of the page. Inside it reside all the partials, portlets and the actual pages content.

Partials on the other hand are the reusable parts of code, which repeat in many places/pages (e.g. footer, which is the same on every layout, sidebar which is the same on a few pages with different layouts, etc.). To include a partial in a layout/partial/email template/portlet type: {% include "partial_name" %}. For full reference of liquid tags check here

Identically as the other parts of the portal, also layouts and partials have the draft/published states and offer a full version history.

In the screenshot above: number 1 is the text editor of the Layout’s structure, number 2 is for saving the draft, reverting it to the published version and publishing the draft. The buttons under number 3 switch between draft and published versions, list all the layout versions and launch the pop-up editor

The last subsection of the Content part are the portlets. They give you some more advanced functionality at hand without the need of any advanced coding. Our CMS provides now 3 different portlets:

  • External RSS Feed - fetches the RSS feed from a given source
  • Table of Contents - generates the links list for the pages in given section
  • Latest Forum Posts - generates the list of the n latest forum posts

While creating the dessired portlet you have to input the requested data in the setup page (e.g. Title, system name and the url feed for the External RSS Feed portlet).

The Editor will come pre-filled with the standard portlet's code using some custom liquid tags. You can try editing the generated structure, but be careful and in any doubts just leave the code as it is or refer to the Portal Formatting Tabs reference

The last elements of the CMS are Redirects and Changes sections. They are much less complicated then the Content section, but also provide an important part and give some custom functionality.

Redirects help you set up redirects of some portal url to other ones. Useful i.e. when you deprecate some old page and dont want to change all the links.

The last, but not least is the ‘Changes’ section. It contains a list of all the newly edited and not published pages and gives you a possibility to publish them selectively or publish them all at once.

The content of all standard email communication with developers can be completely customized. This allows you to closely match the workflows which you have selected for your portal.

At the end of this section you will edit and save a custom email notifications.

There are a lot of potential email templates. However only a subset of them are likely to be relevant for your environment, depending on how you have setup your workflows. You can save yourself time, by making sure you are happy with your workflows, before you begin the task of editing the email templates. This way you only have to edit the templates that you will actually use.

Perform a dry run of your finalized workflows, making sure to test all the possible branches (e.g. approval and rejection). Then identify each email notification that is received by your test developer account in the dry run, and make the edits in the next step.

Notice that all the email templates differentiate whether they are notifications for your developers (or “buyer”), or for the admins (of your API “provider” account).

HowTo portal email templates

The first time you edit a template, you will actually “create” a custom template. Then in subsequent edits, you “save” your changes. Warning: there is no version control. It is recommended that you make a local copy if you want to be able to revert changes.

You can use the “notes” field for any internal notes (which are not visible in the email content). These can be useful to keep track of which email templates are currently in use for your workflows.

Liquid tags can also be used for dynamic content in your email. It is especially recommended to make backups when you make changes to the liquid tags.

HowTo portal email template edit

Complete these same steps until you have covered all the possible branches for your workflows.

Normally you probably do not need to customize notifications to your own admins. However in larger organizations you may want to complete these additional steps. This can be used to provide instructions on what actions to take, in the context of the notification. The steps to customize these emails are exactly the same as for your developer emails.

  • Before customizing your email templates, it is best to have the signup workflows fully finalized and tested.
  • If you intend to change any of the liquid tags within the email templates, be sure to read up on the liquid reference documentation

There are some elements, which are generated by the system and are not possible to change from the CMS. These include the Signup, Dashboard, and Account pages. This guide will show how to customize the content on these pages with some simple CSS/Javascript scripts.

By the end of this section you will be able to modify and/or hide any elements on the system generated pages.

The 3scale system generated pages are subject to change (although infrequently). These changes may break any customizations that you implement following this guide. If you can avoid using these hacks, please do so. Before you continue please be sure that you will be able to monitor for any disruptive changes, and do the necessary maintenance work to keep your portal functioning correctly.

The first and most important thing to do is to identify what we actually want to hide. To do that, we will use Firebug (or you can use any other Developer tools, like Chrome Developers tools, Opera Dragonfly, etc.). Let's choose the desired element and then in the console right click on it and select "Copy CSS path". This way we will have saved the exact CSS path in order to make it easy to manipulate. Remember, that if the element is a part of the sidebar navigation widget, you will also have to specify which position in the list. For this you can use either the "+" selector (e.g. to choose 3rd li element: ul + li + li + li) or the ":nth-child(n)" CSS3 pseudoclass.

HowTo portal modify 3scale system pages css

Now, having identified our elements we can change their display settings. Depending on the type of element we can choose from two possible methods: CSS manipulation or jQuery script. The first one is more lightweight and reliable, but doesn't work well for some kinds of elements, which exist on a number of pages (e.g. 3rd element in the Dashboard's sidebar also exists in the Account section, but has a different value) and some more tricky implementations require use of CSS3 which is not supported by old browsers. In the next two steps I will show you both of those approaches.

As an example lets try to hide the Latest Forum posts box from the Dashboard page. Following the first step, we have identified its CSS path as: We have to keep in mind, that it is the second box with the same path, so we will use the "+" selector. Our path will now look like this: Changing display property to none we make that box invisible:

If we have a more tricky element to hide, like a sidebar menu element, it is better to use some jQuery. This is because the CSS path of these elements is identical on the Dashboard and Account sections, and we don't want to hide elements in both sections. So we will choose the element based on the CSS path and the content. In this example let's assume, we want to hide the messages section from the Dashboard's sidebar. Our CSS path is: In order to match the content we will use the .text() function. We will also include the code inside the document's head and inside the ready function, so it is executed after all the content has been generated.

HowTo portal modify 3scale system pages
The resulting code snippet will look like this:

Please note that this is not the only solution. It just shows one possible way of doing it. This same example could be also accomplished using pure CSS with CSS3 selectors basing on the attributes values. For the complete CSS3 selectors specification take a look here.

If you are using the multiple services functionality, you are able to customize the signup procedure to allow customers for subscribing to different services.

By the end of this section you should be familiar with the procedure to create and customize a multiple service signup page.

You should be familiar with layout and page creation procedures as well as with the basics of Liquid Formatting Tags. You can check our Liquid Tags reference here. Moreover "Multiple Service" functionality must be enabled on your account (available from Pro plan and upwards)"

We strongly recommend reading about the Signup Workflow, so you will have all the setup prepared and be also aware of how it works.

We will start the process with creating a new Layout, which will serve as the template for our multi-service signup page. Let's go in the Layouts section in our CMS system and create the new Layout. We can call it: multiple_service_signup, to easily distinguish it from the other layouts, and in the editor paste the general structure of your standard layout (e.g. home or main layout). Now delete everything which we wont need for the signup (e.g. all the containers, sidebars, additional boxes, etc.).

Having created this backbone of our layout, we can proceed to customizing the code for signup.

In order to retrieve all the informations about the services, which we need to construct the proper signup link, we have to loop through the service objects. Services are a part of the model object.

We already have our layout and loop accessing the service objects. Now we should decide the way we want to display the service's informations and the signup link. I have decided to divide them into columns with a service description and a Signup link in the bottom. Every column will be a div box with a 'service-column' class and containing all the necessary informations.

The container inside serves as a custom description field and service.name is the service name, which in this case will be the containers name.

Now we come to the main part of our custom service signup. To create the signup link we have to extract the signup url and the service id. The first we take from urls object, and the latter from our service object on which we iterate in the loop. The final link code will look like this:

In this moment we also have to take into account a possibility, that the user has already signed up for some of our services. To check that, lets create a conditional block with a possibility to unsubscribe from a service.

With this we can generate the final code:

Let's add some final touch to the generated markup. This depends on the amount of services we have. In my case it's two, so the CSS code for the 'service-column' div will be:

We have used the percentage based layout to dynamicaly assign the width of the column basic on the containing div's dimensions.

Now you should have properly working and properly looking multiple service subscribe page. Congratulations!

If you would like to display the columns in a specific order, you should try using the conditional expressions (if/else/case) conditioning the service name or other value, which you know.

Sometimes you might need to have some pages of your developer portal only accessible for a group of developers. It may also just be a part of a page or even some items in a certain menu. Both goals are achievable through the two techniques introduced below.
Here you will learn how to have content in your developer portal that is only visible for some users.
When creating restricted sections it is often useful to do it in a way that each section maps to a logical group of your users. For this example we will assume that there is a group of developers we call "partners". For every page or group of pages that you want to restrict access to, you should create a new section in the CMS. Uncheck the "public" status field. Then drag and drop any pages you want inside this section.
creating a new private section
Create a group and give it access to the section you created before.
creating a new group
Now every time you have to grant one of your users access to this section you will only need to assign him to this group. The way to do that is to go into the corresponding account detail page, then to "Group Permissions" and once there check the boxes for the sections you want to allow.
group permissions screen

Liquid tags are a very powerful way of customizing your developer portal. We will use them here to hide or display parts of a page based on a condition. 3scale allows creating custom fields for accounts, applications or users. You can leverage this ability to store information that is useful for you as the API provider. Here we will create an custom field attached to all accounts, and we will use it to indicate if a given account is a "partner" or not. You can create such field going to "Settings" > "Field Definitions". Add a field to the Account section and mark it as hidden so it will not be displayed on the sign up page or anywhere else on the portal.
field definitions screen
With the custom field in place, now you are able to show special content to "partners" by wrapping the content in a conditional like in the following snippet: or using the inverse logic, if it suits your case best: From here on, whenever you want to show these pieces of hidden content to a user, you only need to type in 'true' in the partner field of his account detail page.
In many cases you might want to provide access to restricted content to a developer based on some change in his state. For instance, when he upgrades his application plan. A way to streamline the process would be to use [webhooks](https://support.3scale.net/howtos/api-operations/webhooks) together with the [account management API](https://support.3scale.net/refierence/activedocs). Based on the plan the developer has switched to (which can be known from the message sent by the webhook request) you can grant him access to the private content by calling the API to update the "partner" field.
Besides the two ways to restrict access to content described above, there is an additional technique that can be useful: requiring a logged-in user. This is very easy to achieve using Liquid tags. You only need to wrap the content that will be available only for logged-in users inside the following conditional:

This article shows how existing user credentials of your web site can be used to automatically login to the 3scale-powered Developer Portal.

Single Sign-On (SSO) allows you to manage access control of multiple independent systems. By following this guide you will be able to allow users that are logged in in your system to log-in automatically to your 3scale-powered Developer Portal without being prompted to log-in again.

This feature is meant for those API providers that already own the identity of their API consumers (username and password) i.e. the API provider is also the Identity provider.

First of all, the API consumer must have an account in your 3scale-powered Developer portal. You can import your users to 3scale using the Account Management API or create them manually.

Once the user exists, you can use an API request call to generate a URL with a built-in SSO token:

There are 2 parameters in this call: username to specify for whome you are requesting the token and expires_in which is the number of seconds that the token will be valid for and defaults to 10 minutes. You can also pass an additional parameter redirect_url with a location to redirect the user after a successful login. This parameter should be percent encoded. The XML response will contain a URL with a secret token included:

NOTE: You can pass either user_id OR username to identify the 3scale user. Typically, the username will be the same for your system and 3scale Portal. In that case using the username should be easy as it does not require any additional information to be stored on your side. If you however need to do some pairing and machine processes the URLs anyway, you might be better off with user_id.

The response contains an SSO log-in URL with a token:

The URL contains all the required information for the 3scale Developer Portal SSO to log you in and you can embed it directly into web. Bear in mind however, that the URL can expire before user clicks it. It is therefor recommended to have a generic link on your page that will dynamically request a fresh SSO URL and redirect to it. This way, the user will be seamlessly logged into your 3scale-powered Developer Portal.

The URL needs to be unescaped. If you want to try it by hand in a browser or cut and paste, remember to replace the "&amp;" for "&" in your browser. Also any "%" encodings in the token need to be replaced by their unescaped character