WaveMaker Studio is an open source project that enables web application development by non-professional developers. WaveMaker is not a programming language; instead, it is a tool that makes it easy to build web applications in leading languages. As you visually assemble components in your browser, WaveMaker constructs an industrial strength application using leading open source libraries, such as the Spring Framework and the Dojo Toolkit. The result is a standards-based web application that can be built by a beginner and maintained by an expert.
We'll prepare for our journey by setting up our workspace. First, we will need to get ourselves a copy of WaveMaker Studio and the required examples. This book includes eight example applications. Viewing the sample projects in the Studio, as a developer, is a great way to better understand how these applications were built. With the example source code in hand, we will take one of the example applications out for a spin. This will provide us with a tangible understanding of our destination and a look at what we are able to create using WaveMaker. We'll end our introduction with a quick look under the covers of the sample. By examining the sample from a developer's point of view, we'll get our first feel for how things work under the pretty user interface.
In this chapter, we will:
Set you up with your own WaveMaker Studio
Configure your workspace to run the examples
Tour a simple sample WaveMaker project
Peek under the covers of the sample application
In order to build and deploy applications of your own, you'll need WaveMaker Studio. Even if you are not ready to build your own application and just want to examine the sample applications from a developers point of view, you'll want to view the project from within the Studio. So, we shall begin with setting up WaveMaker Studio.
This book is about WaveMaker Version 6.5. WaveMaker is an active open source project with on-going development. The first 6.5 Version of WaveMaker, 6.5.0, was released in October 2012. Patch releases, such as 6.5.1, have followed. In time, newer versions such as 6.6.0 will also be released. For best compatibility with this book and its sample projects, you will want to use the latest release version of 6.5 available, currently 6.5.3. Newer versions of the Studio will generally open and run the sample projects, but the constant evolution of the project will result in changes that may render some things discussed in this book obsolete or incorrect. Instructions provided in this book are for Version 6.5 and may not exactly match how things are done with newer versions.
Now that we know what version we will be using, we will review our browser and installation options. There are two common ways to run the Studio: installing a release package or, for advanced users, building from source. First, let's ensure we're using a good browser.
The reality is that not all browsers are created equal. Things such as rendering speed, developer support, and support of HTML5 features can vary widely among browsers. While there are many browsers out there, more than many people even realize, we shall concern ourselves only with the most common ones. Of those, we can generally categorize them into three families based on their underlying layout engines. Here, the "big three" for both desktops and mobile are—Gecko: used by the Mozilla Foundation for Firefox, WebKit or Webkit forks: used by Apple's Safari and Google's Chrome and Trident: used by Microsoft's Internet Explorer.
WaveMaker applications make heavy use of JavaScript in the browser. Therefore, the faster a browser can parse and run JavaScript, the faster a WaveMaker application will generally run in that browser. Deployed WaveMaker applications will run in the most common browsers. For older versions of Internet Explorer that lack HTML5 support and have rather slow JavaScript engines, we can use plugins such as Google Chrome Frame. Chrome Frame enables our JavaScript application to run in the Chrome V8 engine even when the application is loaded from an older version of Internet Explorer. You can learn more about Chrome Frame at https://developers.google.com/chrome/chrome-frame.
We may not get to dictate what browser our users use to run our application, but we do get to choose what browser we primarily develop in. Here too, some browsers are better than others. As such, Chrome and Safari are the preferred development browsers by most WaveMaker developers today. In this book, we'll be using Google Chrome, as it is fast, has excellent developer support, and is available on all major platforms. You are welcome to use other browsers; however, we will only using Chrome in this book.
WaveMaker applications work in the most popular modern browsers. However, those browsers may interpret your Cascading Style Sheets (CSS), JavaScript, or resultant HTML differently, and you'll want to test your application in the browsers your users will be using before you declare victory. This testing may require using another system or a virtual machine (VM). Someone developing on OS X, for example, might use a VM running Windows in order to test with Internet Explorer. WaveMaker handles most of all the cross-browser issues for you, and your application may "just work" in other browsers. However, you'll still want to test it.
Tip
If something isn't working right, clear the browser cache to ensure the correct file loading. We'll discuss why in Chapter 15, Debugging.
As a general rule, the more customization you do, the more cross-browser testing you'll want to do. I suggest you first get your application working in a developer-friendly browser to flush out the general issues. Then, cross-test in other supported browsers to get the browse-specific issues before declaring the application as done.
Installing a release package is the easy way to install the Studio. WaveMaker 6.5 is distributed as an installation EXE for Windows, a DMG disk image for Mac OS X, and as RPM and DEB packages for Linux. You will need administrator or root access to install WaveMaker. You will also need the Java command available to run the embedded Tomcat. WaveMaker 6.5.3 ships its own compiler, the same one used by eclipse for JDK 6 compilation, but you still need a JRE to run the embedded Tomcat.
You can install the Studio on your local machine or on a remote host on the network. If you install on a remote host, you only need to point your browser at the remote host instead of the local host.
The installation packages for the latest stable release can be downloaded from the WaveMaker site, http://www.wavemaker.com/downloads/. For installation packages of older releases, such as downloading Version 6.5.x when it is no longer the latest version, visit http://dev.wavemaker.com/wiki/bin/wmdoc/Releases.
The release packages are available for Windows, OS X, and Linux. For more information about installing WaveMaker on your platform of choice including overcoming installation issues, see the install guide in the documentation located at http://dev.wavemaker.com/wiki/bin/wmdoc_6.5/WMInstallGuide.
The first thing you need to do after installing a release package is install the dependency bundle. These are files that are required to run the Studio, but cannot be distributed with WaveMaker Studio. WaveMaker is distributed under the Apache 2.0 license. A few libraries used by the Studio, such as the Ace editor, are licensed under the General Public License (GPL). The Apache license is not compatible with most GPLs. Therefore, you must download the GPL libraries separately. To make this as simple as possible, the Studio configuration tool will help you download a pre-packaged bundle of libraries with the correct versions needed. A few other libraries used by WaveMaker, such as the JAR file wsdl4j used for web services, have incompatible licenses. You will be prompted to download and install these libraries if you perform an action that requires an additional library.
Tip
If you experience difficulties running the Studio, the debugging process is described in Chapter 15, Debugging. Studio is a WaveMaker application, and the processes are quite similar as a result.
Building your own Studio from sources takes the most effort to set up, but provides the most flexibility and control over the development environment. It is also the first step should you wish to get involved in open source software and contribute to the development of WaveMaker. This configuration is recommended for advanced users. If you are not comfortable building source code using Maven, use the installed version described previously instead.
To build your own Studio, you will need the following:
A Java 6 JDK
The following are optional, but highly recommended:
Tomcat 6, for running your Studio
A git client, to keep your version up to date
To clone the repository, use the following git clone command:
git clone https://github.com/SpringSource/wavemaker.git
You will want to use the 6.5.X branch:
https://github.com/SpringSource/wavemaker/tree/6.5.X.
git checkout 6.5.X
The preceding git checkout command is used to switch your local copy to the 6.5.X branch. The 6.5.X branch is stable and contains any updates made to 6.5 since the 6.5.3 release. Tags for specific releases, such as 6.5.2, also exist should you want the source for a specific release version.
The master branch, on the other hand, is a work in progress for the next version, and may not be completely stable at any given moment. You generally will not want to use the master branch unless you know what you are doing and are comfortable dealing with the possible consequences. With that said, the master branch is an easy way to see the newest features and fixes in the WaveMaker project.
If you don't have or don't want to use a git client, you can download the source code as a .zip or .tar.gz file directly from GitHub. Using the git client has the advantage of being able to pull updates without having to download the whole source tree, and easily you can switch branches. Downloading as a bundle is an easy way to access the source code. If you just want to browse the source code without downloading it all, you can do so via the GitHub site, https://github.com/SpringSource/wavemaker.
The project README explains how to clone, build, and deploy WaveMaker. It is available at https://github.com/SpringSource/wavemaker/blob/master/README.md.
Tip
The inplace deployment to your own Tomcat lets you use your Tomcat installation. Using the inplace target option with a git clone workspace is the easiest way to update Studio without building an installation package. To use this feature, you will need the manager app enabled with accounts that match those in /wavemaker-tools/src/main/resources/com/wavemaker/tools/project/app-deploy.xml.
Now that you've got a Studio in your browser, let's get the examples set up so you can view them in the Studio. The examples are stored on the code sharing site GitHub. If you aren't familiar with GitHub or otherwise don't have a git client, don't worry. GitHub lets you download and unpack the repository as a .zip file from their site by visiting the following URL:
https://github.com/edwardcallahan/Easy-Web-Samples/archive/master.zip.
If you do have a git client installed, the easiest way to get the examples is to clone the example repository using git clone, as shown in the following command:
git clone https://github.com/edwardcallahan/Easy-Web-Samples.git
However, when you get the example projects, they will need to be copied to a folder on the host running the WaveMaker Studio Tomcat server. Either copy the projects into your Studio's project folder or update the project folder. To do that, go to the WaveMaker File menu and select the Preferences… menu item to set your WaveMaker Folder to the Easy-Web-Samples directory.
You should now see the sample projects listed in the open project dialog. Each project in the bundle also contains a project export in its export folder. Use the Studio file menu to import each project export individually.
Some of the sample projects use a MySQL database and others use an embedded HSQLDB database. HSQLDB examples require no configuration. If a project uses a MySQL database, a database export is included with the project in the src directory. The free community edition is fine as no enterprise version features are used. You'll need to be able to access a MySQL server to import these exports. Setting up MySQL is not required to run those examples, but the examples are more fun with data.
If you want to use the database, you'll need to import the database export file named custpurchase.sql in the project src folder. One way to import the database export is to connect to your MySQL server using the mysql command line client. As the export creates the database for us, we only need to source the file. The easiest way to do this is to start the mysql client from the directory containing the export file. Then, from within the mysql client, use mysql> source custpuchase.sql to load the database schema and data from the file.
We'll cover working with databases in Chapter 7, Working with Databases, but examples are better with data, so let's configure our Java Database Connectivity (JDBC) connection to the database using the following steps:
Open the Services tab with the project open in the Studio.
Select the custpurchaseDB service from the service tree.
Open the database connections dialog by clicking on the wrench button.
In the database connection settings dialog, update the Username, Password, and Host fields to use the same connection you used to create the database in MySQL. Should your MySQL server not be running on port 3306, enter the correct port number as well. No other fields require review for this. The connection URL will be updated based on your other entries. Click on the Test Connection button to verify your settings. Once the connection tests successfully, save the properties by clicking on the Save button.
Simple CRM is precisely what its name implies; a simple customer relationship management (CRM) example application. We have exactly what you'd expect in a basic sample of a CRM application; customers, orders, and ordered items. It is a database-driven application, where the schema consists of five tables and includes one-to-many and many-to-many relationships.
Open the project named CRM_Simple in the Studio and run the app. The Run button in the top menu bar deploys the application and opens a new browser window.
If there are no problems and the database connection is good, the new application is loaded in the new window with the customer list populated. The WaveMaker launcher process sends the Studio URL to the default browser on the system. You can specify a specific browser in the preferences accessed by the Advanced Options button when the Studio has been stopped.
Or, if you prefer, simply copy the URL of the application from the launched windows into the desired browser; in this case, we'll be using Google Chrome.
The first thing we are likely to notice is the size of the layout. The layout of this particular application targets a tablet. If you are using the application from a touch input device, the lists are scrolled with a flick of the finger, as we would expect. If, on the other hand, you load the application in a desktop browser, scroll bars appear where needed, and you can use your mouse to scroll through the list.
At the top of the customer area is a search box. There's some placeholder text informing us that we can search using any part of a company name. Typing city, for example, immediately returns us both "City Light Books" and "Fog City books." It does this even though only City Light Books begins with the word city, and both entries capitalize "city." The X icon at the right end of the search editor clears out our search and resets our results with a single action.
As we select different customers from the list of companies, the details near the top of the screen, including the companies' contact picture, refreshes to the selected customer. The companies Twitter ID is presented as a link, should we wish to send the customer a quick message via Twitter. At the same time, the list of orders to the right is updated. As we make our selections, the lists highlight the currently selected items, lest we forget which customer or order we have chosen. Likewise, when we select an order presented by order date, we are presented with the line items of the chosen order.
Now let's begin to enter a new customer by clicking on the New Customer button. We are presented with a straightforward form. The company name, address, city, state, and zip code fields are required, as suggested by the red asterisk next to the labels. As we would expect from a modern application, validation helps the user complete the form successfully by ensuring the user has entered acceptable data, such as ensuring a phone number has the correct number of digits. When you enter values for all the required fields, the Save button becomes enabled. Click on or otherwise point at an element and that element is given the focus of the application. It becomes the active element that receives input. Moving focus away from that element triggers the blur event for the node. If we trigger the blur event for any required editor in the form without entering a value, validation displays both a warning icon and a friendly pop-up message.
Clicking on the Inventory button navigates us to the list of items in our fictitious book supplier inventory. Again, highlighting provides feedback on the selection we have made. Here we have another form which we can update an existing item, create a new item, or delete an existing entry. When taking a new order, the date editor opens a calendar date picker, just as we'd expect. The Companies button quickly navigates us back to our customer view, ready to look up another.
Not a bad little application, eh? We've seen styled widgets, such as the search editor, combined with rich editor validation and in-form assistance assembled to present intuitive database forms and navigations. Would you call it "pixel perfect" or so compelling that you expect it to race to the top of app store downloads? No, probably not. Is it usable and functional? It certainly is. Does it solve a problem or deliver a business solution, however fictitious the business may be? Yes, yes it does.
Now consider that almost no code was used to create this application. Oh sure, there's plenty of Java and JavaScript being executed, but the vast majority of the effort in building a simple application such as this is done visually. The developer need only select values, tick on and off desired behaviors, and connect events with responses. Many WaveMaker users use some JavaScript code to get the exact behaviors they want in the browser. Java can also be used for custom server-side services. This application does use a data expression analogous to a formula in a spreadsheet cell to sum order totals. However, such expressions are no more complicated than macros in a Microsoft Office document.
In this one example, we get a hint of the professional grade aspects of our application. Because the data access layer is built using popular open source frameworks, the level of customization shown does not require us to code those features ourselves.
Let's continue exploring the application in the Studio. Don't worry if you don't yet understand everything you are about to see. We will explain all of this in detail in future chapters. For now, we just want to explore the application and have a bit of fun.
Studio provides us with a visually-oriented way to view the application's construction. Selecting the Canvas tab brings us to the visual layout of the application. In the canvas area and the model tree, we can see all the visual components or widgets that are on this page of the application. Selecting a component, such as an editor or service variable, either by clicking on it in the canvas area or from the model tree, shows its properties in the property editors on the right. For example, select the title label at the top named labelTitle. It's the label that says CRM Simple with a blue background. Once selected, on the right you'll see a caption property with the value CRM Simple. If you change the value of the caption property, the title shown in the label will also change as soon as you blur the property editor. We'll discuss using the Studio in detail in Chapter 3, Using Studio.
Let's interact with the application at a different level. Open the developer tools built into Chrome. The developer tools can be accessed by clicking on the Chrome menu in the upper-right corner, choose tools, then developer tools. Alternatively, you can use the keyboard shortcut to open the developer tools. On Windows and Linux, use Ctrl + Shift + J. On OS X, press command + option + J. We can do many interesting things here in the developer tools. We'll be using the developer tools as our JavaScript debugger in Chapter 15, Debugging.
Ensure you have the console open. You should see an arrow > symbol, next to which you can enter commands. If you know the JavaScript console, you know how we can execute JavaScript here. We could enter the classic alert("Hello Wavy World") for example to raise an alert dialog. This means from here we can also access the components and the HTML elements, or DOM nodes, of the application. In the case of a WaveMaker application, entering app at the console prompt will return the application object. Entering app.theme will return the string name of the theme used by this application, wm_coolblue in the case of CRM Simple. We'll discuss theming in Chapter 6, Styling the Application, as part of CSS and styling.
In Studio, we saw how easy it was to change the caption of the title label. We can also change the title from the console. Enter main.labelTitle.setCaption("Hello Web"); the title of the app is now Hello Web. We'll be working with applications in this context on and off while working with WaveMaker. In Chapter 10, Customizing the User Interface with JavaScript and Chapter 11, Mastering Client Customization, we'll focus on using JavaScript to customize our application.
Finally, let's take a look at our application from the file system. Open the CRM_Simple project folder in a file system tool such as Finder or Explorer. If you are using the Studio on a remote server, use Source, Resources, and select Project from Folder Shortcuts to view the remote file system. Within the services folder, we see our custpurchaseDB service, in which we will find all the generated source code for our project including the Hibernate mapping for our database schema. We'll discuss how this service came to be in Chapter 7, Working with Databases.
Under webapproot, we see the top level of our deployed application, including index.html. Under the pages folder, we see a folder for each page in our project. Being a Java application, we have a WEB-INF folder, which contains our web.xml as well as our classes and lib folders. Don't worry if this doesn't make sense yet, we'll learn about this soon enough.
There is a lot we can learn by looking at the project on the file system. Touring the file system is always on the day one agenda when training teams on WaveMaker. We'll continue our tour of the project from the file system as we dig into the application architecture in the next chapter.
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com . If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
The example code for this book is also available on GitHub at https://github.com/edwardcallahan/Easy-Web-Samples. The example code has been published under Apache 2.0 license.
We have examined a simple CRM sample application built using WaveMaker. While the scope of the application may have been limited, it still provided us with a robust user interface. We have secured access to a copy of WaveMaker Studio and the example application. We have chosen Google Chrome as our development browser and even started looking at how the sample application is put together.
In the next chapter, we'll continue into the application architecture. We'll look at the JavaScript client and how it is put together, including its use of the Dojo Toolkit. We shall also look at the Java server side of the application and how it works. No understanding of a web application would be complete without looking at the asynchronous transfer of data between browser and server. We'll also look at how types work in WaveMaker.
