Add module export for Microsoft.Maps.d.ts
Chrisbright10 opened this issue · 20 comments
I want to do this....
import { Microsoft } from 'bingmaps/scripts/MicrosoftMaps/microsoft.maps';
but because you are not including an export on the module, I am not able to. Can we add explicit export statements to allow for greater integration with Typescript?
e.g.
change
"declare module Microsoft.Maps {"
to
"export declare module Microsoft.Maps {"
please also do so for all the files inside the "modules" folder... this will allow imports to be cleaner.
Thanks!
Please also correct the package.json. It's main property refers to index.js, which does not exists in the dist. Preferably, you will want to include an index.js so that you can simply do
import {...} from "bingmaps";
Thanks!
Just tried adding the export. It broke everything. Note, these are only typescript definitions, not typescript source code. Doing and import and creating a custom namespace won't work in your actual application as the maps API is only exposed using the Microsoft.Maps namespace.
Thanks Ricky, fully understood about the typescript defs. Perhaps we should explain what we are trying to do: we are creating a set of angular components to make is easy to work with Bing Maps in an ng app. These are published as an npm module (See https://github.com/infusion-code/angular-maps for more detail if interested)
So in our components and services, we want to of course use the Bing types. We nmp-ed the bingmaps package into our project (where we noted the issue with main=index.js), but otherwise not problem.
We would then normally in our .ts files use something like:
import { Microsoft } from "bingmaps/scripts/MicrosoftMaps/Microsoft.Maps.All"
However, that does not work as the Microsoft namespace is not and therefore not visible on import.
In ng2, I was able to work around that by using
import { } from "bingmaps/scripts/MicrosoftMaps/Microsoft.Maps.All"
This would load the reference correctly and compile, but result in double declarations if multiple dependent components each would use that import. We worked around that by moving the import into the module root. Long story short, we got it to work in ng2, were able to publish the module and consume it in an ng2 app.
However, now in angular 4, this approach breaks down as the web pack config included in the ng4 cli complains about the missing types because of the typescript compiler removing the (empty) import statement out of the d.ts when building the moduel (still with me?).
In other words, it breaks.
Now, we were able to fix it in ng4 by adding the export in-front of the namespace declaration in the bing type d.ts file and it did not result in any breakage. But of course, this is not really sustainable.
Could you share some more detail on what all broke when you added the export?
Or, do you have any guidance how to use the Bing definitions in an angular context?
Great to see this project, and that Infusion is still doing a lot of work with Bing Maps (I used to work there many years ago). When I add "export" in front of all the "declare Microsoft.Maps" in the files while in visual studio, all the cross file references stopped working. For example, a reference to "Location", a class in Microsoft.Maps.d.ts, appeared as an unknown reference in the directions module d.ts file.
Fiddling around with import/export I managed to work around the issue, but it results in all existing apps that use the reference tag for the definitions to break and they would need to use import. Seeing how there are 30,000+ apps already using this library with reference tags, I definitely don't want to break those.
Looking around at a lot of large typescript definition projects, I haven't seen any of them using the import/export as being proposed here.
In terms of using these definitions inside an angular app, all others I know of have simply been adding a reference tags like:
/// <reference path="bingmaps/scripts/MicrosoftMaps/Microsoft.Maps.All.d.ts"/>
When this project was first created the plan was to align with DefinatelyTyped which doesn't use seem to need the import/export for definition files like this. We haven't added this library to DefinatelyType yet, but planned to very soon.
I've added an index.js placeholder file to the project locally, but have an update coming in a few weeks and I'm waiting for that before I build a new NPM and update the project.
Would it be an ok solution to put both types of files in your solution? That way we can have the ES6 version alongside the ES5 solution? I think that it would help to increase your audience as there are many Angular 4 devs that are using Webpack and Angular CLI which prefer the "Import" notation. Let me know if that could be a good stop gap.
FYI all of the angular components (e.g. 'angular/core', 'angular/material', etc.) allow for this import notation so it might be good to see how they implement it and if it would be possible to deploy it like they do.
The reason all of the angular components support this, is that they are Typescript code files, not definitions.
I have tried a lot of different options, all of them break the main way this library is being used by developers today. Angular 4 is nice, but the majority of users at the moment that we come across are still using Angular 1 and 2 still.
If you want to make a pull request with the changes you would like to see. I'll test them to see if they break things. If they don't I'll merge them in.
@rbrundritt , played around with this over the weekend and got it to work fine in ng2 and ng4. So thanks for the pointers, that helped. On the other hand, I am not really happy with the fact that the user of our npm module now has to manually add the
/// <reference path="../../node_packages/bingmaps/scripts/MicrosoftMaps/Microsoft.Maps.All.d.ts"/>
line in the ng module that uses our module. The problem is really one of convenience only, but still:
-
the path is likely different for each implementation depending on the actual project structure and the distance of the module that uses the maps from the node package folder.
-
the op has to include the reference even if he wants to use the ESRI provider (for the sake of argument) as the signatures of some of the exported contracts contain concrete references to Bing Maps interfaces (since the concrete Bing Maps realization is part of the package). That is not really that unreasonable, but inconvenient.
While I could address this be putting the concrete Bing Maps realization of our abstracts into a different package, I'd rather keep it together for convenience.
But I though of a possible approach: since you packaged with npm, but really do not use the main entry point, I though that perhaps we can use that to do a ES6 module style export and have both the
/// <reference ...
approach and the ES6 module
import { ... } from "bingmaps"
approach side by side.
So If you don't mind, I would create a fork and play around with that, I think I can get it to work without breaking any existing stuff and we'd have the best of both worlds. To help me out, could you point me to an example that I can use to validate that the existing approach is not breaking? Would the Bing Map Samples on GitHub be a good test case?
Also, thanks for including the reference to the x-map stuff in the Bing Map code samples, I appreciate it. We'll have a plunker available soon for you to include as well. I did adopt your spider cluster approach into x-maps over the weekend, it is wicked. People love it.
Sounds good. The V8 Code Samples on GitHub project has a few TypeScript code samples in there that would be good to test against.
I have followed this discussion over the Memorial Day weekend without success in building a simple Visual Studio 2017 Community Angular Bing Maps program. My request is for someone to publish a "Hello World!" application showing the minimal requirements to get a Bing Map on an Angular Visual Studio solution where the Bing Map is not part of the main module (which I've done) but pulled in as a component. I was most surprised to find that the Bing Maps system could not be incorporated via an import {} command, but instead required the (somewhat hokey) /// reference mechanism as a pre-compiler operation - I thought one of the benefits of Angular was to handle dependencies in a consistent manner. Thanks to all - I know this is all new, but it seems to me that a working solution would be very useful. (On the other hand, if Bing Maps incorporation is not a good Angular application, please advise). One final comment or question: would it be better to forget about a "roll your own" Bing Maps solution, and instead utilize X-Maps? This I have not yet tried, but I am sure many in my situation would appreciate guidance as to the merits of X-Maps.
re: should I use x-maps or roll my own: it depends. When you use a package like x-maps (open source or not) you get what you get. So if your use case is well covered by the package, you are probably better off using it because you get great leverage and you got community support. You can even move the project forward if you want to contribute. To get an idea what is currently in place: basic map, marker support, layer support, clustering support. Polygons and polylines will be added in the next few weeks. Everything works data bound of course, so you can build your map from your data with a few lines of markup.
re: a starter: not a problem. I would suggest you head on over to the x-maps repo https://github.com/infusion-code/angular-maps and follow the instructions. They are pretty straight forward (and updated with the correct references etc.) and show you how to get the package to work. The instructions are written for the root module, but they work exactly the same if you use a feature module (just make sure you keep the path in the reference correctly pointing to the node_modules folder). I suggest you repost the question there as well and I will respond with a sample ng cli project in the next few days (cli is a bit simpler to scaffold than VS, but you should have no problem to move this from VS Code to VS Studio)...
I agree with your comments on the import, hence the thread :) We'll work on that...
thor-schueler - Thanks (or Vielen Dank?) so much for your prompt response. I will delve into this and report back. Let me take this opportunity to thank both you and Rick Brundritt, as I have benefited from Rick's postings for some time.
@smithGit - Gern geschehen ;). I put a plunker out for a basic map with ng4
You should have no problem seeing what's going on and how its wired up. You can simple add the npm packages and copy to code over into your VS solution. The plunker is for ng4, but it will work with ng2 just the same. I placed the map into the app component and there is nothing else there. I will add some more complex samples soon.
Es geht! For newbies like myself, here are the steps to get it running on local Windows machine, all from a new project folder: a. download the x-maps GitHub package, b. download the files from Thor's Plunker link above and put in same folder, c. run npm install, d. put your Bing Maps key in src\app.ts, e. if you do not have web server download it via npm install http-server -g, d. start server on port 8000 by http-server -p 8000, e. in browser access localhost:8000/index.html and you've got a map of Texas. This is great! Next steps are integration into a VS project (using VS web project template and/or placing with the new VS angular template).
Glad it worked. You had asked for another example with it in a separate module. I'll try to add a plunker for that over the weekend...
Gents: Thanks so much, Thor, for your work with x-maps and the Plunker example. This note has to do with new Angular template for Visual Studio plus x-maps plus Bing Maps (and Google if it works): Would it be feasible and beneficial to harmonize x-maps with the Visual Studio 2017 (Community edition) Angular template? [would it not be true that anyone developing for Bing Maps would likely be using VS?] What would be the benefits of being able to merge x-maps into a VS-Angular project? I have compared the x-maps to VS scaffolding or folder hierarchy, and the VS-Angular template consolidates components into the ClientApp > app > components folder, and each component has its own subfolder containing the html, ts and css files that are associated with the component. This strikes me as a pretty good idea for applications that may grow, but I really don't know. Finally, is this a good topic for this thread, or, if it is a worthwhile endeavor, should it be spun off as a separate topic? (Also, Thor, any further Plunker example(s) will be most appreciated if you have had time to work on them or it.)
FYI an excellent tutorial on using the VS Angular template is Daren May's at:
https://channel9.msdn.com/Events/Visual-Studio/Visual-Studio-2017-Launch/WEB-103
(I was not able to get data binding to work due to @angular2-universal not being found)
@smithGit, I think it'd be more appropriate the carry on discussions like this in the x-maps repo. Anyway, to address your requests/questions:
- VS 2017 use - I am not sure that people who develop against Bing maps would necessarily be using VS. In my experience, most angular developers prefer to use the cli in conjunction with VS Code. I am using both as I do a lot of NETCore hosted angular apps (see https://github.com/infusion-code/ng2-spa-netcore-starter). I have used x-maps with both cli/VSCode and NetCore/VS apps.
- Harmonizing with VS folder structure - I think I am not quite understanding where you are coming from on that one. X-Maps not an angular app but an npm package (think library), you'd add it to your angular project via npm, which will install the necessary type definitions and compiled javascript in the node-modules folder of your project. That is independent of your project structure and code editor and works the same in VS Code and VisualStudio. There is really no presence of the x-maps stuff in your clientapp folders. It almost sounds to me like you are copying the actual typescripts files into your project. You probably should not be doing that as you will disconnect from the repo and not be able to get future updates. I suggest you use npm install --save angular-maps instead.
- angular2-universal - not entirely sure I am following this either. Are you talking about the npm package or the nugget that you need to get server side rendering to work in an ASP.Net hosted angular app? X-maps itself has no dependency on universal. ASP.Net based templates tend to use it to enable service side rendering, however, that will be of little use with x-maps. x-maps users the Bing/Google APIs under the covers and both interact heavily with the DOM. Universal has no concept of a DOM and so if you use universal, you need to make sure you write your code appropriately. X-maps contains services to deal with that, and if you need help with that, I'd open a new issue on the x-maps repo. Databinding does not rely on universal though. You databind (for example markers) simply by using *ngFor on your marker tag against an array that has the information for each marker (I'll add a plunk for that in the next few days). In any event, if you want to use it and are looking for the npm package, it is simply angular2-universal (no @). Note that ng4 it has been added to angular proper though and is now @angular/universal https://github.com/angular/universal.
A bit of insights around the Bing Maps web control. Visual Studio is very often used when creating web apps that use Bing Maps, but of course it is not the only tool used. There are a lot of different platforms in which Bing Maps web control is used. For example I have come across a number of apps which are based on or integrated with ColdFusion, ruby, python, WinForm, WPF, Android, IOS. This is not a complete list but shows the wide range of development platforms in which the web control is used. Angular isn't used that often with Bing Maps, I'd say less than 1% of apps. Note that there are hundreds of thousands of apps using Bing Maps. Most of these are used in line of business apps which are not publicly accessible, thus why you don't see it as often as you would think given the number of apps. The majority use plain old JavaScript and HTML. That said, I'm sure more people will use Angular over time, especially with tools like X-Maps available.
Thor and Rick - many thanks. Let me do a bit more homework before asking for further direction. The information you have provided is most helpful. Apologies, Thor, for not understanding how things fit (I think if I had followed your instructions a bit better it would have helped!)
We have now made this available through Definitely Typed as well which uses exports.