37497: Templates should escape string literals in resource files

If the user enters an activity title like "Android's Tools" in the new
template wizard, an invalid strings.xml file is generated, since the
apostrophe is not properly escaped.

To fix this, there's a new string conversion method in the template
engine, "escapeXmlString", which will perform all the necessary
conversions.

It also adds two other XML escaping functions: one to escape text to
be suitable for XML attribute values, and one to be suitable for XML
text values.

Finally, when verifying this, I discovered that if I inserted
ampersands in the MasterDetail template, I ended up with errors in
various places there a filename was derived from the input string. To
help make this work better, there's also a new "extractLetters" method
which pulls all the characters out of a string (effectively stripping
whitespace and punctuation).

In addition to the above 4 new string conversion methods, the
templates have been updated to use them, and the template format
documentation updated.

Change-Id: I4d4e854ab78d63bc86b8eb0fb9d92246534615e7

11 files changed, 66 insertions, 14 deletions

diff --git a/templates/activities/BlankActivity/root/res/values/strings.xml.ftl b/templates/activities/BlankActivity/root/res/values/strings.xml.ftl
index 6c636d6..4ba950a 100644
--- a/templates/activities/BlankActivity/root/res/values/strings.xml.ftl
+++ b/templates/activities/BlankActivity/root/res/values/strings.xml.ftl
@@ -1,6 +1,6 @@
 <resources>
     <#if !isNewProject>
-    <string name="title_${activityToLayout(activityClass)}">${activityTitle}</string>
+    <string name="title_${activityToLayout(activityClass)}">${escapeXmlString(activityTitle)}</string>
     </#if>
 
     <string name="menu_settings">Settings</string>
diff --git a/templates/activities/FullscreenActivity/root/res/values/strings.xml.ftl b/templates/activities/FullscreenActivity/root/res/values/strings.xml.ftl
index 53ff7df..5a43acf 100644
--- a/templates/activities/FullscreenActivity/root/res/values/strings.xml.ftl
+++ b/templates/activities/FullscreenActivity/root/res/values/strings.xml.ftl
@@ -1,7 +1,7 @@
 <resources>
 
     <#if !isNewProject>
-    <string name="title_${simpleName}">${activityTitle}</string>
+    <string name="title_${simpleName}">${escapeXmlString(activityTitle)}</string>
     </#if>
     <string name="dummy_button1">Button 1</string>
     <string name="dummy_button2">Button 2</string>
diff --git a/templates/activities/LoginActivity/root/res/values/strings.xml.ftl b/templates/activities/LoginActivity/root/res/values/strings.xml.ftl
index c2ad046..18bf85f 100644
--- a/templates/activities/LoginActivity/root/res/values/strings.xml.ftl
+++ b/templates/activities/LoginActivity/root/res/values/strings.xml.ftl
@@ -1,6 +1,6 @@
 <resources>
     <#if !isNewProject>
-    <string name="title_${simpleName}">${activityTitle}</string>
+    <string name="title_${simpleName}">${escapeXmlString(activityTitle)}</string>
     </#if>
 
     <!-- Strings related to login -->
diff --git a/templates/activities/MasterDetailFlow/globals.xml.ftl b/templates/activities/MasterDetailFlow/globals.xml.ftl
index 519c081..952e278 100644
--- a/templates/activities/MasterDetailFlow/globals.xml.ftl
+++ b/templates/activities/MasterDetailFlow/globals.xml.ftl
@@ -1,8 +1,8 @@
 <?xml version="1.0"?>
 <globals>
     <global id="srcOut" value="src/${slashedPackageName(packageName)}" />
-    <global id="CollectionName" value="${objectKind}List" />
-    <global id="collection_name" value="${objectKind?lower_case}_list" />
-    <global id="DetailName" value="${objectKind}Detail" />
-    <global id="detail_name" value="${objectKind?lower_case}_detail" />
+    <global id="CollectionName" value="${extractLetters(objectKind)}List" />
+    <global id="collection_name" value="${extractLetters(objectKind?lower_case)}_list" />
+    <global id="DetailName" value="${extractLetters(objectKind)}Detail" />
+    <global id="detail_name" value="${extractLetters(objectKind?lower_case)}_detail" />
 </globals>
diff --git a/templates/activities/MasterDetailFlow/recipe.xml.ftl b/templates/activities/MasterDetailFlow/recipe.xml.ftl
index 2c1f057..8b09c84 100644
--- a/templates/activities/MasterDetailFlow/recipe.xml.ftl
+++ b/templates/activities/MasterDetailFlow/recipe.xml.ftl
@@ -11,7 +11,7 @@
     <instantiate from="res/layout/activity_content_list.xml.ftl"
                    to="res/layout/activity_${collection_name}.xml" />
     <instantiate from="res/layout/activity_content_twopane.xml.ftl"
-                   to="res/layout/activity_${objectKind?lower_case}_twopane.xml" />
+                   to="res/layout/activity_${extractLetters(objectKind?lower_case)}_twopane.xml" />
     <instantiate from="res/layout/fragment_content_detail.xml.ftl"
                    to="res/layout/fragment_${detail_name}.xml" />
 
diff --git a/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl b/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
index 3008e2e..97215c3 100644
--- a/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/values-large/refs.xml.ftl
@@ -6,5 +6,5 @@
     For more on layout aliases, see:
     http://developer.android.com/training/multiscreen/screensizes.html#TaskUseAliasFilters
     -->
-    <item type="layout" name="activity_${collection_name}">@layout/activity_${objectKind?lower_case}_twopane</item>
+    <item type="layout" name="activity_${collection_name}">@layout/activity_${extractLetters(objectKind?lower_case)}_twopane</item>
 </resources>
diff --git a/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl b/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
index c698e6e..d592404 100644
--- a/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/values-sw600dp/refs.xml.ftl
@@ -7,5 +7,5 @@
     For more on layout aliases, see:
     http://developer.android.com/training/multiscreen/screensizes.html#TaskUseAliasFilters
     -->
-    <item type="layout" name="activity_${collection_name}">@layout/activity_${objectKind?lower_case}_twopane</item>
+    <item type="layout" name="activity_${collection_name}">@layout/activity_${extractLetters(objectKind?lower_case)}_twopane</item>
 </resources>
diff --git a/templates/activities/MasterDetailFlow/root/res/values/strings.xml.ftl b/templates/activities/MasterDetailFlow/root/res/values/strings.xml.ftl
index 8c555ae..ea882bc 100644
--- a/templates/activities/MasterDetailFlow/root/res/values/strings.xml.ftl
+++ b/templates/activities/MasterDetailFlow/root/res/values/strings.xml.ftl
@@ -1,6 +1,6 @@
 <resources>
     <#if !isNewProject>
-    <string name="title_${collection_name}">${objectKindPlural}</string>
+    <string name="title_${collection_name}">${escapeXmlString(objectKindPlural)}</string>
     </#if>
-    <string name="title_${detail_name}">${objectKind} Detail</string>
+    <string name="title_${detail_name}">${escapeXmlString(objectKind)} Detail</string>
 </resources>
diff --git a/templates/activities/SettingsActivity/root/res/values/strings.xml.ftl b/templates/activities/SettingsActivity/root/res/values/strings.xml.ftl
index bf881a3..8dc52ac 100644
--- a/templates/activities/SettingsActivity/root/res/values/strings.xml.ftl
+++ b/templates/activities/SettingsActivity/root/res/values/strings.xml.ftl
@@ -1,6 +1,6 @@
 <resources>
     <#if !isNewProject>
-    <string name="title_${simpleName}">${activityTitle}</string>
+    <string name="title_${simpleName}">${escapeXmlString(activityTitle)}</string>
     </#if>
 
     <!-- Strings related to Settings -->
diff --git a/templates/docs/index.html b/templates/docs/index.html
index 0916157..f8e89eb 100644
--- a/templates/docs/index.html
+++ b/templates/docs/index.html
@@ -471,6 +471,58 @@
 <h4>See also</h4>
 <p><a href="#toc_underscoretocamelcase"><code>underscoreToCamelCase</code></a></p>
 
+<h3 data-toctitle="escapeXmlAttribute">string <em>escapeXmlAttribute</em>(string)</h3>
+
+<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&amp;apos;s</code>. In particular, it will escape ', ", &lt; and &amp;.</p>
+
+<h4>Arguments</h4>
+<dl>
+  <dt><code>str</code></dt>
+  <dd>The string to be escaped.</dd>
+</dl>
+
+<h4>See also</h4>
+<p><a href="#toc_escapexmltext"><code>escapeXmlText</code></a></p>
+<p><a href="#toc_escapexmlstring"><code>escapeXmlString</code></a></p>
+
+<h3 data-toctitle="escapeXmlText">string <em>escapeXmlText</em>(string)</h3>
+
+<p>This function escapes a string, such as <code>A &amp; B's</code> such that it can be used as XML text. This means it will escape &lt; and &gt;, 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;amp; B\s</code>. Note that if you plan to use the XML text as the value for a &lt;string&gt; 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>
+
+<h4>Arguments</h4>
+<dl>
+  <dt><code>str</code></dt>
+  <dd>The string to escape to proper XML text.</dd>
+</dl>
+
+<h4>See also</h4>
+<p><a href="#toc_escapexmlattribute"><code>escapeXmlAttribute</code></a></p>
+<p><a href="#toc_escapexmlstring"><code>escapeXmlString</code></a></p>
+
+<h3 data-toctitle="escapeXmlString">string <em>escapeXmlString</em>(string)</h3>
+
+<p>This function escapes a string, such as <code>A &amp; B's</code> such that it is suitable to be inserted in a string resource file as XML text, such as <code>A &amp;amp; B\s</code>. In addition to escaping XML characters like &lt; and &amp;, it also performs additional Android specific escapes, such as escaping apostrophes with a backslash, and so on.</p>
+
+<h4>Arguments</h4>
+<dl>
+  <dt><code>str</code></dt>
+  <dd>The string, e.g. <code>Activity's Title</code> to escape to a proper resource XML value.</dd>
+</dl>
+
+<h4>See also</h4>
+<p><a href="#toc_escapexmlattribute"><code>escapeXmlAttribute</code></a></p>
+<p><a href="#toc_escapexmltext"><code>escapeXmlText</code></a></p>
+
+<h3 data-toctitle="extractLetters">string <em>extractLetters</em>(string)</h3>
+
+<p>This function extracts all the letters from a string, effectively removing any punctuation and whitespace characters.</p>
+
+<h4>Arguments</h4>
+<dl>
+  <dt><code>str</code></dt>
+  <dd>The string to extract letters from</dd>
+</dl>
+
 <h3 data-toctitle="classToResource">string <em>classToResource</em>(string)</h3>
 
 <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>
diff --git a/templates/projects/NewAndroidApplication/root/res/values/strings.xml.ftl b/templates/projects/NewAndroidApplication/root/res/values/strings.xml.ftl
index 557e5c2..ee03444 100644
--- a/templates/projects/NewAndroidApplication/root/res/values/strings.xml.ftl
+++ b/templates/projects/NewAndroidApplication/root/res/values/strings.xml.ftl
@@ -1,3 +1,3 @@
 <resources>
-    <string name="app_name">${appTitle}</string>
+    <string name="app_name">${escapeXmlString(appTitle)}</string>
 </resources>