Customizing WSO2 API Store/Publisher App-Part2

From the Part 1 of this tutorial[1], we discussed on overview of API-Store and its directory structure.This tutorial will be focus on the flow of how a user request is handle by API Store web-application front-end and a example to try out.

Browser Request Flow of the API-Store Front-end

Below image will explain the flow of browser request processing happened inside the API-Store jaggery application.Similarily API-Publisher jaggery application will also handle browser requests.
When a user access the API Store/Publisher application through the web-browser,that request will first hit on the relevant page located at 'site/pages' directory in API-Store/Publisher.Then inside that page,to handle the rendering of the web page,it'll call the render() function defined in jagg.jag file resides on location 'jagg/jagg.jag' inside the both applications.

To invoke that render() method,we are passing a json string which contains the base page name,page body layout name and sub layout blocks names[eg:In the below image we have set a sub layout block name called 'api/listing' to be set to the 'middle' section of the layout] and their corresponding inputs.Once render() method invoked by the web page;it first check whether the relevant blocks[in site/blocks directory] and templates[in site/themes/templates directory] for base page,page body layout and for sub layout blocks,exists.

If not processing will stop and rendering of web page also stopped.Else if the relevant blocks and templates exists,inputs passing for the render method(),will retrieved and processed by the relevant blocks and will pass the processed data to the relevant templates.From the relevant templates,html rendering will happened and the user will able to see the reqested web page will rendered in browser properly.

Example

As you got a basic idea of what each directories doing in the API Store web application,now its time to get use of them with an example. To get a better idea of the flow on creating a new web page inside the API-Store application,below steps will explain how to add such a new page to the API-Store inorder to view created APIs per user.Sample code can be found from here.

1. First Navigate to API-Store web-application code from [1] or simply navigate through the API Manager binary pack as {API Manager Home}/repository/deployment/server/jaggeryapps/apistore.
2. Then create the page called ‘list-user-apis.jag’ by navigating to ‘apistore/src/site/pages/’ directory.This page will list down the APIs created by logged user for the API-Store.Add the page content as its title,base page,layout,included templates by refering to the file inside the attached sample/page directory.
3. Then add a url mapping for it in jaggery.conf file in web-application as below;

   "urlMappings":[           {               "url":"/apis/list",               "path":"/site/pages/list-user-apis.jag"  } ]

4. If you look the attached code sample,since in your added page [list-user-apis.jag],you have defined a template to be included in ‘middle’ part of the layout called ‘list-apis’;Navigate to ‘apistore/src/site/themes/fancy/templates’ and add the directory  ‘list-apis’.
5. Add a template jag and a initializer jag inside it. Add the html code to template.jag and add imports to javascript files and css relevant to this template into initializer.jag. [You can find the sample code for this template.jag and initializer.jag by navigating to attached sample/templates/list-apis].
6. Upto now you have completed adding ‘view’ part of your page.Now its time to add the ‘controller’ and ‘model’ part of it.For that add a directory called ‘list-apis’into the directory ‘apistore/src/site/blocks’ of the web-application and add the block.jag inside it.[Note that template and corresponding block directories should named as equal.]
7. Since you need to output the list of APIs from corresponding template.jag,you can use ‘getOutputs()’ function in block.jag to invoke the relevant method from ‘apistore’ module and return the processed output from block to the template file.[You can find this block from navigating to attached sample/blocks/list-apis.]
8. The directory ‘apistoreweb/src/module’ contains reference to all the functions plugged through the java module into web-application.
   In above case under ‘api store web/src/module/api/’ directory there’s a jag file called ‘published-by-provider.jag’ which contains the corresponding javascript method [getPublishedAPIsByProvider] which will invoke the required java method from the apistore hostobject for this example.
9. Thus you don’t need to add a new java method to java module as to plugged into the web-application.But in-case,if you want to add a new java-level method ,first add it to the API-Store/API-Publisher Host Object and then add that method to a jag file inside a subdirectory of the  ‘api store web/src/module/’ directory.And make sure you have defined that method to the ‘module.jag’ in that subdirectory as well.
10. So now you have done necessary changes to update your change from API-Store web app.Start the API Manager server and navigate to {API Manager Server}/repository/deployment/server/jaggeryapps. Then replace the existing directory ‘apistore’ ,with your changed apistore web app directory.Since exploded mode hot deployment is enabled as default,you can see the changes reflected to web-app UI without restarting the server.
11. From the browser access “https://ip:port/apistore/apis/list”,then you’ll see the list of published API names by corresponding logged user for the web-app. 

References

[1]https://svn.wso2.org/repos/wso2/branches/apimgt/1.0.0-beta/platform/components/apimgt/api-publisher-web/src/