Getting Started with OSCAR-js

What is OSCAR-js?

OSCAR-js is a JavaScript library that you can use in your web pages to add dynamic web maps OSCAR-js comes with tools for navigation, measurement, download, and more.

How do I use OSCAR-js?

In order to use OSCAR-js in your own website, you will need to download the latest OSCAR-js bundle. Now that you have OSCAR-js, you can use as-is by extracting the contents of the bundle to a sub directory on your website, or right in the root of the site.

You will then have to add the location of the Loader.js file, which is located under oscar/ folder to your web page. For example if you extracted OSCAR-js to a folder 'scripts' in the root of your website you will have to add the following to your web page:

<script src="/scripts/oscar/Loader.js"></script>
Follow the Basic Map Controls to add a map to your website.

What do I need to know to use it?

In order to create web pages in OSCAR-js, you will need to have a working knowledge of HTML and CSS.

Once you have a basic understanding of HTML, you have to know JavaScript. Even if you only know a little bit you can still get some exciting results. Using OSCAR-js requires a minimal amount of written code, but the more you know about JavaScript, the easier it will be to understand how OSCAR-js works.

OSCAR-js uses the concept of Map Themes to display data. These Themes are written in either XML or JSON format, so to put your data into OSCAR-js, you will need to know how to write a file in one of these two formats. XML looks very similar to HTML, so if you can figure out one, you can figure out the other.

Where can I learn these things?

As with most web technologies, you can learn a lot about them by searching the web. W3Schools has a wide variety of online tutorials available, including ones on HTML, CSS, XML, and JavaScript.

Okay, now I know HTML, CSS, XML, and JavaScript. What next?

While it is possible to write all of your web pages in Notepad, there are some tools which can make your life easier.

  • Eclipse: A multi-purpose, open-source, plugin-based development environment. While mainly designed with C/C++/Java in mind, there are plugins for JavaScript and HTML coding as well. You can also set up a wide variety of server types within Eclipse for testing your application.
  • Notepad++: An enhanced version of Notepad. This handy little application provides syntax highlighting and indentation, along with a few other time savers. If you're going for a lightweight development environment, this is as light as you can get.
  • Many of the suggestions in this Stack Overflow discussion are worth considering.

Now I've got the skills, and I've got the tools. What else do I need?

The last thing you need to start making OSCAR-js-enabled web applications is an HTTP server. This is what you will place your application into so that the world can access it through the internet. There are a variety of these available, some of which are open-source and easily available. Use whichever best suits your deployment.

OGC®? WMS? WFS? What's all that about?

The Open Geospatial Consortium, INC. (OGC®) is a standards committee that defines a popular set of standards for sharing map data. OSCAR-js draws its maps using these standards. You don't need to know how these standards are written in order to use OSCAR-js - OSCAR-js will handle all of the OGC requests for you. However, knowing which types of service provide which functionality can help you create more useful mapping applications.

Here is a quick list of the different types of OGC services that OSCAR-js can use:

  • Web Map Service (WMS): A service that provides basic map images. This is where the map you see comes from. It sends images that correspond to the area requested by the application and draws them on your screen. However, it doesn't provide much functionality beyond allowing the client to pan around and look at the map.
  • Web Map Tile Service (WMTS): A WMTS is similar in function to a WMS, but it draws the map using cached tiles instead of getting the server to draw the map every time. For data that doesn't change very often, this can result in a significant speed increase.
  • Web Feature Service (WFS): A service that provides feature data, which is information stored in text files about the attributes of what can be seen on the map. Features can be anything, from roads, to buildings, to park boundaries, to soundings, or buoys. A WFS is typically used in tandem with a WMS - the WMS provides the map, while the WFS is queried for information about the map. A WFS can be used for downloading features as well, using the OSCAR-js Download Manager.
  • Web Coverage Service (WCS): A WCS is used to request coverage data. Like a WFS, it is usually used together with a WMS or WMTS to allow the user to create requests based on a map image. Data from these coverages can then be downloaded using the OSCAR-js Download Manager.

What about Projections?

Because the Earth is round, flat computer screens can't exactly duplicate map data. In order to see the data and make sense of it, it must be projected. Depending on where you are in the world, different projections will be more accurate. For a deeper explanation on how projections work, here are some useful links:

A WMTS works slightly differently. Because a WMTS uses cached tiles, it can only have a certain number of pre-defined zoom levels. These zoom levels are defined by using Scale Sets. Each Scale Set displays the data in a certain projection, then divides the data up into the defined zoom levels.

OSCAR-js supports the use of the following two well-known Scale Sets:

  • GlobalCRS84Scale - This Scale Set is based on EPSG:4326, also known as WGS84. If your data uses this projection, you can use this scale set and it will still appear correctly.
  • GoogleMapsCompatible - Use this Scale Set when you are using the EPSG:900913 or EPSG:3857 projections. These projections are identical, one is just the renamed version of the other. This is the projection used by GoogleMaps and OpenStreetMap, so if you're using data from either of those sources, you need to use this projection to make your data match up.

Because maps are prepared for many different areas of the Earth, there are many different projections. A list of these projections can be found at http://www.epsg-registry.org/, where you can use filters to find the number for the EPSG code you want.

Also, OpenLayers (the technology on which OSCAR-js is built) obtains some of the more obscure EPSG codes from spatialreference.org.

Which browser should I use?

There are two factors to consider when deciding which browser to use with OSCAR-js.

  • OSCAR-js is a JavaScript library. That means it is heavily dependent on each browser's JavaScript engine to function correctly. A browser with a fast, reliable JavaScript engine will result in a much more responsive mapping interface.
  • JavaScript runs in the browser, so you will frequently want to debug your application in the browser window. Therefore, it is desirable for a browser to have some sort of debugging utility.

Here's a list of the top five browsers recommended for use with OSCAR-js:

  • Firefox (with the Firebug plugin installed) provides a handy debugging tool. You can do on-the-fly DOM and CSS manipulation, set JavaScript breakpoints, and track your requests with the Net panel, among other things.
  • Internet Explorer 9 contains a "Developer Tools" panel, which provides much of the same functionality that Firebug does. In addition, you can set the browser to display in different modes, so you can test the application with older versions of IE.
  • Opera comes packaged with Dragonfly.
  • Chrome is another alternative, from Google. It contains Developer Tools and a JavaScript console.
  • Safari is available on Macs, and is based on the same WebKit technology as Firefox and Chrome. It comes with a built-in debugger, which can be accessed from the Advanced preferences (enable the "Develop" menu option).
  • All WebKit-based browsers can use Web Inspector, easily enabled in Chrome and Safari and also available for Firefox. For older versions of Safari, it can also be downloaded from its home page.

Whichever browser you choose to use, it is recommended that you use the most recent version, as it will contain the latest JavaScript updates and fix many HTML/CSS-related bugs.

Finally...am I done?

Yes. When you're ready, start learning how to use OSCAR-js in the "Basic Map" tutorial. Good luck, and have fun adding web mapping to your applications using CARIS OSCAR-js!