Tutorial #4 – webODRA2, ODRA eIDE2 and Scaffolding

Scaffolding is a mechanism which helps programmers and/or designers in creating a starting point for further development. It could generate various artefacts, but in ODRA eIDE2 is utilized for building a web GUI for a business class. The GUI supports CRUD (Create, Retrieve, Update, Delete) operations using a client-side library called Knockout.js.

Prerequisites

At the beginning make sure that you have all necessary parts correctly installed:

• ODRA DBMS,
• webODRA2,
• ODRA eIDE2.

The current version of the scaffolding works with any business class implemented in SBQL on the ODRA platform. Existing version supports only simple types, but we are going to expand it in the future.

Class to scaffold

Let’s start with a slightly modified (remove all methods and the Products variable) Product class from the tutorial #2:

module ProductMod {
	class ProductClass {
		instance Product: {
			name: string;
			description: string;
			manufactureDate: date;
			stockItems: integer;
		}		
	}	 
}

As you can see, the IDE reports a warning (a yellow underlining) regarding a missing identification field. This is caused by the fact that the mechanism requires two special fields in a processed class:

• An identification field of type integer: id: integer;
• A label field of type string: name: string.

Let’s see what will happen if we start the process right now. Click the small icon located at the margin in the class instance line and then double click on the link.

As we could expect the scaffolding process reported an error message.

Fixing problems

Fortunately fixing this is really simple. We can manually add a required line of code (id: integer;) or use an another technology implemented in the IDE (a quick fix) which will automatically do it for us: hoover over the warning and click the link as presented below:

As the result a required code has been added to the class. A similar solution can be used in a case of missing name field.

Successful Scaffolding

Right now we are ready to scaffold some GUI – do it by clicking the previously mentioned icon.

After a short while we can observe the results of the operation (a couple of new files and folders added to the project):

• GlobalMod.sbql. This file stores some global data, common for the entire project:
  • Two definitions: RouteClass (each instance stores a single routing rule) and WebParamType (utilized for passing parameters from the web);
  • Routes which is an extent for all the rules;
  • A createRoutes() method which puts global routing rules into the DB;
• ProductControllerMod.sbql. This is a controller for the business class Product. It is responsible for:
  • Storing all instances of Product;
  • Processing web requests (all methods: webXXX. Please note that the methods are referenced by Data routing rules (inside the createRoutesForProduct() method));
  • Creating routes for CRUD operations for the class (the createRoutesForProduct() method);
  • Generating sample data (the seedProduct() method);
• WebRes folder which is a root folder for the web server utilized by the framework. Aside of self-explaining typical folders (css, img, js) there are some others worth a short discussion:
  • The Views folder stores subdirectories for each business class. The subdirectories contain dedicated html files for processing particular CRUD operations. Please note that the files are referenced by Page routing rules (inside the createRoutesForProduct() method);
  • index.html file is a starting point for a web navigation;
  • layout.html file is a master template file providing a coherent look and feel for the entire site;

Testing CRUD operations

To test the GUI we need to do a couple of things. Let’s begin with putting all required data (the business class, the controller and the routing rules) into an ODRA DB:

• First of all, start a new ODRA instance by executing easystart.bat (see the tutorial #1 about installing and starting ODRA DB).
• Then connect the IDE to this instance by using a project’s context menu.
• Next, compile (by saving them in the connected IDE) all required files: GlobalMod.sbql, ProductControllerMod.sbql, Product.sbql.
• Execute the following methods (by clicking an icon next to each of the names):
  • GlobalMod.createRoutes();
  • ProductControllerMod.createRoutesForProduct();
  • ProductControllerMod.seedProduct();

Now, when the ODRA DB contains all required data, we should focus on the web part. Point the webODRA to the generated web root folder. We can do this by passing a dedicated parameter (webRoot) to the main class. This could be achieved in many ways. One of them is to modify the webODRA - only.bat file. At the very end of the file, after the com.mt.odra.webodra.OdraWebServer add the webRoot parameter referencing the generated directory (in my case it is: webRoot="C:\Users\Mariusz\workspace-test\Sbql Test\WebRes").

Finally start the webODRA by executing the modified file webODRA - only.bat. If everything was fine you should see a cmd window with logging information.

Point your web browser to: http://localhost:8080/

Select the Products link (at the very top of the page) and enjoy the Index view.

Try yourself all generated functionalities by clicking appropriate buttons.

Remember that the generated files are just a starting point and they could be modified. To make the process easier you can install additional plugins for Eclipse, e.g. Eclipse Web Developer Tools.

Remarks

• In case of any troubles try restarting ODRA DB server and/or webODRA;
• Remember that webODRA generates two kinds of log files (located in the logs folder) which store helpful information.