am d7170b2a: am 65e62f4f: docs: new web apps dev guides (7bfac24d) · Commits · e / os / android_frameworks_base

docs/html/guide/developing/debug-tasks.jd

+7 −69

Original line number	Original line	Diff line number	Diff line
	@@ -40,10 +40,13 @@ your applications. Here are some tools that you'll use most often:</p>
	your application, which can help you profile the performance of your application.</dd>		your application, which can help you profile the performance of your application.</dd>
	<dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt>		<dt><strong><a href="{@docRoot}guide/developing/tools/ddms.html#logcat">logcat</a></strong></dt>
	<dd>Dumps a log of system		<dd>Dumps a log of system
	messages. The messages include a stack trace when the emulator throws an error,		messages. The messages include a stack trace when the device throws an error,
	as well as {@link android.util.Log} messages you've written from your application. To run		as well as {@link android.util.Log} messages you've written from your application. To run
	logcat, execute <code>adb logcat</code> or, from DDMS, select <strong>Device > Run		logcat, execute <code>adb logcat</code> from your Android SDK {@code tools/} directory or,
	logcat</strong>.		from DDMS, select <strong>Device > Run
			logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT plugin for
			Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from
			<strong>Window > Show View > Other > Android > Logcat</strong>.
	<p>{@link android.util.Log} is a logging		<p>{@link android.util.Log} is a logging
	class you can use to print out messages to the logcat. You can read messages		class you can use to print out messages to the logcat. You can read messages
	in real time if you run logcat on DDMS (covered next). Common logging methods include:		in real time if you run logcat on DDMS (covered next). Common logging methods include:
	@@ -148,72 +151,7 @@ following options (among others):</p>

	<h2 id="DebuggingWebPages">Debugging Web Pages</h2>		<h2 id="DebuggingWebPages">Debugging Web Pages</h2>

	<p>If you're developing a web application for Android devices, you can debug your JavaScript in the		<p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p>
	Android Browser using the Console APIs, which will output messages to logcat. If you're familiar
	debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar
	with the Console APIs. The Android Browser (and the {@link android.webkit.WebChromeClient}) supports
	most of the same APIs.</p>

	<p>When you call a function from the Console APIs (in the DOM's {@code window.console} object),
	you will see the output in logcat as a warning. For example, if your web page
	executes the following JavaScript:</p>
	<pre class="no-pretty-print">
	console.log("Hello World");
	</pre>
	<p>Then the logcat output from the Android Browser will look like this:</p>
	<pre class="no-pretty-print">
	W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82
	</pre>

	<p>All Console messages from the Android Browser are tagged with the name "browser" on Android
	platforms running API Level 7 or higher. On platforms running API Level 6 or lower, Browser
	messages are tagged with the name "WebCore". The Android Browser also formats console messages
	with the log message
	preceded by "Console:" and then followed by the address and line number where the
	message occurred. (The format for the address and line number will appear different from the example
	above on platforms running API Level 6 or lower.)</p>

	<p>The Android Browser (and {@link android.webkit.WebChromeClient}) does not implement all of the
	Console APIs provided by Firefox or other WebKit-based browsers. Primarily, you need to depend
	on the basic text logging functions:</p>
	<ul>
	<li>{@code console.log(String)}</li>
	<li>{@code console.info(String)}</li>
	<li>{@code console.warn(String)}</li>
	<li>{@code console.error(String)}</li>
	</ul>
	<p>Although the Android Browser may not fully implement other Console functions, they will not raise
	run-time errors, but may not behave the same as they do on other desktop browsers.</p>

	<p>If you've implemented a custom {@link android.webkit.WebView} in your application, then in order
	to receive messages that are sent through the Console APIs, you must provide a {@link
	android.webkit.WebChromeClient} that implements the {@link
	android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
	method. For example, assuming that the {@code myWebView} field references the {@link
	android.webkit.WebView} in your application, you can log debug messages like this:</p>
	<pre>
	myWebView.setWebChromeClient(new WebChromeClient() {
	public void onConsoleMessage(String message, int lineNumber, String sourceID) {
	Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID);
	}
	});
	</pre>
	<p>The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
	onConsoleMessage()} method will be called each time one of the Console methods is called from
	within your {@link android.webkit.WebView}.</p>
	<p>When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will
	now look like this:</p>
	<pre class="no-pretty-print">
	D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html
	</pre>

	<p class="note"><strong>Note:</strong> The {@link
	android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
	method was added with API Level 7. If you are using a custom {@link
	android.webkit.WebView} on a platform running API Level 6 or lower, then your Console messages will
	automatically be sent to logcat with the "WebCore" logging tag.</p>




	<h2 id="toptips">Top Debugging Tips</h2>		<h2 id="toptips">Top Debugging Tips</h2>

docs/html/guide/guide_toc.cs

+19 −0

Original line number	Original line	Diff line number	Diff line
	@@ -450,6 +450,25 @@
	</ul>		</ul>
	</li>		</li>

			<li>
			<h2><span class="en">Web Applications</span>
			</h2>
			<ul>
			<li><a href="<?cs var:toroot ?>guide/webapps/targetting.html">
			<span class="en">Targetting Android Devices</span>
			</a> <span class="new">new!</span></li>
			<li><a href="<?cs var:toroot ?>guide/webapps/webview.html">
			<span class="en">Building Web Apps in WebView</span>
			</a> <span class="new">new!</span></li>
			<li><a href="<?cs var:toroot ?>guide/webapps/debugging.html">
			<span class="en">Debugging Web Apps</span>
			</a> <span class="new">new!</span></li>
			<li><a href="<?cs var:toroot ?>guide/webapps/best-practices.html">
			<span class="en">Best Practices for Web Apps</span>
			</a> <span class="new">new!</span></li>
			</ul>
			</li>

	<li>		<li>
	<h2><span class="en">Appendix</span>		<h2><span class="en">Appendix</span>
	<span class="de" style="display:none">Anhang</span>		<span class="de" style="display:none">Anhang</span>

docs/html/guide/webapps/best-practices.jd

0 → 100644

+90 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Best Practices for Web Apps
			@jd:body

			<style>
			.bold li {
			font-weight:bold;
			}
			.bold li * {
			font-weight:normal;
			}
			</style>

			<p>Developing web pages and web applications for mobile devices presents a different set of
			challenges compared to developing a web page for the typical
			desktop web browser. To help you get started, the following is a list of practices you should
			follow in order to provide the most effective web application for Android and other mobile
			devices.</p>

			<ol class="bold">

			<li>Redirect mobile devices to a dedicated mobile version of your web site
			<p>There are several ways you can redirect requests to the mobile version of your web site, using
			server-side redirects. Most often, this is done by "sniffing" the User Agent
			string provided by the web browser. To determine whether to serve a mobile version of your site, you
			should simply look for the "mobile" string in the User Agent, which matches a wide variety of mobile
			devices. If necessary, you can also identify the specific operating system in the User Agent string
			(such as "Android 2.1").</p>
			</li>


			<li>Use a valid markup DOCTYPE that's appropriate for mobile devices
			<p>The most common markup language used for mobile web sites is <a
			href="http://www.w3.org/TR/2008/REC-xhtml-basic-20080729/">XHTML Basic</a>. This standard
			ensures specific markup for your web site that works best on mobile devices. For instance, it does
			not allow HTML frames or nested tables, which perform poorly on mobile devices. Along with the
			DOCTYPE, be sure to declare the appropriate character encoding for the document (such as
			UTF-8).</p>
			<p>For example:</p>
			<pre>
			<?xml version="1.0" encoding="UTF-8"?>
			<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"
			"http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd">
			</pre>

			<p>Also be sure that your web page markup is valid against the declared DOCTYPE. Use a
			validator, such as the one available at
			<a href="http://validator.w3.org/">http://validator.w3.org</a>.</p>
			</li>


			<li>Use viewport meta data to properly resize your web page
			<p>In your document {@code <head>}, you should provide meta data that specifies how you
			want the browser's viewport to render your web page. For example, your viewport meta data can
			specify the height and width for the browser's viewport, the initial web page scale and even the
			target screen density.</p>
			<p>For example:</p>
			<pre>
			<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">
			</pre>
			<p>For more information about how to use viewport meta data for Android-powered devices, read <a
			href="{@docRoot}guide/webapps/targetting.html">Targetting Android Devices</a>.</p>
			</li>


			<li>Avoid multiple file requests
			<p>Because mobile devices typically have a connection speed far slower than a desktop
			computer, you should make your web pages load as fast as possible. One way to speed it up is to
			avoid loading extra files such as stylesheets and script files in the {@code
			<head>}. Instead, provide your CSS and JavaScript directly in the <head> (or
			at the end of the <body>, for scripts that you don't need until the page is loaded).
			Alternatively, you should optimize the size and speed of your files by compressing them with tools
			like <a href="http://code.google.com/p/minify/">Minify</a>.</p>
			</li>


			<li>Use a vertical linear layout
			<p>Avoid the need for the user to scroll left and right while navigating your web
			page. Scrolling up and down is easier for the user and makes your web page simpler.</p>
			</li>

			</ol>

			<p>For a more thorough guide to creating great mobile web applications, see the W3C's <a
			href="http://www.w3.org/TR/mobile-bp/">Mobile Web Best Practices</a>. For other guidance on
			improving the speed of your web site (for mobile and desktop), see Yahoo!'s guide to <a
			href="http://developer.yahoo.com/performance/index.html#rules">Exceptional Performance</a> and
			Google's speed tutorials in <a href="http://code.google.com/speed/articles/">Let's make the web
			faster</a>.</p>

docs/html/guide/webapps/debugging.jd

0 → 100644

+158 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Debugging Web Apps
			@jd:body

			<div id="qv-wrapper">
			<div id="qv">
			<h2>Quickview</h2>
			<ul>
			<li>You can debug your web app using console methods in JavaScript</li>
			<li>If debugging in a custom WebView, you need to implement a callback method to handle debug
			messages</li>
			</ul>

			<h2>In this document</h2>
			<ol>
			<li><a href="#Browser">Using Console APIs in the Android Browser</a></li>
			<li><a href="#WebView">Using Console APIs in WebView</a></li>
			</ol>

			<h2>See also</h2>
			<ol>
			<li><a href="{@docRoot}guide/developing/debug-tasks.html">Debugging Tasks</a></li>
			</ol>

			</div>
			</div>

			<p>If you're developing a web application for Android, you can debug your JavaScript
			using the {@code console} JavaScript APIs, which output messages to logcat. If you're familiar with
			debugging web pages with Firebug or Web Inspector, then you're probably familiar
			with using {@code console} (such as {@code console.log()}). Android's WebKit framework supports most
			of the same APIs, so you can receive logs from your web page when debugging in Android's Browser
			or in your own {@link android.webkit.WebView}.</p>



			<h2 id="Browser">Using Console APIs in the Android Browser</h2>

			<div class="sidebox-wrapper">
			<div class="sidebox">
			<h2>Logcat</h2>
			<p>Logcat is a tool that dumps a log of system messages. The messages include a stack trace when
			the device throws an error, as well as log messages written from your application and
			those written using JavaScript {@code console} APIs.</p>
			<p>To run logcat and view messages, execute
			{@code adb logcat} from your Android SDK {@code tools/} directory, or, from DDMS, select
			<strong>Device > Run logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT
			plugin for Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from
			<strong>Window > Show View > Other > Android > Logcat</strong>.</p>
			<p>See <a href="{@docRoot}guide/developing/debug-tasks.html">Debugging
			Tasks</a> for more information about logcat.</p>
			</div>
			</div>

			<p>When you call a {@code console} function (in the DOM's {@code window.console} object),
			the output appears in logcat. For example, if your web page executes the following
			JavaScript:</p>
			<pre>
			console.log("Hello World");
			</pre>
			<p>Then the logcat message looks something like this:</p>
			<pre class="no-pretty-print">
			Console: Hello World http://www.example.com/hello.html :82
			</pre>

			<p>The format of the message might appear different depending on which version of Android you're
			using. On Android 2.1 and higher, console messages from the Android Browser
			are tagged with the name "browser". On Android 1.6 and lower, Android Browser
			messages are tagged with the name "WebCore".</p>

			<p>Android's WebKit does not implement all of the console APIs available in other desktop browsers.
			You can, however, use the basic text logging functions:</p>
			<ul>
			<li>{@code console.log(String)}</li>
			<li>{@code console.info(String)}</li>
			<li>{@code console.warn(String)}</li>
			<li>{@code console.error(String)}</li>
			</ul>

			<p>Other console functions don't raise errors, but might not behave the same as what you
			expect from other web browsers.</p>



			<h2 id="WebView">Using Console APIs in WebView</h2>

			<p>If you've implemented a custom {@link android.webkit.WebView} in your application, all the
			same console APIs are supported when debugging your web page in WebView. On Android
			1.6 and lower, console messages are automatically sent to logcat with the
			"WebCore" logging tag. If you're targetting Android 2.1 (API Level 7) or higher, then you must
			provide a {@link android.webkit.WebChromeClient}
			that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
			onConsoleMessage()} callback method, in order for console messages to appear in logcat.</p>

			<p>Additionally, the {@link
			android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} method introduced in API
			Level 7 has been deprecated in favor of {@link
			android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} in API Level 8.</p>

			<p>Whether you're developing for Android 2.1 (API Level 7) or Android 2.2 (API Level 8 or
			greater), you must implement {@link android.webkit.WebChromeClient} and override the appropriate
			{@link
			android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
			method. Then, apply the {@link android.webkit.WebChromeClient} to your {@link
			android.webkit.WebView} with {@link android.webkit.WebView#setWebChromeClient(WebChromeClient)
			setWebChromeClient()}.

			<p>Using API Level 7, this is how your code for {@link
			android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} might look:</p>

			<pre>
			WebView myWebView = (WebView) findViewById(R.id.webview);
			myWebView.setWebChromeClient(new WebChromeClient() {
			public void onConsoleMessage(String message, int lineNumber, String sourceID) {
			Log.d("MyApplication", message + " -- From line "
			+ lineNumber + " of "
			+ sourceID);
			}
			});
			</pre>

			<p>With API Level 8 or greater, your code for {@link
			android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} might look like this:</p>

			<pre>
			WebView myWebView = (WebView) findViewById(R.id.webview);
			myWebView.setWebChromeClient(new WebChromeClient() {
			public boolean onConsoleMessage(ConsoleMessage cm) {
			Log.d("MyApplication", cm.{@link android.webkit.ConsoleMessage#message()} + " -- From line "
			+ cm.{@link android.webkit.ConsoleMessage#lineNumber()} + " of "
			+ cm.{@link android.webkit.ConsoleMessage#sourceId()} );
			return true;
			}
			});
			</pre>

			<p>The {@link android.webkit.ConsoleMessage} also includes a {@link
			android.webkit.ConsoleMessage.MessageLevel MessageLevel} to indicate the type of console message
			being delivered. You can query the message level with {@link
			android.webkit.ConsoleMessage#messageLevel()} to determine the severity of the message, then
			use the appropriate {@link android.util.Log} method or take other appropriate actions.</p>

			<p>Whether you're using {@link
			android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} or {@link
			android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)}, when you execute a console method
			in your web page, Android calls the appropriate {@link
			android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
			onConsoleMessage()} method so you can report the error. For example, with the example code above,
			a logcat message is printed that looks like this:</p>

			<pre class="no-pretty-print">
			Hello World -- From line 82 of http://www.example.com/hello.html
			</pre>

docs/html/guide/webapps/targetting.jd

0 → 100644

+419 −0

File added.

Preview size limit exceeded, changes collapsed.