View source for Documentation:Overriding AngularJS MDriven Turnkey Views

You can replace a generated AngularJS Turnkey view with your own <code>.cshtml</code> page when you need to control the layout and HTML for a ViewModel; this is for developers working with [[Documentation:AngularJS Client|the AngularJS Turnkey client]].
== Choose the right override scope ==
Use a page override when you need to reorganize the complete view, such as moving actions into a sidebar, replacing the generated content area, or adding page-specific JavaScript. A page override replaces the built-in page renderer, so you are responsible for rendering the parts of the page that you still need.

If you only need to replace the control for one ViewModel column, use an [[Documentation:EXT Components|EXT Component]] instead. EXT Components support column-level overrides through <code>UIOverride</code> and avoid copying an entire page layout. For example, use an EXT Component to render a text column with a rich-text editor; see [[Documentation:TinyMCE editor]].

{| class="wikitable"
! Need
! Use
! Example
|-
| Change the layout of a whole ViewModel page
| Page override
| Put generated actions in a left column and content in a right column.
|-
| Replace one generated input control
| [[Documentation:EXT Components|EXT Component]]
| Render a specific text column with a custom editor.
|-
| Load a script before AngularJS compiles the application
| [[Documentation:AppWideAngularScriptIncludes|AppWideAngularScriptIncludes]]
| Load a script that registers an AngularJS directive.
|}
== Start from the generated bindings ==
Before writing the override, inspect the bindings suggested for the current ViewModel. Turnkey exposes them at <code>https://&lt;yoursite&gt;/Turnkey/Development?view</code>; the Portal also provides a link. See [[Documentation:Bindings for angular|Bindings for angular]].

The bindings reveal the names that the AngularJS page can use. Data available to your HTML is derived from the [[Documentation:ViewModel|ViewModel]]. Do not expect arbitrary server-side domain objects to be available unless the ViewModel exposes them.

For a ViewModel with a column named <code>RegistrationNumber</code>, bind the input to <code>root.RegistrationNumber</code>:

<syntaxhighlight lang="html">
<input ng-model="root.RegistrationNumber" />
</syntaxhighlight>

The generated bindings also provide status expressions for ViewModel columns. Keep these expressions when your replacement control must follow the modeled enabled, visible, and style behavior:

<syntaxhighlight lang="html">
<input ng-model="root.RegistrationNumber"
       ng-disabled="!root.VM_Status.EditOneCar_RegistrationNumber_Enabled"
       ng-show="root.VM_Status.EditOneCar_RegistrationNumber_Visible"
       ng-class="root.VM_Status.EditOneCar_RegistrationNumber_Style" />
</syntaxhighlight>

In this example, <code>EditOneCar</code> is the ViewModel class runtime name and <code>RegistrationNumber</code> is the column runtime name. Use the names from your generated bindings; do not copy these names unchanged into another model.

If your ViewModel is defined like this:
[[File:Overriding angular - 2.png|none|frame]]
== Create a page override ==
Follow the deployment and override procedure in [[Documentation:Turnkey session 9: View Override|Turnkey session 9: View Override]]. Start with a copy of the generic view and then change one area at a time.

# Create the override <code>.cshtml</code> file as described in [[Documentation:View/Page override|View/Page override]].
# Begin with the generic structure below.
# Confirm that actions, content, loading feedback, and constraint messages still appear.
# Replace generated content with your own AngularJS markup, using the binding names from <code>/Turnkey/Development?view</code>.
# Test both editable and non-editable states, hidden states, validation messages, and master-detail selection.

<syntaxhighlight lang="html">
@using Eco.MVC
@model AngularModel
@{ Layout = null; }

<h3>{{root._ViewModelPresentation}}</h3>

<form>
  <!-- The form enables postback-style validation so constraint messages can appear. -->
  <div id="floatingRectangle" ng-show="root._Admin.Loading()">
    <img src="~/Content/ajax-loader.gif" />
  </div>

  <div class="container-fluid">
    <div class="row">
      <div class="col-md-2" style="vertical-align:top;">
        @Html.AngualarUIActions(Model)
      </div>
      <div class="col-md-10" style="padding:10px;border-left: lightgray thin solid;">
        @Html.AngualarUI(Model)
      </div>
    </div>
    <div class="row">
      <div class="col-md-offset-2 col-md-10">
        @Html.DisplayErrorsWarningsInfos(Model)
      </div>
    </div>
  </div>
</form>

@Html.Partial("_DeveloperInfoPartial")
</syntaxhighlight>

The example uses Bootstrap <code>div</code> layout classes rather than tables for the overall page layout. The table element remains appropriate for tabular data, such as a grid.

Start with this basic structure for your .cshtml page:
<html>
<pre class="code"><span style="background: yellow; color: black">@</span><span style="background: white; color: blue">using </span><span style="background: white; color: black">Eco.MVC
</span><span style="background: yellow; color: black">@model </span><span style="background: white; color: #2b91af">AngularModel
@{ Layout = null; }</span></pre>
=== Preserve the generated helpers unless you replace their behavior ===
The generic view contains helpers that render generated UI and feedback:

{| class="wikitable"
! Helper or expression
! Purpose in the generic view
|-
| <code>@Html.AngualarUIActions(Model)</code>
| Renders the generated action area.
|-
| <code>@Html.AngualarUI(Model)</code>
| Renders the generated ViewModel UI.
|-
| <code>@Html.DisplayErrorsWarningsInfos(Model)</code>
| Renders error, warning, and information constraints.
|-
| <code>root._Admin.Loading()</code>
| Controls the loading indicator.
|}

For example, if you replace <code>@Html.AngualarUI(Model)</code> with hand-written controls, retain <code>@Html.DisplayErrorsWarningsInfos(Model)</code> unless you provide equivalent feedback yourself. Otherwise modeled constraints may no longer be shown on the page.
== Bind common controls ==
Here is an example of binding a heading to display a ViewModel property:
<pre class="code"><span style="background: white; color: #2b91af">
</span><span style="background: white; color: blue">&lt;</span><span style="background: white; color: maroon">h3</span><span style="background: white; color: blue">&gt;</span><span style="background: white; color: black">{{</span><span style="background: white; color: purple">root._ViewModelPresentation</span><span style="background: white; color: black">}}</span><span style="background: white; color: blue">&lt;/</span><span style="background: white; color: maroon">h3</span><span style="background: white; color: blue">&gt;
&lt;</span><span style="background: white; color: maroon">form </span><span style="background: white; color: blue">&gt; </span><span style="background: white; color: #006400">&lt;!--The only reason for having a form is the ability to simulate a <br>            postback so that validation is triggered and the error bubbles may show--&gt;
        &lt;!--Body content--&gt;
        </span><span style="background: white; color: blue">&lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">id</span><span style="background: white; color: blue">="floatingRectangle" </span><span style="background: white; color: red">ng-show</span><span style="background: white; color: blue">='root._Admin.Loading()'&gt;<br>            &lt;</span><span style="background: white; color: maroon">img </span><span style="background: white; color: red">src</span><span style="background: white; color: blue">='~/Content/ajax-loader.gif' /&gt;&lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
        &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="container-fluid"&gt;
          &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="row"&gt;
            &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="col-md-2" </span><span style="background: white; color: red">style</span><span style="background: white; color: blue">="</span><span style="background: white; color: red">vertical-align</span><span style="background: white; color: black">:</span><span style="background: white; color: blue">top</span><span style="background: white; color: black">;</span><span style="background: white; color: blue">"&gt;
                </span><span style="background: yellow; color: black">@</span><span style="background: white; color: black">Html.AngualarUIActions(Model)
            </span><span style="background: white; color: blue">&lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
            &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="col-md-10" </span><span style="background: white; color: red">style</span><span style="background: white; color: blue">="</span><span style="background: white; color: red">padding</span><span style="background: white; color: black">:</span><span style="background: white; color: blue">10px</span><span style="background: white; color: black">;</span><span style="background: white; color: red">border-left</span><span style="background: white; color: black">: </span><span style="background: white; color: blue">lightgray thin solid </span><span style="background: white; color: black">;</span><span style="background: white; color: blue">"&gt;<br>                                      </span><span style="background: yellow; color: black">@</span><span style="background: white; color: black">Html.AngualarUI(Model)</span><span style="background: white; color: blue">&lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
          &lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
          &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="row"&gt;
            &lt;</span><span style="background: white; color: maroon">div </span><span style="background: white; color: red">class</span><span style="background: white; color: blue">="col-md-offset-2 col-md-10"&gt;<br>                      </span><span style="background: yellow; color: black">@</span><span style="background: white; color: black">Html.DisplayErrorsWarningsInfos(Model)</span><span style="background: yellow; color: black">@''</span><span style="background: white; color: #006400">Error,Warning,Info constraints</span><span style="background: yellow; color: black">''@</span><span style="background: white; color: blue">&lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
          &lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;
        &lt;/</span><span style="background: white; color: maroon">div</span><span style="background: white; color: blue">&gt;  
&lt;/</span><span style="background: white; color: maroon">form</span><span style="background: white; color: blue">&gt;
</span><span style="background: yellow; color: black">@</span><span style="background: white; color: black">Html.Partial(</span><span style="background: white; color: #a31515">"_DeveloperInfoPartial"</span><span style="background: white; color: black">)
</span></pre>

</html>
Take a closer look at the parts:
[[File:Overriding angular -1.png|none|frame]]
=== Text input ===
Bind an editable ViewModel column with <code>ng-model</code>. Add the generated status bindings so the control follows the ViewModel's rules.

<syntaxhighlight lang="html">
<input ng-model="root.RegistrationNumber"
       ng-disabled="!root.VM_Status.EditOneCar_RegistrationNumber_Enabled"
       ng-show="root.VM_Status.EditOneCar_RegistrationNumber_Visible"
       ng-class="root.VM_Status.EditOneCar_RegistrationNumber_Style" />
</syntaxhighlight>
=== Select control ===
A pick list can be rendered with <code>ng-options</code>. This example stores the selected object's object ID in <code>root.Brand</code> and displays each option's <code>Name</code>.

<syntaxhighlight lang="html">
<select ng-model="root.Brand"
        ng-options="opt.GetOId() as opt.Name for opt in root.BrandPickList">
</select>
</syntaxhighlight>

Apply the corresponding <code>ng-disabled</code>, <code>ng-show</code>, and <code>ng-class</code> expressions when the select must follow enabled, visible, and style rules.
=== Grid and current row ===
Use <code>ng-repeat</code> to render a collection. All ViewModel objects have a Boolean <code>vCurrent</code> property. Binding a checkbox to it selects the current object and sets the <code>vCurrent_&lt;ViewModelClass&gt;</code> variable used for master-detail currency.

<syntaxhighlight lang="html">
<table>
  <thead>
    <tr>
      <th></th>
      <th>Name</th>
      <th>Length</th>
      <th>Genre</th>
    </tr>
  </thead>
  <tbody>
    <tr ng-repeat="video in root.AllVideo">
      <td><input type="checkbox" ng-model="video.vCurrent" /></td>
      <td>{{video.Name}}</td>
      <td>{{video.Length}}</td>
      <td>{{video.Genre}}</td>
    </tr>
  </tbody>
</table>
</syntaxhighlight>

Use ng-repeat to render a collection with row selection:
<html>
<pre class="code"><span style="background: white; color: green;">       &lt;table&gt;
        &lt;thead&gt;
          &lt;tr&gt;
            &lt;th&gt;&lt;/th&gt;
            &lt;th&gt;Name&lt;/th&gt;
            &lt;th&gt;Length&lt;/th&gt;
            &lt;th&gt;Genre&lt;/th&gt;
          &lt;/tr&gt;
        &lt;/thead&gt;
        &lt;tbody&gt;
          &lt;tr <span style="background-color: #ffff00;">ng-repeat="video in root.AllVideo"&gt;</span>
            &lt;td&gt;  &lt;input type="checkbox" name="input" ng-model="video.<span style="background-color: #ffff00;">vCurrent</span>"&gt;&lt;/td&gt;
            &lt;td&gt;  {{ video.Name }}        &lt;/td&gt;
            &lt;td&gt;  {{ video.Length }}  &lt;/td&gt;
            &lt;td&gt;  {{ video.Genre }}         &lt;/td&gt;
          &lt;/tr&gt;
        &lt;/tbody&gt;
      &lt;/table&gt;
</span></pre>
== Access data in a master-detail hierarchy ==
At the root ViewModel level, a property can be addressed directly. For example, <code>root.RegistrationNumber</code> works when the current <code>EditOneCar</code> object is represented at the root.

When the ViewModel class is deeper in a master-detail hierarchy, retrieve the current object for that ViewModel class through <code>root._Admin.GetCurrentForVMClass(...)</code>:

<syntaxhighlight lang="html">
<input ng-model="root._Admin.GetCurrentForVMClass('EditOneCar')['RegistrationNumber']" />
</syntaxhighlight>

This expression finds the object currently selected for <code>EditOneCar</code> and then accesses its <code>RegistrationNumber</code>. Use this form when a direct <code>root.PropertyName</code> binding does not refer to the intended current detail object.
== Add page-specific JavaScript ==
A page override can contain a <code>&lt;script&gt;</code> block. To obtain the AngularJS scope from an element, use <code>angular.element(this).scope()</code>. For example, an ordinary HTML <code>onclick</code> handler can pass the scope to a function that invokes a ViewModel action after a delay:

<syntaxhighlight lang="html">
<button onclick="DelayedSave(angular.element(this).scope())">Save later</button>

<script>
  function DelayedSave(scope) {
    setTimeout(function () {
      scope.StreamingViewModelClient.CallServerAction('JournalSeeker', 'LazySave');
    }, 2000);
  }
</script>
</syntaxhighlight>

A button can have both <code>ng-click</code> and <code>onclick</code>; both handlers are called. The action names in this example are model-specific. Replace them with the ViewModel class and action names from your application. For details, see [[Documentation:View/Page override|View/Page override]].

If a script must be available before AngularJS compiles the application, add it through [[Documentation:AppWideAngularScriptIncludes|AppWideAngularScriptIncludes]] or the applicable EXT Component mechanism rather than relying on a page-local script.
== Test the override ==
Test the override after every model update and layout change.

# Open the overridden ViewModel page and verify that the expected presentation appears in <code>{{root._ViewModelPresentation}}</code>.
# Trigger each action that you keep or replace.
# Edit a value that has a constraint and verify that errors, warnings, and information messages appear.
# Verify disabled, hidden, and styled column states.
# In each grid, select a row and verify that detail bindings follow the selected <code>vCurrent</code> object.
# Verify that custom scripts and any required AngularJS directives load in the intended order.
== See also ==
* [[Documentation:Turnkey session 9: View Override]]
* [[Documentation:Turnkey Session 11: More on View Override]]
* [[Documentation:Bindings for angular]]
* [[Documentation:EXT Components]]
* [[Documentation:View/Page override]]
* [[Documentation:AppWideAngularScriptIncludes]]

[[Category:Advanced-Friendly]]
[[Category:Custom HTML and JavaScript in UI]]
[[Category:Priority 70]]
[[Category:UI & Styling]]
[[Category:Web UI and Customization]]