2 Getting Started

To start working on your application extension, the first thing you need to do is create a workspace for the Designer in Oracle Visual Builder Studio. A workspace is created for you when you come from your Oracle Cloud Application, but you can also create one in the Designer in VB Studio.

Open an Application Extension from an Oracle Cloud Application

When you're working in an Oracle Cloud Application, if a page has elements that can be extended in VB Studio you can open VB Studio using the Edit Pages in Visual Builder link in the user menu.

Clicking the link opens the app extension in a workspace in VB Studio, and opens the Oracle Cloud Application page in the Designer. If your admin set up things properly, a workspace was created for you if you needed one, and also a repository branch from the app extension's main repository that you can begin to fill in by creating new layouts.

If your admin has set things up for you, you automatically land in the right project. VB Studio looks for the project and workspace associated with your base application and active Oracle Cloud Application sandbox (if you have one). If you have an active sandbox, your app extension opens in a new workspace in VB Studio associated with it, or in an existing workspace if you've already created a workspace associated with your active sandbox. In some cases you might need to select the project or workspace you want to open.

• If you have multiple workspaces associated with the same base application or sandbox, you will be prompted to choose one.

• If you don't have any workspaces, you will be prompted to select the repository that has the extension for the base application, and you might also need to select the base application's development environment.

If it's the first time you're editing the app extension, a new workspace and repository branch are created for you. If it's also the first time you're using the active sandbox, the sandbox is associated with the new workspace.

To access VB Studio you'll need to already be a team member of the VB Studio project configured for your app extension and have the proper user role.

To open a page from your Oracle Cloud Application:

1. In your Oracle Cloud Application, navigate to the page that you want to edit in VB Studio.
2. Open the user menu and click Edit Pages in Visual Builder.
   
   

   
   Description of the illustration fa-edit-page-link.png

   
   

When you click the link, VB Studio checks for the correct project and workspace. If prompted, you might need to select the correct project or workspace before the app extension opens in the Designer.

Create a Workspace Using an Existing Repository

To make changes to an application extension that already exists, you want to create a workspace that contains a clone of the application extension's Git repository.

Two workspaces shouldn't use the same branch. If you want to use a branch used in another workspace, you can create a new workspace and clone the branch for your changes.

When creating a workspace you will create a new local repository by cloning an existing repository or creating a branch. When cloning an existing repository, you will usually want to clone the master branch of your application's repository. This ensures that the new branch that you create contains the most up-to-date changes. If you are making changes that have not been merged to the master branch, you will want to select the branch containing the sources that you want to edit. For example, if you need to make changes to MyFeature, and MyFeature has not been merged to master, you'll want to clone the branch that contains the MyFeature changes (e.g. MyFeature-branch.git). You will make the changes to the MyFeature branch in your workspace.

To create a workspace by cloning a repository containing an app extension:

1. Click Designer in the main menu to view the list of your workspaces in the project.
   The list might already contain workspaces even if you have not created one using the Create Workspace wizard. A workspace is created for you automatically when you open VB Studio from a page in your Oracle Cloud Application.
2. Click Create Workspace.
3. Type a name for your workspace.
4. Click Clone from Git.
5. Select the Git repository.
6. Select the branch of the repository you want to clone. This can be master, or any other branch.
7. Select New branch from selected and type a name for the branch you want to create.

   You can create additional branches and switch between branches in the workspace.

8. Select the Development Environment. You might have only one option.

   Each of your workspaces will probably use the same development environment because a project typically has only one. The environment must also support the type of project you are working on, so to create a workspace for extending an Oracle Cloud Application, your project must be associated with an Oracle Cloud Application environment. If an environment is not defined for your project you should contact an administrator to add one.

9. Optional: Select the Sandbox you want to use with this workspace, if any.
   
   

   
   Description of the illustration workspace-create-clone.png

   
   

Create a Workspace for a New Application Extension

You use the New Application Extension tab when you create a workspace to create a new Git repository that you'll use for a new application extension.

You might want to create a new app extension when no app extension for the base app exists. In some cases you might want to create a new app extension for a base app, but best practice is that the base app should only have one app extension. When you create the new app extension you'll have to specify the base app that it is extending, and the development environment used when developing the extension.

To create a workspace for a new application extension:

1. Click Designer in the main menu to view the list of your workspaces in the project.

   The list might already contain workspaces even if you have not created one using the Create Workspace wizard. A workspace is created for you automatically when you open VB Studio from a page in your Oracle Cloud Application.

2. Click Create Workspace.
3. Type a name for your workspace.
4. Click New Application Extension.

   The details you'll need to provide and the files in the Git repository in your workspace depend on the Initial Content option that you select.

   
   

   
   Description of the illustration workspace-create-new.png

   
   
5. Select the base Oracle Cloud Application that the app extension will extend.
   The base app has already been configured for your project, so most likely there'll only be one application in the dropdown list.
6. Type the name of the Git repository and branch that'll be created for storing your files.

   If you don't want to create a Git repository now, for example, you only want to experiment with creating an app extension, you can select the Scratch repository option. Selecting this will create a repository in your workspace that only you can see.

7. Select the Development Environment for your app extension.
   The Development Environment has already been configured for your project, so most likely there'll only be one environment in the dropdown list. You can't create a workspace or develop an app extension if your project doesn't have a development environment.
8. Select a sandbox if your new app extension will involve changes that have been made to the data model of the Oracle Cloud Application.
9. Click Create Workspace.

What is a Scratch Repository?

When you create a workspace, you have the option to create a scratch repository, rather than using a copy of the project's Git repository. You may want to create a scratch repository instead of a branch when you are experimenting and you're pretty sure you'll never want to merge its contents into an existing repository. A scratch repository is a private repository that only exists in your workspace. No one else can see the repository's contents, and it's deleted when you delete the workspace. It's better to create a branch rather than a scratch repository if you think you might want to eventually merge its contents into the main repository.

If you're using a scratch repository in your workspace and you decide you want to let your team members use it, you can push your scratch repository to a new Git repository.

Push a Scratch Repository to a Git Repository

If you chose to use a scratch repository when creating your application extension, other team members in your project cannot work with your application extension.

You can share the content of your scratch repository with your team members by pushing its content to a Git repository that VB Studio will create for you.

1. Open your application extension.
2. Click the Git icon in the toolbar and select Push in the menu.
3. In the Push Content to Git Repository dialog that appears, enter a value in the Repository to Create input field. You can provide an optional description for the Git repository that VB Studio will create for you.
4. Enter a commit message, and then click Create and Push.
   
   Description of the illustration vbs-push-scratch.png

Create Workspace by Importing an App Extension Archive

If a team member gives you an archive of an app extension, you can import it to create a workspace containing all the files in their branch of the app extension's Git repository. When you create a workspace by importing a file, you create a new Git repository and branch.

To create a workspace by importing an archive:

1. Open the Designer page in VB Studio.
2. Click Create Workspace.
3. Type a name for your new workspace.
4. In the Create Workspace wizard, click Import From File.
   
   

   
   Description of the illustration workspace-create-fromfile.png

   
   
5. Drag the archive into the Import File drop area, or click in the drop area to locate the archive on your computer.

   VB Studio automatically checks the content of your archive to verify that it is a valid app extension archive. If it's not, you will see a message that you can't create a workspace by importing it.

6. Provide a name for the new Git repository and branch that'll be created in the workspace.
7. Select the development environment for the app extension, and a sandbox if you need one. Click Create Workspace.

Open a Page in Your Application Extension

If you log in to VB Studio directly, you'll need to select or create a workspace if you want to edit an application extension. When you open the Designer in VB Studio, you'll see a list of your workspaces. You can select one of them, or create a new workspace. Once you are in the workspace you can select the page you want to edit.

To open a page in your application extension:

1. Log in to VB Studio, if you are not already logged in.

   The Organization page opens when you log in and lists all the projects in your instance. You might only have a few projects.

2. Locate your project and click the project name to open its Project Home page.

   The Project Home page displays details about your project, including the project's environment, repositories and recent activities.

3. Click Designer in the main menu to open a list of your workspaces.
4. Click the name of the workspace you want to open.

   Each workspace is associated with a repository and a branch, and also sometimes a sandbox. If you are using a sandbox, you probably want to open the workspace already associated with it. This helps ensure that your changes are made to the branch using that sandbox.

   If none of your workspaces are using the correct sandbox, you can create a new workspace or open an existing one and switch to the correct sandbox and branch.

5. Click the page in the Navigator to open it.

   The extendable pages are listed under the flow node in the Application Extensions pane.

   
   

   
   Description of the illustration navigator-appextensions.png