Preventing Links In Standalone iPhone Applications From Opening In Mobile Safari

By Ben Nadel

Published 2011-12-27 in JavaScript / DHTML — Comments (47)

When developing web applications for the iPhone, one of the cool things that you can do is save your web application to the "home screen" of your phone. This creates a shortcut to your web application which will launch the site in "standalone mode" or "app mode". When your web application is being viewed in standalone mode, anchor tags (ie. links) open up in the mobile Safari browser which jumps you out of your standalone application. I thought this was just an irritating fact of life. But then yesterday, I came across a Gist by Kyle Barrow that demonstrated how to stay in the iPhone's standalone app mode while still changing the URL of the current document.

The trick, as demonstrated by the Gist, was to prevent the default behavior of links. Instead of letting the browser handle the link actions, we could use event handlers to intercept the click event and manually change the location of the window. In doing so, we can jump from page to page without having to exit the standalone mode and jump into mobile Safari.

Since this was completely changing the way that I understood standalone mode / app mode on the iPhone, I naturally wanted to do some testing. To see this in action, I created two pages that linked to each other:

Index.htm

<!DOCTYPE html>
<html>
<head>
	<title>Index</title>

	<!-- Stand-alone settings for iOS. -->
	<meta name="apple-mobile-web-app-capable" content="yes" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
	<meta name="apple-mobile-web-app-status-bar-style" content="black" />

	<!-- Load scripts. -->
	<script type="text/javascript" src="./jquery-1.7.1.min.js"></script>
	<script type="text/javascript" src="./links.js"></script>
</head>
<body>

	<h1>
		Hello, Index Here
	</h1>

	<p>
		Go to <a href="./index2.htm">Index 2</a>.
	</p>

</body>
</html>

Index2.htm

<!DOCTYPE html>
<html>
<head>
	<title>Index 2</title>

	<!-- Stand-alone settings for iOS. -->
	<meta name="apple-mobile-web-app-capable" content="yes" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no" />
	<meta name="apple-mobile-web-app-status-bar-style" content="black" />

	<!-- Load scripts. -->
	<script type="text/javascript" src="./jquery-1.7.1.min.js"></script>
	<script type="text/javascript" src="./links.js"></script>
</head>
<body>

	<h1>
		Hello, Index 2 Here
	</h1>

	<p>
		Go to <a href="./index.htm">Index</a>.
	</p>

</body>
</html>

As you can see, both of these pages use a Meta tag with the "apple-mobile-web-app-capable" setting enabled. This allows the pages to be used in standalone mode / app mode once they are saved to the home screen of the iPhone.

The JavaScript file, links.js, is where we have the script that overrides the default behavior of links in order to keep the standalone web application in standalone mode.

links.js

// Listen for ALL links at the top level of the document. For
// testing purposes, we're not going to worry about LOCAL vs.
// EXTERNAL links - we'll just demonstrate the feature.
$( document ).on(
	"click",
	"a",
	function( event ){

		// Stop the default behavior of the browser, which
		// is to change the URL of the page.
		event.preventDefault();

		// Manually change the location of the page to stay in
		// "Standalone" mode and change the URL at the same time.
		location.href = $( event.target ).attr( "href" );

	}
);

Since this is just a test, I'm not worrying about local links vs. external links vs. document links; I'm just overriding all links in the document. And, in order to do this in the most efficient way possible, I'm using jQuery's event delegation to assign a single, top-level event handler to all links on the page. When a click event is detected, we cancel the default behavior (which is to open in mobile Safari) and then manually change the window's location. This approach allows the page to be changed without breaking the iPhone standalone application experience.

This is pretty awesome! Up until now, I've thought that iPhone-targeted web applications had to keep all of the required code on a single page. Now that I see that the URL of a standalone application can be changed without jumping into mobile Safari, things are going to get a good deal easier.

Want to use code from this post? Check out the license.

Short link: https://bennadel.com/2302

Reader Comments

Jon Wolski Dec 27, 2011 at 11:45 AM

1 Comments

I don't have an iphone to test this, but could you not simply add target="_self" (via markup or javascript) to those links which need to open in the current window?

Djam Dec 27, 2011 at 2:23 PM

2 Comments

Ben,

returning false in the handler will have the same effect:

$('a').click( function() { location.href = $( this ).attr( "href" ); return false; });

Ben Nadel Dec 27, 2011 at 2:51 PM

15,848 Comments

@Jon,

I haven't tested that yet; but, I think it would still open up in mobile Safari. I'll have to get back to you on that, though.

@Djam,

Good point! The only thing to be careful of is that returning false prevents the default behavior *and* stops propagation. Since the delegation is at the root of the document, I don't think it would be a problem (since I don't believe it stops immediate propagation); but, you just want to be careful not to stop the triggering other event handlers that may or may not be bound to a[click].

Djam Dec 27, 2011 at 4:20 PM

2 Comments

@Ben

Thanks for enlightening!

Radoslav Stankov Dec 27, 2011 at 5:32 PM

1 Comments

Good trick.

Do you know an easy way to check (via js) if our site runs as stand alone app or is running in Safari?

Ben Nadel Dec 27, 2011 at 5:38 PM

15,848 Comments

@Djam,

My pleasure!

@Radoslav,

Yeah, you can actually check for the existence of some JavaScript objects to determine if the browser is in "app mode":

www.bennadel.com/blog/1950-Detecting-iPhone-s-App-Mode-Full-Screen-Mode-For-Web-Applications.htm

Priit Dec 28, 2011 at 3:08 AM

6 Comments

Well, if you are developing web applications, as you say in first sentence, then you must let go of thinking in web pages. Web page needs to be accessible, usable and crawlable by links, but web application absolutely needs not. My way is to ditch links (<a> tags) completely when developing web apps. If something in web app needs to be resposive to the click, add click handler to it and thats it :-) Generally the same with anything which requires Javascript - ditch links from html.

Doug Dec 28, 2011 at 10:33 AM

6 Comments

how would about handling a form post? would that open in mobile safari?

Ben Nadel Dec 28, 2011 at 11:01 AM

15,848 Comments

@Priit,

You bring up a good point - once we get into the realm of creating "applications", we do need to shift our point of view. The same rules don't necessarily apply.

As an aside, on that topic, however, I think I remember PPK once mentioning that on mobile browsers, items that aren't a true [A] tag need to have a "cursor: pointer" in order for the click events to register. I could be mis-remembering though, and I don't recall which mobile OS he was talking about (I think iPhone).

@Doug,

Hmm, that's an excellent question! I assume you're correct - I can't think of anyway to submit a form manually without invoking the native behavior. Perhaps this only works with links.

Priit Dec 28, 2011 at 11:30 AM

6 Comments

No, I'm not aware of that and that would be illogical too (presentational messes with DOM?). So far everything registers clikcs for me, I have global handler in my apps, exactly like you in this example - only one handler, attached to document and all goes through that.

On the other hand - you need to set cursor:pointer anyway, assuming that your app is universal :-)

Ben Nadel Dec 28, 2011 at 11:36 AM

15,848 Comments

@Priit,

I did some Googling and found the old blog posts from PPK:

http://www.quirksmode.org/blog/archives/2010/10/click_event_del_1.html

I think someone, somewhere suggested that it might have to do with the fact that a touch-screen needs more points of data to help figure out which item was intended to receive the touch event (since the finger is large).

Priit Dec 28, 2011 at 12:00 PM

6 Comments

:-)
Did too and you are correct. OTOH I do not use any actual click events on touch interfaces at all because of that 300ms delay. I have written my own handler who handles either mouseupdowns or touchstartends and creates virtual clicks. So this is the reason I didn't know.

WebManWalking Dec 28, 2011 at 3:03 PM

290 Comments

@Doug,

jQuery.post() can do an HTTP post request, so you can code an onsubmit that does that, then returns false.

I'm such a creature of habit. I originally ended the previous paragraph with a semicolon.

Alexander Dec 30, 2011 at 2:21 PM

5 Comments

How do you get the cool video of your iphone while yer developing

Neil Jan 3, 2012 at 1:13 PM

6 Comments

Love it!

Joe Danziger Feb 15, 2012 at 1:13 AM

1 Comments

Hey Ben - do you think it's still possible to keep things loading in the stand alone web app even when using an iframe? I've been able to use your technique above successfully, but when I try to utilize iframes, such as in a lightbox, any links in the iframe bust out and load in Safari instead of continuing within the iframe. Any insight you might have is appreciated..

Thanks,
-Joe

Salomon Mar 16, 2012 at 7:19 AM

1 Comments

Thx man, this was a BIG issue for me!! You code worked flawlessly

Matt Mar 20, 2012 at 7:32 PM

1 Comments

Thanks!! This bug was a thorn in my side. Login form was working, then when a user clicked something it opened in Safari and prompted a login again! What a pain. By swapping the link functionality I'm able to keep the entire experience in standalone mode. Thanks.

Andi Mar 29, 2012 at 5:26 AM

1 Comments

Hey Ben, i´ve got a question:
Everything works well with the standalone mode, except for one thing: Some things i´ve changed in the CSS dont work in "standalone-mode"; just simple thinks like: body{background-color:#fff}.
I´m testing it on a Iphone and deleted the cookies and caches many times!

You have any idea how to solve my problem??

Thanks in advance,

greetings, Andi

Ryan Kelly May 15, 2012 at 4:24 PM

2 Comments

I was having difficulty with making this work with images that were wrapped in a link, as the img tag obviously has no href.

Anywho, this slightly modified version solved that for me:

// Listen for ALL links at the top level of the document. For
// testing purposes, we're not going to worry about LOCAL vs.
// EXTERNAL links - we'll just demonstrate the feature.
$(document).on(
	"click",
	"a",
	function(event){
		// Stop the default behavior of the browser, which
		// is to change the URL of the page.
		event.preventDefault();
		// Manually change the location of the page to stay in
		// "Standalone" mode and change the URL at the same time.
		// Get href of parent if clicked on an image.
		if(!$(event.target).attr("href")){
			location.href = $(event.target).parent().attr("href");
		}
		else{
			location.href = $(event.target).attr("href");
		}
	}
);

Tobias Topyla Jul 14, 2012 at 7:25 PM

1 Comments

Dear Ben,

Thank you for this complete guide that worked for me as well.

In my opinion you should add a check to your guide that looks for the HTTP_USER_AGENT to avoid that the code is not executed in case there is no mobile Safari user calling the web page.

Rumors about iOS 6 are saying that it will come finally with an optional full-screen mode anyway.

Kind regards
Tobias Topyla

Tiffany Jul 19, 2012 at 10:10 AM

1 Comments

hey there, i have used your link.js codes and the other one on my iphone web ap, but its blocking my links to external sites like facebook and twitter, as much as the social medium annoys me it's an imperative part of my business. Do you have some secret else if or else javascript code i can add to the link.js file that you created and i am now using to allow http request to go ahead? thanks in advance, Tiff. love your work BTW!

Ryan Kelly Jul 19, 2012 at 10:19 AM

2 Comments

@Tiffany,

It sounds like we had a similar issue. I wanted links to some sites to open in mobile Safari, so I modified this. If a link with class "external" is clicked, the default behavior occurs. Otherwise, the usual links.js business happens.

SO:

create link with class="external"
new links.js code is:

$(document).on(
	"click",
	"a",
	function(event){
		if(!$(this).hasClass("external")){
			event.preventDefault();
			if(!$(event.target).attr("href")){
				location.href = $(event.target).parent().attr("href");
			}
			else{
				location.href = $(event.target).attr("href");
			}
		}
		else {
		}
	}
);

JohnO Aug 9, 2012 at 4:35 AM

3 Comments

Ben I have used white label app design compamys 1 kept most links in Web APP except Google Maps I think.

Another I use now starts from icon in What I will call standalone mode then on 1st link shows url bar.

Well I like it staying in so I tried ur 2 js files and 2 index files.

And it worked!!! Nice!!!

Now I had written a bunch of redirects on another domain that is a subdomain of my main MobileAdvertisingAPPs.com

The Redirects were to allow smartphone people to type a lot less thus making less mistakes.

Well ur technique worked for a few times. Then I would start in index.htm
and click on the link to go to index2.htm and it would go to My Main Domain MobileAdvertisingAPPs.com and its minisite for detected mobile phones with code error 404.

However in My full size browser it would also go to My Full size site not my small redirect site.

What I noticed was in my big browser If I click on link it gets 404 error.

But if i right click and tell it open in new tab it goes to the correct file the index2.htm.

To me and I am very new to all this.
It seems almost like the js files is a dynamic file. Like someone is changing it over the time I am using it. I assume this cant be so since the files reside on my host.

So it worked ok - then it got Error 404 then later it worked ok.

I never edited the js files. But I was reading on the jQuery.com it said something about using the mobile version which they refer to as stable.

So I downloaded it wrote it into the index & index2.htm files

so if u would try it on my system.
at getvips.com/myapp/index.htm

When I click on the link in Index.htm link it goes to MobileAdvertisingAPPs.com whether i use my iphone 4 or my PC.

The iphone gets redirected to the mobile optimized site the PC of course does not.

I love how it works - when it works right.

The white label apps i used b4 worked well every time. Has anyone else had these kind of problems?

And is there a problem using the mobile version jquery.mobile-1.1.1.min.js

I only tried it when i had problems but have left it in my index.htm code for now since jQuery said it recommended using Mobile. I know i am rambling just want to get this worked out. I will give u my phone if u would be willing to call me.

What about the comments above are any of them a better way to implement this?

Thanks in Advance
JohnO

JohnO Aug 9, 2012 at 4:55 AM

3 Comments

ps so far it seems the index2.htm link always works ok.

Seems the only problem is with the Index.htm

JohnO Aug 9, 2012 at 5:45 AM

3 Comments

Ben dont know if this will help u but a developer group named uncorked works with mobile and sprites. I was looking for a way to show some things and animated gif the white label I use didnt support them they said check ouot spritely.net Hope this helps.

Stephen Aug 9, 2012 at 5:36 PM

1 Comments

So, I'm using the latest version of the ipad. Also using the "apple-mobile-web-app-capable" & "viewport" tags.

Not using the jquery code and everything seems to be working fine, EXCEPT: The CSS to the second page I'm linking to isn't working. It does open up full screen as it should, but again, the styles are missing.

Note: the css works fine when NOT in app mode, but for some reason, none of my styles are showing when IN app mode.

Has anyone else run into this problem?

Thanks in advance,
Stephen

Elliot Taylor Aug 20, 2012 at 10:36 AM

1 Comments

Can you guys please confirm this is working on your current sites in iPhone?

Can't get to work - so just checking if iOS 5 has put an end to this.

Thanks

Shawn Rhoney Dec 14, 2012 at 6:09 PM

1 Comments

This still works on iOS 5.

Muhammadibn Jan 3, 2013 at 9:03 AM

2 Comments

Hi, Thanks for the tutorial.

Just a question: I have been able to open all links within the web-app which is great. My web-app opens a PDF file within the web-app but the problem I'm having is that there is way of returning back to the main page from the PDF.

Any help will be much appreciated.

Thanks

Stephen Feb 10, 2013 at 5:50 AM

2 Comments

Hi,

Great stuff. Except when lauching from the Home screen and touching index2 it's slides away and opens new instance of mobile Safari. I can then seamlessly click between index2 and index without a new instance opening but the Mobile Safari address bar remains at the top of the screen.

I'm assuming it's ignoring the non Mobile Safari code?

I'm using iOS 6.1 on iPhone 4

Any help would wonderful!

Cheers,

Stephen

Stephen Feb 10, 2013 at 8:24 AM

2 Comments

Further to this, I'm not sure any JS is being loaded?
As if I delete the JS from the server and run
It show the same behaviour. This is after clearing the cache

Brandon May 23, 2013 at 9:52 PM

1 Comments

@Muhmmadibn

Did you figure out a solution to launching PDFs? I am running into the same issues myself. There is no way to close the PDF or go back once you launch it.

Thanks in advance!

Muhammadibn May 24, 2013 at 9:11 AM

2 Comments

@Brandon,

Hi, No, I haven't been able to do that. I have just kept it as it is.

Loren Jun 13, 2013 at 9:33 PM

1 Comments

This seems great, very useful. I am having an issue calling the link however after the default is blocked. I copied the code in as is and on iOS, the web app is not launching safari upon click. However it is no longer able to load the linked pages. The page returns as undefined. I have the same result in my desktop browser. Any idea why this wouldn't be working?

Thiago Ogoshi Sep 10, 2013 at 10:46 PM

1 Comments

Hello,

I just tried the code and it`s not working for me... I tested in the iOS Simulator and at my iPhone and none of them worked as expected...

I just copied and pasted the code. Here`s the page:

http://www.ogoshi.com.br/job/

Any advice?

Rich Hosek Oct 23, 2013 at 1:55 PM

1 Comments

For those of you using the modified version to check for the presence of a nested tag in the link:

if(!$(event.target).attr("href")){
	location.href = $(event.target).parent().attr("href");
} else {
	location.href = $(event.target).attr("href");
}

and better way to handle nesting of any depth is to use the jQuery closest method:

location.href = $(event.target).closest("a").attr("href");

this will traverse the DOM starting with the target element and find the first ancestor that is an <a> tag.

Maurice Griffin Dec 4, 2013 at 2:57 PM

1 Comments

@Brandon, @Muhmmadibn,

I too am trying to figure out a way to deal with this. I have a webapp which downloads generated PDFs, and there is no way to leave them or do anything else.

If I could get them to print instead of download that would work, but since data is sent to the server and a PDF is returned, I have not found a way to keep it from taking over the full-screen webapp in iOS.

Bruno (Antonio Carlos Bruno) Dec 21, 2013 at 6:12 AM

1 Comments

Hi,

I use CLASSIC ASP in my applications, but, when i click in the link, the next page open in safari and not in your script.

Sorry, my english is very bad!

Tks a lot for your dedication !

Best regares !

Bruno form Brazil !

Robert Feb 3, 2014 at 6:58 PM

1 Comments

works great. though i would consider changing

event.preventDefault();

if ($( event.target ).prop( "tagName" ) !== "IMG")
event.preventDefault();

so you don't have issue with IMG tags

Antonio Martinez Feb 20, 2014 at 6:20 PM

1 Comments

How do you get this to work with jQuery Mobile 1.4.1?

Luke Feb 20, 2014 at 6:47 PM

1 Comments

I am having trouble getting this to work with 3 different image maps I have. Everything else is working great. Do you have any advice on how to adjust this code to address image maps?

Rich Lingan Feb 26, 2014 at 8:39 AM

1 Comments

How can the link /jump association be preserved when saving as a standalone through the normal user interface controls without additional programming?
I'm a stage lighting and audio professional and the programming takes me a gazillion times longer than if my IT skills included more programming. I really enjoy the challenge and your great brainstorming. You all seriously rock!

Emily Mar 21, 2014 at 3:04 AM

1 Comments

In the event that I could get them to print rather than download that might work, however since information is sent to the server and a PDF is returned, I have not figured out how to keep it from assuming control over the full-screen webapp in ios.

http://www.theweb77.com/simple-website
http://bestappsnwebdesigners.blogspot.com

Fre Jun 29, 2014 at 6:11 PM

1 Comments

Hi all

Anyone managed to integrate in web-app-payments (without leaving the standalone mode)?

I currently use PayPal, but that opens up a page in safari…

Thanks!
Fred

Noorein Aug 20, 2014 at 4:02 AM

2 Comments

Hi, I just love the entire post and beautiful collection of. And I make sure to visit your site often.I would like to thank you for sharing this information.
< a href="http://kharidoatoz.com ">Noorein</a>

Wayhoy Sep 7, 2014 at 6:09 AM

1 Comments

Thank,
your script was useful for us.

Oh my chickens, this post is old!

Hit me up on Twitter if you want to discuss it further.