netlinx-erb 1.1.0 → 2.0.0

data/doc/RPC.html

@@ -687,7 +687,7 @@ data_event[vdvRPC]
 </div>
 
     <div id="footer">
-  Generated on Wed Feb 25 14:28:07 2015 by
+  Generated on Mon Jun 29 16:09:05 2015 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.1.3).
 </div>

data/doc/String.html

@@ -208,12 +208,12 @@
       <pre class="lines">
 
 
-378
-379
-380</pre>
+368
+369
+370</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/netlinx/erb/helpers.rb', line 378</span>
+      <pre class="code"><span class="info file"># File 'lib/netlinx/erb/helpers.rb', line 368</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_remove_comma_after_last_item'>remove_comma_after_last_item</span>
   <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_gsub'>gsub</span><span class='lparen'>(</span><span class='tstring'><span class='regexp_beg'>/</span><span class='tstring_content'>(?&lt;=\}),(.*?)\z</span><span class='regexp_end'>/</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'> \1</span><span class='tstring_end'>&#39;</span></span><span class='rparen'>)</span>
@@ -283,17 +283,17 @@
       <pre class="lines">
 
 
-390
-391
-392
-393
-394
-395
-396
-397</pre>
+380
+381
+382
+383
+384
+385
+386
+387</pre>
     </td>
     <td>
-      <pre class="code"><span class="info file"># File 'lib/netlinx/erb/helpers.rb', line 390</span>
+      <pre class="code"><span class="info file"># File 'lib/netlinx/erb/helpers.rb', line 380</span>
 
 <span class='kw'>def</span> <span class='id identifier rubyid_to_hiqnet'>to_hiqnet</span> <span class='id identifier rubyid_sv'>sv</span> <span class='op'>=</span> <span class='kw'>nil</span>
   <span class='id identifier rubyid_sv'>sv</span> <span class='op'>||=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_end'>&#39;</span></span>
@@ -313,7 +313,7 @@
 </div>
 
     <div id="footer">
-  Generated on Wed Feb 25 14:28:07 2015 by
+  Generated on Mon Jun 29 16:09:05 2015 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.1.3).
 </div>

data/doc/_index.html

@@ -195,6 +195,24 @@
         </ul>
       
         
+        <ul id="alpha_P" class="alpha">
+          <li class="letter">P</li>
+          <ul>
+            
+              <li>
+                <span class='object_link'><a href="NetLinx/Rake/ERB/Push.html" title="NetLinx::Rake::ERB::Push (class)">Push</a></span>
+                
+                  <small>(NetLinx::Rake::ERB)</small>
+                
+              </li>
+            
+          </ul>
+        </ul>
+      
+        
+          </td><td valign='top' width="33%">
+          
+        
         <ul id="alpha_R" class="alpha">
           <li class="letter">R</li>
           <ul>
@@ -215,9 +233,6 @@
         </ul>
       
         
-          </td><td valign='top' width="33%">
-          
-        
         <ul id="alpha_S" class="alpha">
           <li class="letter">S</li>
           <ul>
@@ -239,7 +254,7 @@
 </div>
 
     <div id="footer">
-  Generated on Wed Feb 25 14:28:05 2015 by
+  Generated on Mon Jun 29 16:09:01 2015 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.1.3).
 </div>

data/doc/class_list.html

@@ -50,7 +50,7 @@
 
       <ul id="full_list" class="class">
         <li><span class='object_link'><a href="top-level-namespace.html" title="Top Level Namespace (root)">Top Level Namespace</a></span></li>
-<li><span class='object_link'><a href="Array.html" title="Array (class)">Array</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><span class='object_link'><a href="Hash.html" title="Hash (class)">Hash</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx.html" title="NetLinx (module)">NetLinx</a></span><small class='search_info'>Top Level Namespace</small></li><ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/ERB.html" title="NetLinx::ERB (module)">ERB</a></span><small class='search_info'>NetLinx</small></li><ul><li><span class='object_link'><a href="NetLinx/ERB/HashHelpers.html" title="NetLinx::ERB::HashHelpers (module)">HashHelpers</a></span><small class='search_info'>NetLinx::ERB</small></li><li><span class='object_link'><a href="NetLinx/ERB/Helpers.html" title="NetLinx::ERB::Helpers (module)">Helpers</a></span><small class='search_info'>NetLinx::ERB</small></li></ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/Rake.html" title="NetLinx::Rake (module)">Rake</a></span><small class='search_info'>NetLinx</small></li><ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/Rake/ERB.html" title="NetLinx::Rake::ERB (module)">ERB</a></span><small class='search_info'>NetLinx::Rake</small></li><ul><li><span class='object_link'><a href="NetLinx/Rake/ERB/GenerateERB.html" title="NetLinx::Rake::ERB::GenerateERB (class)">GenerateERB</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li><li><span class='object_link'><a href="NetLinx/Rake/ERB/GenerateRPC.html" title="NetLinx::Rake::ERB::GenerateRPC (class)">GenerateRPC</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li><li><span class='object_link'><a href="NetLinx/Rake/ERB/Lines.html" title="NetLinx::Rake::ERB::Lines (class)">Lines</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li></ul></ul></ul><li><span class='object_link'><a href="RPC.html" title="RPC (class)">RPC</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><span class='object_link'><a href="String.html" title="String (class)">String</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li>
+<li><span class='object_link'><a href="Array.html" title="Array (class)">Array</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><span class='object_link'><a href="Hash.html" title="Hash (class)">Hash</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx.html" title="NetLinx (module)">NetLinx</a></span><small class='search_info'>Top Level Namespace</small></li><ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/ERB.html" title="NetLinx::ERB (module)">ERB</a></span><small class='search_info'>NetLinx</small></li><ul><li><span class='object_link'><a href="NetLinx/ERB/HashHelpers.html" title="NetLinx::ERB::HashHelpers (module)">HashHelpers</a></span><small class='search_info'>NetLinx::ERB</small></li><li><span class='object_link'><a href="NetLinx/ERB/Helpers.html" title="NetLinx::ERB::Helpers (module)">Helpers</a></span><small class='search_info'>NetLinx::ERB</small></li></ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/Rake.html" title="NetLinx::Rake (module)">Rake</a></span><small class='search_info'>NetLinx</small></li><ul><li><a class='toggle'></a> <span class='object_link'><a href="NetLinx/Rake/ERB.html" title="NetLinx::Rake::ERB (module)">ERB</a></span><small class='search_info'>NetLinx::Rake</small></li><ul><li><span class='object_link'><a href="NetLinx/Rake/ERB/GenerateERB.html" title="NetLinx::Rake::ERB::GenerateERB (class)">GenerateERB</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li><li><span class='object_link'><a href="NetLinx/Rake/ERB/GenerateRPC.html" title="NetLinx::Rake::ERB::GenerateRPC (class)">GenerateRPC</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li><li><span class='object_link'><a href="NetLinx/Rake/ERB/Lines.html" title="NetLinx::Rake::ERB::Lines (class)">Lines</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li><li><span class='object_link'><a href="NetLinx/Rake/ERB/Push.html" title="NetLinx::Rake::ERB::Push (class)">Push</a></span> &lt; TaskLib<small class='search_info'>NetLinx::Rake::ERB</small></li></ul></ul></ul><li><span class='object_link'><a href="RPC.html" title="RPC (class)">RPC</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li><li><span class='object_link'><a href="String.html" title="String (class)">String</a></span> &lt; Object<small class='search_info'>Top Level Namespace</small></li>
 
       </ul>
     </div>

data/doc/file.README.html

@@ -66,15 +66,17 @@
 
 <p>netlinx-erb</p>
 
-<p>A code generation utility for AMX NetLinx control systems.</p>
+<p>A code generation framework for AMX NetLinx control systems.</p>
 
 <p><a href="http://badge.fury.io/rb/netlinx-erb"><img
 src="https://badge.fury.io/rb/netlinx-erb.svg"></a> <a
 href="http://www.rubydoc.info/gems/netlinx-erb"><img
-src="http://img.shields.io/badge/docs-api-blue.svg"></a></p>
+src="http://img.shields.io/badge/docs-api-blue.svg"></a> <a
+href="https://github.com/amclain/netlinx-erb/blob/master/license.txt"><img
+src="https://img.shields.io/badge/license-MIT-yellowgreen.svg"></a></p>
 
 <p>Syntax highlighting is included in <a
-href="https://github.com/amclain/sublime-netlinx">sublime-netlinx</a>.</p>
+href="https://github.com/amclain/sublime-netlinx#sublime-text-amx-netlinx-plugin">sublime-netlinx</a>.</p>
 
 <h2 id="label-Overview">Overview</h2>
 
@@ -198,31 +200,497 @@ be installed on your computer for this utility to work. It is included in
 the NetLinx Studio installation by default.</em></p>
 
 <p><strong>If you receive the following error when running gem
-install:</strong> <code>Unable to download data from https://rubygems.org/
-- SSL_connect returned=1</code></p>
+install:</strong> <code>text Unable to download data from
+https://rubygems.org/ - SSL_connect returned=1 </code></p>
 
 <p>Follow this guide: <a
 href="https://gist.github.com/luislavena/f064211759ee0f806c88">Workaround
 RubyGems’ SSL errors on Ruby for Windows (RubyInstaller)</a></p>
 
-<h2 id="label-Prerequisite+Knowledge">Prerequisite Knowledge</h2>
+<h2 id="label-Prerequisites">Prerequisites</h2>
 
 <p>netlinx-erb is a complex utility and does have a learning curve. However,
 the time invested in learning this utility pays off in time saved from
 generating code that would otherwise be handwritten, and troubleshooting
 fewer bugs. Due to this, project maintenance also becomes easier.</p>
 
+<h3 id="label-Programming+Languages">Programming Languages</h3>
+
 <p>Basic experience with the <a href="https://www.ruby-lang.org">Ruby
 programming language</a> is required, as well as <a
-href="http://www.stuartellis.eu/articles/erb/">ERB templating</a>.</p>
+href="http://www.stuartellis.eu/articles/erb/">ERB templating</a>. The
+concept of <a href="http://download.imatix.com/mop/introduction.html">Model
+Oriented Programming (MOP)</a> is also used by this framework.</p>
+
+<p><strong>Resources:</strong></p>
+<ul><li>
+<p><a href="http://shop.oreilly.com/product/9780596803995.do">Head First
+Ruby</a></p>
+</li><li>
+<p><a
+href="http://www.amazon.com/Design-Patterns-Ruby-Russ-Olsen/dp/0321490452/ref=sr_1_1?ie=UTF8&qid=1424904889&sr=8-1&keywords=ruby+design+patterns">Design
+Patterns in Ruby</a></p>
+</li><li>
+<p><a
+href="http://www.amazon.com/Practical-Object-Oriented-Design-Ruby-Addison-Wesley/dp/0321721330/ref=sr_1_2?ie=UTF8&qid=1424904889&sr=8-2&keywords=ruby+design+patterns">Practical
+Object-Oriented Design in Ruby</a></p>
+</li></ul>
+
+<h3 id="label-Development+Tools">Development Tools</h3>
+
+<h4 id="label-Text+Editor">Text Editor</h4>
+
+<p>A good text editor is crucial for working with netlinx-erb. <a
+href="http://www.sublimetext.com/3">Sublime Text 3</a> with the <a
+href="https://github.com/amclain/sublime-netlinx#sublime-text-amx-netlinx-plugin">sublime-netlinx</a>
+plugin is recommended, as it provides syntax highlighting and code
+completion for netlinx-erb.</p>
+
+<blockquote>
+<p><strong><em>Use a Single Editor Well</em></strong></p>
+
+<p><em>The editor should be an extension of your hand; make sure your editor
+is configurable, extensible, and programmable.</em> – <a
+href="http://www.informit.com/store/pragmatic-programmer-from-journeyman-to-master-9780201616224">The
+Pragmatic Programmer</a></p>
+</blockquote>
+
+<h4 id="label-Command+Prompt">Command Prompt</h4>
+
+<p>The command prompt is a powerful, flexible way to issue commands. Due to
+this, many of the tools that netlinx-erb is built on use command line
+interfaces.</p>
+
+<p>This guide will assume the reader is proficient with the command prompt.
+SS64 is a great <a href="http://ss64.com/">command line reference</a> if
+you need to look up a command.</p>
+
+<h2 id="label-Workflow">Workflow</h2>
+
+<p>Developing a NetLinx project with netlinx-erb is significantly different
+than with NetLinx Studio. Although netlinx-erb and NetLinx Studio are not
+strictly mutually exclusive, trying to use NetLinx Studio to develop a
+netlinx-erb project will create unnecessary friction.</p>
+
+<p>There are three applications you will bounce between when developing a
+netlinx-erb project:</p>
+<ul><li>
+<p>Text Editor</p>
+</li><li>
+<p>Command Prompt</p>
+</li><li>
+<p>Source Control Management System</p>
+</li></ul>
+
+<p>At times you may need to open some of the standalone NetLinx tools like
+NetLinx Diagnostics.</p>
+
+<h3 id="label-Transitioning+From+NetLinx+Studio">Transitioning From NetLinx Studio</h3>
+
+<p>The big difference to understand coming from NetLinx Studio is that NetLinx
+Studio is designed to be a monolithic, all-in-one application that contains
+all of the features that you need. Or at least that&#39;s the theory. The
+problem is that in reality NetLinx Studio only contains the features that
+AMX thinks you need, and can&#39;t support features you want to add
+yourself.</p>
+
+<p>What happens when you want to add code generation and automation to NetLinx
+Studio to save time on repetitive tasks? Well, you can&#39;t.</p>
+
+<p>netlinx-erb takes the opposite approach, building on many different
+components that are smaller in scope. To the greatest extent possible,
+these components are extendable, customizable, and cross-platform. This
+means you&#39;re able to modify a netlinx-erb development environment to
+suit a particular project, or your workflow in general.</p>
+
+<p>Integrating with source control management (SCM) systems like <a
+href="http://tortoisehg.bitbucket.org/">Mercurial</a> and <a
+href="http://git-scm.com/">Git</a> was also an important goal of
+netlinx-erb. Due to this, most files are plain text and typically easy to
+read by a human. The philosophy is that configuration should happen in your
+text editor, not a proprietary GUI.</p>
 
 <h2 id="label-Getting+Started">Getting Started</h2>
 
-<h2 id="label-Code+Examples">Code Examples</h2>
+<h3 id="label-Creating+A+New+Project">Creating A New Project</h3>
+
+<p>Open the command prompt in the directory used for your NetLinx projects and
+type:</p>
+
+<pre class="code ruby"><code class="ruby">netlinx-erb -n my_project</code></pre>
+
+<p>Enter the <code>my_project</code> directory and take a minute to skim
+through the files that have been generated.</p>
+
+<h3 id="label-Configuring+The+Workspace">Configuring The Workspace</h3>
+
+<p><code>workspace.config.yaml</code>, referred to as the workspace
+configuration, is a text file that replaces the functionality of a NetLinx
+Studio <code>.apw</code> workspace file. Change this file to the following:</p>
+
+<pre class="code ruby"><code class="ruby">systems:
+  -
+    name: My Project
+    connection: 192.168.1.2 # (or your master)
+    touch_panels:
+      -
+        path: touch_panel.TP4
+        dps:
+          - 10001:1:0
+          - 10002:1:0
+    ir:
+      -
+        path: cable_box.irl
+        dps: 5001:1:0</code></pre>
+<ul><li>
+<p><a
+href="https://github.com/amclain/netlinx-workspace#yaml-workspace-configuration">YAML
+Workspace Configuration Reference</a></p>
+</li></ul>
+
+<p>Now create <code>My Project.axs</code> and
+<code>include/cable-box.axi</code>. Using Sublime Text, these files can be
+populated using the <code>NetLinx: New From Template: Overview</code> and
+<code>NetLinx: New From Template: Include</code> commands, respectively. If
+you used the templates, comment out the code for the <a
+href="https://github.com/amclain/amx-lib-log#amx-log-library">logger</a>
+for this example.</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*                    INCLUDES GO BELOW                    *)
+(***********************************************************)
+
+// Comment this out for the example.
+// #include &#39;amx-lib-log&#39;
+
+(***********************************************************)
+(*                 STARTUP CODE GOES BELOW                 *)
+(***********************************************************)
+DEFINE_START
+
+// Comment this out for the example.
+// logSetLevel(LOG_LEVEL_DETAIL);</code></pre>
+
+<p>Also create <code>ir/cable_box.irl</code> and
+<code>touch_panel/touch_panel.TP4</code>. These files can be empty, or the
+real thing. It doesn&#39;t matter for the example.</p>
+
+<p>To get an idea of how the workspace config file relates to a traditional
+NetLinx Studio workspace, run:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_rake'>rake</span> <span class='id identifier rubyid_generate_apw'>generate_apw</span>
+</code></pre>
+
+<p>Open <code>My Project.apw</code> in NetLinx Studio and take a look at the
+workspace tree.</p>
+
+<p><img src="guides/getting_started/my_project_apw_01.png"></p>
+
+<p>The master source code, touch panel, and IR files show up in the tree, just
+like we would expect. What you might not expect is that
+<code>cable-box</code> has shown up under the <code>Include</code> folder
+even though it wasn&#39;t specified in the config. This is a feature of <a
+href="https://github.com/amclain/netlinx-workspace#netlinx-workspace">netlinx-workspace</a>,
+which automatically consumes include files since there will probably be a
+lot of them. Don&#39;t worry though, unwanted <a
+href="https://github.com/amclain/netlinx-workspace/blob/6e99397b4fcfa6bd1cd6766008fd75e8dd5092c0/spec/workspace/yaml/single_system/workspace.config.yaml#L11-L13">files
+can be explicity excluded</a>.</p>
+
+<h3 id="label-Code+Generation">Code Generation</h3>
+
+<p><em>At this point it is important to have a working knowledge of Ruby and
+ERB. (See <a
+href="https://github.com/amclain/netlinx-erb#prerequisites">prerequisites</a>.)</em></p>
+
+<p>In this example we&#39;ll connect touch panel buttons to the corresponding
+buttons on the cable box remote control. To keep the code encapulated,
+we&#39;ll have <code>include/cable-box.axi</code> model the cable box&#39;s
+remote control, and <code>include/ui/template/panel.axi.erb.tmpl</code>
+will model the functions of the identical touch panels.</p>
+<ul><li>
+<p><a href="guides/getting_started/my_project">“My Project” Reference
+Files</a></p>
+</li></ul>
+
+<p>First, create <a
+href="guides/getting_started/my_project/include/cable-box.axi">include/cable-box.axi</a>.
+This file uses the traditional <code>.axi</code> extension because no code
+generation is necessary. For a file this simple, code generation may
+actually create more work and make the code harder to understand.</p>
+
+<p>Next we&#39;ll configure the touch panels. Open
+<code>include/ui/_config.axi.erb</code>. This is where we&#39;ll instruct
+the system to generate <code>.axi</code> files for each of the touch
+panels:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># Params - Converted into @tmpl_[key]
+</span><span class='comment'># First key (panel name) is available as @tmpl_suffix
+</span><span class='id identifier rubyid_touch_panels'>touch_panels</span> <span class='op'>=</span> <span class='lbrace'>{</span>
+    <span class='label'>CONFERENCE_TABLE:</span> <span class='lbrace'>{</span> <span class='label'>dps:</span> <span class='int'>10001</span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>WALL:</span>             <span class='lbrace'>{</span> <span class='label'>dps:</span> <span class='int'>10002</span> <span class='rbrace'>}</span><span class='comma'>,</span>
+<span class='rbrace'>}</span>
+</code></pre>
+
+<p>The important thing to notice about this file is that values can be passed
+into each touch panel&#39;s hash, which then become available in the
+template as instance variables. By using the instance variable
+<code>@tmpl_dps</code> in the template, the value <code>10001</code> will
+be written to <code>panel-conference-table.axi</code>, and
+<code>10002</code> will be written to <code>panel-wall.axi</code>.
+We&#39;ll go over this more when creating the template file.</p>
+<ul><li>
+<p>Note: <a
+href="https://github.com/amclain/netlinx-erb/issues/1">_config.axi.erb will
+be deprecated</a></p>
+</li></ul>
+
+<blockquote>
+<p><strong>Why not use <code>DEFINE_COMBINE</code>?</strong></p>
+
+<p>Device combining concatenates all of the events into a single DPS, hiding
+which touch panel actually sent the event. Conceptually, all of the
+physical touch panels have to be thought of as one virtual touch panel –
+they all mirror each other. This means that touch panels that want to share
+the same code are forced to share the same state as well.</p>
+
+<p>The answer to this problem is an advanced topic that will be covered in
+another section. It is practical in situations like room combining where
+touch panel B needs to operate autonomously when the rooms are separated,
+but needs to mirror touch panel A when the rooms are combined (a state
+machine).</p>
+</blockquote>
+
+<p>Since the touch panels share the same design file,
+<code>touch_panel.TP4</code>, we&#39;ll use code generation to create the
+source code for each panel based on a single template.</p>
+
+<p>Create <a
+href="guides/getting_started/my_project/include/ui/template/panel.axi.erb.tmpl">include/ui/template/panel.axi.erb.tmpl</a>.
+The first thing to notice is that unique names for the include guards can
+be code generated:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************
+    Example Touch Panel
+    
+    For the netlinx-erb getting started project.
+************************************************************)
+
+#if_not_defined &lt;%= &quot;MY_PROJECT_TP_#{@tmpl_suffix}&quot; %&gt;
+#define &lt;%= &quot;MY_PROJECT_TP_#{@tmpl_suffix}&quot; %&gt; 1</code></pre>
+
+<p>Let&#39;s apply this to assigning the DPS to each touch panel. Since a
+device definition takes the form of <code>CONSTANT_NAME = DPS</code>, we
+can use code generation to populate the constant name and device number for
+each file:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*           DEVICE NUMBER DEFINITIONS GO BELOW            *)
+(***********************************************************)
+DEFINE_DEVICE
+
+&lt;%= &quot;#{@dvTP} = #{@tmpl_dps}:1:0;&quot; %&gt;</code></pre>
+
+<p>When the <code>.axi</code> files are generated,
+<code>panel-conference-table.axi</code> will contain
+<code>dvTP_CONFERENCE_TABLE = 10001:1:0;</code>, and
+<code>panel-wall.axi</code> will contain <code>dvTP_WALL =
+10002:1:0;</code>.</p>
+
+<blockquote>
+<p>When authoring an <code>erb</code> template it is important to think on a
+higher level of abstration than you would with an <code>axi</code> file,
+keeping in mind that you&#39;re writing code that writes code. Creating
+variations of a similar piece of code is a perfect job for the code
+generator.</p>
+</blockquote>
+
+<p>At this point we have a few different sets of data that need to be
+connected together:</p>
+<ul><li>
+<p>Touch panel button numbers</p>
+</li><li>
+<p>Named constants for those buttons</p>
+</li><li>
+<p>The key on the cable box remote control that needs to be triggered when its
+corresponding touch panel button is pressed</p>
+</li></ul>
+
+<p>These connections can be described in one place, making future changes
+simple:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*              CONSTANT DEFINITIONS GO BELOW              *)
+(***********************************************************)
+DEFINE_CONSTANT
+
+&lt;%
+    # Remember, this template generates multiple files.
+    # Guard your global code to prevent include conflicts!
+-%&gt;
+#if_not_defined MY_PROJECT_TP_CONSTANTS
+#define MY_PROJECT_TP_CONSTANTS 1
+
+&lt;% global_constant_justify = 26 -%&gt;
+// Cable Box Buttons
+&lt;%=
+    generate_constant_ivars cable_box_buttons = {
+        # :btn - Touch panel button number.
+        # :key - Cable box remote control key from `cable-box.axi`.
+        BTN_CABLE_BOX_1: { btn: 101, key: :CABLE_BOX_KEY_1 },
+        BTN_CABLE_BOX_2: { btn: 102, key: :CABLE_BOX_KEY_2 },
+        BTN_CABLE_BOX_3: { btn: 103, key: :CABLE_BOX_KEY_3 },
+        BTN_CABLE_BOX_4: { btn: 104, key: :CABLE_BOX_KEY_4 },
+        BTN_CABLE_BOX_5: { btn: 105, key: :CABLE_BOX_KEY_5 },
+        BTN_CABLE_BOX_6: { btn: 106, key: :CABLE_BOX_KEY_6 },
+        BTN_CABLE_BOX_7: { btn: 107, key: :CABLE_BOX_KEY_7 },
+        BTN_CABLE_BOX_8: { btn: 108, key: :CABLE_BOX_KEY_8 },
+        BTN_CABLE_BOX_9: { btn: 109, key: :CABLE_BOX_KEY_9 },
+        BTN_CABLE_BOX_0: { btn: 110, key: :CABLE_BOX_KEY_0 },
+    }
+    
+    print_constant_hash cable_box_buttons.remap(:btn), justify: global_constant_justify
+%&gt;
+
+#end_if</code></pre>
+<ul><li>
+<p><a
+href="http://www.rubydoc.info/gems/netlinx-erb/NetLinx/ERB/Helpers">Helper
+Method API Reference</a></p>
+</li></ul>
+
+<p>Now it&#39;s time to add a button event handler to connect the touch panel
+button to the cable box IR code:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*                   THE EVENTS GO BELOW                   *)
+(***********************************************************)
+DEFINE_EVENT
+
+// Cable Box Controls
+&lt;%=
+    button_event_block(cable_box_buttons.remap(:key), momentary: true) { |key|
+        &quot;cable_box_key(#{key})&quot;
+    }
+%&gt;</code></pre>
+
+<p>Does this section of code look unusually short compared to its NetLinx
+counterpart? Well there&#39;s a good reason for that: The code it writes is
+incredibly repetitive and therefore a lot of work can be handed off to the
+code generator. Even better, since this code references the
+<code>cable_box_buttons</code> hash, every time a button is added or
+modified this section of generated code is updated automatically.</p>
+
+<pre class="code ruby"><code class="ruby">// GENERATED FILE `panel-conference-table.axi`
+
+(***********************************************************)
+(*                   THE EVENTS GO BELOW                   *)
+(***********************************************************)
+DEFINE_EVENT
+
+// Cable Box Controls
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_1]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_2]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_3]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_4]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_5]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_6]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_7]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_8]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_9]
+button_event[dvTP_CONFERENCE_TABLE, BTN_CABLE_BOX_0]
+{
+    push:
+    {
+        to[button.input];
+        
+        switch (button.input.channel)
+        {
+            case BTN_CABLE_BOX_1:    cable_box_key(CABLE_BOX_KEY_1);
+            case BTN_CABLE_BOX_2:    cable_box_key(CABLE_BOX_KEY_2);
+            case BTN_CABLE_BOX_3:    cable_box_key(CABLE_BOX_KEY_3);
+            case BTN_CABLE_BOX_4:    cable_box_key(CABLE_BOX_KEY_4);
+            case BTN_CABLE_BOX_5:    cable_box_key(CABLE_BOX_KEY_5);
+            case BTN_CABLE_BOX_6:    cable_box_key(CABLE_BOX_KEY_6);
+            case BTN_CABLE_BOX_7:    cable_box_key(CABLE_BOX_KEY_7);
+            case BTN_CABLE_BOX_8:    cable_box_key(CABLE_BOX_KEY_8);
+            case BTN_CABLE_BOX_9:    cable_box_key(CABLE_BOX_KEY_9);
+            case BTN_CABLE_BOX_0:    cable_box_key(CABLE_BOX_KEY_0);
+        }
+    }
+    
+    release: {}
+}</code></pre>
+
+<p>A remote control is a simple example of code generation in action. For a
+device like a video matrix, imagine what happens when one of the inputs or
+outputs needs to be repatched or renamed. All of the configuration
+information is in one place; no need to find-and-replace throughout a file.
+This also helps to make the code self-documenting, as all of the system
+configuration information is grouped together.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_matrix_inputs'>matrix_inputs</span> <span class='op'>=</span> <span class='lbrace'>{</span>
+    <span class='label'>VID_SRC_BLANK:</span>          <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>0</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Blank</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_1_PODIUM:</span>  <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>1</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Podium 1</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_1_WP:</span>      <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>2</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Wall Panel 1</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_2_PODIUM:</span>  <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>7</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Podium 2</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_2_WP:</span>      <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>4</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Wall Panel 2</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_3_PODIUM:</span>  <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>5</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Podium 3</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_ROOM_3_WP:</span>      <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>6</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Wall Panel 3</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_BLURAY:</span>         <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>9</span><span class='comma'>,</span>  <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Blu-Ray</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+    <span class='label'>VID_SRC_CABLE:</span>          <span class='lbrace'>{</span> <span class='label'>input:</span> <span class='int'>10</span><span class='comma'>,</span> <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Cable TV</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
+<span class='rbrace'>}</span>
+</code></pre>
+
+<blockquote>
+<p><strong>Separating Configuration From Implementation</strong></p>
+
+<p>netlinx-erb is designed to keep configuration and implementation code
+separated as much as reasonably possible. This makes configuration changes
+fast and easy, with significantly less risk that those changes will
+introduce bugs or break the system.</p>
+</blockquote>
+
+<p>Now that we have a touch panel template, open <code>My Project.axs</code>
+and add the includes for <code>panel-conference-table</code> and
+<code>panel-wall</code>:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*                    INCLUDES GO BELOW                    *)
+(***********************************************************)
+
+// Comment this out for the example.
+// #include &#39;amx-lib-log&#39;
+
+#include &#39;panel-conference-table&#39;
+#include &#39;panel-wall&#39;</code></pre>
+
+<p>Also remember the include for <code>cable-box</code> in
+<code>panel.axi.erb.tmpl</code>:</p>
+
+<pre class="code ruby"><code class="ruby">(***********************************************************)
+(*                    INCLUDES GO BELOW                    *)
+(***********************************************************)
+
+#include &#39;cable-box&#39;</code></pre>
+
+<h3 id="label-Compiling">Compiling</h3>
+
+<p>From the command line:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_rake'>rake</span>
+</code></pre>
+
+<p>Yes, it&#39;s really that simple. This command runs the code generator,
+generates the RPC file, compiles the project, and creates the source code
+bundle. You can also add your own <a
+href="https://github.com/ruby/rake#description">rake tasks</a> if you need
+to customize this process.</p>
+
+<p>See all of the built-in rake tasks with <code>rake -T</code>.</p>
 </div></div>
 
     <div id="footer">
-  Generated on Wed Feb 25 14:28:07 2015 by
+  Generated on Mon Jun 29 16:09:05 2015 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.1.3).
 </div>