by

Open Mac App Via An Html Link

This article is a simple tutorial designed to teach you some fundamental skills for creating cross platform web applications. You will build a sample School Plan app, which will provide a dynamic “app-like” experience across many different platforms and work offline. It will use Apache Cordova and Mozilla’s Brick web components.

The story behind the app, written by Piotr

I’ve got two kids and I’m always forgetting their school plan, as are they. Certainly I could copy the HTML to JSFiddle and load the plan as a Firefox app. Unfortunately this would not load offline, and currently would not work on iOS. Instead I would like to create an app that could be used by everyone in our family, regardless of the device they choose to use.

We will build

I'm a newbie iPhone developer, writing an app that will kind of be the 'mobile version' of a website. I'm wondering whether it's possible to launch my app from a link in a website. So, for example, someone goes into our site in the iPhone Safari, clicks a link, and our app launches. Is that possible? When another app opens a URL containing your custom scheme, the system launches your app, if necessary, and brings it to the foreground. The system delivers the URL to your app by calling your app delegate’s application(: open: options:) method. Add code to the method to parse the contents of the URL and take appropriate actions.

A mobile application which will:

  1. Display school plan(s)
  2. Work offline
  3. Work on many platforms

Prerequisite knowledge

  • You should understand the basics of HTML, CSS and JavaScript before getting started.
  • Please also read the instructions on how to load any stage in this tutorial.
  • The Cordova documentation would also be a good thing to read, although we’ll explain the bits you need to know below.
  • You could also read up on Mozilla Brick components to find out what they do.

Preparation

Before building up the sample app, you need to prepare your environment.

Installing Cordova

We’ve decided to use Apache Cordova for this project as it’s currently the best free tool for delivering HTML apps to many different platforms. You can build up your app using web technologies and then get Cordova to automatically port the app over to the different native platforms. Let’s get it installed first.

  1. First install NodeJS: Cordova is a NodeJS package.
  2. Next, install Cordova globally using the npm package manager:

Note: On Linux or OS X, you may need to have root access.

Installing the latest Firefox

If you haven’t updated Firefox for a while, you should install the latest version to make sure you have all the tools you need.

Installing Brick

Mozilla Brick is a tool built for app developers. It’s a set of ready-to-use web components that allow you to build up and use common UI components very quickly.

  1. To install Brick we will need to use the Bower package manager. Install this, again using npm:
  2. You can install Brick for your current project using

    but don’t do this right now — you need to put this inside your project, not just anywhere.

Getting some sample HTML

Now you should find some sample HTML to use in the project — copy your own children’s online school plans for this purpose, or use our sample if you don’t have any but still want to follow along. Save your markup in a safe place for now.

Stage 1: Setting up the basic HTML project

In this part of the tutorial we will set up the basic project, and display the school plans in plain HTML. See the stage 1 code on Github if you want to see what the code should look like at the end of this section.

  1. Start by setting up a plain Cordova project. On your command line, go to the directory in which you want to create your app project, and enter the following command:

    This will create a school-plan directory containing some files.

  2. Inside school-plan, open www/index.html in your text editor and remove everything from inside the <body> element.
  3. Copy the school plan HTML you saved earlier into separate elements. This can be structured however you want, but we’d recommend using HTML <table>s for holding each separate plan:
  4. Change the styling contained within www/css/index.css if you wish, to make the tables look how you want. We’ve chosen to use “zebra striping” for ease of reading.
  5. To test the app quickly and easily, add the firefoxos platform as a cordova target and prepare the application by entering the following two commands:

    The last step is needed every time you want to check the changes.

  6. Open the App Manager in the Firefox browser. Press the [Add Packaged App] button and navigate to the prepared firefoxos app directory, which should be available in school-plan/platforms/firefoxos/www.

    Note: If you are running Firefox Aurora or Nightly, you can do these tasks using our new WebIDE tool, which has a similar but slightly different workflow to the App Manager.

  7. Press the [Start Simulator] button then [Update] and you will see the app running in a Firefox OS simulator. You can inspect, debug and profile it using the App Manager — read Using the App Manager for more details.
  8. Now let’s export the app as a native Android APK so we can see it working on that platform. Add the platform and get Cordova to build the apk file with the following two commands:
  9. The apk is build in school-plan/platforms/android/ant-build/SchoolPlan-debug.apk — read the Cordova Android Platform Guide for more details on how to test this.

Stage 2

Html Link Open New Tab

In Stage 2 of our app implementation, we will look at using Brick to improve the user experience of our app. Instead of having to potentially scroll through a lot of lesson plans to find the one you want, we’ll implement a Brick custom element that allows us to display different plans in the same place.

You can see the finished Stage 2 code on Github.

We will be using the brick-deck component. This provides a “deck of cards” type interface that displays one brick-card while hiding the others

  1. First, run the following command in www directory to install the needed entire Brick codebase into the app/bower_components.
  2. To make use of it, add the following code to the <head> of your index.html file, to import its HTML and JavaScript:
  3. Next, all the plans need to be wrapped inside a <brick-deck> custom element, and every individual plan should be wrapped inside a <brick-card> custom element — the structure should end up similar to this:
  4. The brick-deck component requires that you set the height of the <html> and <body> elements to 100%. Add the following to the css/index.css file:
  5. When you run the application, the first card should be visible while the others remain hidden. To handle this we’ll now add some JavaScript to the mix. First, add some <link> elements to link the necessary JavaScript files to the HTML:
  6. cordova.js contains useful general Cordova-specific helper functions, while index.js will contain our app’s specific JavaScript. index.js already contains a definition of an app variable. The app is running after app.initialize() is called. It’s a good idea to call this when window is loaded, so add the following:
  7. Cordova adds a few events; one of which — deviceready — is fired after all Cordova code is loaded and initiated. Let’s put the main app action code inside this event’s callback — app.onDeviceReady.
  8. Brick adds a few functions and attributes to all its elements. In this case loop and nextCard are added to the <brick-deck> element. As it includes an id='plan-group' attribute, the appropriate way to get this element from the DOM is document.getElementById. We want the cards to switch when the touchstart event is fired; at this point nextCard will be called from the callback app.nextPlan.

Stage 3

In this section of the tutorial, we’ll add a menu bar with the name of the currently displayed plan, to provide an extra usability enhancement. We will use Brick’s brick-tabbar component. See the finished Stage 3 code on GitHub.

  1. We need to import the component. Add the following lines to the <head> of your HTML:
  2. Next, add an id to all the cards and include them as the values of target attributes on brick-tabbar-tab elements like so:
  3. The Deck’s nextCard method is called by Brick behind the scenes using tab’s reveal event. The cards will change when the tabbar element is touched. The app got simpler, as we are now using the in-built Brick functionality, rather than our own custom code, and Cordova functionality. If you wished to end the tutorial here you could safely remove the <script> elements that link to index.js and cordova.js from the index.html file.

Stage 4

To further improve the user experience on touch devices, we’ll now add functionality to allow you to swipe left/right to navigate between cards. See the finished stage 4 code on GitHub.

  1. Switching cards is currently done using the tabbar component. To keep the selected tab in sync with the current card you need to link them back. This is done by listening to the show event of each card. For each tab from stored in app.planGroupMenu.tabs:
  2. Because of the race condition (planGroupMenu.tabs might not exist when the app is initialized) polling is used to wait until the right moment before trying to assign the events:

    The code for linking the tabs to their associated cards looks like so:

  3. Detecting a one finger swipe is pretty easy in a Firefox OS app. Two callbacks are needed to listen to the touchstart and touchend events and calculate the delta on the pageX parameter. Unfortunately Android and iOS do not fire the touchend event if the finger has moved. The obvious move would be to listen to the touchmove event, but that is fired only once as it’s intercepted by the scroll event. The best way forward is to stop the event from bubbling up by calling preventDefault() in the touchmove callback. That way scroll is switched off, and the functionality can work as expected:

You can add as many plans as you like — just make sure that their titles fit on the screen in the tabbar. Actions will be assigned automatically.

To be continued …

We’re preparing the next part, in which this app will evolve into a marketplace app with downloadable plans. Stay tuned!

[EDIT] See the next part where we separated data from DOM.

About Piotr Zalewa

Piotr Zalewa is a Senior Web Developer at Mozilla's Dev Ecosystem team. Working on web apps. He is the creator of JSFiddle.

About Chris Mills

Chris Mills is a senior tech writer at Mozilla, where he writes docs and demos about open web apps, HTML/CSS/JavaScript, A11y, WebAssembly, and more. He loves tinkering around with web technologies, and gives occasional tech talks at conferences and universities. He used to work for Opera and W3C, and enjoys playing heavy metal drums and drinking good beer. He lives near Manchester, UK, with his good lady and three beautiful children.

Technical Q&A QA1633
LinkNew

Q: How can I create easy-to-read short links to the App Store for my apps and company?

A: The iTunes and App Store apps generate URLs for all apps and companies available in the App Store and Mac App Store by clicking the disclosure triangle next to the app's price (or by right-clicking/control-clicking the app icon) and selecting 'Copy link', or by using iTunes Link Maker. These URLs look similar to Listing 1.

Listing 1 Standard App Store Links.

These URLs are great for linking to your app or company page in the App Store or Mac App Store from your website or inside your app, or anywhere you don't need to type or speak the URL. As a rule, always use these standard links when driving users to your app from your digital marketing communications.

Important: If you're using itunes.apple.com URLs in your app, see Launching the App Store from an iPhone application for important information.

You can also create easy-to-read links to your app using App Store Short Links, which use the AppStore.com base URL plus a specific form of your app or company name. These short links are ideal for use in offline communications materials like print ads, TV spots, app trailers, radio ads and billboards where you need a memorable URL.

Note: Previously, short links were available using the itunes.com URL. AppStore.com replaces itunes.com. iTunes.com links will continue to work but should be updated as soon as feasible.

There are three types of App Store Short Links, in two forms, one for iOS apps, another for Mac Apps:

Company Name

  • iOS: http://appstore.com/<companyname> for example, http://appstore.com/apple

  • Mac: http://appstore.com/mac/<companyname> for example, http://appstore.com/mac/apple

App Name

  • iOS: http://appstore.com/<appname> for example, http://appstore.com/keynote

  • Mac: http://appstore.com/mac/<appname> for example, http://appstore.com/mac/keynote

App by Company

  • iOS: http://appstore.com/<companyname>/<appname> for example, http://appstore.com/apple/keynote

  • Mac: http://appstore.com/mac/<companyname>/<appname> for example, http://appstore.com/mac/apple/keynote

Most companies and apps have a canonical App Store Short Link. This canonical URL is created by changing or removing certain characters (many of which are illegal or have special meaning in a URL (for example, '&')).

To create an App Store Short Link, apply the following rules to your company or app name:

  • Remove all whitespace

  • Convert all characters to lower-case

  • Remove all copyright (©), trademark (™) and registered mark (®) symbols

  • Replace ampersands ('&') with 'and'

  • Remove most punctuation (See Listing 2 for the set)

  • Replace accented and other 'decorated' characters (ü, å, etc.) with their elemental character (u, a, etc.)

  • Leave all other characters as-is.

Listing 2 Punctuation characters that must be removed.

Below are some examples to demonstrate the conversion that takes place.

App Store

Company Name examples

  • Gameloft => http://appstore.com/gameloft

  • Activision Publishing, Inc. => http://appstore.com/activisionpublishinginc

  • Chen's Photography & Software => http://appstore.com/chensphotographyandsoftware

App Name examples

  • Ocarina => http://appstore.com/ocarina

  • Where’s My Perry? => http://appstore.com/wheresmyperry

  • Brain Challenge™ => http://appstore.com/brainchallenge

Mac App Store

Company Name examples

  • PopCap => http://appstore.com/mac/popcap

  • Autodesk Inc. => http://appstore.com/mac/autodeskinc

  • Chen's Photography & Software => http://appstore.com/chensphotographyandsoftware

App Name examples

Open Html File On Mac

  • Pixelmator => http://appstore.com/mac/pixelmator

  • Human Japanese => http://appstore.com/mac/humanjapanese

  • F1 2012™ => http://appstore.com/mac/f12012

Open Mac App Via An Html Link Web

All URLs are accessible worldwide and will direct the customer to their respective country's App Store. Because of the possibility of name conflicts or other errors, URLs which have multiple results, for example <http://appstore.com/airhockey>, will return a search page. Using unique names for your apps will help prevent this.

If you experience incorrect results (for example, a URL which doesn't go where you expect it would) or if there are characters you would like to see removed or changed, please file a bug report via <http://developer.apple.com/bugreporter> with the following information:

  • Full current or desired URL, for example, http://appstore.com/mysuperapp

  • Applicable countries

  • The iTunes-generated URL to the desired landing page, which you get by clicking the disclosure triangle next to the app's price (or by right-clicking/control-clicking the app icon) and selecting 'Copy link' (for example, http://itunes.apple.com/us/app...)

These App Store Short Links are provided as a convenience and are not guaranteed to link to a particular app or company. Be sure to test your URLs before using them in any marketing or other public materials. If there are naming conflicts, continue using the standard itunes.apple.com URLs, which contain a unique numerical identifier within the URL.


Document Revision History


DateNotes
2013-04-24

Added reference to iTunes Link Maker; removed reference to r. 7414684 (itunes.apple.com links to your company's page give an error) as issue is fixed. Minor editorial changes.

2013-02-21

Minor changes to URLs

2013-01-31

Updated to reflect App Store Short Links (appstore.com) and Mac App Store options.

2010-01-25

Corrected link to QA1629; fixed a company name misspelling.

2009-12-10

New document that describes how to create appstore.com short URLs to the App Store.




Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-04-24