Local Installation

This section of the documentation will cover the steps required only for users who wish to use webforJ for web and/or app development with a local BBj instance on their machine. This installation will not allow users to contribute to the webforJ foundation code itself.

info

This walkthrough will cover installation on a Windows system - installation steps may vary for Mac/Linux OS devices.

Installation will be broken down into the following steps:

1. BBj download and installation
2. Using the BBj Plugin Manager to create your app
3. Launching your app

Prerequisites

Before you begin, make sure you have reviewed the necessary prerequisites for setting up and using webforJ. This ensures you have all the required tools and configurations in place before starting your project.

1. BBj download and installation

While following this step, be sure that you install the BBj version that corresponds to the same webforJ version.

This video can help with the installation of BBj if you need assistance with setup. The installation section of the BASIS website can be found at this link

tip

It's recommended to use the latest stable revision build of BBj, and to select "BBj" from the list of options, without Barista or Addon.

2. Install and configure the webforJ plugin

Once BBj has been installed, the Plugin Manager can be accessed to install tools needed to configure webforJ. To start, type "Plugin Manager" into the start menu or Finder.

After the plugin manager has been opened, navigate to the "Available Plugins" tab towards the top.

Once in this section, select the "Show versions under development" checkbox

The DWCJ entry should now be visible in the list of available plugins for download. Click on this entry in the list to select it.

With the DWCJ entry selected, click the "Install" button

Once the plugin has finished installing, click the "Installed Plugins" tab at the top.

This tab displays installed plugins, which should now include the DWCJ entry. Click on the entry within the list.

With the DWCJ entry selected, click the "Configure" button

On the window that opens, click the "Enable Maven Remote Install" button at the bottom left of the window.

tip

Alternatively, navigate to the bin directory within your bbx folder and run the following command:

./bbj -tIO DWCJ/cli.bbj - enable_remote_install

A dialog should display that remote installation has been enabled. Click "OK" to close this dialog.

3. Using the starter project

Once BBj and the required webforJ plugin are installed and configured, you can create a new, scaffolded project from the command line. This project comes with the necessary tools to run your first webforJ program.

To create and scaffold a new bbj-hello-world project, follow these steps:

1. Navigate to the proper directory: Open a terminal and move to the folder where you want to create your new project.
2. Run the archetype:generate command: Use the Maven command below, and customize the groupId, artifactId, and version as needed for your project.

Bash/Zsh

mvn -B archetype:generate \
-DarchetypeGroupId=com.webforj \
-DarchetypeArtifactId=webforj-archetype-bbj-hello-world \
-DarchetypeVersion=LATEST \
-DgroupId=org.example \
-DartifactId=my-app \
-Dversion=1.0-SNAPSHOT \
-DappName=MyApp

PowerShell

mvn -B archetype:generate `
-DarchetypeGroupId="com.webforj" `
-DarchetypeArtifactId="webforj-archetype-bbj-hello-world" `
-DarchetypeVersion="LATEST" `
-DgroupId="org.example" `
-DartifactId="my-app" `
-Dversion="1.0-SNAPSHOT" `
-DappName="MyApp"

Command Prompt

mvn -B archetype:generate ^
-DarchetypeGroupId="com.webforj" ^
-DarchetypeArtifactId="webforj-archetype-bbj-hello-world" ^
-DarchetypeVersion="LATEST" ^
-DgroupId="org.example" ^
-DartifactId="my-app" ^
-Dversion="1.0-SNAPSHOT" ^
-DappName="MyApp"

Argument	Explanation
archetypeGroupId	The group ID of the archetype is com.webforj for webforJ archetypes.
archetypeArtifactId	Specifies the name of the archetype to use.
archetypeVersion	Specifies the version of the archetype to use. This ensures that the generated project is compatible with a specific archetype version. Using LATEST selects the most recent version available.
groupId	Represents the namespace for the generated project. Typically structured like a Java package, such as org.example and is used to uniquely identify your organization or project domain.
artifactId	Specifies the name of the generated project. This will be the name of the resulting artifact and the project folder.
version	Defines the version of the generated project. A common convention is MAJOR.MINOR-SNAPSHOT, like 1.0-SNAPSHOT, where SNAPSHOT denotes that the project is still in development.
appName	An optional parameter that can be used in the generated project's POM file. Depending on the used webforJ archetype, it can be utilized as a default title for the application.

After running the command, Maven will generate the project files necessary to run the project.

4. Launching the app

Once this has been done, run a mvn install in your project directory. This will run the webforJ install plugin, and allow you to access your app. To see the app, you'll want to go to the following URL:

http://localhost:YourHostPort/webapp/YourPublishName

Replace YourHostPort with the Host port you configured with Docker, and YourPublishName is replaced by the text inside the <publishname> tag of the POM. If done correctly, you should see your app render.