Tutorial for OpenLayers?

In addition to the above excellent answers, let me add my own experience. A year and a half ago I decided I wanted to use OpenLayers (OL) in my Master's project and set out to learn it. I have been doing programming and digital map making as part of my work as an archaeologist since the early 1980s, and have been an ArcGIS user for 15 years. I am happy I choose OL for my project, but it wasn't always a smooth path learning it. Some things were not obvious and learned only by trial and error. So, I have some advice for beginners.

My journey learning OL really got going when I signed up for a 5-slot bookshelf account on Safari Books Online for $10/month USD. I wanted to review books before buying, and few stores one can visit carry GIS-related computer books. There are three books out now on OL 2. A newer 58-page book called Instant OpenLayers Starter by Di Lorenzo and Allegri (Apr 2013) is a good quick start, but the first two books and their code samples (available from the publisher's web site, along with a free sample chapter of each book) were good resources:

• OpenLayers 2.10: Beginner's Guide by Erik Hazzard (March 2011)
• OpenLayers Cookbook by Antonio Santiago Perez (August 2012)

Due to occasional frustrations over css and browser compatibility, I ended up learning a JavaScript framework as well. I choose Dojo because this is what Perez used in his book. Modern Dojo (Dojo 1.7 +) is a significantly different approach from earlier versions, using an Asynchronous Module Definition (AMD) format. The way of doing everything changed. I did not understand that this otherwise excellent book uses a pre-1.7 version of Dojo that was made obsolete 9 months before the book was published in August 2012. Esri continued using the pre-1.7 Dojo in their JavaScript ArcGIS API until modernizing in June 2012, and this was a painful switch for many ArcGIS Javascript developers.

To understand how poorly supported Dojo is, other than a book written in 2010 about Dojo 1.3, most of the books were written in 2007 and 2008. There are no published books for Modern Dojo--you must learn from online resources, almost all of which are on their web site. Basically, to work with the examples in Perez's book, you need to know enough about JavaScript to ignore the Dojo bits and move the examples into plain JavaScript or your framework of choice.

In retrospect, I wish I had gone with the ExtJS framework and GeoExt. ExtJS is free if your project is open source, and because many companies happily pay for a supported version, they can afford to spend time on comprehensive web site documentation and tutorials.

I learn best by working with/hacking apart examples. The developers at OpenLayers have this same philosophy as the primary documentation they point to for learning is examining the examples. However, some OL examples on their web site and elsewhere have issues that can make beginners stumble. (See below.)

The reliance on examples as documentation also means that the user does not have a sense of a good work flow for developing a web map. This can lead to making maps that feel incomplete--for instance, they may lack css customizations to the maps user interface and "look and feel." Overriding the OL css with customizations feels daunting to the beginner, but Firebug can help you find the element names that you need to override. The lack of a sense of an accepted work flow can also lead to the creation of Frankencode, as users shoehorn features into their code as they find they want it.

This leads me to the last item that I feel the OL site documentation lacks, a sense of "best practices" for OL maps. Is there a better way to organize my code to make it modular and robust? What are the pitfalls with JavaScript closures and OL objects? Where should I declare my styles? And so on.

Other than the various outdated files in the Wiki, there are two general issues a beginner should be aware of when learning from the official OL examples and API documents. First, there is no organization to the page of OL development examples on the OL web site. It is simply presenting the feed from the xml file in that directory (example-list.xml) of the examples (207 of these as of 13 Feb 2014) and sorting the rows alphabetically by filename into a grid. More advanced examples are mixed with basic ones. You can search the examples by keyword, but many of the examples lack keywords and the search feature includes content and page title in the search, not just keywords. The results are returned with highest number of search terms matched first followed by word frequency. Only one of the search terms need be a match to show up in the results. The UserRecipes page on the OL Wiki lists about 90 examples organized by category, and this categorization is a help. Of these, 66 are live links to the examples on the examples page and the rest are bad links to removed examples.

Second, there are basically two versions of the API documentation which appear to be the same at first glance. The official API is in a directory called /apidocs and the bleeding edge, but volatile, developer library is in a directory called /docs. The URLs are the same otherwise. (There are also trunk versions.) Just edit the address of the page to see the other version. The Wiki notes that the developer library should not be relied upon as properties, functions, etc. might be removed from the library at any time. With OpenLayers 3 being close to reality (it is available in beta and there is a book out on it now), I suspect that not too much will change in OL 2 in the future. The focus now is on OL 3.

In general, I find the OL API pages to be overly skeletal, often lacking explanations or illustrative examples, especially for someone used who is to libraries with more complete API documentation. The way it is presented you don't get a clear picture of the object it is inheriting from.

Of the OL examples on the web in general, many use objects or syntax that has been deprecated because it has been replaced by improved versions. For instance, Layer.Vector is now the preferred way of drawing markers as Layer.Marker is deprecated in version 3. Examine the file deprecated.js to make sure you are not using objects that are on the way out. Or, at least be aware if you upgrade your code to OL 3 you will need to change this.

In addition to the Boundless OpenLayers workshop linked by Julien-Samuel Lacroix above, IBM has a cool tutorial, albeit three years old, that uses OpenLayers, MapServer, Google Gears, and jQuery to build a complete GIS web app: Bring data together with OpenLayers: Using data from multiple divergent sources in web maps

Also, check out this useful post on styling the layer switcher

Google the words OpenLayers and jsFiddle to get some examples of OL fiddles. The result from the techslides site is a page listing quite a few of these.

Last, beware that the map images in most examples are from OpenStreetMap (OSM) servers and these go down every now and then, planned or unplanned, and you will get pink tiles in their place. Sometimes you will think you screwed up your code. You can check platform status on the OpenStreetMap wiki.

While the others have suggested good online tutorials, let me tell you about the book that gave me a much needed strong foundation in OpenLayers.

The book is: Erik Hazzard's OpenLayers 2.10 Beginner's Guide. It is available from Packt Publishers.

I would strongly recommend the book, because it deals with all major parts of the Library. It starts from basics, and slowly helps you grow towards complicated parts of the API.

Look at the Boundless OpenLayers workshop. It covers a lot of material. The workshop is using GeoServer instead of MapServer, but you can simply change the URL of the example to your MapServer WMS service.