2 Get Started

To start working on your application extension, the first thing you need to do is create a workspace in Oracle Visual Builder Studio. A workspace is created for you when you come from your Oracle Cloud Application, but if you open VB Studio directly, or if you need another workspace for some reason, you'll need to create the workspace manually.

If you're not sure why you need a worskpace, see What Is a Workspace and Why Do I Need One?

Create an Application Extension

There are two easy ways to create a new application extension, or to edit an existing one:

• Starting in a page in your Oracle Cloud Application, click the Edit Pages in Visual Builder.

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

  VB Studio opens the workspace associated with the sandbox you’re using (if you are using one), or creates a workspace for you if you don’t have one. Regardless, you should see your page in the Page Designer tab in the Designer, with the extensible areas outlined in green, like this:

  
  
  
  Description of the illustration designer-page-layout.png
  
  

  When you select an extensible area—either by clicking a region in the middle section, by selecting a component in the Property Inspector on the right, or by selecting a dynamic UI in the left Navigator area—you’ll be placed in the dynamic layout editor, where the real work begins. If there are configurable variables or events exposed in the base application, you'll also see the variables and/or events tabs for viewing the configurable variables and events related to the page. (If you’re new to application extensions, you may want to click Help in the user menu to open the VB Studio Help Center and watch some of the videos to help you get oriented.)

• After logging in to Visual Builder Studio, you select the project you want to work in, then click Workspaces in the left navigator to either select the workspace you've been using for your app extension, or create a workspace for a new or existing app extension. If you want to create a workspace, you can create one in the Workspaces page. You should then see something like this:

  
  
  
  Description of the illustration designer-welcome-page.png
  
  

  At this point you can select an app extension page or a dynamic UI artifact in the left navigator, after which you’ll be placed in the artifact's editor. More on that later.

Create a Workspace

A workspace defines the resources available to you when you open the Designer. You can think of a workspace as your editing context while you're working with the Designer.

Before you create a new workspace, make sure a Development environment is defined in your project and it points to an active Oracle Cloud Application instance. Your Project Home page lists your project's environments. Each of your workspaces will probably use the same development environment, because a project typically has only one. If an environment is not defined for your project you should contact an administrator or project owner to add one.

There are three ways to create a workspace.

Create a Workspace for a New Application Extension

If you're creating a new application extension, you'll want to create a new workspace and Git repository for your work.

To create a workspace for a new application extension:

1. Click Workspaces in the VB Studio left navigator to view the list of your workspaces in the project.

   Even if you've never explicitly created a workspace before, you may see workspaces in this list. That's because a workspace is created for you automatically when you open VB Studio from a page in your Oracle Cloud Application.

2. Click New and select New Application Extension in the list:
   
   

   
   Description of the illustration workspace-create-newmenu.png

   
   
3. In the New Application Extension dialog box, type a name for your workspace:
   
   

   
   Description of the illustration workspace-create-new.png

   
   
4. 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.
5. Select the Development Environment for your app extension.
   The Development Environment should have 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 you can't select an environment here. If the list is empty, or it contains more than one environment and you aren't sure which one to choose, contact the project owner.
6. Select a sandbox if your new app extension will involve changes that have been made to the base app's data model.
7. Type the name of the Git repository and branch that'll be created for storing your files. The name you give to the Git repository will be the name of the extension that is created.

   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.

8. Click Create.

Create a Workspace Using an Existing Repository

To create a workspace for an app extension that already exists, you can continue the work that's been started by cloning the app extension's Git repository.

When cloning an existing repository, you'll usually want to clone the master branch of your application's repository, to ensure that your new branch contains the most up-to-date changes.

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.

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

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

   Even if you've never explicitly created a workspace before, you may see workspaces in this list. That's because a workspace is created for you automatically when you open VB Studio from a page in your Oracle Cloud Application.

2. Click Clone from Git.
3. In the Clone from Git dialog, enter a name for your workspace.
4. Select the Git repository.
5. Select the branch of the repository you want to clone. This can be master or any other branch.
6. (Optional) Select New branch from selected and enter a name for the branch you want to create.

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

7. 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 you don't have an environment, ask the project owner or an administrator to create one for you.

8. Optional: Select the sandbox you want to use with this workspace, if any.
   
   

   
   Description of the illustration workspace-create-clone.png

   
   
9. Click Create.

Create a 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 Workspaces page in VB Studio.
2. Click Import to open the Import from file dialog box.
   
   

   
   Description of the illustration workspace-create-fromfile.png

   
   
3. Drag the archive into the Drag and 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.

4. Provide a name for the new Git repository and branch that'll be created in the workspace.
5. Select the development environment for the app extension, and a sandbox if you need one. 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 Your Scratch Repository to the Remote Repository

If you chose to use a scratch repository when creating your workspace, you'll need to push the scratch repository to the remote repository if you want other team members to see the sources. Pushing your scratch repository creates a new remote Git repository in the project.

1. Open your workspace.
2. Click the Git icon in the toolbar and select Push in the menu.
3. In the Push Scratch Repository to Remote dialog, type a Repository Name. This name cannot be the same as an existing project repository.
4. Enter a commit message, and click Push Repository.
   
   

   
   Description of the illustration push-scratch-repo.png

   
   

Use Branches to Isolate Changes

The repository for your app extension was automatically created when your project was created. When you create a workspace, you name the branch in the repository where your changes will be stored. You can have separate branches for each new feature or change to your app extension.

You can use separate branches for changes you want to make for two different sandboxes, or for different versions of a feature that use the same sandbox. For example, when you are modifying a table component in your app extension, you might want to work on two different versions of the table. By creating a branch for each version, you can work on one version in one branch with a Workspace A mapped to it, and then switch to another branch by using Workspace B to work on the other version. This way you can use your workspaces to help you isolate the branches with your changes. After you decide which version you want to use, you can share the branch with others and delete the branches you no longer need.