Which ESRI Javascript API Version to Use – 3.x vs 4.x

by Ryan DavisonGISPosted on No Comments

Which ESRI Javascript API version should you use for your next mapping app? I wish it were as simple as just using the most up to date version. And maybe it will be for your situation. But there are a few considerations to address before pushing ahead.

Start With Your Goal

Always start with your goal. What do you want the app to look like and do? Probably, the biggest question you should ask yourself is whether you will be creating a 3D app or a standard 2D app?

As of this post, the 4.x API is at version 4.11. According to ESRI’s API Capability page, version 3.28 (the latest 3.x version) doesn’t support 3D rendering. Version 4.11 only has partial support for 2D. So, if you’re planning to create an app that supports 3D visualization in any way, you’ll need to use 4.11.

On the other hand, if you are only supporting 2D visualization you’ll want to use the latest API that supports all of the other functionality you might want to use. This is really important to consider if you’re thinking about migrating existing 3.x code to the 4.x world. You would hate to get deep into the conversion only to find out a critical component you rely on is not yet supported.

Check out ESRI’s functionality matrix to determine if 4.11 is implementing all the functionality you need right now. ESRI’s stated goal is to eventually have 4.11 eventually exceed the functionality of the 3.28 API. But until it does, you’ll want to proceed with at least a little bit of caution.

Consider Your Time

Another thing you will want to think about is the time you will spend getting up to speed on the syntax changes that version 4.11 brings. Right away, when creating a basic map with 4.11, you’ll notice that you now have to not only create a map but a map view (or map scene if it’s a 3D app) in order to get anything to render.

With the old 3.x API you would simply declare the map object and pass in a reference to the HTML element you want to use to render it in. As of 4.11, the Map object is now simply a container for the various layers you want to associate with the app you’re creating. There is now a new class called View that manages UI methods for your app like rendering the map within the HTML element and placing components (like widgets and images) on screen.

I like most of the new syntax changes that I’ve seen in 4.11 but I realize these slow down my development time as I get used to them.

It’s The Little Things That Get You

by Ryan DavisonProgrammingPosted on No Comments

I spent some time today dealing with a layer of data that was added to an ESRI REST service. The service layers are zero base indexed which means you can reference them based on their position relative to each other. The first layer is identified at position zero while the second is 1, the third is 2 and so on.

The new layer was just before the fourth existing layer. This means the new layer became the fourth, the fourth became the fifth and the fifth became the sixth. Are you following along?

 

Anyway, I was working on a web app that consumes this service and it references the service layers based on those index positions. I added some new markup and some code for the added layer and changed the existing code to reference their two new position numbers. At first everything seemed to be working fine. Then a coworker noticed that the new layer’s data was showing on screen by default (you’re supposed to check a box first). It took me a while before I finally realized that it was being controlled by a different checkbox that controls the layer right after it in the service.

To make an already long and confusing story shorter, there was a second reference to the service indexes in my code. When I had designed the app a few years ago I, for some reason, found it expedient to make two, hard coded references to the index. Instead of taking the time to create a variable, I had repeated a hard coded number that could be changed by an outside source.

My poor design choice came back to bite me. Not only did I repeat code, I made it confusing to update. It’s embarrassing to admit that I wrote code that even I couldn’t figure out later. But it goes to show that taking the time to design things correctly from the start will pay off in the future. It’s the little things that get you; that second hard coded index number that’s nearly impossible to notice.

Taking Time To Tinker

by Ryan DavisonCreativityPosted on No Comments

In his famous lectures on creativity, John Cleese says that if you play around with a problem and put off calling it done for a while, you’ll often come up with a better solution than if you simply took the first solution that came to you.

Tinkering with an idea or a map or a code base is a great way to not only develop it but to develop it into something better than it had been before. It’s taking something that could be called complete but then further playing with it and manipulating it until it becomes something else.

This is an approach I take with application and code I’ve written. Even after I’ve finished a project, I’ll let it sit for a while and then come back to it. When I do, I try to reimagine its uses or how it can be written. I went through this process today with a code module I had written over a year ago. With fresh eyes I was able to play around with the code. I asked myself why something was written a certain way. I tried things like stripping out important lines of code just to see if it would improve performance in other areas. I also had fun seeing just how massively I could make the code fail.

The result of my playing around with my code wasn’t as dramatic as an entirely new application. But I was able to reduce its size and rewrite parts of it more elegantly. Well worth the time it took to tinker.

Objective Reasoning – The Basic Javascript Object

by Ryan DavisonProgrammingPosted on Comments are Disabled

What is an Object?

In Javascript an object is simply a container or store of properties that are related to what the object is modeling. These properties can be primitive data types, other objects or functions. Here’s an example of an empty object with no properties:

const furBearingTrout = {};

I’ve used object literal notation which is doing just what it sounds like – literally writing out the notation of an object. We do this using curly braces {}.

How to create properties

When we want to set a property on our object we can do it one of two ways:
1. Use bracket notation where we state the object name along with a property name in brackets and then assign a value using the equal sign:

furBearingTrout[“name”] = ‘Alpino-Pelted’;
furBearingTrout[“url”] = 'http://www.furbearingtrout.com/fish2.html';

2. Use dot notation where we state the object name followed by a dot followed by the property name we want to use and then assign a value using the equal sign:

furBearingTrout.name = ‘Alpino-Pelted’;
furBearingTrout.url= 'http://www.furbearingtrout.com/fish2.html';

I could have created our object with properties already assigned. Note that properties are written as name:value pairs separated by commas.

const furBearingTrout = { 
  name: ‘Alpino-Pelted’, 
  url: 'http://www.furbearingtrout.com/fish2.html'
}

How to access properties

Once we have properties we can access them using the same two methods we used to set them just without the equal signs that assign values.

console.log(furBearingTrout.name); //outputs ‘Alpino-Pelted’
console.log(furBearingTrout[‘url’]); //outputs 'http://www.furbearingtrout.com/fish2.html'

We can also create objects using the constructor method (new Object) or the Object.create() method but for this article we’ll stick to the literal notation for its simplicity and visual aid.

Functions in objects are methods

When the property is a function we call it a method. Methods do something with the data stored in the object. Imagine we had the following properties:

const furBearingTrout = {
  name: ‘Alpino-Pelted’,
  url: 'http://www.furbearingtrout.com/fish2.html',
  view: function () {
    console.log(`View the ${this.name} trout at ${this.url`;)
    }
}

You call a method by accessing the property name it’s associated with followed by parentheses.

furBearingTrout.view(); //ouputs ‘View the Alpino-Pelted trout at http://www.furbearingtrout.com/fish2.html’

Why do I use ‘this’ ?

The ‘this’ keyword simply references the very object it’s inside of. So this.name is the same as saying neighbor.name. Outside of the object we would refer to furBearingTrout.name but inside the object we refer to this.name.

There’s a lot more to objects than what I’ve written here. But if you understand these basics you’ll already be able to model some fairly complex real world data and be able to manipulate it.

5 Ways to Comment Your JSON

by Ryan DavisonComPosts, ProgrammingPosted on No Comments

Comments aren’t part of the official JSON specification. According to an old (2012) Google Plus post by Douglas Crockford, he removed them to preserve interoperability.  But that same post suggests you can still use comments  so long as you remove them through minification before parsing.

There are a few other ways to handle JSON comments besides minification:

  1. You can add a new data element to your object. The element key would be named  “_comment_” or something similar. The value would be the actual comment. This method is slightly intriguing but feels kind of dirty. It looks like a hack. It is a hack! bulk is also added to the network payload. JSON is a lightweight data exchange. Adding comment elements takes away from this.
  2. Use Scripts that programmatically remove comments from your JSON before it’s parsed. Sindre Sorhus published a comment stripping module which does just that. This is similar to Crockord’s method of minification in that it removes the comments before parsing but you can inline it in your code rather than use it during a build process.
  3. You can forget comments in your JSON entirely. Put comments in the code where you make the data request in the first place. You should already know what kind of returned data is expected so comments would make sense here. You can stay in your code without the need to view a separate file. This makes your code easier to understand.
  4. Finally, if JSON is being used as a configuration file or some other static data store, you might even try commenting it in a separate file. Put a text README in the same directory the configuration file is stored. The README could contain a paragraph describing the data or you could copy the JSON into the README and use inline comments.

There are several ways to take care of the problem of commenting JSON files. All have their strengths and weaknesses. The best method depends on your particular situation and needs.

Why Gulp is Great

by Ryan DavisonProgrammingPosted on No Comments

In my last post I talked about why I started and then stopped using Grunt. Basically, Grunt seemed too slow and my workflow was being halted too often while I waited for it to build. There are several other task running/app building tools out there (Broccoli, Cake, Jake…) but I decided to try Gulp first since it has a large user base and there are plenty of plugins out there to keep me from having to think too much.

At first, Gulp didn’t seem quite as straightforward as Grunt. Grunt was easy to use. You just had to write (sometimes lengthy) configuration objects for the plugins you wanted to run and then fire off the tasks using the command window. Even someone like me could figure out how to add a source file and a destination location to a minification plugin and be reasonably sure I would get a minified file out of it.

It was also very easy to visualize what your Gruntfile was doing because every task plugin worked independently of the rest. You would configure ten different tasks and then register them all together in a row and expect them to run one after another until they all completed.

With Gulp, you don’t just configure plugins, you write JavaScript code to define your tasks and how you want them run. A Gulp task asks you to require the plugins you want to use, or write a custom task using plain old JavaScript, then call Gulp.src to provide a source file for the tasks to run on. Doing this opens a Node stream which keeps your source object in memory. If you want to run one of the task plugins you required at the top of your script, you simply pass the in-memory object to it by calling the .pipe() method. You can continue piping the object from one task to another until you’re finished. Finally, you call Gulp.dest and provide a destination location.

var gulp = require('gulp');
var plumber = require('gulp-plumber');
var addsrc = require('gulp-add-src');
var less = require('gulp-less');
var cssnano = require('gulp-cssnano');
var concatCss = require('gulp-concat-css');
var rename = require('gulp-rename');
var concat = require('gulp-concat');
var uglify = require('gulp-uglify');
var watch = require('gulp-watch');

gulp.task('less', function(){
    return gulp.src('./source/style/style.less')
        .pipe(plumber())
        .pipe(less())
        .pipe(cssnano())
        .pipe(addsrc.append(['./source/style/anotherStyleSheet.min.css', './source/style/stillAnother        StyleSheet.min.css']))
        .pipe(concatCss('concat.css'))
        .pipe(rename("style.min.css"))
        .pipe(gulp.dest('./destination/style/'));
});

gulp.task('js', function(){
    return gulp.src(['./source/scripts/javaScript.js'])
        .pipe(plumber())
        .pipe(uglify({
            mangle: false,
        }))
        .pipe(addsrc.prepend(['source/scripts/someJSLibrary.min.js', 
        'source/scripts/anotherJSFile.min.js','source/scripts/stillAnotherJSFile.min.js']))
        .pipe(concat("all.js"))
        .pipe(rename("finalFile.min.js"))
        .pipe(gulp.dest('./destination/scripts/'));
});

gulp.task('default', ['less', 'js'] , function() {
gulp.watch(['./source/style/style.less']);
gulp.watch(['./source/scripts/javaScript.js']);
});

The great thing about using Node streams is that you don’t have to keep opening and closing files for each task like in Grunt. This lack of i/o overhead makes running a series of tasks very fast. Even so, you really need to use the built-in watch task to take advantage of this speed. In my experience, running a default task with four or five tasks in it, from the command line, was almost as slow as in Grunt. With the watch task running, it only took milliseconds to rebuild what it needed to. But I’m new to Gulp so what do I know?

You can see in the code above that I used several plugins to manipulate the input file as it is piped down the stream. There are two that I found particularly helpful. The first is Gulp-Plumber which is basically a patch that keeps streams from being un-piped when an error is encountered. Supposedly, streams breaking on error will be fixed in version 4.0.

The second helpful plugin here is Gulp-Add-Src which does exactly what the title says. You can add additional source files to your stream so you can do neat things like concatenation. With these and other plugins I haven’t found anything with Gulp that would keep me from doing everything I could with Grunt.

The only thing I really don’t like about Gulp is the icon. It’s a cup with a straw in it and the word Gulp across its side. A cup by itself indicates an ability to gulp what is in it. But you don’t gulp through a straw, you sip or suck. Who wants their product to suck? And sip indicates a lack of passion. So what’s with the straw?

Gulp.js cup icon

Why Grunt is Gone From My Build Team Lineup

by Ryan DavisonProgrammingPosted on No Comments

I have to admit, I don’t always research every option when I’m looking for a solution to a problem. I’ll usually start out with a broad web search to see what others are using and if their solutions seem to fit my situation. Then I’ll take maybe the top two solutions and try to implement them. The first one that serves all of my requirements and is relatively easy to implement usually becomes my solution.This is exactly how I came to start utilizing Grunt as a build tool for a large web mapping application I develop.

When I first started using Grunt, the JavaScript API development team at ESRI was using it for their projects. Lots of other developers were using it too and I didn’t know any better than to follow. A few people were talking about Gulp too as an alternative to Grunt. So I took a brief look at Gulp, didn’t immediately understand it, then started putting together my Grunt configuration file and collecting all the plugins I needed.

What can I say – it worked great and I was happy that I wasn’t still using code minifiers and copying files by hand to production folders. When I started using Adobe Brackets as my default code editor, I was pleased to find it had a great Grunt plugin to integrate task running directly.

Things were great for a while but I was always bothered by how long Grunt took to run through all my tasks and complete my build. It would take 10+ seconds to finish and I would have to sit there waiting to check my latest edits. It can be really hard to develop a piece of code when you are constantly halting your flow.

However, I was lazy and didn’t want to have to learn another tool. What I had in place worked,  just not efficiently. But eventually I knew something had to change. Strangely, it wasn’t inefficiencies with Grunt that made me dump it, it was Brackets. My Brackets install was slowing down and freezing at inopportune times, like whenever I wanted to use it. I was also getting the Brackets “white screen of death” from time-to-time which required the Task Manager just to shut the program down. So now I was waiting 30 seconds for my editor to unfreeze so I could wait 10 seconds for my task runner to finish.

The upshot is, I revisited Atom and am now using it as my default editor. Fortunately, I wasn’t happy with Atom’s Grunt integration. I figured it was a great time to jump ship and try again with the second biggest player in the JavaScript task running world: Gulp.

In my next couple of posts I’ll talk more about why Gulp is great and why I shouldn’t have nuked Atom when I was first choosing a new editor.

Five Things I Love About the ESRI Javascript API

by Ryan DavisonProgrammingPosted on No Comments

Having worked with both the ArcGIS Silverlight and Javascript APIs I have to say Javascript has been much more fun. There is just something about working on the front end of a web map and being able to have it do so many amazing things. Here are my top five reasons I enjoy working with this API.

1. Your maps are device independent. Unlike the Flex and Silverlight APIs, Javascript and HTML5 can be viewed on almost any device. The obvious advantage here is that you can reach more people with your spatial data.  Of course having the ability to code for multiple devices means having to customize your code for different screen sizes which can turn into a lot of work. Check out this post from the Treehouse Blog for a great primer on responsive web design.

2. Plenty of code samples and live examples. Code samples are a great way to get your own map up and running quickly without having to figure everything out first. While the samples are not perfect they are a good way to discover map functionality that you might want to incorporate.

3. Support for a ton of layer and data formats. From GeoRSS and GeoJSON to KML and shapefile, this API pretty much covers it.

4. Well written API reference documentation. If you are going to use an API (any API) you want to be able to understand it so you can use it effectively. Good documentation is critical for this. The Esri JS API is (in my own humble opinion) extremely easy to read and understand. Each class has all the information you need to use it without having to decode any meanings. Furthermore, there are links from each class to samples that use it.

5.  Editing tools for online editing of SDE data. Let’s be honest, online editing through a web browser is not a great idea if you are trying to build accurate data. However, there is definitely a place for it. If you are trying to outline an area inhabited by a herd of elk or mark an area of weed infestation, browser editing is probably fine.  It is great just to be able to have this ability so more diverse mapping applications can be developed.

Wow, this list was a lot harder to write than 5 Things I Hate About the ESRI Javascript API. One reason is that there are other APIs out there that do a lot of what the ESRI API does (yes I am thinking about OpenLayers). Another reason is that as I write I think about things I would like ESRI to do better or differently. Oh well, you can’t have everything. Let me know what your thoughts are on the ESRI Javascript API – good or bad.

5 Things I Hate About the ArcGIS Javascript API

by Ryan DavisonProgrammingPosted on One Comment

Building a mapping application with ESRI’s Javascript API is a lot of fun. But it can also be a real pain. Here are five things that absolutely drive me crazy when writing an ArcGIS Javascript map.

1. It is based on Dojo. It’s probably just my lack of Javascript programming sophistication but I find Dojo a little hard to work with. Although the API documentation has improved in recent versions, I don’t find it very intuitive. If you are a beginner or new to Javascript, the getting started documents are just plain frustrating. Ben Farrell thinks there are seven stages of learning Dojo including anger and acceptance. I’m not sure if there are really only seven stages but I can attest to the anger and acceptance.

2. It uses multiple versions of Dojo. Here I go again with the Dojo thing. Half of the developer samples on the ArcGIS.com developer’s site seem to be written pre version 1.7 while the others are post 1.7 and rely on the AMD module format.  I understand that version transitions of supporting libraries can be difficult but this is ridiculous. Since the ArcGIS API updated to version 3.6, many of the developer samples have been updated to show the AMD require format. Unfortunately, the transition has been slow and there is still a lot of mixed version code and a lot of live samples are broken. If you are going to upgrade to a new version of your API, let’s have things ready to go.  

3. No built-in label engine for dynamic, on-screen annotation. It seems obvious to me that the users of a map would want to mark it up with text; especially in conjunction with a draw toolbar. Apparently it isn’t obvious to the ESRI developers. Instead we are left to work with with the labelPoints function which uses the geometry server to create an unseen point and then puts a text symbol on top of it.

4. The label engine problem above leads me to my next gripe. The LabelPoints function doesn’t allow line breaks. That means that if you want to label a polygon with something like, oh say, area and perimeter, you have to have it all on one line or call the labelPoints function twice and use an offset. How about we get the ability to at least use a newline character (\n) and be done with it.

5. No out-of-the-box support for a table of contents. There is a lot of debate about whether an ArcGIS-like table of contents is a good thing in a web map. No matter what side of the debate you fall on, the fact is that people are used to using them and users often want the ability to turn layers on and off. There are a few projects out there that attempt  to solve the problem but each has its own limitation and problems.  It is a little surprising that ESRI doesn’t have a solution for this one yet. Or, maybe it isn’t really that surprising.

I have plenty more gripes with the Javascript API than the ones listed above but I don’t want to get too depressing. Also, I actually enjoy developing with the API (most days) and there are some great things about it. If you want to add to my list put it in the comments.