App Builder

About App Builder

App Builder is a WebSphere sMash application. As you become familiar with it, you'll see an AJAX client (implemented in Dojo) interacting with RESTful resource handlers running in a backend application. There's a core set of functionality (zero.appbuilder.core (client) and zero.appbuilder.core.resources (backend)) with extensions packaged as WebSphere sMash modules and registered via configuration (e.g. zero.appbuilder.pageeditor). Finally, App Builder is acquired, started, and updated like any other WebSphere sMash application, although you might not see the details since we provide shell scripts that recast the application as a tool.

Contents

This article contains the following sections:

Pre-requisites

• WebSphere sMash DE or the latest command-line interface (CLI).
• Firefox version 2 or 3

Running App Builder

The installed CLI contains the appbuilder shell script, which is used to start and stop App Builder:

appbuilder open

Starts App Builder and launches Firefox to http://localhost:8070/. This is the easiest way to get started.

appbuilder start

Performs a subset of the appbuilder open command: Starts the App Builder application without launching a browser. This is useful when running App Builder remotely or when trying a browser other than Firefox. (Although Firefox is the supported browser, we are working to also support other mainstream browsers. See the list of known browser-specific problems for details.)

appbuilder stop

Stop the App Builder application. Browsers are not closed.

Note that the first invocation might take about 30 seconds to complete (depending on your network connectivity) because the App Builder dependencies are downloaded and your linked copy of App Builder is created. Subsequent invocations complete within seconds since they operate on the linked copy.

For users of older versions of WebSphere sMash DE (CLI 1.0.0.1 and older): The appbuilder script first appeared in sMash DE on CLI 1.0.0.2. (Invoke zero version from the installed CLI directory to determine your CLI version.) For older versions of sMash DE, use the older scripts:

• Invoke startAppBuilder in place of appbuilder open
• Invoke stopAppBuilder in place of appbuilder stop

Updates

You can update your installed version of App Builder by invoking the custom update command from the appbuilder script:

• appbuilder update

App Builder is now updated to the latest version. You can restart App Builder by executing appbuilder start.

For users of older versions of WebSphere sMash DE (CLI 1.0.0.1 and older): The appbuilder script first appeared in sMash DE on CLI 1.0.0.2. (Invoke zero version from the installed CLI directory to determine your CLI version.) For older versions of sMash DE, update the installed App Builder with the following steps:

1. Stop App Builder (execute stopAppBuilder)
2. Change directory to App Builder's home directory (<zero_home>/appbuilder, where <zero_home> is the directory where the sMash DE CLI was installed)
3. Execute zero modulegroup update
4. Execute zero update

App Builder is now updated to the latest version. You can restart App Builder by executing startAppBuilder.

Installing a fixed level of App Builder with sMash DE

For sMash DE users, App Builder is installed, by default, from the latest code. This ensures that you're getting the latest tooling capabilities, but also introduces some variability since the latest code is the result of our continuous build process.

If you need a more stable source for the App Builder (e.g. you want to use the most recent milestone instead of latest), then you'll need to re-define your experimental modulegroup before installing App Builder. If you've previously installed App Builder, then you'll need to re-install it; all of your current App Builder settings will be lost.

Remove App Builder (if needed)

1. Stop App Builder (execute appbuilder stop)
2. Delete the <zero_home>/installed/appbuilder directory

Install App Builder from another source

1. Destroy the experimental modulegroup (execute zero modulegroup destory experimental)
• If the modulegroup doesn't exist, then you'll see the following error message: "CWPZT0828E: Modulegroup, experimental, does not exist." This is expected; continue to the next step.
2. Set the default experimental modulegroup URI to your desired source for the App Builder. For example, to install App Builder from the Silverstone milestone M1 driver, change the value in <zero_home>/config/bootstrap.properties as follows:
   experimental=https://www.projectzero.org/zero/silverstone/M1/repo/
3. Install App Builder by running it (the first invocation will install App Builder automatically; execute either appbuilder open or appbuilder start)

Configuration

The default configuration is sufficient to use App Builder in a common environment. However, there are a few changes you might need to make for your specific environment. This section describes what changes are available and how to make them.

HTTP port

By default, App Builder runs on port 8070. You can change this by editing <zero_home>/installed/appbuilder/config/zero.config (For users of older versions of WebSphere sMash DE (CLI 1.0.0.1 and older): edit <zero_home>/appbuilder/config/zero.config). For example, the following line would configure App Builder for port 8060:

You must stop App Builder before you change the port. So, the steps would be:

1. Stop App Builder (execute appbuilder stop).
2. Edit App Builder's zero.config file, as needed.
3. Start App Builder (execute appbuilder start).

Hidden-file filter

App Builder is configured to show only "interesting" files in the File Editor tab. The other files ("hidden") are filtered out by a configurable setting, which consists of a list of regular-expression patterns. The default setting is:

/config/ide/hiddenFiles = [
   "/classes/.*",
   "/export/.*",
   "/logs/.*",
   "/reports/.*",
   "/db/resource/.*",
   ".*\\.ctrl",
   ".*\\.dat",
   ".*\\.lck",
   ".*\\.log",
   ".*\\.gif",
   ".*/\\..*"]

You can override the default by specifying your own list of patterns in <zero_home>/installed/appbuilder/config/zero.config (For users of older versions of WebSphere sMash DE (CLI 1.0.0.1 and older): use <zero_home>/appbuilder/config/zero.config). You must restart App Builder to pick-up the changes.

Troubleshooting

Your instance of the App Builder application is installed at <zero_home>/installed/appbuilder. App Builder logs are available in the logs directory.

Problems running App Builder in Firefox

Firefox plug-ins can interfere with one another and with AJAX applications. If you're experiencing problems with App Builder in Firefox, then disable your plug-ins and try again. If App Builder still fails, then please open a bug report.

Current limitations

• Single user
• localhost (can be configured for remote operation, if desired)

Remote operation

App Builder is configured for localhost operations, which means localhost users don't need user ids and passwords and there is no security risk from remote users.

You can enable remote operation by disabling the localhost setting and configuring security rules. (The security rules are optional, but recommended. Without security rules, there would be no protection against anonymous users using the full functionality of App Builder, which includes writing and running code on your server.)

Following is a sample configuration snippet to enable remote operations with Basic authentication. This snippet, or similar, must be added to <zero_home>/installed/appbuilder/config/zero.config (For users of older versions of WebSphere sMash DE (CLI 1.0.0.1 and older): use <zero_home>/appbuilder/config/zero.config). You must restart App Builder to pick-up the change.

# Disable localhost restriction
/config/http/ipAddress="*"


# For users of older versions of sMash DE (CLI 1.0.0.1 and older):
# Uncomment the following line by removing the '#':
#/config/appbuilder/requireLocalhost=false

# Protect access to App Builder; here, using Basic authentication.
#
# "yourname" must be a valid username for your application, e.g. set
# with the "zero user" command.

## run zero secretKey CLI command to generate secretKey
/config/security/secretKey=<**************>

## enable security for the application
@include "security/enableSecurity.config"

## authentication type is BasicAuth
@include "security/basicAuthentication.config"

## specify authorized user
@include security/authorization.config{
   "users" : ["yourname"]
}

For other security options, see Security considerations in the Developer's Guide.