Portrait Foundation v5.0.4 ASP.NET Application Development ...€¦ · Data transformations are XSLT files . which transform the XML returned by the . execution of the configured

ASP.NET Application Development User Guide

Edition 17.0

01 July 2014

UK

Portrait Software

The Smith Centre

The Fairmile

Henley-on-Thames

Oxfordshire, RG9 6AB, UK

Email: [email protected]

Tel: +44 (0)1491 416778

Fax: +44 (0)1491 416601

America

Portrait Software

125 Summer Street

16th Floor

Boston, MA 02110

USA


Tel: +1 617 457 5200

Fax: +1 617 457 5299

Norway

Portrait Software

Portrait Million Handshakes AS

Maridalsveien. 87

0461 Oslo

Norway


Tel: +47 22 38 91 00

Fax: +47 23 40 94 99

P o r t r a i t F o u n d a t i o n

ASP .NET App l i ca t ion Deve lopment User Gu ide

©2014 Copyright Portrait Software International Limited

All rights reserved. This document may contain confidential and proprietary information belonging to

Portrait Software plc and/or its subsidiaries and associated companies.

Portrait Software, the Portrait Software logo, Portrait, Portrait Software's Portrait brand and Million

Handshakes are the trademarks of Portrait Software International Limited and may not be used or

exploited in any way without the prior express written authorization of Portrait Software International

Limited.

Acknowledgement of trademarks

Other product names, company names, marks, logos and symbols referenced herein may be the

trademarks or registered trademarks of their registered owners.

About Portrait Software

Portrait Software is now part of Pitney Bowes Software Inc.

Portrait Software enables organizations to engage with each of their customers as individuals, resulting

in improved customer profitability, increased retention, reduced risk, and outstanding customer

experiences. This is achieved through a suite of innovative, insight-driven applications which empower

organizations to create enduring one-to-one relationships with their customers.

Portrait Software was acquired in July 2010 by Pitney Bowes to build on the broad range of capabilities

at Pitney Bowes Software for helping organizations acquire, serve and grow their customer relationships

more effectively. The Portrait Customer Interaction Suite combines world leading customer analytics,

powerful inbound and outbound campaign management, and best-in-class business process integration

to deliver real-time customer interactions that communicate precisely the right message through the

right channel, at the right time.

Our 300 + customers include industry-leading organizations in customer-intensive sectors. They include

3, AAA, Bank of Tokyo Mitsubishi, Dell, Fiserv Bank Solutions, Lloyds Banking Group, Merrill Lynch,

Nationwide Building Society, RACQ, RAC WA, Telenor, Tesco Bank, T-Mobile, Tryg and US Bank.

Pitney Bowes Software Inc. is a division of Pitney Bowes Inc. (NYSE: PBI).

For more information please visit: http://www.pitneybowes.co.uk/software/

http://www.pb.com/software

http://www.pitneybowes.co.uk/software/

Edition 17.0

Portrait Foundation ASP.NET Application Development User Guide

3 of 40

About this document

Purpose of document This document provides guidelines for the usage of the Portrait Foundation Software Development Kit (SDK) in relation to ASP.NET application development.

For a detailed overview of the SDK along with installation instructions please refer to the Software Development Kit User Guide.

Intended audience Portrait Foundation project implementation teams.

Related documents Software Development Kit User Guide (Foundation SDK User Guide)

Enhancing ASP.NET Applications User Guide

Localizing ASP.NET Applications User Guide

Software release Portrait Foundation 5.0 or later.

Edition 17.0


5 of 40

Contents

1 Foundation Application Framework 6

2 Portrait Foundation application development concepts 7

2.1 Foundation application 7

2.2 Foundation package 7

2.3 Foundation implementation reference 7

2.4 Foundation custom control 9

2.5 Foundation data source controls 11

3 Foundation Web SDK 12

3.1 Web application framework 12

3.2 Creating a new web application 12

3.3 Creating a new web package 13

3.4 Creating new web pages 14

3.5 Using the web control library 25

3.6 Creating a new web control 32

3.7 Using a native ASP.NET Web Application Project 33

3.8 Error handling and reporting (Service Centre channel) 33

Appendix A AIT.Portrait.Web controls 37

Edition 17.0


6 of 40

1 Foundation Application Framework

The Portrait Foundation application framework is based on the standard Microsoft .NET framework and is represented by a set of interface definitions and base class implementations that bridge the technology specific application with the Portrait Foundation system.

This framework manages the common functionality at the Portrait Foundation presentation layer and offers a high level interface for producing new or customised Portrait Foundation applications based on the .NET technology. Its source code cannot be modified by project implementations.

Error handling and reporting functionality is provided in this framework, enabling applications to recover from transient errors and be more resilient. The error

reporting framework allows easy diagnosis of system problems in a production environment.

The Portrait Foundation application framework components are located in the following directory:

<SDK_installation_directory>\Development Environment\dotNET\Portrait Framework

Table 1 – Application framework assemblies

Name Assembly Brief description

Portrait elements applicable to the .NET Web forms implementations

AIT.Portrait.Web.dll Portrait web application framework and the Portrait web controls library

Portrait elements applicable to the .NET SDK

AIT.Portrait.dll Base classes for integration with intrinsic Portrait functionality e.g. interop, logging, error handling.

NB: All assemblies included in this framework are strong-named and reliant upon the specific public key.

Edition 17.0


7 of 40

2 Portrait Foundation application development concepts

This section explains the key concepts involved in implementing a Portrait Foundation application.

2.1 Foundation application A Portrait Foundation application delivers a navigationally controlled and functionally rich environment using Microsoft ASP.NET. These applications typically correspond to an Application Framework Model (AFM) configured using the Portrait Foundation Configuration Suite. The starting point of any such application will be a request to run the AFM on the Process Server, which then

controls the rest of application navigation.

A Portrait Foundation application typically makes use of multiple portrait packages to deliver the functionality.

2.2 Foundation package A Portrait Foundation package contains the user interface collateral required to support a configured Package. This includes the implementation for the following configurable business entities:

Implementation references for screens and custom views

Data transformations for custom controls

Input definitions for custom controls

A Portrait Foundation package would typically reside in a package repository, along with the configuration collateral.

2.3 Foundation implementation reference A Portrait Foundation implementation reference corresponds to a configured Custom UI, Generated UI or View.

The custom interaction sampled below has its implementation reference configured as AIT_HRZ_SearchForParty.aspx, therefore the web package should contain a web page with the same name to achieve the required business functionality at runtime.

Edition 17.0


8 of 40

Figure 1 – Configuration Suite Custom UI

The view sampled below has its implementation reference configured as AIT_HRZ_WorkflowSummary.aspx, therefore the Web package should contain a Web page with the same name to achieve the required business functionality at runtime.

Figure 2 – Configuration Suite View

Edition 17.0


9 of 40

2.4 Foundation custom control A Portrait Foundation custom control derives from a standard .NET WebControl and, in addition, implements the ICustomControl interface which allows the binding of the control to a configured custom control. The ICustomControl interface definition is specific to the technology being used and the details can be found in the technology specific sections.

Listed below are the typical steps that are involved in the process of binding a Portrait Foundation custom control to a configured custom control:

Request name binding

Input interface definition

Data transformation

The sample below shows a custom control configured using the Portrait Foundation Configuration Suite:

Figure 3 – Configuration Suite Custom Control

ist break

2.4.1.1 Request name binding

Every Portrait Foundation Custom control that can be dragged and dropped on a Portrait Foundation screen or view implements the RequestName property of the ICustomControl interface. The value of this property must be set to the name of the configured business custom control e.g.

RequestName = SearchResults

This property can be set in the design view by selecting the .NET control’s properties window. This tells the Portrait Foundation application framework that the .NET custom control sources its data from a configured custom control.

Edition 17.0


10 of 40

2.4.1.2 Input interface definition

For every binding, a new entry needs to be added in the application/package custom control input definitions XML file, which usually resides in the xml subfolder. These definitions imply static data bindings for the configured inputs.

The input definition ensures correct data mapping between the .NET control and its corresponding configured custom control, as shown in the code snippet below:

<UIE name="SearchResults">

<InputSource name="SEARCH_CRITERIA"

source="RequestContext"

sourceField="SEARCH_CRITERIA"></InputSource>

<InputSource name="PARTY_TYPE"

source="RequestContext"

sourceField="PartyType"></InputSource>

<Input name="MaximumRecordsReturned"

value="50"></Input>

</UIE>

The following table details the XML elements used in the input definition file.

Table 2 – How to define inputs for Portrait Foundation custom controls

XML element Description

UIE The containing element for a custom control input definition. The name attribute is the system name of the Portrait business custom control as defined in the configuration

InputSource Use this element for configured inputs that have their values sourced dynamically from one of the source contexts listed below:

RequestContext – value sourced from the Web application context e.g. forms collection, query string.

InputContext – value sourced from the configured inputs to the custom interaction that hosts the custom control.

GlobalsContext – value sourced from the globals context.

Input Use this element for configured inputs that have constant values.

Name – system name of the configured input

Value – a constant value

Note that the interface definitions for Portrait Foundation custom controls are currently under review and are subject to change in future product releases.

2.4.1.3 Data transformations

Data transformations are XSLT files which transform the XML returned by the execution of the configured custom control into an XML/HTML format understood by the Portrait Foundation custom controls. The path where the data transformation XSLT files reside is configurable at application level. Typically, the files reside in an “xsl” subfolder within the .NET application folder.

Edition 17.0


11 of 40

2.5 Foundation data source controls The Foundation SDK provides specialised custom controls that behave as ASP.NET Data Source controls. These implement the ICustomControl interface (see above) and .NET IDataSource, IListSource and IHierarchicalDataSource interfaces. This means that, like a standard Portrait Foundation custom control, they can be bound to a Portrait Foundation configured Custom Control, BUT in addition they can be used for standard ASP.NET data binding in order to present business data from Portrait Foundation in any ASP.NET data bound control.

These controls also provide support for the SelectParameters collection. This allows the page designer to override the Portrait Foundation custom control input interface definition by specifying that (some or all) parameters are sourced from ASP.NET objects such as controls on the page, query string properties, cookies etc.

Edition 17.0


12 of 40

3 Foundation Web SDK

The Web SDK consists of the following elements:

Portrait Foundation application framework built using Microsoft ASP.NET

Visual Studio project templates:

Foundation Web Application

Foundation Web Package

Visual Studio item templates:

Foundation Custom UI Page

Foundation View Page

Foundation Internet Page

Foundation Base Page

Foundation Web Control

Portrait Foundation web control library that can be added to the Visual Studio designer toolbox.

The following sections provide guidelines on using these SDK elements in a typical Portrait Foundation implementation environment.

3.1 Web application framework The framework consists of a server side framework using ASP.NET and client side framework using JavaScript. Providing a set of interfaces definitions and page

base classes that provide the common functionality required by Portrait Foundation ASP.NET applications. The client framework includes a set of client side JavaScript files which provide the functionality for:

Client side event handling and validation

Communication to the web tier using XMLHTTP

Browser window management

State management

3.2 Creating a new web application A Portrait Foundation web application uses Microsoft ASP.NET to implement and deliver the end-user browser-based Portrait Foundation implementation.

A new Portrait Foundation application can be created using the “Foundation Web

Application” project template which is installed as part of the SDK.

Edition 17.0


13 of 40

Figure 4 – Web Application template

The template:

Creates a Visual C# Web application project with the specified name

Adds references to the following Portrait Framework assemblies

AIT.Portrait

AIT.Portrait.Web

Creates a xml subfolder for placing the custom controls input definitions file

Creates a xsl folder for placing the custom control data transformations

Adds the HTML and .ASPX files required by Foundation SDK

Adds a default template of the Web.config file

Adds a default template for Global.asax and Global.asax.cs files

New Portrait pages can be added to the package by using the Portrait web page templates.

3.3 Creating a new web package A web package is an ASP.NET specific implementation of the user interface collateral included in a Portrait Foundation package.

Typically, it has the following components:

Set of .ASPX pages

A .NET assembly which contains the compiled source for the code behind files

Set of XSLT data transformations

Edition 17.0


14 of 40

A custom control input definitions XML file

A new web package can be created using the “Foundation Web Package” project template which is installed as part of the SDK.

Figure 5 – Web Package template

The template:

Creates a Visual C# Web application Project

Adds references to the following Portrait Framework assemblies

AIT.Portrait

AIT.Portrait.Web

Creates an xml subfolder for placing the custom controls input definitions file

Creates an xsl subfolder for placing the custom control data transformations

New web pages can be added to the package by using the Foundation web item templates.

3.4 Creating new web pages

3.4.1 What is a Portrait Foundation web page

An ASP.NET Web form page must comply with the following requirements in order to become a Portrait Foundation web page:

Correspond to a configured Portrait Foundation business custom interaction or custom view

Extend one of the Portrait Foundation page base classes:

AIT.Portrait.Web.UI.Page

Edition 17.0


15 of 40

AIT.Portrait.Web.UI.Dialog

AIT.Portrait.Web.UI.TabPage

AIT.Portrait.Web.UI.InternetPage

Implement page loading i.e. the private method Page_Load(…) that is required by the Visual Studio intrinsic designer support;

Contain specific form properties i.e. form identifier, initial control identifier, page layout, session state, view state.

Web implementation

Each of the configured implementation references materialise in physical Web pages that must be included in the Foundation ASP.NET application.

3.4.1.1 Extend the page base class

The Foundation base page classes implement the IAspNetPage interface.

Figure 6 – Foundation ASP.NET page interface

The Foundation base page extends the standard .NET System.Web.UI.Page class and implements the Portrait IAspNetPage.

Edition 17.0


16 of 40

Figure 7 – Foundation page base class implementation

3.4.1.2 Implement page loading

Every functional page must implement the private method Page_Load(…) that is needed by the Visual Studio intrinsic designer support.

There are a number of distinct scenarios for page loading as detailed below.

List break

1 A page containing .NET server controls that also use client side execution scripts calls the Initialise method on the base class to register the client side scripts and initialise the custom controls. The client side scripts used by the base class are located in the JavaScript file common.js.

Figure 8 – Foundation page loading

Figure 9 – Foundation page initialisation

Edition 17.0


17 of 40

2 A page containing only .NET server controls calls the InitialiseCustomControls method on the base class to initialise the custom controls i.e. replace Initialise with InitialiseCustomControls.

3 A page containing .NET controls that only use client side execution scripts calls the RegisterClientSideScripts method on the base class to register the client side scripts i.e. replace Initialise with RegisterClientSideScripts. The client side scripts used by the base class are located in the JavaScript file common.js.

4 A page that does not contain any .NET controls does not use any base class initialisation functionality i.e. remove the call to Initialise.

5 Additionally a new page could override the methods available on the page base class interface e.g. override the GetInitialisationScript method to force execution of custom client side script at page start-up.

3.4.1.3 Specify form properties

The properties listed below are compulsory for any Portrait Foundation page:

Form ID

Initial control

Page layout

Session state

View state

Form ID

A Portrait Web page requires a specific value for the form identifier, as shown below. The default identifier is provided by the page template.

Figure 10 – Foundation page property – form identifier

Initial control

Identify the control that gains initial focus on the page by setting the page property InitialControlID in the InitializeComponent method.

Figure 11 – Foundation page property – initial control identifier

Page layout

The default Foundation page setting is "flow layout", for localization flexibility, therefore the controls are positioned sequentially. The table layout, used in the Foundation implementation, is currently applied manually and depends on the specific requirements.

Edition 17.0


18 of 40

Session state

For improved application performance, the ASP.NET session state is disabled at the Portrait Foundation application level by setting sessionstate mode="off" in the web.config file. To ensure implementation flexibility, the session state is also disabled in the Portrait page templates that contain the page directive EnableSessionState="false".

View state

By default, the ASP.NET view state is enabled for all pages and controls. To improve application performance, this has been changed for all Portrait Controls i.e. the Portrait control class constructor contains statement EnableViewState="false". and the base class EnableViewState property has been hidden by one that has a default value of false. If non-Portrait controls are used it is recommended to set their EnableViewState properties to false in the form designer.

For pages that contain a control that needs to use the view state, set the

control’s EnableViewState property to true in the form designer.

Note that the view state is an intrinsic .NET page property, therefore it is present in the form context even when its usage is explicitly disabled.

3.4.2 Foundation ASP.NET page types

There are four main types of Portrait Foundation Web pages for an application that is based on Web forms, as detailed below.

3.4.2.1 Base page

A Foundation base page derives from the AIT.Portrait.Web.UI.Page base class. A runtime sample implementation is shown below.

Figure 12 – Base page sample implementation

Edition 17.0


19 of 40

3.4.2.2 Custom UI page

A Foundation Custom UI derives from the AIT.Portrait.Web.UI.Dialog base class. A runtime sample implementation is shown below.

Figure 13 – Custom UI page sample implementation

3.4.2.3 View page

A Foundation view page derives from the AIT.Portrait.Web.UI.TabPage base class. A runtime sample implementation is shown below.

Figure 14 – View page sample implementation

Edition 17.0


20 of 40

3.4.2.4 Internet page

A Foundation Internet page derives from the AIT.Portrait.Web.UI.InternetPage base class. A runtime sample implementation is shown below.

Figure 15 – Internet page sample implementation

3.4.2.5 Generated UI page

A Foundation Generated UI page extends the AIT.Portrait.Web.UI.Dialog base class. However, unlike the Dialog page (above), the page content is generated by

server controls rather than designed. A runtime sample implementation is shown below.

Edition 17.0


21 of 40

Figure 16 – Generated UI page sample implementation

Generated UI page templates

The standard Generated UI page (AIT_HRZ_AMCDQESession.aspx) relies on a databound templated custom ASP.NET server control (GIControl) to display a Generated Interaction’s page elements within a form (GIForm). The AIT_HRZ_AMCDQESession page parses Generated UI page XML into a data representing the page. This data structure is then passed to the GIControl which generates the corresponding HTML hierarchy of controls (which themselves are templated). The top-level template can be configured by specifying a TemplateFile value in the implementation reference query string.

The top-level templates for two ‘styles’ of Generated UI layout rendering are provided:

AIT_HRZ_GIDefaultTemplate.ascx This template displays a standard data capture Generated UI dialog where question labels, controls, info icons and question action buttons are presented in a table. It is used if there is no TemplateFile specified in the implementation reference query string.

AIT_HRZ_GIScriptingTemplate.ascx This template is intended for use with scripting-related presentation styles and displays question text above the corresponding (widened) question control, icons and action button. (The exception to this is in the case of a single checkbox

Edition 17.0


22 of 40

presentation style where the checkbox is presented to the left of the question text.)

Both templates render the titles (top and bottom) and page action and outcome buttons in the same way.

Both templates display a horizontal bar above and below the question panel. This may be removed by editing the .ascx contents, setting the ‘alternate’ variable to ‘false’.

Both templates include AIT_HRZ_GIStandardTemplates.ascx which contains common templates used to render individual sections of the Generated UI page. These comprise:

pageInitialisationTemplate Contains boilerplate client side script for setting the dialog title and handling page errors.

titleRowTemplate Renders a Generated UI title row (top or bottom)

actionTemplate Renders an action button (question action or page action)

pageActionsTemplate Renders page action buttons on the left hand side of a table row.

questionInfoAndAction Renders info icons (error, help, hint) and question action buttons.

questionTemplate Renders a Generated UI question item: label, control, info and action elements.

textTemplate Renders a Generated UI text item.

Generated UI page layout customisations

Generated UI page layout is most easily customised by taking copies of the supplied Generated UI Page aspx and template files and then editing the HTML markup. The following steps should be followed to avoid conflicts with the supplied AIT_HRZ_UserInterface package:

List break

1 Create a new web package

2 Take copies of the starting Generated UI page and supporting templates (AIT_HRZ_AMCDQESession.aspx, AIT_HRZ_GIDefaultTemplate.ascx, AIT_HRZ_GIScriptingTemplate.ascx, AIT_HRZ_GIStandardTemplate.ascx)

3 Rename them

4 Add them to your own web package.

5 Edit the new versions of Generated UI page and templates.

6 Modify those implementation references in the configuration suite that should use the new page layout.

Note that the GIControl is generic in implementation and may be reused and bound at any level in the Generated UI data structure. The template used at each level is determined by the data type of the bound data and may be configured through various control properties. These properties are either supplied inline as child markup e.g. <PageTemplate>, or set as attributes on the GIControl markup.

The following properties are used:

Edition 17.0


23 of 40

Template Used where the datatype is known, for example within a PageTemplate

<amc:GIControl runat="server"

DataItem="<%# Container.DataItem %>"

Template="<%# pageInitialisationTemplate %>"/>

QuestionTemplate, TextTemplate, TitleTemplate Used for a collection of question elements, for example:

<amc:GIControl runat="server"

DataItem="<%# Container.DataItem %>"

QuestionTemplate="<%# questionTemplate %>"

TextTemplate="<%# textTemplate %>" >

<TitleTemplate/>

</amc:GIControl>

ActionTemplate

Used for an action button.

TitleRowTemplate

Used for title rows (top and bottom).

PageTemplate

Used at the top-level (page level).

Generated UI presentation styles

The GIQuestionControl class ‘implements’ a number of presentation styles by instantiation of appropriate AIT Web Controls:

Table 3 – Generated UI presentation styles

Style DataType Control

singlelineedit

(default)

floatingpointnumber FloatEdit

integer NumericEdit

string

(default)

StringEdit

multilineedit StringEdit

(TextMode=MultiLine)

checkbox boolean CheckBox

Single select RadioButtonList

Multi select CheckBoxList

radio RadioButtonList

combo DropDownList

listbox ListBox

(cssClass=”DropDown”)

password StringEdit

(TextMode=Password)

currency CurrencyEdit

date DateEdit

time TimeEdit

Edition 17.0


24 of 40

List break

In order to alter the implementation of these styles or support new styles, the following steps must be taken:

1 A new class must be derived from the GIQuestionControl class

2 The method InstantiateControl must be overridden. If the question.Presentation property matches one to be handled the method must set the InputControl property to a new instance of the appropriate control and set appropriate properties on that control. The base class method should be called at the end of the override.

3 The method InitialiseControl may be overridden. If some control property settings depend on question object properties, then the modifications may be done here.

The base class method should be called at the end of the override and accounts for question.IsReadOnly.

4 The method PopulateControl may be overridden. The base class method populates ListControl, TextBox and CheckBox control base classes. An override should only be required if a new control is used that is not derived from any of these base classes.

5 Finally, the new class should be used within the templates (.ascx) in place of the GIQuestionControl (i.e. the questionTemplate within AIT_HRZ_GIStandardTemplate.ascx)

If, for example, you have implemented controls that support masking you could devise presentation style names that identify those controls and the mask to be applied, for example: “MaskingDateEdit_DD/MM/YYYY”.

3.4.3 How to create a new Foundation web page The Foundation SDK contains an item template for each type of Foundation web page.

Figure 17 – Web item templates

In Visual Studio, right click on the web project in the Solution Explorer and select “Add” > “New Item…”. Select the relevant Foundation Page template, give it a name and click “Add”.

Edition 17.0


25 of 40

The template generates the *.aspx and *.aspx.cs source files that contain the Portrait Foundation specific code i.e. the newly created class inherits from the corresponding Portrait Foundation base class as shown in the sample below.

Figure 18 – Simple form sample

Controls from the Portrait Foundation toolbox that are dragged and dropped onto a Foundation web page are automatically bound to the Portrait Foundation framework at runtime.

3.5 Using the web control library The Foundation web control library is delivered within the web application framework in the AIT.Portrait.Web.dll assembly that is located in the following directory:

<SDK_installation_directory>\Development Environment\dotNET\Portrait Framework

The library contains a set of reusable controls that aid the development process. There are a number of manual steps that should be followed in order to load the controls library into the Visual Studio designer toolbox, as detailed below.

Edition 17.0


26 of 40

Table 4 – How to add the controls library to the Visual Studio toolbox

Item Description

Create a new tab in the Visual Studio toolbox

Open the Visual Studio toolbox (View menu, Toolbox). Right click inside the toolbox view and select “Add Tab”. Give the tab a name “Portrait Foundation” then press enter.

Add the Portrait Foundation controls to the newly created tab in the Visual Studio toolbox

In the toolbox view click on the Portrait Foundation tab to expand it. Only the Pointer item is present by default. Right click inside the tab and select “Choose Items…”.

Select the .NET Framework Components tab and click the “Browse…” button. In the Open dialog navigate to the directory <SDK_installation_directory>\Development Environment\dotNET\Portrait Framework.

Select AIT.Portrait.Web.dll, click Open, and click OK.

Refresh the Portrait Foundation Control Library content in the Visual Studio toolbox

For new versions of the controls library assembly follow the step described above to refresh the content of the Portrait Foundation Control Library in

the Visual Studio toolbox1

Add a Portrait Foundation control to a web page

Open a Foundation web page (*.aspx) in design view (View menu, Designer) to activate the toolbox.

Drag & drop the required control(s) from the Portrait Foundation toolbox tab onto the page.

The figure below shows the Portrait Foundation toolbox populated with all of the available Portrait Foundation controls. The Web page being constructed is displayed in design view.

1 The content of the Visual Studio toolbox is cached and does not refresh automatically when the corresponding assembly is updated.

Edition 17.0


27 of 40

Figure 19 – Visual Studio Toolbox

Appendix A details the functionality and usage of the controls currently included in the standard Portrait Foundation library.

There are two main types of Portrait Foundation web controls and each of them is defined by a set of properties, as detailed below. There is a third type of control, the Foundation Data Source control, and a definition of its usage and properties follows.

3.5.1 Foundation web custom controls

A control must fulfil three basic requirements in order to qualify as a Portrait Foundation Custom control. These requirements are detailed below.

3.5.1.1 Correspond to a configured custom control

This is explained in the section 2.4

Edition 17.0


28 of 40

3.5.1.2 Implement the ICustomControl interface

The code snippets below are for SDK guidance and separate documentation is provided for the Portrait Foundation application framework interface definitions.

Figure 20 – Custom control interface

Figure 21 – Custom control sample implementation

3.5.1.3 Override the base class initialisation

The base class initialisation must be overridden in the OnInit method, to ensure that the new control is registered on the Foundation page.

Figure 22 – Custom controls initialisation

Edition 17.0


29 of 40

3.5.1.4 Implement the localization solution

Typical Portrait Foundation Custom controls handle dynamic data that is served by the Portrait Foundation system, therefore is already localized. However, there are circumstances that require a control to implement additional attributes as static text e.g. the Portrait Foundation CustomGrid control. The static text elements must implement the Portrait localization solution as shown in Figure 23 – Foundation localization solution. For details on the Portrait localization solution see Localising_the_Portrait_Application.pdf.

3.5.1.5 Extend a standard base class

A new Portrait Foundation Custom control would, preferably, extend one of the controls that are already implemented in either the Portrait or the Microsoft .NET standard libraries. This approach ensures maximum reuse of pre-built functionality and minimum development effort.

For sample code refer to Figure 22 – Custom controls initialisation.

3.5.2 Foundation web controls

A control must fulfil one basic requirement in order to qualify as a Portrait Foundation Web control, as detailed below.

3.5.2.1 Implement the localization solution

Typical Portrait Foundation Web controls handle static data, most commonly text that must implement the Portrait localization solution as shown below.

Figure 23 – Foundation localization solution

Note that the ResourceKey property is only applicable to those controls that are locale dependent e.g. label, button text. For optimum runtime performance ensure that this property is only implemented where appropriate. For details on the Portrait localization solution see Localizing_NET_Applications.pdf

Edition 17.0


30 of 40

3.5.2.2 Extend a standard base class

A new Portrait Foundation Web control would, preferably, extend one of the controls that are already implemented in either the Portrait or the Microsoft .NET standard libraries. This approach ensures maximum reuse of pre-built functionality and minimum development effort.

3.5.3 Foundation data source control

The Portrait Data Source Control is used to expose a Portrait business custom control as a standard ASP.NET data source. One or more instances of this control may be placed anywhere on a page (it is not visible at runtime).

Figure 24 – Foundation Data Source Control

The Foundation Data Source Control properties must be configured as follows:

Table 5 - Foundation Data Source Control properties

Name Description

ID Unique control ID – normal ASP.NET stuff.

RequestName

The name of the configured Portrait business custom control to run. Note that this request name must have a corresponding entry in the input definition XML file.

XPath

This is an XPath query that must be specified in order to select the data that should be extracted from the transformed custom control data and made available for ASP.NET data binding. Binding may take one of two forms so the XPath query may depend on the intended control:

Dataset – Xpath identifies a collection of XML nodes that represent rows in the dataset. (Used for GridView, List, DropDownList etc.

Hierarchical = XPath identifies the nodes at the root of a tree. (Used for TreeView, Menu etc.)

Edition 17.0


31 of 40

Name Description

SelectParameters (Collection)

While the request name must have a corresponding entry in the input definition XML file, it is possible to override the input definition settings by specifying input bindings. Using the standard ASP.NET Parameter Collection Editor, an input may be bound to a cookie, control, form, profile querystring or session value. A default value for the selected in put may also be specified. Note that the editor supports other binding directions BUT only the Input direction is supported.

If SelectParameters are configured, parameter names must match the corresponding XML input definition.

Figure 25 – SelectParameters Editor

Standard ASP.NET data bound controls and third party controls that support data binding may then be bound to a Foundation data source in order to populate them with business data from Portrait Foundation.

Figure 26 – GridView bound to a Foundation Data Source

When configuring a databound control, you will need to know the names of the XML attributes you wish to bind to. For example in an ASP.NET GridView, when adding a BoundField, the BoundField.DataField property should be set to the name of an XML node attribute in the selected dataset.

Edition 17.0


32 of 40

Figure 27 – GridView field configuration

3.6 Creating a new web control A Foundation web control derives from a standard .NET WebControl, and, in addition, implements the AIT.Portrait.Web.UI.WebControls.ICustomControl interface.

A new custom control can be created by using the “Foundation Web Control” item template.

Figure 28 – Web Control template

The template generates a class file with the specified name. It creates a class derived from System.Web.UI.WebControls.WebControl and provides a default implementation of the ICustomControl interface, with “TODO:” comment block where customisation is required.

Edition 17.0


33 of 40

3.7 Using a native ASP.NET Web Application Project The sections above describe the development of Portrait web applications and pages using the Portrait Foundation page base classes. This is only strictly necessary if you wish to use the Foundation SDK controls and/or the Portrait client-side framework supplied in the Foundation SDK

There may be a requirement to implement an application using a standard ASP.NET Web Application project (or extend an existing one). In this case it is still possible to integrate to Portrait following these steps:

Table 6 - Steps to add Foundation functionality to an existing ASP.NET Web

Application

Step Description

Update web.config Portrait sections/settings are required to be present in the web.config file.

Add PortraitAspNetClient control to page

All communication to Foundation is via this control (when using Foundation web page base classes it is instantiated by the base class). The control provides methods such as StartOperation and Resume to invoke and continue models. It provides methods to run custom controls and retrieve their results, as well as access to session data GLOBALs etc.

This control has a single custom property HandleErrors. When set to true the control will generate an error page rather than throwing a n exception when Portrait errors are encountered. A DisplayError event is also raised when HandleErrors. is set to true allowing the page developer to control how the error is displayed.

Add PortraitXmlDataSource control(s) to page

While it is possible to invoke custom controls by calling methods on the Foundation ASP.NET Client (above), the Foundation Data Source control is supported on a native ASP.NET page.

Configuration and use of this control is described in section 3.5.3.

Note that the Foundation ASP.NET Client control must appear before any Foundation Data Source control(s) on the page.

3.8 Error handling and reporting (Service Centre channel) The Portrait Foundation SDK incorporates an error reporting framework. This functionality is readily available to any application that utilises the SDK libraries provided with the latest Portrait Foundation release.

System errors are propagated from the Portrait Foundation runtime components, which also detect database and network failures, to the Web application which handles the errors and displays appropriate messages. Once the error is resolved, the application recovers gracefully.

3.8.1 Error status The error reporting framework is designed to harden existing Portrait Foundation applications and allow users to interpret errors that would otherwise be hidden. The application’s response to errors depends on the error status and the stage at which the error is raised.

Edition 17.0


34 of 40

There are two main types of system errors that are dependent on the failed component and the nature of failure: permanent and transient errors, as detailed below.

3.8.2 Permanent errors

Permanent errors are the result of irrecoverable system failures, for example when the system sends a malformed SQL statement to the database server. The application at this stage will not be able to continue functioning, hence the only available option to the user would be to avoid carrying out the failed action or close the application.

3.8.3 Transient errors

Transient errors are the result of temporary system failures, for example when the system cannot communicate with the database server. The runtime environment is resilient enough to resume functionality as soon as the communication is re-established, hence it allows the user to continue interacting with the Portrait Foundation applications.

3.8.4 Error handling user interface

Special user interface elements are available for displaying the error information and handling user actions. Two ASP.NET pages have to be incorporated into the Web application in order to utilise the error handling functionality: ErrorDialog and ErrorTab.

ErrorDialog is the dialog that is shown when a component fails to execute because of a system error, as shown in the figure below. The error dialog box contains a Close application button that depends on business requirements and can be configured in the application’s configuration file, as detailed in the Foundation SDK help. Similarly, the dialog text and presence of the details panel can be configured in the application’s configuration file.

Figure 29 – Error dialog

Edition 17.0


35 of 40

3.8.5 How to use error handling

The SDK handles errors differently depending on what stage the error has occurred. Below is a description of the different scenarios.

Error during Start Model, Start Operation and Resume flag the session state to be rolled back to the last committed state when the system was fully functional. When one of the previous actions fail, the framework displays an error dialog box as described previously and the application’s user interface is kept in the same state as it was before the action was triggered.

Errors during Execute Custom Control and Get Session State usually happen once models successfully resume to a user interface node, hence session state is not flagged to be rolled back. The framework displays an error dialog box, however the page contents may be invalid at this stage and the user should be able to cancel the action. The only exception to this rule is in Generated Interaction Pages where a Get Session State failure causes the session to be flagged to be rolled back.

Errors while initialising the Web controller indicates a failure to carry out session management and in this case the framework displays an error dialog box and retains the existing session state flag.

Error handling and reporting is built into the SDK and the application framework, hence development of custom interactions does not need special error handling unless the Portrait Foundation Adapter object is accessed directly. Accessing the AIT.Portrait.ChannelAdapters.AspNetAdapter object in the page can potentially fail because of a system error manifested as a raised exception.

The page base class AIT.Portrait.Web.UI.Page offers two methods for handling errors, using as the input parameter an exception that contains the system error information: HandleError( ExceptionManager.Exception e ) and HandleSingleError( ExceptionManager.Exception e ).

HandleError adds that exception to an internal list which is then displayed once the page finishes processing. This means that the page displays most of its contents with certain elements being corrupt e.g. elements that are dependent

on custom controls. The page also displays the error dialog box containing the error collection’s information.

An example of how to use the above method is given below.

Figure 30 – Sample error handling using HandleError

HandleSingleError terminates the processing of the page and displays the error

dialog box directly. This method should only be used when the failed code renders the page contents unusable or causes the user to be in a deadlock situation where the application could not be closed e.g. integration of Portrait Foundation with 3rd party components.

An example of how to use the above method is given below.

Edition 17.0


36 of 40

Figure 31 – Sample error handling using HandleSingleError

3.8.6 How to replace the error dialog

All web pages that integrate with Portrait ultimately use the PortraitAspNetClient SDK control to communicate with Portrait. This may be instantiated by the Foundation AspNetPage base class or directly in a native ASP.NET page.

At the point where the PortraitAspNetClient control determines an error must be displayed (either in HandleSingleError() or prior to page rendering after HandleError() has been called), PortraitAspNetClient raises a DisplayErrors event. The event arguments for the DisplayErrors event contains a property, Cancel, which if set to true, prevents the PortraitAspNetClient control from processing the error further.

The Portrait Foundation page base classes handle the DisplayErrors event by calling the virtual method DisplaySystemErrors() and cancelling further error processing.

The application may therefore elect to handle the DisplayErrors event as follows:

Pages derived from Portrait Foundation page base classes override DisplaySystemErrors(), displaying the exception(s) in the required form.

Native ASP.Net pages handle the DisplayErrors event from the PortraitAspNetClient control, displaying the exception(s) in the required form and cancelling further processing.

Edition 17.0


37 of 40

Appendix A AIT.Portrait.Web controls

The table below summarises the content of the currently available library of Portrait Foundation controls and references their usage in the Service Centre channel.

Please note that most of these controls are only compatible Microsoft Internet Explorer and have not been tested in any other browser.

Table 7 – Foundation control library

Control name Brief description Browser compatibility

Sample usage

ApplicationVersion Displays the application version as specified in the web.config file.

IE, Mozilla AIT_HRZ_Logon.aspx, included in the package AIT_HRZ_Logon

Button Derives from the standard.NET Button class and extends it to provide support for internationalization and validation. The Type property modifies the client side submit behavior of the button.

IE, Mozilla (only if type set to be basic)

AIT_HRZ_CallWrapUp.aspx, included in the package AIT_HRZ_Telephony

CancelButton A specialized Portrait Foundation Button class with default values for the required properties i.e. removes the need for setting the properties manually on every page.

The resource extraction tool treats it as a special case and makes only one entry in the resource file for the Cancel text.

IE AIT_HRZ_SearchForParty.aspx, included in package AIT_HRZ_Parties

CheckBox Derives from the standard .NET CheckBox class and extends it to provide internationalization support.

IE, Mozilla AIT_HRZ_TransferCallConfirmation.aspx, included in package AIT_HRZ_telephony

CurrencyEdit An input box for currency values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes properties for range and format validation, which can be set at design time and are passed to the client side validation framework at run time.

IE Not used in current release

CustomGrid

Deprecated - The FlexGrid control supersedes the functionality provided by CustomGrid and should be used instead.

DataGrid Derives from the standard .NET DataGrid and uses the same rendering mechanism.

In addition it implements the Portrait Foundation ICustomControl interface, which provides the ability to bind it to data returned by a Portrait request.

IE, Mozilla AIT_HRZ_WorkflowSummary.aspx, included in package AIT_HRZ_Workflow

DateEdit Input box for date values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes properties for range and format validation, which can be set at design time and are passed to client side validation framework at run time.

IE AIT_HRZ_ScheduleCallBack.aspx, , included in package AIT_HRZ_Schedule_callBack

Edition 17.0


38 of 40


Sample usage

DropDownList Derives from the standard .NET DropDown class and uses the same rendering mechanism.

In addition it implements the Portait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request.

IE AIT_HRZ_Retrieveroles.aspx, included in package AIT_HRZ_Logon

FloatEdit Input box for float values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes properties for client side float validation.


FlexGrid The FlexGrid derives directly from the standard .NET WebControl class and does custom rendering to display a grid, with a facility to show additional details for each row. It provides the flexibility to customize its user interface and behavior based on the input data and the design/run time settings for its public properties. It also provides the much needed client side keyboard and mouse event handling functionality which is not available with the standard .NET DataGrid and Table controls.

IE AIT_HRZ_EngagementHistory.aspx, included in package AIT_HRZ_EngagementHistory

GridActionButton Deprecated

Label Derives from the standard .NET Label class and extends it to provide internationalization support.

IE, Mozilla AIT_HRZ_Logon.aspx, included in package AIT_HRZ_Logon

ListBox Derives from the standard .NET ListBox class and uses the same rendering mechanism.

In addition it implements the Portrait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request.

IE, Mozilla AIT_HRZ_RerouteTask.aspx, included in package AIT_HRZ_Workflow

MultiGrid Derives directly from the standard .NET WebControl class. Enables the display of multiple grids within a given page area. It should be used where the results of a custom control request contain more than one Grid.

IE AIT_HRZ_ContactDetails.aspx, included in package AIT_HRZ_Workflow

NameText Deprecated IE AIT_HRZ_Activities.aspx, included in package AIT_HRZ_Agent_Management

NumericEdit Input box for numeric values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes property for range validation, which can be set at design time and are passed to client side validation framework at run time.

IE AIT_HRZ_ScheduleCallback.aspx, included in package AIT_HRZ_Schedule_Callback

Edition 17.0


39 of 40


Sample usage

OKButton Specialised Portrait Button with default values for the required properties, removing the need for setting the properties manually on every page.

The resource extraction tool treats it as a special case and makes only one entry for the OK text.

IE AIT_HRZ_Logon.aspx, included in package AIT_HRZ_Logon

PortraitASPNETClient Control used under the covers by all Foundation SDK page base classes to communicate with Portrait. May be instantiated in a native ASP.NET page. Required for use with PortraitXmlDataSource control.

IE, Mozilla

PortraitXmlDataSource Control used to expose a configured Portrait business custom control as an ASP.NET datasource. Provides Portrait data for either hierarchical or dataset bindings.

IE, Mozilla

OKButton Specialised Portrait Button with default values for the required properties, removing the need for setting the properties manually on every page.

The resource extraction tool treats it as a special case and makes only one entry for the OK text.


RadioButton Derives from the standard .NET RadioButton and extends it to provide internationalization support.

IE, Mozilla Not used in current release

ShutterView Deprecated

StringEdit Input box for string values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes properties for length and regular expression validation, which can be set at design time and are passed to client side validation framework at run time.


SwapBox .NET wrapper implementation for the existing Portrait JavaScript control.

IE AIT_HRZ_AssignAgentRoles.aspx, included in package AIT_HRZ_Agent_Management

TabControl The TabControl provides the functionality to display a complex hierarchy of tabs together with the associated page view(s). The TabControl contains a TabStrip control and a MultiPage control as it's children. A TabStrip contains multiple tabs. The tabs can contain text and optionally an image. The MultiPage contains multiple PageViews, which have one to one correspondence with the tabs in the TabStrip. Selecting a tab displays the associated PageView. PageViews can contain any control, including TabControls. The TabControl provides client side keyboard and mouse event handling functionality.

IE AIT_HRZ_GenericDesktop.aspx, included in package AIT_HRZ_Generic_desktop

Edition 17.0


40 of 40


Sample usage

TextArea Derives from the standard .NET TextArea class and uses the same rendering mechanism.

In addition it implements the Portrait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request.

IE AIT_HRZ_CallWrapUp.aspx, included in package AIT_HRZ_Telephony

TimeEdit Input box for time values that derives from the Portrait Foundation ValidatorEdit abstract base class.

Exposes properties for range and format validation, which can be set at design time and are passed to the client side validation framework at run time.

IE AIT_HRZ_ScheduleCallBack.aspx, included in package AIT_HRZ_Schedule_Callback

TimeSelect Derives from the standard .NET Dropdown class and allows time selection, in short time string format.

The StartTime, EndTime and the TimeInterval properties determine the elements in the list.


TitleText Deprecated

WebCustomControl Derives from the standard .NET WebControl. In addition it implements the Portrait Foundation ICustomControl interface, which provides the ability to bind it to data returned by a Portrait request.

It is a generic control that does not implement any specific rendering logic. If the Visible property is set to true, it just writes the data loaded by LoadData() to the HTML stream.

IE, Mozilla AIT_HRZ_GeneratedView.aspx, included in package AIT_HRZ_User_Interface

Documents

Portrait Foundation v5.0.4 ASP.NET Application Development ...€¦ · Data transformations are XSLT files . which transform the XML returned by the . execution of the configured