Isolate customizations from boilerplate

[MikeTschudi]

Proposed change to make it easier to keep custom apps synchronized with the boilerplate.

main.js necessarily changes as the boilerplate is updated and improved, and this can make it hard to update apps built upon the boilerplate. Yet main.js needs to be separate from Boilerplate.js because it comes in three flavors--webscene, webmap, and group--while Boilerplate.js serves all three. The proposed change introduces a custom main program with two entrypoints called from main.js: initialization and after the view's deferred resolution.

Because the updated boilerplate includes the delivery of JSON files, a web.config file is proposed to make the delivery automatic--not necessary to go into IIS and authorize JSON.

webmap.js and main.js were made as similar as possible; the group.js example is not updated in this pull request.

[MikeTschudi]

Update: propose adding portalUrl parameter to settings to permit access to webscenes hosted in a portal

[kellyhutchins]

@MikeTschudi looks like we already have portal url in https://github.com/Esri/application-boilerplate-js/blob/4master/config/config.json

[MikeTschudi]

@kellyhutchins That works for locally-hosted sites, but not if one needs to supply it in the URL so that a webscene can be opened in a generalized app, e.g., ?webscene=0bba4e0a18fc4847b64d8d2d9694145c&portalUrl=http://3dsolutions.esri.com/portal

The many urlItems in settings.json provide a kind of documentation for the hooks supported by the boilerplate, so portalUrl fits in and can be removed if not needed, as opposed to figuring it out so that it can be added if needed.

[driskull]

Main.js is not something the boilerplate expects to update. Its basically just a starting point/example. The only "meat" is the boilerplate class, config, etc.

I actually just removed the examples and have the webmap, webscene and group in main.js for sample use.

@MikeTschudi Can you re-author this with just the portalUrl changes and the webconfig stuff?

[MikeTschudi]

@driskull But the main program is modified all the time. For example, there were major changes between a month ago's 4.x version and the current version, and the 3.x version similarly changes over the years. It's inevitable as our technology gets better and better.

The regular and significant changes to main.js make it always difficult to graft apps onto new versions of the boilerplate, which tends to discourage the updates, leaving apps behind on security and other improvements. We need to recognize that main will continue to evolve and to provide a landing point that we will (virtually) never change.

[driskull]

Hmm. I think main.js is designed to change though. It's not meant to have anything significant that would require the user to update. It will still interact with the boilerplate however it wants.

What part of main.js do you see changing? Creating a webmap or scene?

Main also has things that the user might just want to remove like changing the direction of the html, reporting errors to users. These are designed to be changed.

[MikeTschudi]

It's good that main.js improves. The problem for a developer user of the boilerplate is when he/she wants to keep the app based on the the boilerplate up-to-date with the latest boilerplate improvements. If the app's customizations are made in main.js, this gets to be a tedious, error-prone, line-by-line process.

Preferably, as a user of the boilerplate, I would take the boilerplate as-is and tack on my app. Might need a few settings file changes, but basically, I don't want to modify the foundation, including main.js. The boilerplate supplies a tested way to create a webmap or scene and that's great. But an an app based on the boilerplate naturally has more features and the code has to be put somewhere.

main.js has had 13 non-trivial commits since it was created for the 4.0 version. Depending on how long one waits between boilerplate refreshes in an app, one may see a lot of merge work. By pulling the app out of main.js except for a very few access points, the merge becomes almost trivial. The proposed pull request was one approach to minimizing the app's footprint in main.js.

The approach doesn't matter, but it really helps to have one, and it's even better if the approach is supported and consistent across apps. So the pull request has a CustomMain.js file that the boilerplate doesn't ever change. The footprints of CustomMain.js in main.js may move around, but that doesn't matter as long as it's guaranteed that CustomMain is instantiated with the configuration and called when the WebMap or WebScene deferred is resolved (like a higher-level domReady).

Maybe there are more customization points, such as the error message. But we could start with a basic non-changing foundation for apps and add customization callbacks later. Those are vastly easier to merge than when app code is in main.js.

[kellyhutchins]

@MikeTschudi I think this brings up a good point. We do want to make sure its as easy as possible to keep the boilerplate code up to date. The 3.x boilerplate didn't update main.js very often but when we did it was quite a process to get all the template apps merged correctly. So if we can make this easier for developers but still keep the boilerplate in a structure that makes sense I'm all for it.

[driskull]

Its tricky because each user's app is going to be different. Some may use webmaps, some may use webscenes, some may use a gallery for display and some may use some unique combination or none at all.

I don't think there's a way to keep main.js pristine because its designed to be messed up by the user. The Boilerplate, and how to interact with it should not change. Main.js, however, could change to be anything. It's designed to be totally rewritten.

It would be good to know which parts _specifically_ of main.js would you like to see not change?

[driskull]

I don't see main.js as a class that needs to be unmodified by the user. I see it as a sample.

The boilerplate is the "do not touch" part.

[driskull]

I tried to abstract out everything common that a user wouldn't need to modify into the boilerplate. Everything in main.js could be changed by the user. They might want to do things before the map or scene is created. The boilerplate also doesn't do anything to the DOM. It's just a class for fetching and managing template data.

[kellyhutchins]

@driskull makes sense to me. I didn't think about the 'main.js' part as a sample but looking at the code and keeping that thought in mind it makes sense. So when updating this in the future we just need to make sure to keep all essential app logic in the boilerplate portion. If we do that then all devs should need to update to be current is the boilerplate.