Initializing help system before first use

VDL Basics - a Recap

This section revisits and extends the basic principles introduced in Building a Basic Xpress Insight App, which is recommended reading prior to this chapter.

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

Below is the companion file from the example app, saved as foliodata.xml. 
xml version="1.0" encoding="UTF-8"?>
<!--
    File Type: Model companion file. Configures an Xpress Insight application.
    Purpose: Defines the custom views used by the application.
    (c) 2016-2019 Fair Isaac Corporation.
-->
<model-companion xmlns="http://www.fico.com/xpress/optimization-modeler/model-companion" version="3.0">

    <client>
        <view-group title="Main">

            <vdl-view title="Portfolio" path="foliodata.vdl" empty-selection-default="true" />
        </view-group>
    </client>

</model-companion>

Note how the path attribute of the vdl-view element points to a file called foliodata.vdl—Xpress Insight searches for this file in the client_resources directory just below the app root. For more, see Introducing the Companion File.

When viewed in the code editor, the referenced foliodata.vdl file contains the following code: 
<vdl version="4.7">
    <vdl-page>
        <vdl-header draggable="true">
            <vdl-action-group name="action_group_1" draggable="true">
                <vdl-action-execute></vdl-action-execute>
            </vdl-action-group>
        </vdl-header>
        <vdl-section heading="Welcome to Portfolio Optimization" heading-level="1">
            <vdl-row>
                <vdl-column heading="INPUT DATA" size="6">
                    <vdl-table page-size="5" page-mode="paged">
                        <vdl-table-column entity="Shares_Return" editable="true"></vdl-table-column>
                    </vdl-table>
                    <vdl-button vdl-event="click:actions.action_group_1" 
                        label="Run Optimization">
                    </vdl-button>
                </vdl-column>
                <vdl-column heading="CONFIGURE THE BASIS FOR YOUR DECISION" size="6">
                    <vdl-form>
                        <vdl-field label="Maximum investment per share" entity="MaxPerShare" size="4"></vdl-field>
                        <vdl-field label="Maximum investment into high-risk values" entity="MaxHighRisk" size="4"></vdl-field>
                    </vdl-form>
                    <vdl-execute-button caption="Run Optimization"></vdl-execute-button>
                </vdl-column>
            </vdl-row>
            <vdl-row>
                <vdl-column heading="RESULTS" size="6">
                    <span vdl-text="Calculated optimal return: "></span>
                    <span vdl-text="=insight.Formatter.formatNumber(scenario.entities.TotalReturn.value,'00.##')"></span>
                    <vdl-table column-filter="true" show-filter="true" page-mode="paged" page-size="5">
                        <vdl-table-column set="ShareIds"></vdl-table-column>
                        <vdl-table-column entity="Shares_fraction"></vdl-table-column>
                    </vdl-table>
                </vdl-column>
                <vdl-column heading="SCENARIO COMPARISON" size="6">
                    <ol>
                        <li vdl-repeat="=s, scenarioIndex in scenarios"><span vdl-text="=s.props.name"></span></li>
                    </ol>
                    <vdl-chart vdl-repeat="=s,i in scenarios">
                        <vdl-chart-series entity="Shares_fraction" type="pie" scenario="=i"></vdl-chart-series>
                    </vdl-chart>
                </vdl-column>
            </vdl-row>
        </vdl-section>
    </vdl-page>
</vdl>
In the View Designer, the same file looks like this:

View Designer Palette and artboard

In the code editor view, you can see that:
  • All Views begin with a <vdl> tag specifying the version number of the VDL syntax for the page.
  • The <vdl-page> element contains the 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. The heading of the top section has been set to Welcome to Portfolio Optimization.

The View Designer does not show VDL tags but displays the title or text for the element. If you click on an element to select it on the artboard, the Attributes panel on the right displays the element type at the top. The text field in the RESULTS column, identifiable by the Calculated Optimal Return: attribute in the code editor, displays the Text value shown in the Attributes panel, and contained between the double quotes in the code editor.

Attributes pane

The adjacent field displays the text: 
=insight.Formatter.formatNumber(scenario.entities.TotalReturn.value, '00.##')
The Text attribute for this field is assigned to an expression, a specially structured string that uses the Xpress Insight data bindings to reach into the runtime model, extract, and manipulate some data and display the value in the rendered paragraph.
Note Attributes that can accept expressions are identified by the lightning symbol in the Attributes panel.

All expressions begin with =. Here, it is retrieving and formatting the value of the entity whose fully-qualified name is scenario.entities.TotalReturn—this as the scalar value that contains the optimal return in the baseline example. The dynamic binding means the element value is kept up-to-date if the entity changes locally or remotely.

Covered Topics
  • Tags and Attributes
    All tags and logic attributes, when viewed in the code editor, are prefixed with vdl- so that they are easy to identify and do not conflict with current or future HTML tags and attributes.
Parent Topic Using the View Designer and VDL to Create Custom Views

© 2001-2020 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.