Embedding ArcGIS Online web maps in iBooks

(Contributed by Owen Evans, Esri solution engineer). Embedding maps on the web is a great way to bring your content to places it will benefit people the most such as blog posts, news articles, and press releases. Another place that web maps can be embedded is in electronic textbooks that support web content.

Apple’s iBooks app supports a new generation of e-textbooks that are easy to navigate on the iPad’s touchscreen and can contain many types of interactive content in addition to standard images and text. A few weeks ago, at their recent WWDC developer conference, Apple announced the next version of Mac OS X, due out later this year, will support these iBooks textbooks on laptop and desktop computers.

This post explains how to embed our favorite type of HTML web content – ArcGIS Online web maps – in an iBook. To see what this looks like, you can download this example iBook that has an example map, app, and gallery.

What you’ll need

To create an iBook, you’ll need a Mac computer and Apple’s free iBooks Author software. This software is similar to other word processing tools like Microsoft Word or Apple’s Pages. iBooks Author is available to download from the Mac App Store. At this time iBook textbooks are supported only on the iPad and not the iPhone or iPod touch.

For creating widgets that contain your ArcGIS Online maps you’ll also need iAd Producer, which is Apple’s latest developer tool for making custom HTML widgets that enable iBooks to display web content. Downloading iAd Producer requires you to sign into the Apple Developer website using your AppleID, but you do not need to be a paid member of Apple’s Developer program.

Create a Widget

Using an iBooks HTML widget, you can embed a web map, an app, or even a group shared as a gallery of maps. Note that only HTML/JavaScript apps can be embedded (no Flash or Silverlight apps).

After you download and install iBooks Author and iAd Producer, follow the steps below to create your first HTML widget for iBooks:

  1. From ArcGIS.com, obtain the HTML code needed to embed your map, app, or group.
  2. Create a new HTML iBooks Widget project in iAd Producer and paste the code from step 1 into the HTML view of the new widget.
  3. Export your project as a new iBooks Widget and add it to your iBook in iBooks Author.

In Step 1, your items must be shared publicly to embed them. Also note that you can embed any public map, app, or group whether or not you own it (you don’t even need your own ArcGIS Online account). If you embed an item owned by others, however, realize that you don’t have any control over the item’s availability. If the owner removes the item it will no longer show up in your iBook.

In Step 2, after creating the new widget you’ll need to double click on the <HTML> page created by your widget and then double-click again to get to where you’ll paste the code for your item. There is a placeholder between two <div> tags (“Your HTML here.”) that you replace with your copied code (be sure to leave the <div> tags in tact).

Click to view larger image

Click to view larger image

Improve and Finish the Widget

Once you paste the code into the widget you can customize your widget to make it look and behave better. Below are some tips for doing that. Note: To edit the HTML code after it has been pasted and saved, click the “</> Code” button at the bottom of iAd Producer, then expand the HTML folder, and select htmlView.html – this is where your pasted code appears.

One change you’ll almost always want to make is to resize your iframe so that your map, app, or gallery will fill the iPad screen. A good starting point is 1000px x 730px. Simply edit the “width” and “height” tags in the iframe code to reflect these new dimensions.

Optionally, adjust the widget’s layout using iAd Producer’s WYSIWYG tools. Using the frame handles you can drag and/or resize the HTML element as needed. Crop the frame so that your newly resized iframe is just visible and center it.

You’ll also want to set a few important widget properties in the Project Inspector as you get started, specifically the Widget Title and Bundle Identifier. These are both used by iBooks Author to identify your widget.

Adding a Preview Image will help people understand what your widget contains before it is opened. You can always add or override a preview later in iBooks Author, but adding it directly to the widget in iAd Producer is good practice and will especially help if you end up reusing the widget.

Consider changing the background of the widget to something that will complement (and not compete with) your embedded content. A simple dark grey gradient works well as would a muted image. To set the background, click on the Background layer in Shared Layers, open the Inspector, and set the properties you want in the Background section.

For those of you who are web developers (or have access to developers), you aren’t limited to pasting in the code ArcGIS.com provides and using iAd Producer’s WYSIWYG tools. You can write your own custom HTML, JavaScript, and CSS to embed maps, apps, and galleries with your own styles and functions. You could create a frame that has your organization’s logo and colors or other behavior like a place finder or map switcher. Your code can be added directly to the iBooks widget or hosted as a custom JavaScript template.

To package your finished widget, choose File…Export to Disk (optimized). Now you can drag the resulting .wdgt file right into iBooks Author where you want it to appear. Once you finish your iBook project, export it to iBook format (using the Share… menu in iBooks Author) and open it on your iPad.

Final thoughts

Make sure to have a plan for the content you embed in an iBook; once you release the iBook the links to your content are hardwired. If your services, maps, apps, or groups go away your iBook will break and that will be frustrating to your readers. Certain kinds of changes are ok, for example you can safely change the contents or configuration settings of a web map, app, or group; modify their item descriptions; or add/remove items from an embedded group; however, if you unshare a map that you’ve embedded the iBook widget will show nothing and appear broken. Also, if you change an embedded item so that it no longer matches the text in your iBook that will be confusing to your readers. These thoughts are no different than the ones you’d need to consider if you were embedding content in a website or blog; however, they are more important with an iBook since it is a downloadable item.

Once you create your iBook, you can distribute it for free on your own via email, by posting it to the web (using a web server or a service like Dropbox or Amazon S3), or by submitting it to Apple’s iBookstore. An advantage of using the iBookstore is that it can help issue updates to your iBook to anyone who has downloaded it. For a case where your iBook contains embedded content that may change over time the ability to issue updates may be important. To utilize the iBookstore you’ll also need a free iBooks account and iTunes Producer.

See also:

This entry was posted in ArcGIS Online, Mapping and tagged , , , . Bookmark the permalink.

Leave a Reply


  1. ihamilton63 says:

    Hi There this sounds really interesting, I was wondering if this approach would only work for ArcGIS online Web Maps or would it also work with my own javascript app and services on our server,



    • oevans says:

      Hi Ian — Yes, you can embed apps too! One of the links above is to a previous blog post that shows what code to use for apps — in the “Create a Widget” section above just click on the word “app” in bullet #1 (or, here is the direct link to the blog post about embedding apps in web pages).

  2. cpaloma says:

    Being able to embed ArcGIS Online web maps and web maps and applications from our server will help keep iBook readers focused. Before, the web maps would open in Safari. After readers were done with the web map, it was confusing for them to close Safari and return back to the iBooks application. This will make it much easier for readers. Thanks!

    One suggestion: It would be easier for teachers if the widget was made available through the Bookry widget library.