Skip to main content

Customizing WSO2 API Store/Publisher App-Part1

Up to now,hope most of the audience is familiarized with writing java web applications. Now it's time to write a complete javascript based web application with the help of Jaggery.

Jaggery

Jaggery is a Server Side Javascript Framework to write web-applications and HTTP-focused web services for all aspects of the application:front-end, communication, server-side logic and persistence in pure javascript. It offers a completely javascript way to write all parts of Web applications and services as a way to reduce/eliminate mismatches across different layers of the Web application and API development experience. Such that it provides closing the gap between web apps from web services by allowing one to create both application and APIs at the same time.For more information visit the site [1] ,which contains more information,API documentation and samples of it.

This article will focus on how to write a web application with Jaggery. For that as a real use-case,it'll focus on the implementation of two web applications released with WSO2 API Manager [available with Beta1 version] known as API-Store and API-Publisher.

WSO2 API Manager

WSO2 API Manager is a complete solution for publishing APIs,creating and managing  a developer community and for scalably routing API traffic.Basically it contains with three components called API-Store,API -Publisher and API-Gateway. Out of these three API-Store and API-Publisher are web-applications developed to interact with third party users.Importantly those were bulit as javascript web applications by using Jaggery.For more information on API Manager refer  [2].

Getting Started

Pre-RequestiesWSO2 API Manager

In real world, web applications are not much simple as above. For a web application there are a large number of inter-connected UI pages written using HTML,CSS and Javascript with JQuery or a similar library and the interaction with back-end is happening via form POST,JSON or XML data processing and data storing part done via SQL or a file type.As you can see every step of the process has significant impedance mismatches. This is where Jaggery comes to the spot as its capability of writing all parts of Web applications as a way to reduce/eliminate impedance mismatches across different layers of the Web application and API development experience.
If we pay attention on API Publisher and API-Store web applications,below is the general view of how we have implemented them with the help of jaggery.


Overview

Simply we can separate the story into three components.

1.Back-end Java Implementation [Data Access Layer]

All the API Manager apps related functionalities were written based on a java API as a Data Access Layer and some of the metadata had been stored to WSO2 Governance Registry while final storage kept as database storage.

2.Java Module implementation based on Javascript Hostobjects[3]

As API-Manager related functionalities have been implemented based on a java API and not on a Web Service API,to invoke those back-end java implementations,there was a requirement to plug a java module to interact with both back-end layer[java] and front-end application[javascript]. That's how the two javascript hostobjects named as APIProviderHostObject and APIStoreHostObject were written and mapped the java logic in back-end to the javascript in front-end application.
How we have plugged these two hostobjects to the web-applications in API-Manager product is that,we have defined a module called 'apistore' from these two host objects from a module.xml file which you can found from {API Manager Home}/modules/apistore/module.xml and define two hostobjects inside that module.Sameway you can write your own java modules and plugged as above.

3.Front-end web-app implementation

Front-end web-applications has been written based on jaggery with using HTML,CSS and Javascript and Jquery. For clarity and extensibility purposes,the web-applications have followed Model View Controller pattern. Below shown image is the folder structure of the api-store web app. Note that there's no specific directory structure to create a jaggery app,its upon to you based on the complexity of the app.

API-Store jaggery app directory structure

1) jaggery.conf -This file specifies the application specific configurations. It has used to define the URL-mappings for the pages, define welcome page,security-constraints,etc.
2) site directory -This directory contains below important sub-directories;

  1. Themes- The web-app has the capability of multiple-theme support and easily a user can add a new theme with less customized effort to the app. Currently API-Store app contains two themes called 'fancy' and 'modern'.Each theme contains;     

    • CSS -Contains the stying files of the application.

    • Images-Contains the styling images of the application.

    • js-Contains the globally used JavaScript libraries related files as jquery,bootstrap

    • templates-Contains views of the web-application. The layout of a web page has been separated into layout blocks and each UI of such layout blocks has created using templates. A template can be considered as a re-usable UI block. Inside such a template the rendering HTML for the web UI part and related javaScript event triggering have been included. Note that these templates can be reusable in any page,by including it to the required page. Each template should contain two files as; 

       -template.jag-Which contains the html code.Below is a sample template code.

      <% jagg.template( "api", function(inputs, outputs, jagg) { %>
//The outputs displaying from the template and the inputs for the template can be via outputs and inputs parameters. 
//All the htmls included here
 <% }); 
 %>

        -initializer.jag -Which uses to initialize the template by embedding javascript files or css to the template.Below is a sample initializer code. 

      <% jagg.initializer( "api ", {    preInitialize:function (data) {                
 //Below is how to import a javascript and CSS file to a template         
 jagg.addHeaderJS("template", "key", "jsFilePath"); 
jagg.addHeaderCSS("template", "key", "CSSFilePath");  
 } }); %>

      The layout which is predefined for a web page in API-Store is as below and the templates are set to the each sub layout parts according to the below layout.  


      The basic layout for a web page in API-Store is as above and it can be found with navigating to ‘templates/layout/base/template.jag’.  

      The basic web page template of the app can be found from templates/pages/base/remplate.jag.

      This base page contains the globaly common stylesheets and other related ui library references.

      From a template,you can include another template also by using following code.In current API-Store app you can find such a location from here.

      jagg.includeBlock("nameOfTemplae", inputParamsAsaJson);

       

  1. Blocks -

    This directory can be considered as the Controller part of the web app. User actions on each View(template) are sent to the relevant block and then it handle the incoming HTTP requests.

    Each template has a corresponding block. Handling of incoming HTTP requests done from the jag files included inside directory called ‘ajax’ of each block.A block receives user requests and translates them to actions that the module directory should take from these jag files.Then with the response from module directory,the block selects the appropriate template [view] to pass the response as an input to the template.Below is a sample code of a block.

     

    <%
    jagg.block("api", {
       initializer:function (data) {
       //This initializer function is required when defining a block
       },
     getInputs:function () { //This method is optional,and it can be used to define input                                           //parameters for a block. 
    },
      getOutputs:function(inputs) { //Do some operations from the inputs of the block.  }
    });
    %>

  1. Conf - This directory contains configurations related to web application User Interface. Inside the 'conf' directory,there's a file called site.conf which contains the settings for default theme,site context of the web application.

  1. Pages- This directory contains the main pages that the web-application.This is the intial location comes after a browser request done by a user.

    In a page you can define its titile,what is the basic page and the layout referring from this page,what templates need to add into the page layout and inputs which has to pass into those templates as a json and page will render accordingly using render method of jagg.jag file. Below is a sample code block to render the page with defining its base page,tittle and templates for layouts.

jagg.render({"name":"page/base",
"inputs":{
"title":"API Store Listing",  //Page title
"pagePath":"/site/pages/list-apis.jag", //Page path
"body":[
{
"name":"layout/extended", //Page layout
"inputs":{   //Page inputs
"title":null,
 "middle":{
  "name":"api/listing", //template for the middle
   "inputs":{  //inputs for the template
    "apis":apis
        }
     }
    }
   }
  ]
}
});

3) Module directory 

This can be considered as the 'Model' of the application. It handles the state of the application.When a block invoke an action of a particular module from this directory,it will invoke the relevant function from javascript hostobject.

From jaggery server runtime,it'll process the requests which will go to javascript hostobjects.Then the server will return the response from backend as a mapped javascript object with java response and pass the response again to block and then block will pass the response to corresponding template[view].

4) jagg directory

This is the most important directory of the API-Store web application as it contains the file jagg.jag ,which has kept for handling all functionalities to control and manage interactions among the modules,blocks and templates of the application. It contains custom methods develop for API Store/Publisher web applications to control its functionalities from Jaggery.Some of the important methods defined here is as below

  • jagg.render(obj) -To render the html content for a particular web-page of the application.
  • jagg.getThemePath() -To retrieve the theme defined in 'site/conf/site.json'.
  • jagg.getUserTheme() -To retrieve the user's theme defined in session.
  • jagg.getAbsoluteUrl(path) -To retrieve the absolute path of a relative url .
  • jagg.addHeaderJS(template, key, js) -To import a js file to a given template header .

References

[1] http://jaggeryjs.org

[2] http://wso2.com/products/api-manager/

[3]http://wso2.org/library/tutorials/writing-custom-hostobject

Comments

Post a Comment

Popular posts from this blog

Convert an InputStream to XML

For that we can use DocumentBuilder class in java. By using the method parse(InputStream) ; A new DOM Document object will return. InputStream input; DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); DocumentBuilder parser = factory.newDocumentBuilder(); Document dc= parser.parse(input); In the above code segment,by using the created Document object,the corresponding XML file for the inputStream can be accessed. References: http://www.w3schools.com/dom/dom_intro.asp http:// download.oracle.com/javase/1.4.2/docs/api/javax/xml/parsers/DocumentBuilder.html
2 comments
Read more

CORS support from WSO2 API Manager 2.0.0

Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources  on a web page to be requested from another domain outside the domain from which the first restricted resource was served. For example, an HTML page of a web application served from http://domain-a.com makes an <img src >  request for a different domain as 'domain-b.com' to get an image via an API request.  For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts as in above example and only allows to make HTTP requests to its own domain. To avoid this limitation modern browsers have been used CORS standard to allow cross domain requests. Modern browsers use CORS in an API container - such as  XMLHttpRequest  or Fetch - to mitigate risks of cross-origin HTTP requests.Thing to  note is it's not only sufficient that the browsers handle client side of cross-origin sharing,but also the servers from which these resources getting need to handl
Post a Comment
Read more

[WSO2 AM] APIStore User Signup as an approval process

In previous versions of WSO2 APIManager before 1.6.0, it was allowed any user who's accessible the running APIStore come and register to the app.But there will be requirement like,without allowing any user to signup by him/her self alone,first get an approve by a privileged user and then allow to complete app registration.Same requirement can be apply to application creation and subscription creation as well.To fulfill that,we have introduced workflow extension support for  WSO2 APIManager  and you can find the introductory post on this feature from my previous blog post on " workflow-extentions-with-wso2-am-160 " . From this blog-post,I'll explain how to achieve simple workflow integration with default shipped resources with  WSO2 APIManager 1.6.0 and WSO2 Business Process Server 3.1.0 with targeting "user-signup" process. Steps First download the WSO2 APIManager 1.6.0[AM] binary pack from product download page . Extract it and navigate to
Post a Comment
Read more