SDK Overview

If the built-in configurability of VertiGIS Studio Web does not serve your purposes, then it might be time to dive into the VertiGIS Studio Web SDK. Building applications on top of the VertiGIS Studio Web SDK requires engaging in the development, testing, and deployment of custom code, so it's worthwhile to make sure your problem cannot be solved with workflow or other advanced configuration.

If you still think you need to use the VertiGIS Studio Web SDK, then let's get started!

Have you explored the VertiGIS Studio Web Designer?

The VertiGIS Studio Web Designer allows you to edit your application's layout, configure custom behaviors for buttons and other UI components, and solve complex business problems through VertiGIS Studio Workflow. Many use cases can be solved through the VertiGIS Studio Web Designer and don't require custom development.

Overview

The VertiGIS Studio Web SDK provides a development toolkit for building custom components, services, and more into a package that can be deployed to VertiGIS Studio Web called a library. Once the library has been developed, it can then be deployed to your SaaS or on-premises environment.

Extension Points

There are three main extension points in the SDK:

Components

Components power the UI experience of VertiGIS Studio Web. Components are composed of a React Component and a backing data model. Layout files are composed of a nested hierarchy of components which are instantiated at runtime.

Services

Services provide the shared infrastructure and core logic that power app behavior. Services do not have an associated UI, and there is only one instance of a service per application.

Commands and Operations

Commands and operations provide a framework for executing application wide behavior. Services and components can both run and implement commands and operations, allowing for interaction and consistent behavior without tight coupling. Commands and operations can also be run in the app config and by Workflows. This can allow you to customize the behavior of built-in components.

Application Interactions

Components, services, and commands and operations interact to form a VertiGIS Studio Web Application.

• Services are used to implement application wide behavior, such as theming or authentication, and then expose that logic through commands and operations, such as ui.set-theme (implemented by the BrandingService) or auth.sign (implemented by the AuthenticationService).
• Components can run commands and operations to interact with services or other components. Components can also implement commands and operations to allow themselves to be affected by other services and components.
• Component and service interaction through commands and operations is preferred, but components and services can also be tightly coupled to each other through model injection or service injection.

Requirements

• The latest LTS version of Node.js
  • You can run node -v in your terminal to check the version you have installed
• A code editor of your choice. We recommend Visual Studio Code

Getting Started

1. Run npx @vertigis/web-sdk@latest create <library-name> where <library-name> is the name of the directory that will be created in the current working directory
   • For example: npx @vertigis/web-sdk@latest create test-lib
2. Open the library-name directory in your favorite IDE. We recommend using Visual Studio Code for the best experience.
3. Run npm start to start the development server

The running development server automatically detects changes to your source files. You can simply edit the layout, config, or custom code and the development server will automatically refresh the application with the latest changes.

Project Structure

The created project contains a few important directories:

1. The src directory, which contains your custom library code. We've included a sample component to get you started
2. The app directory, which contains a minimal development application layout and app config to be used for testing your custom code before deployment to production

Library Entry Point

The VertiGIS Studio Web SDK compiles custom components, services, and commands and operations into a library. The library is defined by the registration function exported from src/index.ts. This registration code informs VertiGIS Studio Web about the components, services, and commands and operations in your library so that they can be referenced in the app config and layout.

src/index.ts

export default function (registry: LibraryRegistry) {
    registry.registerService({
        id: "custom-service",
        getService: (config) => new CustomService(config),
    });
    registry.registerComponent({
        name: "custom-component",
        namespace: "your.custom.namespace",
        getComponentType: () => CustomComponent,
        itemType: "custom-component-model",
        title: "Custom Component",
    });
    registry.registerModel({
        getModel: (config) => new CustomComponentModel(config),
        itemType: "custom-component-model",
    });
    registry.registerCommand({
        name: "my.custom-command",
        serviceId: "custom-service",
    });
    registry.registerOperation({
        name: "my.custom-operation",
        serviceId: "custom-service",
    });
}

Development Patterns

If you are developing custom code that is mostly independent of app context, we suggest that you use the minimal layout and app config with only the required components.

If you need to develop custom code that requires the context of a custom application built in VertiGIS Studio Web Designer, take the following steps to import your SaaS or on-premises application into your local Web SDK environment.

1. Open your application in VertiGIS Studio Web Designer.
2. Download the application configuration.
3. Delete the contents of the app directory.
4. Extract the contents to you in your Web SDK Applications app directory, overwriting existing app config and layout.
5. Develop your custom code on top of your existing application.

Important

You may need to rename the downloaded layout file to layout.xml.

Next Steps

Create a Component

Learn how to create a basic component

Get Started

Create a Service

Learn how to create a basic service

Get Started

Deploy your Application

Learn how to deploy your custom library, layout and app config

Get Started

SDK Samples

Check out a collection of samples that demonstrate how to configure and customize VertiGIS Studio Web apps using the VertiGIS Studio Web SDK

Get Started