Projects

Contents Hide

 

A BrightBuilder project is a file that contains the definition of an application. It has a BSP file extension, which stands for Bright Software Project. A project comprises of forms, tables, queries, reports, sync rules and the global elements. It also includes the images and other files used in the application.

This section will discuss in detail what can be done with projects.

Creating a New Project

To start using BrightBuilder, a project must first be created.

To create a new project,

  1. Either:

    • Click on the New icon in the BrightBuilder toolbar or Projects panel, or

    • Select File>New Project... from the Main Menu, or

    • Right Click the "Mobile & Web Applications" node in the projects panel and select "New Project ..."

    The New Project-Select Project Type dialog will display as shown below.

  1. Select the type of project that will be created and click the Next button.

  2. From this screen, a new blank project may be created with the Blank Project option selected, or alternatively, a quick template based on BrightXpress Tutorials may be selected as a starting point.

  3. Tapping 'Next' will open the project aspects screen, where the default aspect of the project may be selected. Tapping 'Finish' with either option selected will open a dialog to save the new project.

  4. From the second New Project Dialog, select the directory where the project will be saved to.

  5. Enter the project name in the "File Name" field as show below, then tap the 'Create' button to save the project and open it in BrightBuilder.

    It is important to remember that once you have named your project from the New Project dialog, BrightBuilder will not allow you to rename the project anymore.

    A valid project name must start with a letter, and continue with letters, numbers and the underscore characters and must contain no spaces. Maximum size of the project name is 64 characters.

    If the name entered is invalid, BrightBuilder will display an error message, as shown below:

  6. Click the Create button, the new project will be listed under the Projects Window.

Once you have created your project, you can now create the project elements such as forms and reports.

Note that BrightBuilder does not allow you to delete or rename a project. You can only close a project. However, you will be able to rename the project via the windows explorer.

Opening an Existing Project

To open and make a project accessible in BrightBuilder,

  1. Either:

    • Click on the Open icon in the BrightBuilder toolbar or Projects panel, or

    • Select File>Open Project... from the Main Menu, or

    • Right Click the "Mobile & Web Applications" node in the projects panel and select "Open Project ..."

    2. The Open Project dialog will display as shown below.

  2. Select the directory where the project is located. BrightBuilder project files will be displayed with the green butterfly logo.

  3. Select the project and click the Open button. The opened project will be listed in the Projects Window.

If there are two projects with the same name, then the file path will also be display together with the project name in the Projects Window.

Changing Project Properties

Let us discuss first what properties BrightBuilder projects have.

Project Properties

To display a project's properties, do any of the following:

  • With the Properties Window active, view the project properties by selecting the project name. If this panel is not present, it may be displayed by selecting Windows > Properties in the menu bar.

  • Otherwise, right-click the project name and select Properties from the pop-up menu, this will display a new Properties dialog.

Project properties (sorted by property name) include:

Property Name

Description

About Form Name

The form to be displayed when the BrightForms user selects the Help > About menu. This allows you to brand your mobile applications with your own logo and about/contact details.

All Files

A read-only property that specifies where the project file is saved.

App Settings

End user application specific settings.

Each end user can have a unique Id, for example, each sales agent has a specific sales area, using the App Settings properties, the end user does not have to enter their Id or sales area code for every transaction made by the user.

This has project scope, such that it is available in any of the project elements. The main difference with the Global Variables is that App Settings are persisted in a local file and is much slower as the application settings file is always updated every time the App Setting is assigned a value. Whereas Global Variables are persisted in the memory.

Aspects

This opens the Aspects Dialog which list all the aspect templates that can be used within the project.

A default Pocket PC Portrait and Landscape aspects are available on the form layout.

Author

The person or organization who created the project.

Default Font

Specifies the font and point size for text used in forms and form controls, will be used throughout the program. This should be set on project creation before any form controls has been added to the form layout.

Default Form Size

Specifies the form size that will be the default for all new forms. Initially, this value is blank, and populated with the value assigned for the first form created in the project.

Description

A text that describes the project.

Enable Background Synchroniser

Set to true if data synchronisation messages are to be sent in the background. See Chapter 8: Sync Rules for further details on synchronisation and BrightForms Chapter 3: Background Synchronisation for more information on background synchronisation.

Enable Push Listener

Set to true to enable BrightForms to listen to unsolicited push messages.

File Size

A read-only property that shows the project file size.

Main Form Name

Sets the initial form that will be opened upon execution of the project.

Modification Time

Displays the modification date and time of the project.

Name

Name of the project.

Settings - Password

Optionally provide the password with which to access BrightForms system settings. If not specified, BrightForms will use the default BrightForms password generated daily by BrightBuilder from the Tools>Today's BrightForms Settings Password menu.

Settings - Password Protected

Set to true if BrightForms Setting menu needs to be password protected.

Use Latest Look-and-Feel

Turn this on to enable BrightForms to use the most up-to-date Look-and-Feel..

Version

The version number of the project.

Web Main Form Name

In web mode, identifies the starting form for the application. (If this is not specified, then the 'Main Form Name' property will be used).

Web Menu Background Colour

In web mode, background colour of the menu.

Web Menu Font

In web mode, font of the menu.

Web Menu Has Image

In web mode, whether the top of the menu should display an image. Only applies to left positioned menus.

Web Menu Image File

In web mode, image to display on the top of the menu. Only applies to left positioned menus. This image is displayed only if Web Menu Has Image property is selected.

Web Menu Position

In web mode, where to position the menu, top or left of the form

Web Menu Text Colour

In web mode, text colour of the menu.

Web Menu Item Width

In web mode, the width (in pixels) of the menu. In Left positioned menus, defines the menu width. In Top positioned menus, defines the item width.

Web Menu Item Height

In web mode, the height (in pixels) of the menu item. This applies to items of the menus located on top or left.

Changing Project Properties

To change the properties or attributes of a project,

  1. Select the project, the properties will be listed in the Project Properties window

  2. Select project property by clicking on the right hand side of the property name.

  3. Type an entry or select from the options.

Adding an App Setting

  1. Select the project, and view the project's properties in the Properties panel.

  2. Locate the 'App Settings' property, and tap on its customiser button . The  App Settings dialog will appear to edit the project's settings.

  3. Right-click on the App Settings grid and select Add New Setting from the popup menu. A new setting row will appear with Setting1 as default Name, string as default Data Type with blank Description and Value.

  4. Change the App Setting attributes i.e. Name as desired.

The following image is a sample App Settings dialog box with three settings already added.

Once defined, app settings may be used freely within expressions and throughout the project. For more information, please refer to the Using App Settings tutorial.

Selecting a Main Form

To be able to execute a project, BrightForms must know which form to initially open; this is the purpose of the Main Form Name property of the project.

To select the main form to execute,

  1. Select the project name to list the project properties.

  2. Click the Main Form Name property to enable the drop-down arrow.

  3. Click on the drop-down arrow and select the main form from the list.

If this property was left blank, BrightBuilder will issue a validation error, and the project may not be deployed.

Saving a Project

Projects can be saved by clicking on the Save and Save All icons in the toolbar or using Save and Save All options from the File Menu..

Save is usually used when changes made to a specific project needs to be saved. To do this, select the project name and click on the Save button. Any changes made to other projects in the local directory will not be saved.

Save All is used when you want to save all changes made to all projects in the local directory.

Saving without confirmation is always performed before executing a project.

Closing BrightBuilder with project modifications unsaved will open the Save dialog box before closing as shown below. This ensures that changes made to projects will be saved before BrightBuilder is closed.

BrightBuilder will create three files in the local directory, with the following file extensions:

  1. .bsp - XML application definition file.

  2. .bsp~ - backup file, created and updated when the project is saved.

  3. .bak~ - backup file, created and updated when the project is initially loaded in BrightBuilder. This file is a recovery file when project save was corrupted.

Closing a Project

Closing a project will remove the project name from the Projects Window and will not be accessible for modifications. This will also close any project elements that are open in the Editor Window.

To close a project, right-click on project name and select Close Project from the pop-up menu.

The image above shows the Close Project option selected. Any projects left open when BrightBuilder closes will be re-opened when BrightBuilder restarts.

Creating Project Elements

Each project element subtree has a pop-up menu that allows you to create new elements such as forms, tables, queries and sync rules. BrightBuilder will create the project element and open this project element in the Editor window to be modified as required by the mobile application.

Each project element will be discussed in more detail in subsequent chapters of this documentation.

When project elements are opened in the Editor Window and there exists two or more elements with the same name, the project name will also be displayed on the Editor Window tab to define which projects the elements belong to.

Grouping Project Elements

BrightBuilder allows users to manage project elements into developer defined groups, which may be used to easier view and navigate through applications, especially when large numbers of forms, queries and other element types are used. These are known as 'Groups' in BrightBuilder.

To create a new group, right click the project element and selecting 'New Group'. This will create a new empty group within the element set.

Once a group is created, new project elements may also be created within the group in the project, using the right click context menu.

Existing project elements may also be copied and pasted into groups through context menus, as demonstrated below.

Closing Project Elements

When project elements, like forms and queries are opened Editor view, they can be closed to keep the Editor window uncluttered. Do any of the following:

  • To close all project elements in the Editor, click on the Close button (icon) on the Editors upper right hand corner.

  • Multiple elements may be closed by right clicking on the tab heading, and selecting "Close All" or "Close Other" from the options.

Validation and Execution of Projects

Validation

BrightBuilder has a built-in validation function that checks the project for any inconsistencies or errors in the content of the application definition file, for examples:

  • Invalid data sources used within an expression

  • Renamed project elements

  • Incomplete statements

  • Incomplete project element definitions such as a missing query for a sync rule

  • Incomplete form control definition such as missing query for a listview or default value for radio button controls

Validation ensures that the project is error free before execution or deployment. It also acts as a guide for the valid content of a project as it warns users with issues like table primary keys and using reserved words.

You can validate a project at any time by using the following methods:

  • Select the project and click the Validate icon , or

  • Right-click the project name and select Validate from the pop-up menu, or

  • Select the project name and press F5 key.

The Output-Validation Window will appear each time a project is validated.

A project is also validated each time it is executed, this step is configurable within the BrightBuilder's Tools>Options menu. Read more on BrightBuilder's Option Menu in Appendix G.

 

Execution

Projects can be run directly on the desktop or on the remote device.

The remote device must have an active sync connection to the device so BrightBuilder can download the application to the device.

You can execute a project at any time by using the following methods:

  • Select the project and click the Execute icon or Execute on Windows Mobile Device , or Execute on Android Device .
     

  • Right-click the project name and select Execute or Execute on Remote Device from the pop-up menu, or

  • Select the project name and press F6 key to execute on desktop or F7 key to execute on remote device.

Read the chapter dedicated to Project Validation and Execution for more details.

View Table Definitions Document

This is an option in BrightBuilder projects that allows you to have auto documentation of your table definitions. When selected, BrightBuilder creates an HTML file on the export directory and opens it on the default web browser to display all the tables - its attributes, properties, description and notes; in the project.

To view table definitions, right-click on the project name and select View Table Definitions Document from the pop-up menu.

Show Differences Between Projects

BrightBuilders offers developers the tool to compare BSP projects with one another, and highlights any differences made between any two given projects, across all project elements, right down to expression level changes. This may be achieved via the "Show Differences Between Projects ..." option in the context menu for opened projects, which returns a result set of the differences between the given project and a selected project.

For more information, please refer to the BrightBuilder > Show Differences chapter of this document.

Exporting and Importing Project Elements

Export and import of project elements allows you to reuse the definitions of forms, tables, queries, sync-rules and app-settings.

The following are the commands used to export and import project elements which is accessible from the project's right-click pop-up menu :

  • Export Project Elements... This command saves project elements into .BSE files in the selected "Export to Directory" field. The .BSE file is the definition files for each form, table, query, sync rule or app-settings exported. This file will then be recognised by the Import Project Elements option.

  • Import Project Elements... This option allows BrightBuilder to import the .BSE files and include these elements in the current project. For example, you can have a Login form template that you can reuse across all your mobile applications.

  • Export... This command allows you to specify the folder where the BrightForms executable files will be saved and executed. This directory contains all BrightForms files including the application settings file and the database files when a bsp project is run through BrightBuilder.

Import Database Tables

The Import Database Tables... feature may be selected from the project's context menu and is used to import database tables from existing databases such as MS SQL Server, MySQL, DB2, Oracle and even a JDBC/ODBC connections.

Upon selecting the Import Database Tables option, a dialog will appear. Using the drop down menu populated with databases previously accessed, the database whose tables are to be imported may be selected. Once selected, the details will be used to connect to the database, and its tables will be listed in the table. Here, tables may be selected to be imported into the project, using the left hand side check box column. The tables checked will only be added if not present in the project, unless the 'overwrite if already exists' option is checked.

 If a new database is to be defined, the 'New Database Connection' may be used to enter in the credentials of the new server. The details will also be saved in the drop down control for future use.

To connect with custom JDBC drivers in BrightBuilder, the drivers must be placed in BrightBuilder's install directory. For more information, please refer to the Appendix > Using Custom Database Connections topic.

Create Database Tables

BrightBuilder may be used to export defined tables to a database directly via connection, or via generating an SQL script to do so. To do this, select the Create Database Tables ... option under the right click context menu of the project. The tables contained in the project will be shown and selectable via check box controls on the left.

 

Once selecting tables to be exported, select or create a database selection. Then tap 'Create Tables'. This will create tables on the database specified, provided they do not exist. If they do exist, they may be dropped via the 'Drop tables that already exist' option in the dialog before the 'Create Tables' operation.

A script containing the table's CREATE TABLE statement may also be generated using the 'Show Script' button. This will open a new window, displaying a script that may be run to create the selected table(s).

To connect with custom JDBC drivers in BrightBuilder, the drivers must be placed in BrightBuilder's install directory. For more information, please refer to the Appendix > Using Custom Database Connections topic.

Discover Data Sources

Data sources are necessary for the stored procedure/RPC record types queries, allowing them to retrieve information from a specific, targeted data source defined via server definition. These data sources must first be discovered before assigning them to a query, performed by the 'Discover Data Sources' option in a project's context menu.

 

There are two of these options, as follows:

  • Discover Data Sources from Server Prompts the user to connect to a server, and when achieved, returns a list of all active deployed BrightServer configurations on the server containing exposed data sources. Selecting a configuration in the dialog will display all the exposed data sources available, and tapping the 'Update' button will load them for the project.

  • Discover Data Sources from File Returns a list of all currently opened BEP project files which may be selected to list all available data sources in the file to add as data sources. Data source containing files will not contain a version number. Once selected with data sources listed, tapping the 'Update' button will also load them for the project.

 After being found, sources are assigned via queries' 'Data Source' property, listing all the found, target data points via drop down box.

Deploying a Project

Once a project has been fully tested for its functionality and flow control, it can then be deployed to the BrightServer for application distribution to the mobile users. Only projects that are error free can be deployed to the server.

BrightServer 5 or older uses what is known as the 'BrightServer Deployment Directory' to manage applications, configured via the Servers panel, under the heading 'Application Distribution'. For more information, please refer to the BrightServer > Configuring BrightServer > Server Settings chapter in the documentation.

If using this older version of BrightServer, ensure that the BrightServer Deployment Directory Settings have been configured and are correct. If the BrightServer Deployment Directory is required to be set up, then the first time that you deploy an application, BrightBuilder will ask you to choose a directory for deployment.

BrightServer 6 or later uses an internal database based application distribution and update mechanism, and thus does not require this directory to be configured.

To deploy a project to the server:

  1. Right-click on the project name to display the project's context menu, and select the Deploy to Server... option.

  2. The project will be saved, then validated by BrightBuilder for server deployment. If any errors are detected by BrightBuilder at this stage, the deployment may not continue. Errors, along with any warnings, will be shown in the Outputs panel of BrightBuilder.

  3. The Select Server dialog will then appear to specify the target BrightServer instance for deployment. Select a server from the dialog. If the target server does not exist, it may also be created via selecting the New Server ... option in this dialog.

  4. Proceed to supply a description and any other files (if necessary) in the Release Description and File Attachments dialog.

  5. Click Yes to confirm deployment. Once complete, BrightBuilder will display a confirm message with the version number, as well as an option to jump to the Configuration > Users editor of the BrightServer instance to deploy the release.

This process is covered in further detail in the BrightBuilder > Project Deployment chapter of this document.

Creating Android Install Files

'Create Android Install File ...' : This option is used to create white labelled (branded) Android application packages (APKs) by packaging the project files and the application icon, splash screen imagery etc. into a single signed installable APK. This APK package can be distributed to users for side loading or submitted to the Google Play store for publication to a wider audience. Using this option organisations have the full control on the application branding (look-and-feel) and product release cycle. For more information, please refer to the Creating White Labelled Android Install Packages chapter.

Project Password Protection

The Set Password... command allows you to password protect projects. Projects that has been password protected cannot be opened for modification or viewing.

To set the password,

  1. Right-click on the project name to display the pop-up menu.

  2. Select Set Password... from the pop-up menu.

  3. Enter the password in the Enter New Password dialog and click OK to save the changes.

To open a password protected project, you must first enter the password for that project as shown below:

Note that this command is different from the Settings - Password project property. The Settings - Password pertains to BrightForms Help Settings password protection.

Cut/Copy and Paste

Project elements such as forms, tables, queries, sync-rules and reports can be cut/copied and pasted within projects. To achieve this, use each project element's pop-up menu to Cut or Copy a form or a table, as shown in the following image:

Use the Paste option from the project's pop-up menu to paste an element unto the project. If the element name already exists in the project, then the pasted element will be renamed and added with a number at the end, i.e. frmMainMenu1.

Backup Project

BrightBuilder provides quick functionality to backup project files via the project node. This serves as a "save as" functionality of the project and includes the date-time stamp (yyyyMMdd_HHmmss).

Use the Backup Now... option from the project's pop-up menu to make a back up of the bsp file. BrightBuilder will first save the project, then display the Backup dialog as shown below.

Add Files to Project

When a file is used within a form's layout, it is typically embedded in the form, and therefore bsp, itself. However, for files which are not in the layout, this embedding process cannot take place. The 'Add Files to Project' option of projects thus enables any type of file to be added to projects, and suit files that a project needs but does not use directly in forms or reports.

To add a file, perform the following steps:

  1. Select the 'Add Files to Project' option from the project's context menu

  2. The following 'Add Files to Project' dialog will appear, containing files which have been previously defined to be added, if any.

  3. Files may be added with the 'Add New' button, which will invoke the following dialog to select the files to be attached.

  4. Once selected, the file will be added into the list within the dialog.

  5. Once added, you may continue adding more files, or commit the list by clicking the 'OK' button. The 'Remove' button may also be used, which removes the selected file from the list.

Any files attached in this manner will be placed in the defined BrightServer Deployment Directory when distributed remotely.  Note, that this method differs from attaching files on project deployment as it will ensure files are distributed each time the application is deployed, as opposed to being a one off.

Switch Display Language

The project's main design locale may be selected via this option, which allows viewing of project elements in a defined locale. For more information, refer to Application Localisation > Switching project locales.

Copyright © 2002-23 Bright Software Pty. Ltd. All rights reserved