Inserting components

Many of the client-side, non-visual components are added via the Insert menu. Variables are named storage locations. More specifically, the insert variable menu item adds a wm.variable to the project. You can define and use JavaScript variables in JavaScript code as any JavaScript developer would expect. Unlike a JavaScript variable, wm.variable (http://dev.wavemaker.com/wiki/bin/wmjsref_6.5/Variable) is a variable type component class of which you can add instances of to a project. This means they can be used in the visual component tooling of Studio like other project components. JavaScript variables may be easier to manipulate in JavaScript, but wm.variable can often be exclusively managed via the visual tooling. JavaScript variables on the other hand can only be managed via code.

Subclasses of wm.variable include the service variable wm.ServiceVariable and its subclass, the live variable wm.LiveVariable. Service variables merge the ability to make server calls with the data storage capabilities of a variable. The resultant component can collect any inputs for a service call, make the call to the server-side function, and store its results. Live variables are server calls specifically for the read, write, update, and delete calls to WaveMaker database services. Live variables can only be used with database services that implement the LiveDataService interface. For the majority of all practical purposes, these are the services generated by the database import process.

Navigation calls are another commonly used component used for navigating between pages, layers, and dialogs in a project. A number of navigations can be performed without adding a navigation component to the project. As we have tab layers in our project, the showing of those layers are automatically available as tooled events. For example, if we add a button to layer1, its on-click event menu includes the navigation to layer2 and layer3, a common task in layers without visible controls such as tabs. Let's set our button1 on click event to genericDialog1.show().

The other two call components are notification calls and PhoneGap calls. Notification calls are the componentized versions of alert, confirm, prompt, toast, and warn. Like wm.variable, we can use these notification components from the visual tooling instead of creating them in code. PhoneGap calls provide componentized access to some of the PhoneGap API, such as camera, contact database, geolocation, and microphone access. These only work when the application is deployed as a PhoneGap app, discussed in Chapter 14, Mobile Deployment.

The insert menu also includes a number of handy pre-configured client-side components for us to use. The Prebuilt Variables submenu is made up of exactly that, wm.variable that are pre-populated with days of the week, months of the year, the fifty states of the United States, and countries of the world. The data of any of these can be customized after being added to the project using the Edit JSON button of its properties.

Under Graphics, we have the image list component in three flavors. An image list is a component that lets us have a grid of icon images within a single image. Concatenating multiple images into a single file reduces the number of file requests needed to use any number of the images in the grid to a single request. Instead of downloading a new file every time we need an image, we specify the index of the sub-image within the single image file to be displayed. Image list is an un-configured instance. Silk icons use the silk icon files from http://famfamfam.com/lab/icons/silk/ we saw in the Studio installation folder. The Boolean Icons Imagelist, http://prax-08.deviantart.com/art/Boolean-1-1-166457851, is also available to use and defaults to the Signage collection. The Boolean collection includes other collections that you can use simply by changing the URL property of the image list, say for example, you wanted to use electronics instead.

These provided icon lists make it really easy to liven up an application. For example, let's insert the Boolean image list and leave it as the default signage collection. Now take that button we added to show our generic dialog. Select imageList1 from the image list drop-down property in the Properties panel. Finally, use the editImageIndex button to specify an image from the signage collection to display in the button.

This brings us to the Advanced submenu of Insert. Here we have an eclectic array of components. LogoutVariable and LoginVariable are for use with secured applications, which we will discuss in Chapter 12, Securing Applications. A timer is a componentized version of JavaScript setTimeout(), and is used to schedule something after a short delay or on an interval. See the client API reference for the timer for more details at, http://dev.wavemaker.com/wiki/bin/wmjsref_6.5/Timer.

We have discussed TypeDefinition in the previous chapter. You will recall that it is how we define client only types.

Rounding out the advanced insert menu we have Composite Publisher and Template Publisher. We'll discuss these further in Chapter 11, Mastering Client Customization.

The only top level menu items we have yet to discuss are Page, Run, and Help. The Page menu is where we manage project pages. We'll be discussing pages in later chapters. In addition to creating new pages and renaming and deleting existing pages, this menu allows us to specify the home page for the project as well as import pages from other projects. Note that when importing pages, only those components defined on the page are copied. Application-owned components, such as wm.variable we moved earlier, are defined in the application JS file, not the page's widgets file, and thus are not imported. This means that the import page menu item is functionally equivalent to copying a page folder into the current project's pages folder.

The Run menu item isn't a menu item like the others. If you click on it, it will run the project. In this case, run means deploy the project to the same embedded Tomcat server we are running the Studio application in and open a browser window on it. As we learned in the previous chapter, adding ?debug to the URL of any WaveMaker application uses the debug loading path. Instead of loading a limited number of gzip libraries, many smaller, uncompressed files are loaded individually. If we click on the downward arrow to the right of Run, we can choose the buttons action. The other options are Test and Compile. Test simply runs the application in debug mode with debug in the URL. Otherwise, it is, same as the Run menu item. This action is often referred to as "test run", which is reflective of the equivalence of the action. The test run deployed application is reachable to any browser that can reach the Tomcat server. Copying the URL, adding or removing debug, and launching the application in a non-default browser or a browser from another system on our network, is an easy way to begin testing you application in other browsers.

Compile, on the other hand, only compiles our project's services. This can be handy particularly when we are working with Java services that are being updated. If the project's server-side services do not compile, the application cannot be deployed or viewed in the browser.

Last but certainly not least is Help. The Help top level menu item opens a new tab on the product documentation page, http://dev.wavemaker.com/wiki/bin/wmdoc_6.5/. There's nothing special about this link, and you see the same documentation by pointing any browser at the product documentation URL.