Can someone explain the syntax involved in this require.js example?

Question

I hope this question isn't too broad, but there's a LOT of unfamiliar syntax happening in this particular require.js/ESRI example, and I am hoping someone can explain some of this to me.

First, this code works (that is, it does what I expect it to do): it creates a base map and adds a FeatureLayer pulled from a map service. It's a stripped-down version of an example from the ESRI Javascript API page. Here's the code:

    var map;
    var featureLayer;

    require(["esri/map", "dojo/domReady!", "esri/layers/FeatureLayer"], function (Map) {
        map = new Map("map", {
            basemap: "topo",
            center: [-100.195, 39.567], // long, lat
            zoom: 4
        });

        featureLayer = new esri.layers.FeatureLayer(
            "http://my-server-url.com/arcgis/rest/services/Projects/MapServer/0",
            {
                mode: esri.layers.FeatureLayer.MODE_ONDEMAND
            }
        );

        map.addLayer(featureLayer);

    });

Now for the particular questions:

1. What is this require([...], function(args) { } syntax doing? I don't even know how to read this. Is it a function call to require.js? What goes in the square brackets? What are the function arguments?

2. From other examples, it looks like there normally should be one function argument per include in the require.js call. But here, if I add an argument for FeatureLayer, it doesn't work.

3. The "dojo/domReady!" include doesn't seem to ever have a corresponding argument in any example. Is this related to the exclamation point? What does the exclamation point mean?

4. Can anyone point me to a USEFUL require.js reference? The requirejs.org website reads more like a tech spec than a user manual. And the ESRI website seems to assume you know how to use require.

And yes, I have been Googling--the problem is that Google isn't great at searching for computer syntax questions since it strips punctuation, and because "require javascript syntax" and the like make for crappy (over-broad) search terms.

Answer 1

1. The require([...], function(args) { } syntax is saying "load this list of modules, and once they're all loaded, call this function with the return values of those modules as arguments". What goes in the square brackets is an array of either paths to a script file (minus the .js) or a module IDs mapped using the require.config paths section. The arguments to the callback function correspond to the paths/modules in the array, but not all modules return a useful value, as you noticed in your next question...

2. Adding an argument for FeatureLayer doesn't work because you can't skip arguments. But note that many modules don't actually return a value intended to be used. You will see this a lot with jQuery plugins, where the loading of the module simply registers the plugin with jQuery but doesn't return a value to the caller. I don't know ESRI, but from the code snippet it looks like loading FeatureLayer simply adds FeatureLayer to the esri.layers global object.

3. The exclamation point syntax is reserved for plugins. Typically there would be something else following the exclamation point which indicates the resource that the plugin would load, e.g. text!myTemplate.html, but in the case of domReady! the plugin exists just as a way to wait until DOM loaded before invoking your callback function, so nothing needs to follow the exclamation point.

4. Recommendation lists of external resources is off-topic for StackOverflow, but here's one that I found helpful in getting the basic concepts: http://aaronhardy.com/javascript/javascript-architecture-requirejs-dependency-management/

Answer 2

This section of the requirejs docs describes what the exclamation point means in the context of domReady: http://requirejs.org/docs/api.html#pageload

Since DOM ready is a common application need, ideally the nested functions in the API above could be avoided. The domReady module also implements the Loader Plugin API, so you can use the loader plugin syntax (notice the ! in the domReady dependency) to force the require() callback function to wait for the DOM to be ready before executing.