> For the complete documentation index, see [llms.txt](https://docs.prebilt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.prebilt.com/prebilt-for-im-wm-strm/enhancing-prebilt/general-setup-and-best-practices.md).

# General setup and best practices

## Setting up PreBilt and creating an app

This section describes how to build a PreBilt application in the frontend from scratch.

It covers the process of creating a new PreBilt app and using GitLab as the source control repository, alongside existing PreBilt applications. If you are building a customer-specific application, it should be created and maintained in a separate GitLab repository.

### Prerequisites

The following tools are required to complete the steps in this guide:

* Visual Studio Code (VS Code), including the **Live Server** extension
* Git
* Node.js
* A browser extension or mechanism to handle CORS

### Setup

If not already installed, install VS Code, Git, and Node.js.

Run the `npm install -g live-server` command in a terminal to install **Live Server**, which is used as the local HTTP server throughout this guide. In the terminal to add the HTTP server used in this guide, other HTTP servers will also work. Other local HTTP server solutions can also be used if preferred.

## How to setup the PreBilt Base Application

This section can be skipped if you already have the base application set up and are just creating a new app.

{% stepper %}
{% step %}

### Clone

Clone the repository in GitLab. (If you are working on PreBilt you should have access to this repository.)
{% endstep %}

{% step %}

### Create

Create a ‘sapui5’ folder in the root of the project and download a UI5 library from SAP or alternatively copy/unzip the sapui5 folder into your local repository.  

The sapui5 folder is not included in the download, as it is ignored in GitLab by being in the .gitignore file . 
{% endstep %}

{% step %}

### Folder and file structure 

Details of the folder and file structures can be found in the section ‘Folder Structure’ and ‘File Structure’. Code for PreBilt apps can be found in the apps and js folders.

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2FQQFdzb0LZZNgoXwiR4hM%2Fimage.png?alt=media&amp;token=9a678383-8da7-4181-973c-fd4e0cef2316" alt=""><figcaption></figcaption></figure>

The folder structure for release version 5.8.0 and later is slightly different. A webapp folder has been added which is now where we will place our sapui5 folder and the code for any apps is in <kbd>webapp -> apps and webapp -> js</kbd>.&#x20;

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2FEKqJaAz5qTHoA2mkMoKH%2Fimage.png?alt=media&amp;token=14aa70c7-8531-457b-9ab0-0a46d2b46d00" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2FSHO6b0Hz64C8TjF9SOrs%2Fimage.png?alt=media&amp;token=64a1c453-4a33-439f-a405-3fdb05bd429f" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Run live-server

Run `live-server` in the terminal in the root directory of the project. This will launch the browser and you should see the log in page. The SAPUI5 libraries should have loaded successfully and should look something like the following.

PreBilt can be run locally during development, but for a customer we may use a URL or build an APK.

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2FtIc9U0CI25flDYu0jfK6%2Fimage.png?alt=media&amp;token=dcdc2749-29fe-4e80-881c-c8142c7be7b9" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

## New Releases &#x9;

As the PreBilt app library evolves and new functionality is introduced, existing applications may receive updates. Customers may wish to upgrade their deployed applications to a newer version to take advantage of these enhancements.

PreBilt supports this by using extensions within the app code. These extensions allow a newer version of an application to be deployed into a customer environment without overwriting any existing custom functionality.

To perform an upgrade, the required application version can be retrieved from GitLab and deployed into the customer system. After deployment, testing must be carried out to validate that any previously added custom functionality continues to operate as expected. Changes introduced in newer application versions may impact existing extensions and require adjustment.

## Comments&#x20;

Comments are used to give details about certain sections of code and to allow for simple navigation around the code making it easier to edit and understand the code in the future.

### JavaScript Comments&#x20;

Region comments can be used using the following format:&#x20;

`//#region RegionName`&#x20;

`//#endregion`&#x20;

Section comments or one line comments can be used in the following format:&#x20;

`//Comment here`&#x20;

Sections of comments can be used in the following format:&#x20;

`/* Start of comment`&#x20;

`* Additional line`&#x20;

`/* end of comment`&#x20;

### JavaScript Section/Region Comments&#x20;

Comments are used to create sections and regions in the code. Regions are used in the App\_XXX.controller.js file to group the functions that are specific to one page or one AJAX call, any additional functions are also in regions and at the end of each file the extension definitions are grouped by region comments. &#x20;

Some apps may have additional functionality where the functions can be grouped, this can be done using either region comments or just normal comments to create a new section.&#x20;

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2Fs34JGFtc9k3oNczdQO8a%2Fimage.png?alt=media&amp;token=d8dcc2a9-3ddc-4eff-a74c-0995f07e8c70" alt=""><figcaption></figcaption></figure>

Regions are used in the App\_XXX.view\.js file are used to separate the code for each page e.g.

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2Ffx36WQSYsv3yW5MEdW9o%2Fimage.png?alt=media&amp;token=699d91a0-eef5-4868-bcc7-dc3bdb2baeb6" alt=""><figcaption></figcaption></figure>

Recommended sections we use in the App\_XXX.controller.js file are:&#x20;

`//Pages`&#x20;

`//AJAX Calls`&#x20;

`//Additional Functions`&#x20;

Recommended sections we use in the App\_XXX.view\.js are:&#x20;

`//Shell`&#x20;

`//App`&#x20;

### JavaScript General Comments&#x20;

Comments are also used in the apps to explain certain functionality. These comments are not needed everywhere to explain every line of code but are used when there are sections of code that may need some additional explanation. Comments are also used to detail the different parameters for a function and their return values. &#x20;

In addition to these comments, the App\_XXX.view\.js file should contain a comment at the top of the file detailing an overview of the sections e.g.&#x20;

`/**`&#x20;

`* Overview details for app`&#x20;

`* oPage0100 = Selection Screen - Create`&#x20;

`* oPage0200 = Destination Input Screen - Create`&#x20;

`* oPage1000 = Selection Screen - Confirm`&#x20;

`* oPage2000 = Transfer Order List Screen`&#x20;

`* oPage3000 = Transfer Order Item List Screen`&#x20;

`* oPage4000 = Transfer Order Source Screen`&#x20;

`* oPage5000 = Transfer Order Destination Screen`&#x20;

`*/`&#x20;

### Comments in CSS&#x20;

Comments in CSS can be written in the following format:&#x20;

`/* Comment here */`&#x20;

There are no comment requirements for CSS code in PreBilt™, however they can be used if needed.&#x20;

### Comments in HTML&#x20;

Comments in HTML can be written in the following format:&#x20;

`<!-- Comment here -->`&#x20;

### Comments in ABAP&#x20;

Comments in ABAP can be either a line using \* at the start of a line or by using double quotes (“) part way across a line. Often double quotes are used on the line above a block of code and then lined up which creates a cleaner code.

<figure><img src="https://3149936122-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2CkvzIq48sLzTY4bfcWl%2Fuploads%2F7PO501ldz6dnGbxL4niu%2Fimage.png?alt=media&amp;token=37802168-8664-4b78-b9d0-272363177934" alt=""><figcaption></figcaption></figure>