Move custom smarty template documentation to Views.

content/developer/Views.adoc

@@ -163,4 +163,89 @@ most common ones to override are:
   alter this behaviour or to output anything after the main display. You
   usually want to call parent::display(); to ensure that the display
   code is run (unless, of course, you are adding your own display
-  logic). link:../views[↩]
+  logic). link:../views[↩]
+
+
+=== Customising with Smarty templates.
+
+Instead of using including HTML files in PHP, you can use Smarty templates to create complex HTML for custom views.
+
+Let's say you're adding a custom module called `Store`, and you've made a file at `custom/modules/Store/views/view.store.php` that uses HTML in HEREDOCs and Strings to create a dynamic page:
+
+[source,php]
+----------
+<?php
+if (!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
+
+require_once('include/MVC/View/SugarView.php');
+
+class StoreView extends SugarView
+{
+    public function display()
+    {
+        $storeName = $store->storeName;
+        $location = $store->location;
+        $products = $store->products';
+
+        $html = <<<"HTML"
+<h1>$storeName</h1>
+<h2>Location: $location</h2>
+
+<ul>
+HTML;
+
+        foreach ($products as $id => $product) {
+            $html .= "<li>$product->name: $product->price</li>";
+        }
+
+        $html .= <<<"HTML"
+</ul>
+HTML;
+
+        echo $html;
+    }
+}
+----------
+
+This works, but it isn't very nice to look at, and it's hard to maintain and understand. You're combining your backend logic with the frontend HTML, which we should try to avoid as much as possible.
+
+Instead, we can accomplish the same thing using a Smarty template. We can change the `custom/modules/Store/views/view.store.php` file to just provide the variables for the Smarty template, instead of creating the HTML itself.
+
+[source,php]
+----------
+<?php
+if (!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');
+
+require_once('include/MVC/View/SugarView.php');
+
+class StoreView extends SugarView
+{
+    public function display()
+    {
+        $smarty = new Sugar_Smarty();
+        $smarty->assign('storeName', $store->storeName);
+        $smarty->assign('location', $store->location);
+        $smarty->assign('products', $store->products);
+        $storePage = $smarty->fetch('custom/modules/Store/templates/store.tpl');
+        return $storePage;
+    }
+}
+----------
+
+And then we'll create a file at `custom/modules/Store/templates/store.tpl`, that looks like this:
+
+[source,tpl]
+----------
+<h1>{$storeName}</h1>
+<h2>Location: {$location}</h2>
+
+<ul>
+    {foreach name=productsIteration from=$products key=id item=product}
+        <li>{$product->name}: {$product->price}</li>
+    {/foreach}
+</ul>
+----------
+
+Much simpler!
+
+You can read more about Smarty template files and their syntax https://www.smarty.net/docsv2/en/[in the Smarty documentation].