You are here

Develop GIS Widgets with the New Esri Javascript 4.3 API

The Esri JavaScript 4.3 API has been released. With it comes a pretty big change in the way we develop GIS widgets on the platform. Why? The development team at Esri has re-written the engine that drives GIS widgets, and they have chosen Typescript as the technology that brings the widgets to life. Let's dive in to what this means for developers. 

Typescript: What is it? Why Use It? 

In the past 18 months, the popularity of Typescript has taken off. What is Typescript? Typescript is open source technology managed — and created — by Microsoft. Typescript is a super set of JavaScript, meaning it has all of the capabilities of JavaScript, but it also has additional language features, such as types, that aren't available in JavaScript. Typescript transpiles to your JavaScript version of choice, where it can be used in browsers or a node.js server environment. The current JavaScript version of choice for most developers to transpile to is ECMAScript 5 (ES 5). This is because browsers such as Internet Explorer 11 only understand ES 5. ES 2016, on the other hand, has a lot of new language features such as classes, arrow functions, and new variable keywords. If you're using a modern browser such as Firefox, Safari, Chrome or Edge, you'll find that these browsers will support most of the new ES 2016 features.

So why do we use Typescript? What Typescript allows developers to do is to develop with the most modern language features that aren't yet supported in browsers. The transpiler assures that that modern Typescript code that you write? Well, it will work across all browsers. Typescript also offers a great development experience that developers would use in certain environments, such as a C# development environment. "Find All References," "Go To Definition," "Global Rename" are just a few of the advantages you have when developing your application in Typescript. Being able to create types allows this for this rich development experience.

Not convinced yet? Consider these compelling examples of teams adopting Typescript. The Dojo team is doing a rewrite of their framework using Typescript (Dojo 2.0). Similarly, the popular JavaScript platform Angular, developed by Google, has been rewritten from the ground up using Typescript. Angular even promotes the use of Typescript when developing your own Angular applications. Google has also just approved Typescript as a language internal development teams can use to create applications and products.

So, How is Esri Using Typescript? 

When developing a custom GIS widget in the 4.3 and above Esri JavaScript API, you'll find that you get to the pleasure of working with Typescript to create your widget. Esri has some great documentation on how this can be done. Be sure to refer to this documentation and code samples when developing your widget.

Let's Build a GIS Widget! 

If you've built a GIS widget before, you'll notice the tool chain for building a widget now is dramatically different. Never fear! I will explain each part of the process in a clear and easy to understand manner!

What you'll need to install:

The tutorial I'm following a long with is from the Esri site. What I'll be doing is trying to explain some of the concepts along the way.

Step 1: Create a new directory on your computer where you'd like to host the widget project. I'll go ahead and call mine HelloGalaxy (as opposed to HelloWorld).

Step 2: Open VS Code and then within VS Code select File > Open Folder. Open the folder location you had just created for your widget.

Step 3: Create a new file called tsconfig.json. Each Typescript project you'll create will need this json file to operate. There a number of configuration options but the important one to note is the jsx, react, and target config options. Notice the target is ES5, which stands for ECMAScript Version 5. To learn more about ECMAScript and what that really mean, this link is helpful.

Step 4: A shortcut to get a command line window with bash capabilities is to select View > Integrated Terminal. Within the terminal type: npm init --yes. This will create a shell package.json for you. You should see the package.json it created. Go ahead and inspect it to see what it created. Then in the terminal type: npm install --save @types/arcgis-js-api. Notice what was just saved to the package.json file. That package is now included in the dependencies section of the package.json. Now if you look within the directory you created you'll see a node_modules folder. Within there if you drill down you'll see an index.d.ts file which contains the type definitions we'll need for Typescript to work properly with our widget project. This will also give us some excellent intelligence when developing our widget!  

Step 5 (optional): While we're at it let's make this folder a git repo. If you have git installed just type: git init in the terminal window. If you do this, create a new file called .gitignore and then within that file type node_modules. Then we'll ignore the node_modules folder from our new source control repo we just created.

A screenshot of what my VS Code looks like after Step 5:

VS Code - Develop GIS Widgets & Popups with the Esri Javascript 4.3 API

Step 6: Create a new file called HelloGalaxy.tsx within a new folder called app. The app folder will be at the root of the application. What is the tsx extension? TSX lets the Typescript compiler know that you're writing JSX. Typescript supports JSX to be compiled in ES5 compatible JavaScript. Remember in our tsconfig.json we set the jsx property as react and reactNamespace as jsxFactory. What we're doing here has no direct relationship to the react framework, but takes ideas from it. Feel free to do some research of JSX. To me it's not that clear what the advantage is, but feel free to research and read up on the topic.

Full contents of HelloGalaxy.txs with comments explaning the functions of the code:

Step 7: With your terminal open, type in the tsc command. Once you run that command you should see a HelloGalaxy.js file and a file in your app folder. Inspect the HelloGalaxy.js file to see what the Typescript compiler has spit out just from the contents of the tsx file. It's doing this so any browser that supports ES5 (which is all of them) can interpret the code.

VS Code - Develop GIS Widgets & Popups with the Esri Javascript 4.3 API

Step 8: Create a new file named index.html in the app directory. Set the contents of the file as follows:

Step 9: Open the index.html in a browser. You should see the following in your browser:

Output - Develop GIS Widgets & Popups with the Esri Javascript 4.3 API

Wrapping It Up: Working in the New GIS WIdget Framework 

What we just went through was an exercise about working with the new widget framework. This framework includes Typescript, TSX files, and compiling that to interact with your index.html.

In this example, the index.html was the entire widget. A more complicated example on the Esri site explains how to place the widget on a map. They use view.ui.add([WidgetClassName]) where we just simply set ours to the widgetDiv container.

Hopefully you can see how this widget model will be useful in developing widgets. What Esri is trying to do is make widget development into component driven design. To download the full project or simply browse through the code examples browse to our GitHub repository where this code is hosted.

Author Information

  • Josh King

    Josh King

    Josh King works as a Senior Consultant, specializing in software architecture, at the GIS consulting company SSP Innovations in Centennial, Colorado. Since 2000 Josh has worked on a number different software applications with his most recent experience being in developing field operations applications for the Telecom, Oil and Gas, and Utility industries.

    See all items created by this author >

    Connect with me on:

Category Tags:


Add new comment