ASP.NET Application Development User Guide
Edition 17.0
01 July 2014
Portrait Foundation ASP.NET Application Development User G u i d e
©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/
UK America Norway
Portrait Software Portrait Software Portrait Software The Smith Centre 125 Summer Street Portrait Million Handshakes AS The Fairmile 16th Floor Maridalsveien. 87 Henley-on-Thames Boston, MA 02110 0461 Oslo Oxfordshire, RG9 6AB, UK USA Norway
Email: [email protected] Email: [email protected] Email: [email protected] Tel: +44 (0)1491 416778 Tel: +1 617 457 5200 Tel: +47 22 38 91 00 Fax: +44 (0)1491 416601 Fax: +1 617 457 5299 Fax: +47 23 40 94 99
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 3 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 5 of 40
Edition 17.0
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:
NB: All assemblies included in this framework are strong-named and reliant upon the specific public key.
Portrait Foundation ASP.NET Application Development User Guide 6 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 7 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 8 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 9 of 40
Edition 17.0
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:
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.
Portrait Foundation ASP.NET Application Development User Guide 10 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 11 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 12 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 13 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 14 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 15 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 16 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 17 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 18 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 19 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 20 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 21 of 40
Edition 17.0
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.
The following properties are used:
Portrait Foundation ASP.NET Application Development User Guide 22 of 40
Edition 17.0
Template Used where the datatype is known, for example within a PageTemplate
QuestionTemplate, TextTemplate, TitleTemplate Used for a collection of question elements, for example:
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 floatingpointnumber FloatEdit (default) integer NumericEdit string StringEdit (default) 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
Portrait Foundation ASP.NET Application Development User Guide 23 of 40
Edition 17.0
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”.
Portrait Foundation ASP.NET Application Development User Guide 24 of 40
Edition 17.0
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:
Portrait Foundation ASP.NET Application Development User Guide 25 of 40
Edition 17.0
Table 4 – How to add the controls library to the Visual Studio toolbox Item Description Open the Visual Studio toolbox (View menu, Create a new tab in the Toolbox). Right click inside the toolbox view and Visual Studio toolbox select “Add Tab”. Give the tab a name “Portrait Foundation” then press enter. 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 Add the Portrait “Choose Items…”. Foundation controls to Select the .NET Framework Components tab and the newly created tab click the “Browse…” button. In the Open dialog in the Visual Studio navigate to the directory toolbox
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.
Portrait Foundation ASP.NET Application Development User Guide 26 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 27 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 28 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 29 of 40
Edition 17.0
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. The name of the configured Portrait business custom control to run. Note that this request name RequestName must have a corresponding entry in the input definition XML file. 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: XPath 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.)
Portrait Foundation ASP.NET Application Development User Guide 30 of 40
Edition 17.0
Name Description 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 SelectParameters ASP.NET Parameter Collection Editor, an input may (Collection) 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.
Portrait Foundation ASP.NET Application Development User Guide 31 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 32 of 40
Edition 17.0
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 Portrait sections/settings are required to be present Update web.config in the web.config file. 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 Add well as access to session data GLOBALs etc. PortraitAspNetClient control to page 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. While it is possible to invoke custom controls by calling methods on the Foundation ASP.NET Client (above), the Foundation Data Source control is Add supported on a native ASP.NET page. PortraitXmlDataSource Configuration and use of this control is described in control(s) to page 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.
Portrait Foundation ASP.NET Application Development User Guide 33 of 40
Edition 17.0
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
Portrait Foundation ASP.NET Application Development User Guide 34 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 35 of 40
Edition 17.0
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.
Portrait Foundation ASP.NET Application Development User Guide 36 of 40
Edition 17.0
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 Sample usage compatibility ApplicationVersion Displays the application version as specified IE, Mozilla AIT_HRZ_Logon.aspx, in the web.config file. included in the package AIT_HRZ_Logon Button Derives from the standard.NET Button class IE, Mozilla AIT_HRZ_CallWrapUp.aspx and extends it to provide support for (only if type , included in the package internationalization and validation. The set to be AIT_HRZ_Telephony Type property modifies the client side basic) submit behavior of the button. CancelButton A specialized Portrait Foundation Button IE AIT_HRZ_SearchForParty.a class with default values for the required spx, included in package properties i.e. removes the need for setting AIT_HRZ_Parties 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. CheckBox Derives from the standard .NET CheckBox IE, Mozilla AIT_HRZ_TransferCallConfi class and extends it to provide rmation.aspx, included in internationalization support. package AIT_HRZ_telephony CurrencyEdit An input box for currency values that IE Not used in current derives from the Portrait Foundation release 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. CustomGrid Deprecated - The FlexGrid control supersedes the functionality provided by CustomGrid and should be used instead. DataGrid Derives from the standard .NET DataGrid IE, Mozilla AIT_HRZ_WorkflowSumma and uses the same rendering mechanism. ry.aspx, included in In addition it implements the Portrait package Foundation ICustomControl interface, AIT_HRZ_Workflow which provides the ability to bind it to data returned by a Portrait request. DateEdit Input box for date values that derives from IE AIT_HRZ_ScheduleCallBac the Portrait Foundation ValidatorEdit k.aspx, , included in abstract base class. package Exposes properties for range and format AIT_HRZ_Schedule_callBa validation, which can be set at design time ck and are passed to client side validation framework at run time.
Portrait Foundation ASP.NET Application Development User Guide 37 of 40
Edition 17.0
Control name Brief description Browser Sample usage compatibility DropDownList Derives from the standard .NET DropDown IE AIT_HRZ_Retrieveroles.as class and uses the same rendering px, included in package mechanism. AIT_HRZ_Logon In addition it implements the Portait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request. FloatEdit Input box for float values that derives from IE Not used in current the Portrait Foundation ValidatorEdit release abstract base class. Exposes properties for client side float validation. FlexGrid The FlexGrid derives directly from the IE AIT_HRZ_EngagementHist standard .NET WebControl class and does ory.aspx, included in custom rendering to display a grid, with a package facility to show additional details for each AIT_HRZ_EngagementHist row. It provides the flexibility to customize ory 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. GridActionButton Deprecated
Label Derives from the standard .NET Label class IE, Mozilla AIT_HRZ_Logon.aspx, and extends it to provide included in package internationalization support. AIT_HRZ_Logon ListBox Derives from the standard .NET ListBox IE, Mozilla AIT_HRZ_RerouteTask.asp class and uses the same rendering x, included in package mechanism. AIT_HRZ_Workflow In addition it implements the Portrait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request. MultiGrid Derives directly from the standard .NET IE AIT_HRZ_ContactDetails.a WebControl class. Enables the display of spx, included in package multiple grids within a given page area. It AIT_HRZ_Workflow should be used where the results of a custom control request contain more than one Grid. NameText Deprecated IE AIT_HRZ_Activities.aspx, included in package AIT_HRZ_Agent_Managem ent NumericEdit Input box for numeric values that derives IE AIT_HRZ_ScheduleCallbac from the Portrait Foundation ValidatorEdit k.aspx, included in abstract base class. package Exposes property for range validation, AIT_HRZ_Schedule_Callba which can be set at design time and are ck passed to client side validation framework at run time.
Portrait Foundation ASP.NET Application Development User Guide 38 of 40
Edition 17.0
Control name Brief description Browser Sample usage compatibility OKButton Specialised Portrait Button with default IE AIT_HRZ_Logon.aspx, values for the required properties, included in package removing the need for setting the AIT_HRZ_Logon properties manually on every page. The resource extraction tool treats it as a special case and makes only one entry for the OK text. PortraitASPNETClient Control used under the covers by all IE, Mozilla Foundation SDK page base classes to communicate with Portrait. May be instantiated in a native ASP.NET page. Required for use with PortraitXmlDataSource control.
PortraitXmlDataSource Control used to expose a configured IE, Mozilla Portrait business custom control as an ASP.NET datasource. Provides Portrait data for either hierarchical or dataset bindings.
OKButton Specialised Portrait Button with default IE AIT_HRZ_Logon.aspx, values for the required properties, included in package removing the need for setting the AIT_HRZ_Logon 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 IE, Mozilla Not used in current RadioButton and extends it to provide release internationalization support. ShutterView Deprecated
StringEdit Input box for string values that derives IE AIT_HRZ_Logon.aspx, from the Portrait Foundation ValidatorEdit included in package abstract base class. AIT_HRZ_Logon 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 IE AIT_HRZ_AssignAgentRoles existing Portrait JavaScript control. .aspx, included in package AIT_HRZ_Agent_Managem ent TabControl The TabControl provides the functionality IE AIT_HRZ_GenericDesktop. to display a complex hierarchy of tabs aspx, included in package together with the associated page view(s). AIT_HRZ_Generic_desktop 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.
Portrait Foundation ASP.NET Application Development User Guide 39 of 40
Edition 17.0
Control name Brief description Browser Sample usage compatibility TextArea Derives from the standard .NET TextArea IE AIT_HRZ_CallWrapUp.aspx class and uses the same rendering , included in package mechanism. AIT_HRZ_Telephony In addition it implements the Portrait Foundation ICustomControl interface which provides the ability to bind it to data returned by a Portrait request. TimeEdit Input box for time values that derives from IE AIT_HRZ_ScheduleCallBac the Portrait Foundation ValidatorEdit k.aspx, included in abstract base class. package Exposes properties for range and format AIT_HRZ_Schedule_Callba validation, which can be set at design time ck and are passed to the client side validation framework at run time. TimeSelect Derives from the standard .NET Dropdown IE Not used in current class and allows time selection, in short release time string format. The StartTime, EndTime and the TimeInterval properties determine the elements in the list. TitleText Deprecated
WebCustomControl Derives from the standard .NET IE, Mozilla AIT_HRZ_GeneratedView.a WebControl. In addition it implements the spx, included in package Portrait Foundation ICustomControl AIT_HRZ_User_Interface 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.
Portrait Foundation ASP.NET Application Development User Guide 40 of 40