Integrating Cesium and Angular

CesiumJS
1

Aristeidis Bampakos has written a guest post on the Cesium blog about integrating Cesium with Angular. Check it out!

https://cesium.com/blog/2018/03/12/cesium-and-angular/

2

Readers might be interested in the Typescript Typings I've been maintaining for Cesium. https://gist.github.com/thw0rted/c0c73335c9968d5e7b6dd18a43ef6c42

Still hoping to get some kind of official support rolled in, but I recognize that nobody on the core team is a TS expert and I don't think the tooling is there to automate maintenance...

3

Τη Δευτέρα, 2 Απριλίου 2018 - 3:14:18 μ.μ. UTC+3, ο χρήστης james.b...@gmail.com έγραψε:

4

That’s a good point, but there’s a few problems. In no particular order:

  • It’s all maintained by hand, starting from an old version I found online. There’s an outstanding issue for the team to maintain something but they insist on it being automated (from JSDoc or similar). Of course, that’s entirely reasonable (why should they care about TS?) but I have not found such a tool yet.

  • The typings are incomplete, and it’s entirely possible that stuff I don’t personally use could be wrong. When I find a mistake in the typings, I fix it. When I find mismatches in the docs, I file a bug, but I certainly haven’t checked everything. It’s a huge public API. (Would certainly be a lot easier to maintain if you split it into a half-dozen or so modules…)

  • Cesium is under really active development and doesn’t follow Semantic Versioning (speaking of which, c’mon, y’all!), so it’s really important to have the exact same typings point release as the Cesium package in use. I don’t know how easy it is to set this up on DT, and as far as I can tell Cesium doesn’t have any kind of RC / beta release cycle so I don’t know what might change until the day the new version drops.

That said, if anybody wants to publish my rickety edits as “official”, I’m not going to stop them. It’s just something I found useful for myself and I thought it might give somebody else a head start.

V/R,

James

5

Hey James,

I am aware of this tool that generates types from javascript libraries. I have not used it before but it is baked from Microsoft, so it might worth. Have you tried it?

6

I hadn’t done much searching, but it looks like that one goes by “runtime shape”, which would not take advantage of Cesium’s extensive JSDoc type information. That prompted me to find this similar effort (https://github.com/englercj/tsd-jsdoc) but I don’t know how effective that one is. If I have some time next week maybe I can throw it at Cesium and see what happens :smiley:

-J

7

Hi James,
I gave a try on the tsd-jsdoc library that you proposed and I have uploaded an *.d.ts file here for testing purposes. I was forced to make some small modifications on the initial library to get it working.

Also, it would be great if anyone from the Cesium team or the community could try it and give us a feedback.

8

Sorry, I’ve had this on my todo list for a month now! Thanks for trying it. The good news is that all the JSDoc seems to carry over very well including the extensive parameter descriptions and examples that Cesium has been so good about including. The bad news is that some things immediately jump out at me as being problematic:

  • It looks like global functions get turned into empty “declare namespace” sections (ex. binarySearch, destroyObject, etc). Bug in tsd-jsdoc?

  • Some incompatible JSDoc syntax is carried over, ex. BingMapsGeocoderService constructor including a param called “options.key” which is of course not a param name but rather a description of the structure of the options param. Cesium uses this pattern a lot.

  • Subclasses don’t actually extend superclasses or implement interfaces – this is totally Cesium’s fault (sorry folks!) – which would improve the type system and reduce the quite considerable size of the file

  • A lot of Cesium class members return a Property whose getValue() returns the “actual” type of the data, ex BillboardGraphics. This is tricky to capture in docs because the constructor for these classes will take a Property wrapping the desired value or the value itself, which will be wrapped automatically. But if you don’t declare the types correctly, simple code like new Entity({label:{text:“Hello”}}) shows a typing error. Named interfaces for constructor options would go a long way to alleviating this (see my latest definitions for an example).

With that said, it’s very promising, certainly. But I think before I personally made the jump to generated typings, there would have to be a repeatable process where simply running tsd-jsdoc against the current codebase resulted in output that solves all the above issues (that I currently work around by hand-jamming my own). This means that the Cesium team would have to be amenable to PRs updating their JSDoc to be more technically correct (the best kind of correct), and that assumes we can figure out a syntax that JSDoc likes for e.g. options object structure.

Team, what say you?

-James

9

Generally, I did some modifications on the source code of tsd-jsdoc so that the output will be much aligned to the Cesium documentation, but as you say it needs to and can be improved. Maybe, we could maintain a version of tsd-jsdoc that fits nicely with Cesium.

Either way, it would be nice to hear thoughts from the Cesium team about that.

10

Is there a reason it has to be a fork of tsd-jsdoc? Is it possible to update Cesium’s docs to look the way tsd-jsdoc already expects them to look? Maybe it’s possible to submit a PR to tsd-jsdoc to support whatever syntax Cesium is already using?

I know I’m oversimplifying, but it would really be great to get everybody on the same page – with JSDoc having a robust enough vocabulary to describe how Cesium really works, then with Cesium using that vocabulary precisely, then with tsd-jsdoc correctly interpreting that vocabulary into accurate typings. What needs to change to get to that place? How much work is involved? What would you be willing to do yourself, or what could I help with?

V/R

James

11

Our JSDoc tools have been modified by our team specifically to add some custom behavior for Cesium, for example, link to examples, and an “experimental” tag. Is it possible to ignore these and have the tool work?

12

Hey Gabby,

Can you clarify a bit on this? It should already ignore examples and experimental tags because I have not done any modifications for the opposite to happen.

13

Maybe, we could maintain a version of tsd-jsdoc that fits nicely with Cesium.

I just wanted to add that since Cesium follows JSDoc other than the extra tags, hopefully a version that just ignores unknown tags would be generic and also sufficient to support Cesium, but I haven’t taken a close look at this.

14

When I run the tool, I noticed some inconsistencies between the primitive types that are defined in Cesium and those that the library expects to parse. For example: the tool looks for string, number, boolean and not String, Number, Boolean. So, I had to make some modifications for that. In some cases the error handling was not so good and the library was crashing if it could not find some properties. I added some code there also to handle exceptions.

The library does not seem to be stable yet. It had stuck for a year on 2.0.0-beta.1 version and suddenly there were some new pre-releases out in the last 2 days.

What are your thoughts on the above comments? I am open to help on any way though.

15

Got it. There are definitely a handful of issues throughout the docs, and generating typescript files make them obvious, so please open issues (or let me know, or submit fixes if they’re easy to resolve) for specific problems you see.

Overall, there’s been similar conversations in the past on GitHub, such as #5717, so feel free to add your thoughts there as well!

16

Good post. One thing: where it says

  • We use ElementRef class to get a reference to the HTML element that has the directive attached to it and initialize the Cesium viewer with that reference:*

const viewer = new Cesium.Viewer(this.el.nativeElement);

it doesn’t say that you also need to pass the ElementRef via the constructor. It should include the following:

"

Change the constructor to

constructor(private el: ElementRef) {}

"

gb

17

Thanks for the correct Greg! I’l make a note to fix that.

18

Great. Note too that as of I believe Angular 6, they no longer use the angular-cli.json file; they now use angular.json.

This is in the ‘Integrating Cesium and Angular’ thread.

19

Hey all,

Note that the blog post covers a working example with Angular 5 and Angular CLI 5 in this repository https://github.com/Developer-Plexscape/cesium-angular-example.

Due to the new version of Angular 6, we kept the working example that works with Angular 5 in this branch https://github.com/Developer-Plexscape/cesium-angular-example/tree/ng5 and the master now points to Angular 6.

You can read more here https://groups.google.com/d/msg/cesium-dev/B0IdY4I0yc0/0nr5NNYQBQAJ

20

Hi all,

Just to let you know that we have updated the blog post to point to the correct branch of our repository and we have also made slight improvements according to feedback from readers.

In the Angular 6 branch we have added an example on how to pass your Cesium ion access token correctly to the Angular application (You can use it the same way for Angular 5 applications). Check this out here.

Thanks!