Aligning Cesium.js and AMD usage

Currently, our Sandcastle examples prefix all Cesium types with “Cesium.”, e.g., “Cesium.Cartesian3.” Our examples look verbose, especially compared to engine code and examples in the reference doc, both of which do not prefix with “Cesium.” Depending on if a user is using Cesium.js or AMD, they have to adjust depending on where they are copying and pasting code from.

Is it possible - or, well, reasonable - for Cesium.js users to have all Cesium types dumped into the global namespace (perhaps as the default option)?

If not, how else can we bridge the gap? Is something incremental like changing “Cesium.” to “c.” worthwhile?

Patrick

No, we shouldn’t pollute the global namespace with our dozens of classes and types. I’m OK with the abbreviation if it’s a user choice: For example jQuery doesn’t have to be "" if you want to use for something else. We could add all our types to “Cesium” and then just “var C = Cesium;” in the example code to get the alias.

–Ed.

It’s not one of “the good parts” of JavaScript, but there is always the with statement:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with

Dumping Cesium types into the global namespace is a really bad idea. Having the prefix is just a side-effect of non-AMD development. The only viable option, as you suggested already, is to alias Cesium to shorthand, like “C”. However, users can easily do this themselves by just aliasing Cesium, so we shouldn’t do it officially or anything.

The doc and Sandcastle examples will always be different, unless we decide to go all prefix or all AMD in one direction or the other. Ultimately, I don’t think there’s anything we need to do here on our sides, it’s just something we deal with when supporting both AMD and legacy “single file” usage.

The “with” statement is forbidden by “use strict”.

–Ed.

This is true, but just because we use strict internally in Cesium doesn't
mean that client code has to do so.

I thought that a lot of single file JavaScript libraries allowed users to pass the namespace name to them, and if it was not provided, would put their types in some default namespace, maybe even the global one.

Part of our mission is ease of use, and these inconsistencies are painful early in the adoption curve, exactly where we don’t want any pain. We all agree that we can make the examples more concise using “C.” or whatever, but how can we address the ease of use? I agree that the global namespace feels bad - especially coming from the C++ world - so how do we bridge the gap?

Here’s one idea: Use “C.” by default and include it in all our @examples, tutorials, etc. The only people who feel pain are those using AMD (smart folks that can handle it) and folks working on Cesium itself.

Patrick

Any feedback on this?

Here’s one idea: Use “C.” by default and include it in all our @examples, tutorials, etc. The only people who feel pain are those using AMD (smart folks that can handle it) and folks working on Cesium itself.

This isn’t something I want to jump on today, but I would like to submit an issue for when time permits.

Patrick

That’s okay with me, we would just have to be diligent about it since we have no way to verify doc samples.

Submitted #926.

Patrick