Initializing help system before first use

VDL Basics - a Recap

This section revisits and extends the VDL basics introduced in Getting Started , which is recommended reading prior to this chapter.

Before you can include a VDL view in your app, you need to declare it in your app's companion file - an XML file located directly in your app root folder.

Below is the companion file from the example app. 
<?xml version="1.0" encoding="UTF-8"?>
  <model-companion xmlns="http://www.fico.com/xpress/optimization-modeler/model-companion" version="3.0">
    <client>
      <view-group title="Portfolio Optimization">
        <vdl-view title="Portfolio" path="foliodata.vdl"></vdl-view>
      </view-group>
    </client>
  </model-companion>

Note how the path attribute of the vdl-view element points to a file called foliodata.vdl - Xpress Insight expects to find this in a client_resources directory just below the app root. See Introducing the Companion File for more information.

The referenced foliodata.vdl file contains the following code: 
<vdl version="4.1">
  <vdl-page>
    <vdl-section heading="Welcome to Portfolio Optimization"
                 heading-level="1">
      <vdl-section heading="Return per share"
                   heading-level="2">
        <vdl-form>
          <vdl-field entity="changeShare"
                     options-set="SHARES"
                     label="Choose share"></vdl-field>
          <vdl-field entity="RET"
                     indices="=scenario.entities.changeShare.value"
                     label="Estimated ROI">
            <vdl-validate pass="=value >= 0">ROI must be zero or greater.
            </vdl-validate>
            <vdl-tooltip title="Estimated ROI"
                         content="Specify the expected percentage return on investment">
          </vdl-field>
        </vdl-form>
        <vdl-execute-button caption="Run scenario"></vdl-execute-button>
      </vdl-section>
      <vdl-section heading="Optimal result" heading-level="2">
        <span vdl-text="Calculated optimal return: "></span>
        <span vdl-text="=insight.Formatter.formatNumber(
          scenario.entities.Return.value, '00.##')">
        </span>
      </vdl-section>
      <vdl-section heading="Recommended share allocations"
                  heading-level="3">
        <vdl-table page-mode="paged" page-size="5"
                   show-filter="true"
                   column-filter="true">
          <vdl-table-column entity="frac"></vdl-table-column>
          <vdl-table-column entity="RET"></vdl-table-column>
        </vdl-table>
      </vdl-section>
    </vdl-section>
  </vdl-page>
</vdl>

All VDL views begin with a <vdl> element that specifies the version number of the VDL syntax for the page. Within this, a <vdl-page> element acts as a container for your view contents.

Page content is organized into sections using the <vdl-section> element. For smaller pages, you might only use one section, but for larger pages, separating your content into several sections will help you organize your layout. Sections can be nested, and each can have an optional heading, set via a heading attribute. Above, the heading of the top level section has been set to Welcome to Portfolio Optimization.

Embedded within several elements above are <p> elements with vdl-text attributes - in VDL, there are special attributes prefixed with vdl- that can be applied to several elements. In this case, the vdl-text attribute sets the text of the element to which it belongs to the value contained between the double quotes

The lines: 
<span vdl-text="=insight.Formatter.formatNumber(
          scenario.entities.Return.value, '00.##')">
        </span>
contain a vdl-text attribute which is assigned to an expression, a specially structured string that using the Xpress Insight data bindings, is able to reach into the runtime model, extract and manipulate some data and deposit its value in the rendered paragraph for display. All expressions begin with =. Here, it is simply retrieving and formatting the value of the entity whose fully-qualified name is scenario.entities.Return - you will recognize this as the scalar value that contains the optimal return in the baseline example. Furthermore, VDL will keep the element value up-to-date if the entity changes locally or remotely.
Covered Topics
  • VDL Tags and Attributes
    All VDL tags and standalone attributes are prefixed with vdl- so that they are easy to identify and don't conflict with current or future HTML tags and attributes.
Parent Topic Using VDL to Create Custom Views

© 2001-2019 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.