Customizing WSO2 API Manager Store/Publisher - Part 2
- Lalaji Sureshika
- - WSO2
Browser request flow of the API Store front end
The image below explains the flow of a browser request processing that takes place inside the API Store Jaggery application. Similarly, the API Publisher Jaggery application will also handle browser requests. When a user accesses the API Store/Publisher application through the web-browser, that request will first hit the relevant page located in the 'site/pages' directory in API-Store/Publisher.
Each page is constructed using blocks. A block has a name, an input and an output. The block input and output can contain other blocks as well. Inside this page, to handle the rendering of the web page, it'll call the render() function defined in jagg.jag file contained in the location 'jagg/jagg.jag' in both applications. This jagg.render() method accepts block configurations. A block configuration consists of the block name and the input configuration. When a block needs to be included in some place, the block is called by its name by passing an object as its input. Then, the block generates an output object by executing block logics with the passed input object.
In this instance, we pass a json object that contains the base page name, page body layout name and sub layout blocks names (e.g. in the image below, 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 the render() method is invoked by the web page, it first checks whether the relevant blocks (in site/blocks directory) and templates (in site/themes/templates directory) for the base page, page body layout and for sub layout blocks exist. If not, processing will stop and rendering of the web page will also be stopped. Nevertheless, if the relevant blocks and templates exist, the inputs passing in the render method() will be retrieved and processed by the relevant blocks and generate output objects by executing block logics with the passed input objects.
Then a template in the active theme, which matches the exact block name, is called by passing the above-mentioned input and output objects. The template will generate an HTML content using its logic and the user will be able to see the requested web page, which will be rendered properly in the browser.
Example
As you probably have a basic idea of the function of each of the directories in the API Store web application, it's now time to explain these with an example. To get a better idea of the flow on creating a new web page inside the API Store application, we explain the steps below on how to add such a new page to the API Store in order to view the created APIs per user.
-
First Navigate to the 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.
-
Then create the page called ‘list-user-apis.jag’ by navigating to ‘api-store-web/1.1.2/src/site/pages/’ directory. This page will list the APIs created by the logged user of the API Store. Add the page content such as its title, base page, and layout included in the templates by referring to the file named 'list-user-apis.jag' in the attached sample.
-
Then add a url mapping in jaggery.conf file in the web application as shown below;
"urlMappings":[ { "url":"/apis/listing", "path":"/site/pages/list-user-apis.jag" } ] -
If you look at the attached code sample, in your added page [list-user-apis.jag], you have defined a template to be included in the ‘middle’ part of the layout called ‘list-apis’; navigate to ‘api-store-web/1.1.2/src/site/themes/fancy/templates’ and add the directory ‘list-apis’.
-
Add a template jag and an 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 the attached sample/templates/list-apis).
-
Up to now, you have completed adding the ‘view’ part of your page. Now its time to add the ‘controller’ and ‘model’ parts. For this, add a directory called ‘list-apis’ into the directory ‘api-store-web/1.1.2/src/site/blocks’ of the web application and add the block.jag inside it (note that the template and corresponding block directories should be named as equal).
-
Since you need to output the list of APIs from the corresponding template.jag, you can use the ‘getOutputs()’ function in block.jag to invoke the relevant method from ‘apistore’ module and return the processed output from the block to the template file (you can find this block by navigating to the attached sample/blocks/list-apis).
-
The directory ‘api-store-web/1.1.2/src/module’ contains references to all the functions plugged through the java module into the web application.
In the above case, under ‘api-store-web/1.1.2/src/module/api/’ directory there’s a jag file called ‘published-by-provider.jag’ that contains the corresponding javascript method (getPublishedAPIsByProvider), which will invoke the required java method from the apistore hostobject for this example.
-
Therefore, you don’t need to add a new java method to the java module to be plugged into the web-application. However, 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 sub-directory of the ‘api-store-web/1.1.2/src/module/’ directory. Make sure you have defined that method in the ‘module.jag’ in that sub-directory as well.
-
Now you have carried out the 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 the exploded mode hot deployment is enabled as default, you can see the changes that have been reflected in the web-app UI without restarting the server.
-
From the browser, access “https://ip:port/apistore/apis/listing”; here you’ll see the list of published API names by the corresponding logged user for the web-app.
References