#867 Update theme docs. Mention hook_TYPE_tpl_html().

docs/05_Themes/Create_a_Custom_Theme.md

@@ -1,48 +1,24 @@
-For a complete example of a custom theme, check out the drupalgap_demo app. Otherwise, to create a custom theme in DrupalGap, follow these steps:
-
-## 1. Create a directory for your theme:
-
-`app/themes/my_theme`
-
-## 2. Create an html file for your theme's page template:
-
-`app/themes/my_theme/page.tpl.html`
+> Q: How to fix @deprecated notice? (*2016-10-13*)
 
-## 3. Design your page template using html, region placeholders and the drupalgap page id placeholder:
+A: See the `hook_TYPE_tpl_html` example implementations below.
 
-Latest dev snapshot use this (as of 2014-09-25):
+For a complete example of a custom theme, check out the drupalgap_demo app. Otherwise, to create a custom theme in DrupalGap, follow these steps:
 
-```
-<div {:drupalgap_page_attributes:}>
-  {:header:}
-  {:navigation:}
-  {:content:}
-  {:footer:}
-</div>
-```
+### 1. Create a directory
 
-Versions of the DrupalGap SDK prior to April 2014 should use this instead:
+Create a directory to store the files and images associated with your theme:
 
-```
-<div id="{:drupalgap_page_id:}" class="{:drupalgap_page_class:}" data-role="page">
-  {:header:}
-  {:navigation:}
-  {:content:}
-  {:footer:}
-</div>
-```
-
-Please note, DrupalGap expects each theme to implement at a minimum the following three regions (more info: http://api.drupalgap.org/global.html#system_regions_list):
+`app/themes/my_theme`
 
- - header
- - content
- - footer
+### 2. Create a theme .js file
 
-## 4. Create a javascript file for your theme. The name of the file must match the name of your theme's directory:
+Create a `.js` file to build the custom theme:
 
 `app/themes/my_theme/my_theme.js`
 
-## 5. Set up your theme and its regions in the javascript file:
+### 3. Build the .js file
+
+Now we can set up our theme, regions and template string functions in the `my_theme.js` file:
 
 ```
 /**
@@ -68,13 +44,6 @@ function my_theme_info() {
     }
   };
 
-  // Navigation region.
-  theme.regions['navigation'] = {
-    attributes: {
-      'data-role': 'navbar'
-    }
-  };
-
   // Content Region
   theme.regions['content'] = {
     attributes: {
@@ -95,17 +64,59 @@ function my_theme_info() {
   return theme;
 
 }
+
+/**
+ * Implements hook_TYPE_tpl_html().
+ */
+function my_theme_page_tpl_html() {
+  return '<div {:drupalgap_page_attributes:}>' +
+            '{:header:}' +
+            '{:content:}' +
+            '{:footer:}' +
+          '</div>';
+}
+
+/**
+ * Implements hook_TYPE_tpl_html().
+ */
+function my_theme_node_tpl_html() {
+  return '<h2>{:title:}</h2>' +
+          '<div>{:content:}</div>' +
+          '<div>{:comments:}</div>' +
+          '<div>{:comments_form:}</div>';
+}
+
+/**
+ * Implements hook_TYPE_tpl_html().
+ */
+function my_theme_user_profile_tpl_html() {
+  return '<h2>{:name:}</h2>' +
+          '<div>{:created:}</div>' +
+          '<div class="user-picture">{:picture:}</div>' +
+          '<div>{:content:}</div>';
+}
+
 ```
 
-## 6. Add blocks to your theme's regions in settings.js:
+In previous versions of DrupalGap, the strings returned by the `hook_TYPE_tpl_html()` implementations above used to live in files like `page.tpl.html`, `node.tpl.html` and `user-profile.tpl.html`.` However, loading one or more of these files from disc each time we navigate to a page can have a noticeable performance degradation on mobile devices. Now we just return those template files as a string with functions in our theme's `.js` file.
+
+#### Minimum Required Regions
+
+Please note, DrupalGap expects each theme to implement at a minimum the following three regions (more info: http://api.drupalgap.org/global.html#system_regions_list):
+
+ - `header`
+ - `content`
+ - `footer`
+
+### 4. Add Blocks to the Regions
+
+Add blocks to your theme's regions in the `settings.js` file:
 
 ```
 // The my_theme blocks.
 drupalgap.settings.blocks.my_theme = {
   header: {
-    title: {}
-  },
-  navigation: {
+    title: {},
     main_menu: {}
   },
   content: {
@@ -117,16 +128,13 @@ drupalgap.settings.blocks.my_theme = {
 };
 ```
 
-The title, main_menu, main, and powered_by blocks are all system blocks provided by DrupalGap. You may create your own custom blocks if needed.
+The `title`, `main_menu`, `main`, and `powered_by` blocks are all system blocks provided by DrupalGap. You may create your own custom blocks if needed.
 
-## 7. Copy the other tpl.html files from the core theme into your theme's directory, so they live here:
+## 5. Set active theme
 
-    www/app/themes/my_theme/node.tpl.html
-    www/app/themes/my_theme/user-profile.tpl.html
-
-## 8. Make drupalgap aware of your theme by specifying it in settings.js
+Make DrupalGap aware of your theme by specifying it in the `settings.js` file:
 
 ```
 // Theme
 drupalgap.settings.theme = 'my_theme';
-```
+```