eXNAVHost - FAQ
Exontrol.COM Software - Frequently Asked Questions - ExNAVHost Component
1:
The Exontrol's NAVHost /NET assembly is a Control-AddIn for Microsoft Dynamics NAV environment, that extends your NAV fields with any UI element of the /NET framework, by using the x-script code. 

For instance, 'Height=32;AssemblyQualifiedName = "System.Windows.Forms.TrackBar, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"; Host.Template = "Value = 5"'' adds a track-bar to your NAV form. The eXNAVHost component is a Control-AddIn that can be used to any field on your Microsoft Dynamics NAV pages. 

In order to use the control on your Microsoft Dynamics NAV, you need to follow:

2:
Here's a few samples you can easily add to your NAV pages:
  • System.Windows.Forms.DateTimePicker, 'Height=24;AssemblyQualifiedName = "System.Windows.Forms.DateTimePicker, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"'
  • System.Windows.Forms.HScrollBar, 'Height=24;AssemblyQualifiedName = "System.Windows.Forms.HScrollBar, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"; Host.Template = "Value = 15"'
  • System.Windows.Forms.NumericUpDown, 'Height=24;AssemblyQualifiedName = "System.Windows.Forms.NumericUpDown, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"'
  • System.Windows.Forms.ProgressBar, 'AssemblyQualifiedName = "System.Windows.Forms.ProgressBar, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089";Host.Template = "Value = 50"; Height=24'
  • System.Windows.Forms.PropertyGrid, 'Height=196;AssemblyQualifiedName = "System.Windows.Forms.PropertyGrid, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"; Host.Template = "SelectedObject=Me"'
  • System.Windows.Forms.TrackBar, 'Height=32;AssemblyQualifiedName = "System.Windows.Forms.TrackBar, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"; Host.Template = "Value = 5"'
  • System.Windows.Forms.TreeView, 'Height=64;AssemblyQualifiedName = "System.Windows.Forms.TreeView, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089";Host.Item("Nodes.Add(`Root 1`)").Template = "Nodes{ Add(`Child 1`); Add(`Child 2`) }; Expand() }"'
  • System.Windows.Forms.VScrollBar, 'Width=24;Height=128;AssemblyQualifiedName = "System.Windows.Forms.VScrollBar, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"; Host.Template = "Value = 15"'
3:
The exontrol.NAVHost.dll assembly file can be located on the eXNAVHost\Control.Add-In folder ( For instance, C:\Program Files\Exontrol\eXNAVHost\Control.Add-In )

On the computer running the RoleTailored client, copy the exontrol.NAVHost.dll to the Add-ins folder of the RoleTailored client installation.
By default, the path to this folder is C:\Program Files\Microsoft Dynamics NAV\80\Service\Add-ins. You can also place assemblies in a subfolder of the Add-ins folder. This can be useful when you have multiple assemblies and dependencies.

  • Go To Microsoft Dynamics NAV's Add-ins folder and create a new folder ( for instance "Exontrol.NAVHost" )
  • Copy the exontrol.NAVHost.dll to newly Exontrol.NAVHost folder.

( Source: https://msdn.microsoft.com/en-us/library/dd983803.aspx )

4:
In order to register the Control-AddIn to NAV's "Client Add-in." table do the following:
  • Open the Classic client.
  • On the Tools menu, click Object Designer.
  • Click Tables, and then locate the table with ID 2000000069 and name Client Add-in.
  • Click the table, and then click Run.
  • On a blank line in the Client Add-in table, fill in the Control Add-In Name (Exontrol.NAVHost) and Public Key Token (aaab53cf43a9de9d) fields.
  • Close the Client Add-in table.

(source: https://msdn.microsoft.com/en-us/library/dd983818.aspx )

5:
Once you Register the Control-AddIn to NAV's "Client Add-in." table you can extend your page by doing the following:
  • To set the ControlAddIn property on the field
  • In Object Designer, click Page.
  • Select the page with ID 21 and name Customer Card, and then click Design.
  • Select the Name field, and then on the View menu, click Properties.
  • In the ControlAddIn property value, click the lookup button, and then select the Exontrol.NAVHost;PublicKeyToken=aaab53cf43a9de9d from the Client Add-in window.
  • Select the Caption field, and paste the Template code you want to display ( The C:\Program Files\Exontrol\eXNAVHost\Sample folder includes several templates you can choose from). The X-Script / Template ( for .NET assemblies ) describes using the x-script with the NAVHost component.
  • Close all forms
  • Close the Properties window.

Running the page you should get:

(source: https://msdn.microsoft.com/en-us/library/dd983804.aspx#SetupAddin )

6:
The Caption property of any field ( whose ControlAddIn property value is 'Exontrol.NAVHost;PublicKeyToken=aaab53cf43a9de9d' ), supports x-script or template script. The Template/ x-script code is a simple way of calling control/object's properties, methods/ events using strings. Exontrol owns the x-script implementation in its easiest way and it does not require any VB engine to get executed. Our simple rule is using the component alone without any other dependency than the Windows system.

For instance Caption property on: 'Height=64;AssemblyQualifiedName = "System.Windows.Forms.TreeView, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089";Host.Item("Nodes.Add(`Root 1`)").Template = "Nodes{ Add(`Child 1`); Add(`Child 2`) }; Expand() }"' generates a result such as:

or in other words inserts a TreeView control with a root and two-child elements.

The Template/x-script syntax in BNF notation is defined like follows:

<x-script> := <lines>
<lines> := <line>[<eol> <lines>] | <block>
<block> := <call> [<eol>] { [<eol>] <lines> [<eol>] } [<eol>]
<eol> := ";" | "\r\n"
<line> := <dim> | <createobject> | <call> | <set> | <comment>
<dim> := "DIM" <variables>
<variables> := <variable> [, <variables>]
<variable> := "ME" | <identifier>
<createobject> := "CREATEOBJECT(`"<type>"`)"
<call> := <variable> | <property> | <variable>"."<property> | <createobject>"."<property>
<property> := [<property>"."]<identifier>["("<parameters>")"]
<set> := <call> "=" <value>
<property> := <identifier> | <identifier>"("[<parameters>]")"
<parameters> := <value> [","<parameters>]
<value> := <boolean> | <number> | <color> | <date> | <string> | <createobject> | <call>
<boolean> := "TRUE" | "FALSE"
<number> := "0X"<hexa> | ["-"]<integer>["."<integer>]
<digit10> := 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
<digit16> := <digit10> | A | B | C | D | E | F
<integer> := <digit10>[<integer>]
<hexa> := <digit16>[<hexa>]
<color> := "RGB("<integer>","<integer>","<integer>")"
<date> := "#"<integer>"/"<integer>"/"<integer>" "[<integer>":"<integer>":"<integer>"]"#"
<string> := '"'<text>'"' | "`"<text>"`"
<comment> := "'"<text>

where:

<identifier> indicates an identifier of the variable, property or method, and should start with a letter.
<type> indicates the type the CreateObject function creates, as the assembly-qualified name of the type to create.
<text> any string of characters

The Template / x-script is composed by lines of instructions. Instructions are separated by "\r\n" ( new line characters ) or ";" character. The TemplateThrowError property specifies whether the control fires an exception/error when the Template call fails. The TemplateError / TemplateException gets the error if the Template calls fails. The TemplateResult property returns the result of the last instruction into a Template call, as a NAVObjectTemplate object.

An x-script instruction/line can be one of the following:

  • Dim variable[, variable, ...] declares the variables in the context. Multiple variables are separated by commas. The SetTemplateDef method can declare new variables to be available for the main context. ( Sample: Dim h, h1, h2 )
  • variable = [object.][property/method( arguments ).]property/method( arguments ) assigns the result of the property/method call to the variable. ( Sample: h = Nodes.Add(`Node`) )
  • [object.][property/method( arguments ).]property( arguments ) = value assigns the value to the property. ( Sample: Nodes.Add(`Node`).BackColor = RGB(255,0,0) )
  • [object.][property/method( arguments ).]property/method( arguments ) invokes the property/method. ( Sample: Nodes.Add(`Node`) )
  • {context } delimits the object's context. The properties/fields or methods called between { and } are related to the last object returned by the property/method prior to { declaration. (Sample: Nodes{Add(`Child 1`);Add(`Child 2`)} )
  • . delimits the object than its property or method. (Sample: Nodes.Add(`Element`), or Nodes.Add(`Element`) and Nodes{Add(`Element`)} are equivalents )

where

  • variable is the name of a variable declared with Dim command or previously defined using the SetTemplateDef method.
  • property is the name of a property/field of the current object in the current context.
  • method is the name of a method of the current object in the current context.
  • arguments include constants and/or variables and/or property/method calls separated by comma character.
  • object can be a variable of an Object type, Me or CreateObject call.

The x-script uses constant expressions as follows:

  • boolean expression with possible values as True or False. The True value is equivalent with -1, while False with 0. (Sample: Visible = False )
  • numeric expression may starts with 0x which indicates a hexa decimal representation, else it should starts with digit, or +/- followed by a digit, and . is the decimal separator. Sample: 13 indicates the integer 13, or 12.45 indicates the double expression 12,45. ( Sample: BackColor = 0xFF0000 )
  • date expression is delimited by # character in the format #mm/dd/yyyy hh:mm:ss#. For instance, #31/12/1971# indicates the December 31, 1971 ( Sample: Chart.FirstVisibleDate = #1/1/2001# )
  • string expression is delimited by " or ` characters. If using the ` character, please make sure that it is different than ' which allows adding comments inline. Sample: "text" or `text` indicates the string text, while the ' text , specifies the comment text. ( Sample: Text = "caption" )

Also , the template or x-script code supports general functions as follows:

  • Me property indicates the original object, and it is defined as a predefined variable.  ( Sample: Me.Nodes.Add(`Root 1`) )
  • RGB(R,G,B) property retrieves an RGB value, where the R, G, B are byte values that indicates the Red Green Blue bytes for the color being specified. ( Sample: Nodes.Add(`Root 1`).BackColor = RGB(255,0,0) )
  • LoadPicture(file) property loads a picture from a file and returns a Picture object required by the picture properties. (Sample: BackgroundImage = LoadPicture(`C:\exontrol\images\auction.gif`)
  • CreateObject(assemblyQualifiedName) property creates an instance of the specified type using that type's default constructor. The assemblyQualifiedName indicates the assembly-qualified name of the type to get. See AssemblyQualifiedName. If the type is in the currently executing assembly or in Mscorlib.dll, it is sufficient to supply the type name qualified by its namespace. ( Sample: "CreateObject(`System.Windows.Forms.TabPage, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089`){Text = `Page`;UseVisualStyleBackColor = True}" )
7:
The OnControlAddIn(Index : Integer;Data : Text) trigger notifies your application once the hosting control fires any event. The events being fired depends on the hosting control which usually is specified by the AssemblyQualifiedName call in the Caption property.

In order to handle the OnControlAddin trigger of the Control-AddIn in the NAV's page you have to:

  • Open the NAV's page that hosts the Control-AddIn, in design mode
  • Go to the field that hosts the Control-AddIn
  • Right-Click the field, and choose "C/AL Code"
  • Locate the "OnControlAddIn(Index : Integer;Data : Text)" for the field
  • Add the Message(Data) as in the following sample:
    Name - OnControlAddIn(Index : Integer;Data : Text)
      MESSAGE(Data);
  • Save and Close the page
  • Run the Page, and click the Control-AddIn, and so the message box "Click" is displayed.
8:
The Microsoft Dynamics NAV Development Environment fires "The last editing action (often 'paste') was ignored because it would have caused the maximum number of characters (1024) for the text box to be exceeded." error, in case you are trying to paste a longer template to Caption field. In order to prevent this, you need to create a variable and build the template by concatenating smaller strings as in the following sample:
OnInit()
ContactEditable := TRUE;
MapPointVisible := TRUE;
akaCaption := 'Height=64;';
akaCaption := akaCaption + 'AssemblyQualifiedName = "System.Windows.Forms.TreeView, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089";';
akaCaption := akaCaption + 'Host.Template = `Nodes.Add("Child 1")`;';
akaCaption := akaCaption + 'Host.Template = `Nodes.Add("Child 2")`;';
akaCaption := akaCaption + 'Host.Template = `Nodes.Add("Child 3")`;';
akaCaption := akaCaption + 'Host.Template = `Nodes.Add("Child 4")`;'; 

The akaCaption is a global variable assigned to the CaptionClass property of the field ( whose ControlAddIn property value is 'Exontrol.NAVHost;PublicKeyToken=aaab53cf43a9de9d' )

General Questions