API Store has two themes “Fancy” ,and “Modern”. Both of these themes are created on top of Twitter Bootstrap framework. I used 12 column grid system to layout elements. It is recommended that anyone attempting to modify the existing API Store themes to get a clear understanding about css grid systems. If you are totally new to the css grid systems, reading the following article will lighten things up. Even though this article is about 960 grid system, it explains general principles behind the gird systems.

https://sixrevisions.com/web_design/the-960-grid-system-made-easy/

Also https://twitter.github.com/bootstrap/scaffolding.html explain the grid system used in API Store.

We will be working through few example use cases during this tutorial.

1. – Changing the API Store Logo
2. – Changing the API Store footer copyright message.
3. – Add New About page to API Store.
4. – Adding a new theme to the API Store (ancient)
5. – Setting the ancient theme as the default theme.

Beta2/1.0

Changing the API Store Logo

Let's find the image responsible for displaying the logo. The following image illustrate the folder structure of WSO2 API Manage. Fist locate “jaggeryapps” by browsing to “wso2am-1.0.0-ALPHA\repository\deployment\server\jaggeryapps”. This is where all the jaggeryapps are deployed. There are two web applications in this folder. “apiprovider” and “apistore” which are “API Provider”, “API Store” applications respectively. For our theming experiments we are only going to theme the “apistore” application. For the sake of simplicity let's call “ wso2am-1.0.0-ALPHA\repository\deployment\server\jaggeryapps\apistore” as <root>.

Let's take a look at the folder structure of the “apistore” web application.

A theme in apistore is not simply a collection of images and css files. It has the applications front end logic as well. Each theme can have it's own logic, making it's extremely flexible to do customizations to the UI. Right now "Fancy" theme is the main theme. This "Fancy" theme has a sub-theme named "Modern". This "Modern" theme contains only the files that are different from the main theme. The files inside the "Modern" theme will override the corresponding files in the main theme. This theming architecture is designed by our own ( Ruchira Wageesha )

Site logo and other images used by each theme can be found from there images folder. Simply replacing the “logo.png” on each theme will change the logo of “apistore”.

Changing the API Store footer copyright message.

Now let's look at how to change the footer copyright notice of “fancy” theme.

Template file responsible for displaying the copyright notice is “<root>\site\themes\fancy\templates\page\base\template.jag” .Please make a backup copy of this file before proceeding. This file has normal HTML markup mixed with jaggery code. This file holds the main html structure of the page. Search for the magic word “Copyright” in this file and change the text accordingly.

 

Add New About page to API Store.

Navigate to “<root>\site\pages” folder. There you can find the pages available with the “apistore” web app. These pages are common to all the themes in the app. Let's duplicate the page “sign-up.jag” and rename it to “about.jag”. Open the "about.jag" file you just created.

Note:These line number can differ if you are using a different version than Beta2. In that case, please search for the text or code segment given.

Go to line 9 and change "Create New Account" to “About API Store”.

Go to line 10 and change "/site/pages/sign-up.jag" to "/site/pages/about.jag"

Go to line 50 and change “user/sign-up” to “about/about-view”

Navigate to “<root>\site\blocks” and create the following folders

“about”, “about\about-view”.

Navigate to “<root>\site\blocks\about\about-view” and create a new file and name it “block.jag”

Open the above file and add the following code.

<%
jagg.block("about/about-view", {
initializer:function (data) {},
getInputs:function () {}
});
%>

Now navigate to “<root>\site\themes\fancy\templates” and create the following folders

“about”, “about\about-view”.

Navigate to “<root>\site\themes\fancy\templates\about\about-view” and create new file “initializer.jag” with the following content.

<%
jagg.initializer("about/about-view", {});
%>

Also create “template.jag” with the following content in the same location.

<% jagg.template("about/about-view", function(inputs, outputs, jagg) { %>
<h3>About API Store</h3>
<p> -- About content -- </p>
<% }); %>

The above “template.jag” is the one with the actual content of the “About” page.

Now we need to link this page from the top navigation menu. Navigate to “<root>\site\blocks\menu\primary” and open block.jag. Please make a backup copy of this file before proceeding. Now add the following code after line 40.

links.push({
"title":"About",
"url":jagg.getMappedUrl("/site/pages/about.jag"),
"classes":"link-about",
"tooltip":"About API Store",
"active":(path == "/site/pages/about.jag")
});

Adding a new theme to the API Store (ancient)

We have “fancy” and it's sub-theme "Modern" theme. Let's create a new theme (“ancient” theme.)

We can do this in two different ways. We can either create a new sub-theme for "Fancy" or create a new main theme.

Creating "ancient" theme as a sub-theme

Sub-themes are suitable when you are not changing the structure of the files inside the theme. Navigate to "site\themes\fancy\subthemes" folder. There you will find the "Modern" theme. When examining the folder structure of the "Modern" theme you will notice that it contains the same folder structure in "site\themes\fancy". The theme system is designed in such a way that ones the files are placed according to the same folder structure as in "site\themes\fancy", the files in sub-theme folder will take the priority.

Make a copy of "site\themes\fancy\subthemes\modern" folder and rename it to "ancient".

Let's make this new “ancient” theme header background to red color.

Navigate to “site\themes\fancy\css\styles-layout.css”. Add the following css rule at anywhere in the file.

.header-menu div.navbar-inner div.container-fluid{
	background:red;
}

With the above change the header of the ancient theme will be in red color. Now we need to add this theme to the theme selection menu.

Next navigate to “<root>\site\themes\fancy\templates\user\login” and open the “template.jag” file. Find the html table with the theme thumbnails. Add a new table row element with the following markup.

. You will have to create a thumbnail image for the new theme "thumb-ancient.png" . You can get the image use in this example from here.

<tr>
	<td>
		<div class="thumbnail <% if(jagg.getUserTheme().base == "fancy" && jagg.getUserTheme().subtheme == "ancient") { %>currentTheme<% } %>">
			<a data-theme="fancy" data-subtheme="ancient" class="badge themeLabel" onclick="applyTheme(this)">
				<img src="<%=jagg.getAbsoluteUrl(jagg.getThemeFile("images/thumb-ancient.png"))%>" />
				<br /><div class="themeName">Ancient</div>
			</a>
		</div>

	</td>
	<td>
	</td>
</tr>

Setting the sub theme as the default theme

Let's set the sub theme we created as the default theme. For this, we need to do some modifications to site.json file.

Navigate to “\site\conf" and open "site.json".

"theme" : {
        "base" : "fancy",
        "subtheme" : "ancient"
}

This means, the base theme is "fancy" and its overridden by the "ancient" sub-theme, So you will see the effects of the sub theme. if you dont mention "subtheme" property the base theme will be the default.

I hope this tutorial provided you with a basic knowledge required to start hacking the themes. But this tutorial is not digging deep in to the syntax and logic of jaggery code. They will be covered in a separate tutorial in more detail.