1 <!DOCTYPE html> 2 <html> 3 <!-- 4 Copyright 2012 The Android Open Source Project 5 6 Licensed under the Apache License, Version 2.0 (the "License"); 7 you may not use this file except in compliance with the License. 8 You may obtain a copy of the License at 9 10 http://www.apache.org/licenses/LICENSE-2.0 11 12 Unless required by applicable law or agreed to in writing, software 13 distributed under the License is distributed on an "AS IS" BASIS, 14 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 See the License for the specific language governing permissions and 16 limitations under the License. 17 --> 18 <head> 19 <meta charset="utf-8"> 20 <title>ADT Template Format</title> 21 <link rel="stylesheet" href="cssreset-min.css"> 22 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic,bold;Inconsolata" title="roboto"> 23 <link rel="stylesheet" href="prettify.css"> 24 <link rel="stylesheet" href="default.css"> 25 <script src="jquery-1.8.0.min.js"></script> 26 <script src="prettify.js"></script> 27 <script src="default.js"></script> 28 </head> 29 <body> 30 31 <nav> 32 33 </nav> 34 35 <div id="page-content"> 36 37 <h1>ADT Template Format</h1> 38 <br> 39 <dl style="margin:0"> 40 <dt>Status</dt> 41 <dd style="margin:0">Draft</dd> 42 43 <dt>Format Version</dt> 44 <dd style="margin:0">3</dd> 45 46 <dt>Last Updated</dt> 47 <dd style="margin:0">8/30/2012</dd> 48 </dl> 49 50 51 52 53 54 <h2>Overview</h2> 55 56 <p>This document describes the format and syntax for Android code templates. These templates provide starting points for entire projects (e.g. <code>NewAndroidApplication</code>) or application components such as activities (e.g. <code>BlankActivity</code>).</p> 57 58 <p>Although these templates were originally introduced in the <a href="http://developer.android.com/tools/sdk/eclipse-adt.html">ADT Plugin</a> for Eclipse, the template format is designed for use by any IDE or command-line tool.</p> 59 60 <p>Templates are customizable. Each template exposes several options (called parameters) that allow developers to customize the generated code. The most common workflow for <em>using</em> a template is as follows:</p> 61 62 <ol> 63 <li>Choose a template.</li> 64 <li>Populate template options (parameters).</li> 65 <li>Preview and then execute the additions/changes to your project.</li> 66 </ol> 67 68 <h3>FreeMarker</h3> 69 70 <p>Templates make heavy use of <a href="http://freemarker.sourceforge.net/">FreeMarker</a>, a Java templating engine used to enable things like control flows and variable substitutions inside files. It's similar to PHP, Django templates, etc. For those more acquainted with C/C++, think of it as a <a href="http://en.wikipedia.org/wiki/C_preprocessor">preprocessor</a> language (i.e. <code>#ifdef</code>).</p> 71 72 <p>By convention, any file in the template directory structure that is to be processed by FreeMarker should have the <code>.ftl</code> file extension. So if one of your source files is <code>MyActivity.java</code>, and it contains FreeMarker instructions, it should be named something like <code>MyActivity.java.ftl</code>.</p> 73 74 <p>For more documentation on FreeMarker, see the <a href="http://freemarker.sourceforge.net/docs/index.html">docs</a>. In particular, the <a href="http://freemarker.sourceforge.net/docs/ref_builtins_string.html">reference on string operations</a>.</p> 75 76 <p>An example, templated version of an Android manifest, normally named <code>AndroidManifest.xml.ftl</code> is shown below.</p> 77 78 <pre class="prettyprint lang-xml"> 79 <manifest xmlns:android="http://schemas.android.com/apk/res/android"> 80 <application> 81 <activity android:name="<strong>.${activityClass}</strong>" 82 android:label="@string/title_<strong>${activityToLayout(activityClass)}</strong>"> 83 <strong><#if parentActivityClass != ""></strong> 84 <meta-data android:name="android.support.PARENT_ACTIVITY" 85 android:value="<strong>${parentActivityClass}</strong>" /> 86 <strong></#if></strong> 87 <strong><#if isLauncher></strong> 88 <intent-filter> 89 <action android:name="android.intent.action.MAIN" /> 90 <category android:name="android.intent.category.LAUNCHER" /> 91 </intent-filter> 92 <strong></#if></strong> 93 </activity> 94 </application> 95 </manifest> 96 </pre> 97 98 <p>In this example excerpt from the <code>BlankActivity</code> template:</p> 99 100 <ul> 101 <li>The expression <code>${activityClass}</code> is bound to the value of the 'Activity Class' template parameter.</li> 102 <li>The expression <code>${activityToLayout(activityClass)}</code> uses the <code>activityToLayout</code> method built into ADT to convert an activity class such as <code>MyFooActivity</code> to <code>activity_my_foo</code>.</li> 103 <li>The <code>isLauncher</code> boolean variable and <code>parentActivityClass</code> string varaibles are bound to the values of the 'Launcher Activity' and 'Hierarchical Parent' template parameter, respectively.</li> 104 </ul> 105 106 107 108 109 110 <h2>Directory Structure</h2> 111 112 <p>A template is a directory containing a number of XML and FreeMarker files. The only two mandatory files are <code>template.xml</code> and <code>recipe.xml.ftl</code>. Template source files (PNG files, templated Java and XML files, etc.) belong in a <code>root/</code> subdirectory. An example directory structure for a template is below:</p> 113 114 <ul> 115 <li><strong>MyTemplate/</strong> <span class="dim">— Root directory</span><ul> 116 <li><a href="#toc_templatexml">template.xml</a> <span class="dim">— Metadata (description, parameters, etc.)</span></li> 117 <li><a href="#toc_recipexmlftl">recipe.xml.ftl</a> <span class="dim">— Instructions/script (files to copy, etc.)</span></li> 118 <li><a href="#toc_globalsxmlftl">globals.xml.ftl </a><span class="dim">— Optional global variables</span></li> 119 <li>template.png <span class="dim">— Default template thumbnail</span></li> 120 <li>template_foo.png <span class="dim">— Thumbnail when option 'foo' is selected</span></li> 121 <li>template_bar.png</li> 122 <li><strong><a href="#toc_root">root/</a></strong> <span class="dim">— Source files (which get processed/copied/merged with the output project)</span><ul> 123 <li>AndroidManifest.xml.ftl</li> 124 <li><strong>res/</strong> <ul> 125 <li>…</li> 126 </ul></li> 127 <li><strong>src/</strong> <ul> 128 <li><strong>app_package/</strong> <ul> 129 <li>MyActivity.java.ftl</li> 130 </ul></li> 131 </ul></li> 132 </ul></li> 133 </ul> 134 </li> 135 </ul> 136 <br> 137 138 <p>More on the role of each of these files is discussed in the sections below.</p> 139 140 <h3>template.xml</h3> 141 142 <p>Each template directory must contain a <code>template.xml</code> file. This XML file contains metadata about the template, including the name, description, category and user-visible parameters that the IDE will present as options to the user. The XML file also indicates the name of the <a href="#toc_recipexmlftl">recipe XML file</a> (which gets processed by FreeMarker), and the <a href="#toc_globalsxmlftl">global variables XML file</a> if there are global variables besides the template parameter values that should be visible to all FreeMarker-processed files (<code>.ftl</code> files).</p> 143 144 <p>An example <code>template.xml</code> is shown below.</p> 145 146 <pre class="prettyprint lang-xml"> 147 <!-- A template for a blank activity. Use template format 148 version 3, as described in this document. --> 149 <template 150 format="3" 151 revision="1" 152 minApi="4" 153 minBuildApi="11" 154 name="New Blank Activity" 155 description="Creates a new blank activity, with navigation."> 156 157 <!-- Indicate that the Android Support Library (r8) should be 158 added to the project, if it isn't already in the project. --> 159 <dependency name="android-support-v4" revision="8" /> 160 161 <category value="Activities" /> 162 163 <!-- A string parameter; the value is available to FreeMarker 164 processed files (.ftl files) as ${activityName}. --> 165 <parameter 166 id="activityName" 167 name="Activity Name" 168 type="string" 169 constraints="class|unique|nonempty" 170 suggest="${layoutToActivity(layoutName)}" 171 default="MainActivity" 172 help="The name of the activity class to create." /> 173 174 <parameter 175 id="layoutName" 176 name="Layout Name" 177 type="string" 178 constraints="layout|unique" 179 suggest="${activityToLayout(activityClass)}" 180 default="main" 181 help="The name of the layout to create for the activity" /> 182 183 <parameter 184 id="navType" 185 name="Navigation Type" 186 type="enum" 187 default="none"> 188 <option id="none" default="true">None</option> 189 <option id="tabs" minApi="11">Tabs</option> 190 <option id="pager" minApi="11">Swipe Views</option> 191 <option id="dropdown" minApi="11">Dropdown</option> 192 </parameter> 193 194 <!-- 512x512 PNG thumbnails. --> 195 <thumbs> 196 <!-- Default thumbnail. --> 197 <thumb>template_default.png</thumb> 198 <!-- Attributes act as selectors based on chosen parameters. --> 199 <thumb navType="tabs">template_tabs.png</thumb> 200 <thumb navType="dropdown">template_dropdown.png</thumb> 201 </thumbs> 202 203 <!-- Optional global variables. --> 204 <globals file="globals.xml.ftl" /> 205 206 <!-- Required recipe (script) to run when instantiating 207 the template. --> 208 <execute file="recipe.xml.ftl" /> 209 </template> 210 </pre> 211 212 <p>Below is a listing of supported tags in <code>template.xml</code>.</p> 213 214 <h4 class="includetoc"><template></h4> 215 216 <p>The template root element.</p> 217 218 <dl> 219 <dt><code>format</code></dt> 220 <dd>The template format version that this template adheres to. Should be <code>3</code>.</dd> 221 222 <dt><code>revision</code></dt> 223 <dd>Optional. The version of this template (which you can increment when updating the template), as an integer.</dd> 224 225 <dt><code>name</code></dt> 226 <dd>The template's display name.</dd> 227 228 <dt><code>description</code></dt> 229 <dd>The template's description.</dd> 230 231 <dt><code>minApi</code></dt> 232 <dd>Optional. The minimum API level required for this template. The IDE will ensure that the target project has a <code>minSdkVersion</code> no lower than this value before instantiating the template.</dd> 233 234 <dt><code>minBuildApi</code></dt> 235 <dd>Optional. The minimum build target (expressed as an API level) required for this template. The IDE will ensure that the target project is targeting an API level greater than or equal to this value before instantiating the template. This ensures that the template can safely use newer APIs (optionally guarded by runtime API level checks) without introducing compile-time errors into the target project.</dd> 236 </dl> 237 238 <h4 class="includetoc"><dependency></h4> 239 240 <p>Indicates that the template requires that a given library be present in the target project. If not present, the IDE will add the dependency to the project.</p> 241 242 <dl> 243 <dt><code>name</code></dt> 244 <dd>The name of the library. Currently accepted values are:<ul> 245 <li><code>android-support-v4</code></li> 246 <li><code>android-support-v13</code></li> 247 </ul></dd> 248 249 <dt><code>revision</code></dt> 250 <dd>The minimum revision of the library required by this template.</dd> 251 </dl> 252 253 <h4 class="includetoc"><category></h4> 254 255 <p>The template type. This element is optional.</p> 256 257 <dl> 258 <dt><code>value</code></dt> 259 <dd>The template type. Should be one of the following values: <ul> 260 <li><code>Applications</code></li> 261 <li><code>Activities</code></li> 262 <li><code>UI Components</code></li> 263 </ul></dd> 264 </dl> 265 266 <h4 class="includetoc"><parameter></h4> 267 268 <p>Defines a user-customizable template parameter.</p> 269 270 <dl> 271 <dt><code>id</code></dt> 272 <dd>The identifier representing this variable, made available as a global variable in FreeMarker files. If the identifier is <code>foo</code>, the parameter value will be available in FreeMarker files as <code>${foo}</code>.</dd> 273 274 <dt><code>name</code></dt> 275 <dd>The display name of the template parameter.</dd> 276 277 <dt><code>type</code></dt> 278 <dd>The data type of the parameter. Either <code>string</code>, <code>boolean</code>, <code>enum</code>, or <code>separator</code>.</dd> 279 280 <dt><code>constraints</code></dt> 281 <dd>Optional. Constraints to impose on the parameter's value. Constraints can be combined using <code>|</code>. Valid constraint types are: <ul> 282 <li><code>nonempty</code> — the value must not be empty</li> 283 <li><code>apilevel</code> — the value should represent a numeric API level</li> 284 <li><code>package</code> — the value should represent a valid Java package name</li> 285 <li><code>class</code> — the value should represent a valid Java class name</li> 286 <li><code>activity</code> — the value should represent a fully-qualified activity class name</li> 287 <li><code>layout</code> — the value should represent a valid layout resource name</li> 288 <li><code>drawable</code> — the value should represent a valid drawable resource name</li> 289 <li><code>string</code> — the value should represent a valid string resource name</li> 290 <li><code>id</code> — the value should represent a valid id resource name</li> 291 <li><code>unique</code> — the value must be unique; this constraint only makes sense when other constraints are specified, such as <code>layout</code>, which would mean that the value should not represent an existing layout resource name</li> 292 <li><code>exists</code> — the value must already exist; this constraint only makes sense when other constraints are specified, such as <code>layout</code>, which would mean that the value should represent an existing layout resource name</li> 293 </ul></dd> 294 295 <dt><code>suggest</code></dt> 296 <dd>Optional. A FreeMarker expression representing the auto-suggested parameter value (a 'dynamic default'). When the user modifies other parameter values, and if this parameter's value has not been changed from its default, then the value changes to the result of this expression. This may seem to be circular since parameters can <code>suggest</code> against each other's values, but these expressions are only updated for non-edited values, so this approach lets the user edit either parameter value, and the other will automatically be updated to a reasonable default.</dd> 297 298 <dt><code>default</code></dt> 299 <dd>Optional. The default value for this parameter.</dd> 300 301 <dt><code>help</code></dt> 302 <dd>The help string to display to the user for this parameter.</dd> 303 304 </dl> 305 306 <h4 class="includetoc"><option></h4> 307 308 <p>For parameters of type <code>enum</code>, represents a choice for the value.</p> 309 310 <dl> 311 <dt><code>id</code></dt> 312 <dd>The parameter value to set if this option is chosen.</dd> 313 314 <dt><code>minApi</code></dt> 315 <dd>Optional. The minimum API level required if this option is chosen. The IDE will ensure that the target project has a <code>minSdkVersion</code> no lower than this value before instantiating the template.</dd> 316 317 <dt><code>[text]</code></dt> 318 <dd>The text content of this element represents the display value of the choice.</dd> 319 </dl> 320 321 <h4 class="includetoc"><thumb></h4> 322 323 <p>Represents a thumbnail for the template. <code><thumb></code> elements should be contained inside a <code><thumbs></code> element. The text contents of this element represent the path to the thumbnail. If this element has any attributes, they will be treated as selectors for parameter values. For example, if there are two thumbnails:</p> 324 325 <pre class="prettyprint lang-xml"> 326 <thumbs> 327 <thumb>template.png</thumb> 328 <thumb navType="tabs">template_tabs.png</thumb> 329 </thumbs> 330 </pre> 331 332 <p>The template 'preview' thumbnail will show <code>template_tabs.png</code> if the value of the <code>navType</code> template parameter is <code>tabs</code> and <code>template.png</code> otherwise.</p> 333 334 <h3>globals.xml.ftl</h3> 335 336 <p>The optional globals XML file contains global variable definitions, for use in all FreeMarker processing jobs for this template.</p> 337 338 <p>An example <code>globals.xml.ftl</code> is shown below.</p> 339 340 <pre class="prettyprint lang-xml"> 341 <globals> 342 <global id="srcOut" 343 value="src/${slashedPackageName(packageName)}" /> 344 <global id="activityNameLower" 345 value="${activityName?lower_case}" /> 346 <global id="activityClass" 347 value="${activityName}Activity" /> 348 </globals> 349 </pre> 350 351 <h3>recipe.xml.ftl</h3> 352 353 <p>The recipe XML file contains the individual instructions that should be executed when generating code from this template. For example, you can copy certain files or directories (the copy instruction), optionally running the source files through FreeMarker (the instantiate instruction), and ask ADT to open a file in Eclipse after the code has been generated (the open instruction).</p> 354 355 <p class="note"><strong>Note:</strong> The name of the recipe file is up to you, and is defined in <code>template.xml</code>. By convention, however, it's best to call it <code>recipe.xml.ftl</code>.</p> 356 357 <p class="note"><strong>Note:</strong> The global variables in <code>globals.xml.ftl</code> are available for use in <code>recipe.xml.ftl</code>.</p> 358 359 <p>An example <code>recipe.xml.ftl</code> is shown below.</p> 360 361 <pre class="prettyprint lang-xml"> 362 <recipe> 363 <!-- runs FreeMarker, then copies from 364 [template-directory]/root/ to [output-directory]. --> 365 <instantiate from="AndroidManifest.xml.ftl" /> 366 367 <!-- automatically creates directories as needed --> 368 <copy from="res/drawable-hdpi" /> 369 <copy from="res/drawable-mdpi" /> 370 <copy from="res/drawable-xhdpi" /> 371 <copy from="res/values/dimens.xml" /> 372 <copy from="res/values/styles.xml" /> 373 <copy from="res/values-large/dimens.xml" /> 374 375 <copy from="res/menu/main.xml" 376 to="res/menu/${activityNameLower}.xml" /> 377 378 <instantiate from="res/values/strings.xml.ftl" /> 379 380 <!-- Decide which layout to add --> 381 <#if navType?contains("pager")> 382 <instantiate 383 from="res/layout/activity_pager.xml.ftl" 384 to="res/layout/activity_${activityNameLower}.xml" /> 385 <#elseif navType == "tabs" || navType == "dropdown"> 386 <copy from="res/layout/activity_fragment_container.xml" 387 to="res/layout/activity_${activityNameLower}.xml" /> 388 <#else> 389 <copy from="res/layout/activity_simple.xml" 390 to="res/layout/activity_${activityNameLower}.xml" /> 391 </#if> 392 393 <!-- Decide which activity code to add --> 394 <#if navType == "none"> 395 <instantiate from="src/app_package/SimpleActivity.java.ftl" 396 to="${srcOut}/${activityClass}.java" /> 397 <#elseif navType == "pager"> 398 <instantiate from="src/app_package/PagerActivity.java.ftl" 399 to="${srcOut}/${activityClass}.java" /> 400 <#elseif navType == "tabs"> 401 <instantiate from="src/app_package/TabsActivity.java.ftl" 402 to="${srcOut}/${activityClass}.java" /> 403 <#elseif navType == "dropdown"> 404 <instantiate from="src/app_package/DropdownActivity.java.ftl" 405 to="${srcOut}/${activityClass}.java" /> 406 </#if> 407 408 <!-- open the layout file when done --> 409 <open file="res/layout/${activityNameLower}.xml" /> 410 </recipe> 411 </pre> 412 413 <p>The instructions below are supported:</p> 414 415 <h4 class="includetoc"><copy></h4> 416 417 <p>The only required argument is <code>from</code> which specifies the location of the source files to copy under the <code>root/</code> directory. All necessary ancestor directories are automatically created if needed.</p> 418 419 <p>The default destination location is the same path under the output directory root (i.e. the location of the destination project). If the optional <code>to</code> argument is provided, this specifies the output directory. Note that if the from path ends with <code>.ftl</code>, it will automatically be stripped. For example <code><instantiate from="res/values/strings.xml.ftl" /></code> is adequate; this will create a file named <code>strings.xml</code>, not <code>strings.xml.ftl</code>.</p> 420 421 <p>This argument works recursively, so if <code>from</code> is a directory, that directory is recursively copied.</p> 422 423 <h4 class="includetoc"><instantiate></h4> 424 425 <p>Same as <code><copy></code>, but each source file is first run through FreeMarker.</p> 426 427 <h4 class="includetoc"><merge></h4> 428 429 <p>This instruction will be used to merge the contents of a source file into an existing file in the project. The most common use case for this will be to add components to the <code>AndroidManifest.xml</code> file of the destination project, or to merge resources such as strings into an existing <code>strings.xml</code> file.</p> 430 431 <h4 class="includetoc"><open></h4> 432 433 <p>Instruct ADT to open the file created by the specified <code>file</code> argument in Eclipse after code generation is complete.</p> 434 435 <h3>root/</h3> 436 437 <p>The actual template files (resources, Java sources, Android Manifest changes) should be placed in the <code>root/</code> directory, in a directory structure that roughly resembles what the output directory structure should look like.</p> 438 439 <p>One difference is that instead of placing source files in <code>src/com/google/...</code> you can just use a naming convention like <code>src/app_package/</code> to indicate that files under this directory will be placed in the destination project's source file package root.</p> 440 441 442 443 444 <h2>Extra Template Functions</h2> 445 446 <p>Several functions are available to FreeMarker expressions and files beyond the standard set of built-in FreeMarker functions. These are listed below.</p> 447 448 <h3 data-toctitle="activityToLayout">string <em>activityToLayout</em>(string)</h3> 449 450 <p>This function converts an activity class-like identifer string, such as <code>FooActivity</code>, to a corresponding resource-friendly identifier string, such as <code>activity_foo</code>.</p> 451 452 <h4>Arguments</h4> 453 <dl> 454 <dt><code>activityClass</code></dt> 455 <dd>The activity class name, e.g. <code>FooActivity</code> to reformat.</dd> 456 </dl> 457 458 <h4>See also</h4> 459 <p><a href="#toc_layouttoactivity"><code>layoutToActivity</code></a></p> 460 461 <h3 data-toctitle="camelCaseToUnderscore">string <em>camelCaseToUnderscore</em>(string)</h3> 462 463 <p>This function converts a camel-case identifer string, such as <code>FooBar</code>, to its corresponding underscore-separated identifier string, such as <code>foo_bar</code>.</p> 464 465 <h4>Arguments</h4> 466 <dl> 467 <dt><code>camelStr</code></dt> 468 <dd>The camel-case string, e.g. <code>FooBar</code> to convert to an underscore-delimited string.</dd> 469 </dl> 470 471 <h4>See also</h4> 472 <p><a href="#toc_underscoretocamelcase"><code>underscoreToCamelCase</code></a></p> 473 474 <h3 data-toctitle="escapeXmlAttribute">string <em>escapeXmlAttribute</em>(string)</h3> 475 476 <p>This function escapes a string, such as <code>Android's</code> such that it can be used as an XML attribute value: <code>Android&apos;s</code>. In particular, it will escape ', ", < and &.</p> 477 478 <h4>Arguments</h4> 479 <dl> 480 <dt><code>str</code></dt> 481 <dd>The string to be escaped.</dd> 482 </dl> 483 484 <h4>See also</h4> 485 <p><a href="#toc_escapexmltext"><code>escapeXmlText</code></a></p> 486 <p><a href="#toc_escapexmlstring"><code>escapeXmlString</code></a></p> 487 488 <h3 data-toctitle="escapeXmlText">string <em>escapeXmlText</em>(string)</h3> 489 490 <p>This function escapes a string, such as <code>A & B's</code> such that it can be used as XML text. This means it will escape < and >, but unlike <a href="#toc_escapexmlattribute"><code>escapeXmlAttribute</code></a> it will <b>not</b> escape ' and ". In the preceeding example, it will escape the string to <code>A &amp; B\s</code>. Note that if you plan to use the XML text as the value for a <string> resource value, you should consider using <a href="#toc_escapexmlstring"><code>escapeXmlString</code></a> instead, since it performs additional escapes necessary for string resources.</p> 491 492 <h4>Arguments</h4> 493 <dl> 494 <dt><code>str</code></dt> 495 <dd>The string to escape to proper XML text.</dd> 496 </dl> 497 498 <h4>See also</h4> 499 <p><a href="#toc_escapexmlattribute"><code>escapeXmlAttribute</code></a></p> 500 <p><a href="#toc_escapexmlstring"><code>escapeXmlString</code></a></p> 501 502 <h3 data-toctitle="escapeXmlString">string <em>escapeXmlString</em>(string)</h3> 503 504 <p>This function escapes a string, such as <code>A & B's</code> such that it is suitable to be inserted in a string resource file as XML text, such as <code>A &amp; B\s</code>. In addition to escaping XML characters like < and &, it also performs additional Android specific escapes, such as escaping apostrophes with a backslash, and so on.</p> 505 506 <h4>Arguments</h4> 507 <dl> 508 <dt><code>str</code></dt> 509 <dd>The string, e.g. <code>Activity's Title</code> to escape to a proper resource XML value.</dd> 510 </dl> 511 512 <h4>See also</h4> 513 <p><a href="#toc_escapexmlattribute"><code>escapeXmlAttribute</code></a></p> 514 <p><a href="#toc_escapexmltext"><code>escapeXmlText</code></a></p> 515 516 <h3 data-toctitle="extractLetters">string <em>extractLetters</em>(string)</h3> 517 518 <p>This function extracts all the letters from a string, effectively removing any punctuation and whitespace characters.</p> 519 520 <h4>Arguments</h4> 521 <dl> 522 <dt><code>str</code></dt> 523 <dd>The string to extract letters from</dd> 524 </dl> 525 526 <h3 data-toctitle="classToResource">string <em>classToResource</em>(string)</h3> 527 528 <p>This function converts an Android class name, such as <code>FooActivity</code> or <code>FooFragment</code>, to a corresponding resource-friendly identifier string, such as <code>foo</code>, stripping the 'Activity' or 'Fragment' suffix. Currently stripped suffixes are listed below.</p> 529 530 <ul> 531 <li>Activity</li> 532 <li>Fragment</li> 533 <li>Provider</li> 534 <li>Service</li> 535 </ul> 536 537 <h4>Arguments</h4> 538 <dl> 539 <dt><code>className</code></dt> 540 <dd>The class name, e.g. <code>FooActivity</code> to reformat as an underscore-delimited string with suffixes removed.</dd> 541 </dl> 542 543 <h4>See also</h4> 544 <p><a href="#toc_activitytolayout"><code>activityToLayout</code></a></p> 545 546 <h3 data-toctitle="layoutToActivity">string <em>layoutToActivity</em>(string)</h3> 547 548 <p>This function converts a resource-friendly identifer string, such as <code>activity_foo</code>, to a corresponding Java class-friendly identifier string, such as <code>FooActivity</code>.</p> 549 550 <h4>Arguments</h4> 551 <dl> 552 <dt><code>resourceName</code></dt> 553 <dd>The resource name, e.g. <code>activity_foo</code> to reformat.</dd> 554 </dl> 555 556 <h4>See also</h4> 557 <p><a href="#toc_activitytolayout"><code>activityToLayout</code></a></p> 558 559 <h3 data-toctitle="slashedPackageName">string <em>slashedPackageName</em>(string)</h3> 560 561 <p>This function converts a full Java package name to its corresponding directory path. For example, if the given argument is <code>com.example.foo</code>, the return value will be <code>com/example/foo</code>.</p> 562 563 <h4>Arguments</h4> 564 <dl> 565 <dt><code>packageName</code></dt> 566 <dd>The package name to reformat, e.g. <code>com.example.foo</code>.</dd> 567 </dl> 568 569 <h3 data-toctitle="underscoreToCamelCase">string <em>underscoreToCamelCase</em>(string)</h3> 570 571 <p>This function converts an underscore-delimited string, such as <code>foo_bar</code>, to its corresponding camel-case string, such as <code>FooBar</code>.</p> 572 573 <h4>Arguments</h4> 574 <dl> 575 <dt><code>underStr</code></dt> 576 <dd>The underscore-delimited string, e.g. <code>foo_bar</code> to convert to a camel-case string.</dd> 577 </dl> 578 579 <h4>See also</h4> 580 <p><a href="#toc_camelcasetounderscore"><code>camelCaseToUnderscore</code></a></p> 581 582 <h2>Notes for Template Authors</h2> 583 584 <h3>Tools metadata</h3> 585 586 <p>When creating activity layouts, make sure to include the activity name in the root view in the layout as part of the <code>tools</code> namespace, as shown in the following example:</p> 587 588 <pre class="prettyprint lang-xml"> 589 <TextView xmlns:android="http://schemas.android.com/apk/res/android" 590 <strong>xmlns:tools="http://schemas.android.com/tools"</strong> 591 android:layout_width="match_parent" 592 android:layout_height="match_parent" 593 android:gravity="center" 594 android:text="@string/hello_world" 595 android:padding="@dimen/padding_medium" 596 <strong>tools:context=".${activityClass}"</strong> /> 597 </pre> 598 599 <p>As of ADT 20 we use this attribute in layouts to maintain a mapping to the active activity to use for a layout. (Yes, there can be more than one, but this attribute is showing the activity context you want to edit the layout as. For example, it will be used to look up a theme registration (which is per-activity rather than per-layout) in the manifest file, and we will use this for other features in the future—for example to preview the action bar, which also requires us to know the activity context.</p> 600 601 </div> 602 603 </body> 604 </html> 605
