webOS OSE Extension for Visual Studio Code

webOS OSE provides a Microsoft Visual Studio Code extension in the marketplace, to assist developers in creating webOS apps (web apps, Enact apps, JS services).

The extension simplifies the following aspects of handling an app/service:

• Creating web apps, Enact apps, or JS services from a template.
• Assisting the use of webOS LS2 APIs and Enact APIs through content assist.
• Debugging the implementation.
• Previewing an app locally.
• Running ESLint on Enact apps.
• Packaging, installing, and running apps.
• Configuring and managing VirtualBox emulator.
• Analyzing an IPK.

Additionally, since support for the above operations is provided by the easy-to-use extension, developers do not have to learn the ares-cli (used to create, package, install and run, and debug apps/services) and enact-cli commands (used for working with Enact apps).

We recommend that developers use this extension for all webOS app development. If you are new to Microsoft Visual Studio Code, refer to the documentation at code.visualstudio.com/docs/.

Note: Some features of this extension re-use the webOS TV extension.

Prerequisites

• Install Microsoft Visual Studio Code v1.58.0 and higher.
• Install Nodejs 8.12.0 to 14.15.1 (recommended).
• Developers must have a basic understanding of webOS web app, Enact app, and JS service development. For reference, see www.webosose.org/docs/tutorials/.

Note: The components ares-cli, enact-cli, and patch-package, are also required. If not already available on the system, the installation of these components is prompted to the user.

Install the Extension

To install the extension, open Microsoft Visual Studio Code and do the following:

1. Navigate to View > Extensions.
2. Search for "webOS OSE" in the search bar click Install.
3. On successful installation, you see the webOS OSE icon in the Activity bar.
4. Click the icon to see the interface of the extension:

   

As mentioned in the prerequisites, if some of the required components are not available, you get:

• An error message indicating that the device list could not be fetched.
• A prompt in the notification area. On clicking Yes, the relevant components are installed and the device list is fetched.

Using the Extension

The usage of this extension is explained taking into account the typical flow that is to be followed in webOS app/service development.

Note: When the IDE is opened, a notification indicates the VirtualBox is not installed, even when VirtualBox is in fact installed and working properly. To resolve this issue, update the environment path variable to point to the VirtualBox installation directory.

Step 1: Creating the App/Service

The extension provides support to create different apps and services (check FAQs).

Before creating your first project, we recommend that you set the workspace (directory) for all your webOS apps/services. All projects contained within the workspace are shown in the APPS IN WORKSPACE tab. This will make managing your projects easier and more seamless.

Set the workspace:

The workspace can be defined in one of two ways:

• Navigate to File > Open Folder and select the directory to be set as the workspace.
• When creating an app/service, the project location is automatically set as the workspace.

To add a project:

1. Navigate to the APPS IN WORKSPACE pane.

   

2. Click the + icon.
3. In the command palette, select the project type (the type of app or service to be created) and respond to the prompts.
   • Some important points for a JS service:
     • A JS service must be packaged in an app.

       

       - Choose "**--Select App--**", to package the service in a dummy app. - Choose the required app in which the JS service must be packaged. - Choose '**Choose a Different App**' to select an app that is not available in the workspace.
     • Add webOS library if you want to invoke webOS LS2 APIs within the app.

       

   • Some important points for an Enact app:
     • When creating an enact app, select the required template (sandstone or moonstone).
     • Add webOS library if you want to invoke webOS LS2 APIs within the service.
4. The created project entry is shown in the pane.

   

Step 2: Developing the App/Service

Now that the app or service is created, update (implement) the source code for the project.

Within the Visual Studio Code interface:

1. Open the Explorer tab.
2. Navigate to the app/service project directory.
3. Update the code and the configurations as required.
4. Any additional resources (such as images, libraries, and modules) that are required for the project must be provided in the project directory (manually or through the npm command).

Note: To invoke webOS LS2 APIs in an enact app or JS service, the webOS NPM library must be available in your project. You might have already added this library when creating the Enact app or JS service. If not done, go to the APPS IN WORKSPACE pane, right-click the project and select Install webOS NPM Library.

Using the content assist feature:

The extension also provides the content assist feature for Enact apps (for webOS LS2 APIs and Enact APIs) and JS service (for webOS LS2 APIs). This means that content assist is available in source code where any of the modules/components of Enact/webOS are imported/required.

As the developer types a keyword, through the content-assist feature, the API syntax and documentation (if available) are shown:

Step 3: Launching the App

After completing the development activities on the app/service, you must package, install, and run the app (check FAQs). You must select the screen on which the app must be displayed/launched.

Prerequisite: Before running an app, make sure that the relevant device is available in the KNOWN DEVICE pane. Some important points:

• To add a device, click the + icon, and in the command palette, respond to the prompts to specify the details of the device.

• By default, an emulator device is listed in the KNOWN DEVICE pane.

  • This emulator device points to an emulator that is running on the local system.
  • If no emulator is available on the local system, navigate to the EMULATOR MANAGER pane and set up the emulator.
  • Make sure that the relevant emulator is launched before launching an app.

• Set a device as a default device. This ensures that all device operations are performed on that device.

  • Initially, the emulator is set as the default device.

• To remove an app from a device, uninstall the app from the device.

To launch an app:

1. Navigate to the APPS IN WORKSPACE pane.
2. Corresponding to the app, click the Run App (triangle) icon to auto-trigger the operations (package, install, and launch) sequentially. Alternatively, select each one of the operations to perform them individually. When performing the launch operation, select the screen on which the app must be launched.

   

3. In the command palette, respond to the prompts to specify the details of each operation.
   • When packaging the app, you can specify the JS service to be included within:

     

     - Choose "**--Select Service--**" if no JS service must be packaged. - Choose the required JS service that must be packaged. - Choose '**Choose a Different Service**' to select a JS service that is not available in the workspace.
4. After each sub-operation, you are informed in the notification area.

Alternatively, you can do the following:

• Install and then run the app from within the Explorer tab. Simply locate the IPK file to install and/or run the app.
• Run the installed app from the KNOWN DEVICE pane.

To run a JS service:

• JS services in webOS are always packaged in some app.
• Therefore, to run a JS service, you must run the app in which it is hosted.

Step 4: Debugging the App/Service

Note: This step is optional.

The extension provides support to debug web apps, Enact apps, and JS services that are installed on the device (or emulator).

Prerequisite:

• Google Chrome browser must be available/installed on the local system.
• IP address of target device (or emulator) and IDE should be in same network for debugging.

To debug an app/service:

1. Navigate to the KNOWN DEVICE pane.
2. Right-click an installed app and select Debug App/Service.

   

3. The Run and Debug view is automatically opened. If not opened, navigate to View > Open View... and select Run and Debug.
   • When debugging an Enact app, the scripts that are loaded are trans-compiled. To debug using the pre-compiled source files:
     • Copy the command that is shown in the notification area (format: window.location = "http://:").
     • Paste it in the DEBUG CONSOLE execution prompt.
     • Press Enter to execute the command.
4. In the CALL STACK pane, select the relevant app/service entry.
5. In the LOADED SCRIPTS pane, select the relevant source file to be debugged.
6. Add a breakpoint to the code and debug the app as required.
   • The logs are shown in the DEBUG CONSOLE.
7. To stop the debugging, click the disconnect button corresponding to the app entry in the CALL STACK pane.

Note: (very unlikely to occur) You could sometimes get a notification indicating that a debug session is already active, even when all debug sessions are closed. To resolve this issue, restart the IDE and try debugging again.

Step 5: Previewing the App (Web and Enact)

Note: This step is optional.

The extension provides support to preview the web app or Enact app locally before it is deployed on the device.

To preview an app:

1. Navigate to the APPS IN WORKSPACE pane.
2. Right-click the required app and select App Preview.

   

3. Preview the app in the App Preview tab that is automatically opened.

Note: Only one app can be previewed at a time. If an app is previewed while another preview is open, the new app preview is launched in the same tab.

Step 6: Running ESLint on the Enact App

Note: This step is optional.

The extension provides support to run Enact ESLint to statically analyze files for potential errors (or warnings) and to help enforce a common coding style. For more information, check ESLint Configurations.

To run ESLint on an app:

1. Navigate to the APPS IN WORKSPACE pane.
2. Right-click the required app and select Run Lint.

   

3. Open the Problems view (View > Problems).
4. Click an entry from the view to see the issue in the source code.
5. Update the source code as required.
6. Run Lint again to get the updated list of issues.

Note: To clean the Lint messages from the view, click Clear Lint.

Emulator Manager

The extension provides support to add webOS emulator (on VirtualBox) instances from within the IDE. This eliminates to need to access the VirtualBox interface to create/configure/run the emulator.

Prerequisites:

• VirtualBox must be installed on the local system.
• Emulator VMDK is required.

For details on the above prerequisites, check Emulator User Guide.

Note: By default, any webOS emulator that is deployed as a VirtualBox guest system is listed in the EMULATOR MANAGER pane.

To create and run an emulator instance:

1. Navigate to the EMULATOR MANAGER pane.
2. Click the + icon, and in the form, enter the details for creating the emulator instance. For the VMDK file and memory requirements, check Emulator User Guide.

   

3. Open the Problems view (View > Problems).
4. Click Add Instance and the emulator instance is listed in the pane.

   

5. Click the (triangle) icon to run the emulator. On doing this:
   • The launched emulator opens in a VirtualBox window.
   • The icon in the list indicates the launched entry.

Important points:

• To stop or close an emulator instance, simply close the running emulator window.
• When deleting an emulator instance, the associated VMDK file is also deleted. Make sure that the VMDK file is safely backed.
• Multiple emulator instances cannot use the same vmdk file.
• Only one emulator instance can be running at a time.

IPK Analyzer

The IPK analyzer feature allows you to analyze the IPK and more specifically to analyze the file size of the app and/or services available in the IPK. To analyze an IPK:

1. Open the Command Palette (Ctrl+Shift+P) and type webOS OSE: IPK Analyzer.
2. Click Import IPK to load the IPK.
3. After the IPK is loaded, you can view the details of the IPK.
4. To view the details of another IPK (for example, an older version of the IPK), click the Compare IPK button to load another IPK. The details of the other IPK will be loaded below.

Operations from Command Palette

In the above sections, we have seen the operations provided by the extension. These same operations can be performed entirely from the command palette. To see all available webOS OSE commands, open the Command Palette (Ctrl+Shift+P) and type webOS OSE.

More Information

• FAQ
• Forum