Skip to content

Commit 65e62f4

Browse files
scottamainscottamain
committed
docs: new web apps dev guides
Change-Id: I08b80de0544fec5d46a58e1c1b4c0e2ff1fd4fa2
1 parent ef5afa0 commit 65e62f4

File tree

11 files changed

+1021
-69
lines changed

11 files changed

+1021
-69
lines changed

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

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

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

151-
<p>If you're developing a web application for Android devices, you can debug your JavaScript in the
152-
Android Browser using the Console APIs, which will output messages to logcat. If you're familiar
153-
debugging web pages with Firefox's FireBug or WebKit's Web Inspector, then you're probably familiar
154-
with the Console APIs. The Android Browser (and the {@link android.webkit.WebChromeClient}) supports
155-
most of the same APIs.</p>
156-
157-
<p>When you call a function from the Console APIs (in the DOM's {@code window.console} object),
158-
you will see the output in logcat as a warning. For example, if your web page
159-
executes the following JavaScript:</p>
160-
<pre class="no-pretty-print">
161-
console.log("Hello World");
162-
</pre>
163-
<p>Then the logcat output from the Android Browser will look like this:</p>
164-
<pre class="no-pretty-print">
165-
W/browser ( 202): Console: Hello World http://www.example.com/hello.html :82
166-
</pre>
167-
168-
<p>All Console messages from the Android Browser are tagged with the name "browser" on Android
169-
platforms running API Level 7 or higher. On platforms running API Level 6 or lower, Browser
170-
messages are tagged with the name "WebCore". The Android Browser also formats console messages
171-
with the log message
172-
preceded by "Console:" and then followed by the address and line number where the
173-
message occurred. (The format for the address and line number will appear different from the example
174-
above on platforms running API Level 6 or lower.)</p>
175-
176-
<p>The Android Browser (and {@link android.webkit.WebChromeClient}) does not implement all of the
177-
Console APIs provided by Firefox or other WebKit-based browsers. Primarily, you need to depend
178-
on the basic text logging functions:</p>
179-
<ul>
180-
<li>{@code console.log(String)}</li>
181-
<li>{@code console.info(String)}</li>
182-
<li>{@code console.warn(String)}</li>
183-
<li>{@code console.error(String)}</li>
184-
</ul>
185-
<p>Although the Android Browser may not fully implement other Console functions, they will not raise
186-
run-time errors, but may not behave the same as they do on other desktop browsers.</p>
187-
188-
<p>If you've implemented a custom {@link android.webkit.WebView} in your application, then in order
189-
to receive messages that are sent through the Console APIs, you must provide a {@link
190-
android.webkit.WebChromeClient} that implements the {@link
191-
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
192-
method. For example, assuming that the {@code myWebView} field references the {@link
193-
android.webkit.WebView} in your application, you can log debug messages like this:</p>
194-
<pre>
195-
myWebView.setWebChromeClient(new WebChromeClient() {
196-
public void onConsoleMessage(String message, int lineNumber, String sourceID) {
197-
Log.d("MyApplication", message + " -- From line " + lineNumber + " of " + sourceID);
198-
}
199-
});
200-
</pre>
201-
<p>The {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
202-
onConsoleMessage()} method will be called each time one of the Console methods is called from
203-
within your {@link android.webkit.WebView}.</p>
204-
<p>When the "Hello World" log is executed through your {@link android.webkit.WebView}, it will
205-
now look like this:</p>
206-
<pre class="no-pretty-print">
207-
D/MyApplication ( 430): Hello World -- From line 82 of http://www.example.com/hello.html
208-
</pre>
209-
210-
<p class="note"><strong>Note:</strong> The {@link
211-
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
212-
method was added with API Level 7. If you are using a custom {@link
213-
android.webkit.WebView} on a platform running API Level 6 or lower, then your Console messages will
214-
automatically be sent to logcat with the "WebCore" logging tag.</p>
215-
216-
154+
<p>See the <a href="{@docRoot}guide/webapps/debugging.html">Debugging Web Apps</a> document.</p>
217155

218156

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

‎docs/html/guide/guide_toc.cs‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -450,6 +450,25 @@ localized titles are added in the language order specified below.
450450
</ul>
451451
</li>
452452

453+
<li>
454+
<h2><span class="en">Web Applications</span>
455+
</h2>
456+
<ul>
457+
<li><a href="<?cs var:toroot ?>guide/webapps/targetting.html">
458+
<span class="en">Targetting Android Devices</span>
459+
</a> <span class="new">new!</span></li>
460+
<li><a href="<?cs var:toroot ?>guide/webapps/webview.html">
461+
<span class="en">Building Web Apps in WebView</span>
462+
</a> <span class="new">new!</span></li>
463+
<li><a href="<?cs var:toroot ?>guide/webapps/debugging.html">
464+
<span class="en">Debugging Web Apps</span>
465+
</a> <span class="new">new!</span></li>
466+
<li><a href="<?cs var:toroot ?>guide/webapps/best-practices.html">
467+
<span class="en">Best Practices for Web Apps</span>
468+
</a> <span class="new">new!</span></li>
469+
</ul>
470+
</li>
471+
453472
<li>
454473
<h2><span class="en">Appendix</span>
455474
<span class="de" style="display:none">Anhang</span>

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
page.title=Best Practices for Web Apps
2+
@jd:body
3+
4+
<style>
5+
.bold li {
6+
font-weight:bold;
7+
}
8+
.bold li * {
9+
font-weight:normal;
10+
}
11+
</style>
12+
13+
<p>Developing web pages and web applications for mobile devices presents a different set of
14+
challenges compared to developing a web page for the typical
15+
desktop web browser. To help you get started, the following is a list of practices you should
16+
follow in order to provide the most effective web application for Android and other mobile
17+
devices.</p>
18+
19+
<ol class="bold">
20+
21+
<li>Redirect mobile devices to a dedicated mobile version of your web site
22+
<p>There are several ways you can redirect requests to the mobile version of your web site, using
23+
server-side redirects. Most often, this is done by "sniffing" the User Agent
24+
string provided by the web browser. To determine whether to serve a mobile version of your site, you
25+
should simply look for the "mobile" string in the User Agent, which matches a wide variety of mobile
26+
devices. If necessary, you can also identify the specific operating system in the User Agent string
27+
(such as "Android 2.1").</p>
28+
</li>
29+
30+
31+
<li>Use a valid markup DOCTYPE that's appropriate for mobile devices
32+
<p>The most common markup language used for mobile web sites is <a
33+
href="http://www.w3.org/TR/2008/REC-xhtml-basic-20080729/">XHTML Basic</a>. This standard
34+
ensures specific markup for your web site that works best on mobile devices. For instance, it does
35+
not allow HTML frames or nested tables, which perform poorly on mobile devices. Along with the
36+
DOCTYPE, be sure to declare the appropriate character encoding for the document (such as
37+
UTF-8).</p>
38+
<p>For example:</p>
39+
<pre>
40+
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
41+
&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.1//EN"
42+
"http://www.w3.org/TR/xhtml-basic/xhtml-basic11.dtd"&gt;
43+
</pre>
44+
45+
<p>Also be sure that your web page markup is valid against the declared DOCTYPE. Use a
46+
validator, such as the one available at
47+
<a href="http://validator.w3.org/">http://validator.w3.org</a>.</p>
48+
</li>
49+
50+
51+
<li>Use viewport meta data to properly resize your web page
52+
<p>In your document {@code &lt;head&gt;}, you should provide meta data that specifies how you
53+
want the browser's viewport to render your web page. For example, your viewport meta data can
54+
specify the height and width for the browser's viewport, the initial web page scale and even the
55+
target screen density.</p>
56+
<p>For example:</p>
57+
<pre>
58+
&lt;meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no"&gt;
59+
</pre>
60+
<p>For more information about how to use viewport meta data for Android-powered devices, read <a
61+
href="{@docRoot}guide/webapps/targetting.html">Targetting Android Devices</a>.</p>
62+
</li>
63+
64+
65+
<li>Avoid multiple file requests
66+
<p>Because mobile devices typically have a connection speed far slower than a desktop
67+
computer, you should make your web pages load as fast as possible. One way to speed it up is to
68+
avoid loading extra files such as stylesheets and script files in the {@code
69+
&lt;head&gt;}. Instead, provide your CSS and JavaScript directly in the &lt;head&gt; (or
70+
at the end of the &lt;body&gt;, for scripts that you don't need until the page is loaded).
71+
Alternatively, you should optimize the size and speed of your files by compressing them with tools
72+
like <a href="http://code.google.com/p/minify/">Minify</a>.</p>
73+
</li>
74+
75+
76+
<li>Use a vertical linear layout
77+
<p>Avoid the need for the user to scroll left and right while navigating your web
78+
page. Scrolling up and down is easier for the user and makes your web page simpler.</p>
79+
</li>
80+
81+
</ol>
82+
83+
<p>For a more thorough guide to creating great mobile web applications, see the W3C's <a
84+
href="http://www.w3.org/TR/mobile-bp/">Mobile Web Best Practices</a>. For other guidance on
85+
improving the speed of your web site (for mobile and desktop), see Yahoo!'s guide to <a
86+
href="http://developer.yahoo.com/performance/index.html#rules">Exceptional Performance</a> and
87+
Google's speed tutorials in <a href="http://code.google.com/speed/articles/">Let's make the web
88+
faster</a>.</p>
89+
90+

‎docs/html/guide/webapps/debugging.jd‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
page.title=Debugging Web Apps
2+
@jd:body
3+
4+
<div id="qv-wrapper">
5+
<div id="qv">
6+
<h2>Quickview</h2>
7+
<ul>
8+
<li>You can debug your web app using console methods in JavaScript</li>
9+
<li>If debugging in a custom WebView, you need to implement a callback method to handle debug
10+
messages</li>
11+
</ul>
12+
13+
<h2>In this document</h2>
14+
<ol>
15+
<li><a href="#Browser">Using Console APIs in the Android Browser</a></li>
16+
<li><a href="#WebView">Using Console APIs in WebView</a></li>
17+
</ol>
18+
19+
<h2>See also</h2>
20+
<ol>
21+
<li><a href="{@docRoot}guide/developing/debug-tasks.html">Debugging Tasks</a></li>
22+
</ol>
23+
24+
</div>
25+
</div>
26+
27+
<p>If you're developing a web application for Android, you can debug your JavaScript
28+
using the {@code console} JavaScript APIs, which output messages to logcat. If you're familiar with
29+
debugging web pages with Firebug or Web Inspector, then you're probably familiar
30+
with using {@code console} (such as {@code console.log()}). Android's WebKit framework supports most
31+
of the same APIs, so you can receive logs from your web page when debugging in Android's Browser
32+
or in your own {@link android.webkit.WebView}.</p>
33+
34+
35+
36+
<h2 id="Browser">Using Console APIs in the Android Browser</h2>
37+
38+
<div class="sidebox-wrapper">
39+
<div class="sidebox">
40+
<h2>Logcat</h2>
41+
<p>Logcat is a tool that dumps a log of system messages. The messages include a stack trace when
42+
the device throws an error, as well as log messages written from your application and
43+
those written using JavaScript {@code console} APIs.</p>
44+
<p>To run logcat and view messages, execute
45+
{@code adb logcat} from your Android SDK {@code tools/} directory, or, from DDMS, select
46+
<strong>Device > Run logcat</strong>. When using the <a href="{@docRoot}sdk/eclipse-adt.html">ADT
47+
plugin for Eclipse</a>, you can also view logcat messages by opening the Logcat view, available from
48+
<strong>Window > Show View > Other > Android > Logcat</strong>.</p>
49+
<p>See <a href="{@docRoot}guide/developing/debug-tasks.html">Debugging
50+
Tasks</a> for more information about logcat.</p>
51+
</div>
52+
</div>
53+
54+
<p>When you call a {@code console} function (in the DOM's {@code window.console} object),
55+
the output appears in logcat. For example, if your web page executes the following
56+
JavaScript:</p>
57+
<pre>
58+
console.log("Hello World");
59+
</pre>
60+
<p>Then the logcat message looks something like this:</p>
61+
<pre class="no-pretty-print">
62+
Console: Hello World http://www.example.com/hello.html :82
63+
</pre>
64+
65+
<p>The format of the message might appear different depending on which version of Android you're
66+
using. On Android 2.1 and higher, console messages from the Android Browser
67+
are tagged with the name "browser". On Android 1.6 and lower, Android Browser
68+
messages are tagged with the name "WebCore".</p>
69+
70+
<p>Android's WebKit does not implement all of the console APIs available in other desktop browsers.
71+
You can, however, use the basic text logging functions:</p>
72+
<ul>
73+
<li>{@code console.log(String)}</li>
74+
<li>{@code console.info(String)}</li>
75+
<li>{@code console.warn(String)}</li>
76+
<li>{@code console.error(String)}</li>
77+
</ul>
78+
79+
<p>Other console functions don't raise errors, but might not behave the same as what you
80+
expect from other web browsers.</p>
81+
82+
83+
84+
<h2 id="WebView">Using Console APIs in WebView</h2>
85+
86+
<p>If you've implemented a custom {@link android.webkit.WebView} in your application, all the
87+
same console APIs are supported when debugging your web page in WebView. On Android
88+
1.6 and lower, console messages are automatically sent to logcat with the
89+
"WebCore" logging tag. If you're targetting Android 2.1 (API Level 7) or higher, then you must
90+
provide a {@link android.webkit.WebChromeClient}
91+
that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
92+
onConsoleMessage()} callback method, in order for console messages to appear in logcat.</p>
93+
94+
<p>Additionally, the {@link
95+
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} method introduced in API
96+
Level 7 has been deprecated in favor of {@link
97+
android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} in API Level 8.</p>
98+
99+
<p>Whether you're developing for Android 2.1 (API Level 7) or Android 2.2 (API Level 8 or
100+
greater), you must implement {@link android.webkit.WebChromeClient} and override the appropriate
101+
{@link
102+
android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
103+
method. Then, apply the {@link android.webkit.WebChromeClient} to your {@link
104+
android.webkit.WebView} with {@link android.webkit.WebView#setWebChromeClient(WebChromeClient)
105+
setWebChromeClient()}.
106+
107+
<p>Using API Level 7, this is how your code for {@link
108+
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} might look:</p>
109+
110+
<pre>
111+
WebView myWebView = (WebView) findViewById(R.id.webview);
112+
myWebView.setWebChromeClient(new WebChromeClient() {
113+
public void onConsoleMessage(String message, int lineNumber, String sourceID) {
114+
Log.d("MyApplication", message + " -- From line "
115+
+ lineNumber + " of "
116+
+ sourceID);
117+
}
118+
});
119+
</pre>
120+
121+
<p>With API Level 8 or greater, your code for {@link
122+
android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} might look like this:</p>
123+
124+
<pre>
125+
WebView myWebView = (WebView) findViewById(R.id.webview);
126+
myWebView.setWebChromeClient(new WebChromeClient() {
127+
public boolean onConsoleMessage(ConsoleMessage cm) {
128+
Log.d("MyApplication", cm.{@link android.webkit.ConsoleMessage#message()} + " -- From line "
129+
+ cm.{@link android.webkit.ConsoleMessage#lineNumber()} + " of "
130+
+ cm.{@link android.webkit.ConsoleMessage#sourceId()} );
131+
return true;
132+
}
133+
});
134+
</pre>
135+
136+
<p>The {@link android.webkit.ConsoleMessage} also includes a {@link
137+
android.webkit.ConsoleMessage.MessageLevel MessageLevel} to indicate the type of console message
138+
being delivered. You can query the message level with {@link
139+
android.webkit.ConsoleMessage#messageLevel()} to determine the severity of the message, then
140+
use the appropriate {@link android.util.Log} method or take other appropriate actions.</p>
141+
142+
<p>Whether you're using {@link
143+
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} or {@link
144+
android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)}, when you execute a console method
145+
in your web page, Android calls the appropriate {@link
146+
android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
147+
onConsoleMessage()} method so you can report the error. For example, with the example code above,
148+
a logcat message is printed that looks like this:</p>
149+
150+
<pre class="no-pretty-print">
151+
Hello World -- From line 82 of http://www.example.com/hello.html
152+
</pre>
153+
154+
155+
156+
157+
158+

0 commit comments

Comments
 (0)