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
Email: [email protected]
Tel: +1 617 457 5200
Fax: +1 617 457 5299
Norway
Portrait Software
Portrait Million Handshakes AS
Maridalsveien. 87
0461 Oslo
Norway
Email: [email protected]
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/
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
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
Portrait Foundation ASP.NET Application Development User Guide
38 of 40
Control name Brief description Browser compatibility
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.
IE Not used in current release
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
Portrait Foundation ASP.NET Application Development User Guide
39 of 40
Control name Brief description Browser compatibility
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.
IE AIT_HRZ_Logon.aspx, included in package AIT_HRZ_Logon
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.
IE AIT_HRZ_Logon.aspx, included in package AIT_HRZ_Logon
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
Portrait Foundation ASP.NET Application Development User Guide
40 of 40
Control name Brief description Browser compatibility
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.
IE Not used in current release
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