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 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 additional time to complete (depending on your network connectivity) as 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.

• 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.

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 directory <zero_home>/installed/appbuilder

Install App Builder from another source

1. Destroy the experimental modulegroup by running the following:
   zero modulegroup destroy 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. Create the experimental modulegroup with the remote repository URI to your desired source for App Builder. For example:
   zero modulegroup create experimental https://www.projectzero.org/zero/sebring/M0/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 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. 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. You must restart App Builder to pick-up the change.

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


# 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 secret key
/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.