vlcweb net application standards...1.1.1 asp.net ajax asp.net ajax refers to new components in...

VLCWeb .NET Application Standards

of 23 VLCWeb .NET Application Standards


Author: Jim Mohrle Date: December 17, 2007 Revision: 1.0 Revision Date: December 17, 2007



Table of Contents 1 INTRODUCTION ..................................................................................................................................... 3

1.1 AJAX .................................................................................................................................................... 3 1.1.1 ASP.NET AJAX .............................................................................................................................. 3

1.1.1.1 Adding ASP.NET AJAX ......................................................................................................................... 3 1.1.1.2 Using ASP.NET AJAX ............................................................................................................................ 4

1.1.2 AJAX Control Toolkit .................................................................................................................... 5 1.1.2.1 Adding the AJAX Control Toolkit ........................................................................................................... 5 1.1.2.2 Using the AJAX Control Toolkit ............................................................................................................. 6

1.1.3 AJAX Loading Image ..................................................................................................................... 6 1.2 VLCWeb GridView .............................................................................................................................. 7

1.2.1 MRBGridView ............................................................................................................................... 7 1.2.1.1 Adding the MRBGridView ...................................................................................................................... 8 1.2.1.2 Using the MRBGridView ........................................................................................................................ 8 1.2.1.3 Custom Properties .................................................................................................................................. 12

1.3 VLCWeb Popups ................................................................................................................................ 13 1.3.1 Confirmation ModalPopup .......................................................................................................... 13 1.3.2 MRBGridView ModalPopup ........................................................................................................ 15

1.4 User Interface ..................................................................................................................................... 16 1.4.1 Themes and Styles ........................................................................................................................ 16 1.4.2 Sample Screenshot ....................................................................................................................... 17 1.4.3 Common Controls ........................................................................................................................ 18

1.4.3.1 MRBGridView ...................................................................................................................................... 18 1.4.3.2 Ajax Control Toolkit ModalPopupExtender .......................................................................................... 18 1.4.3.3 Ajax Control Toolkit Calendar .............................................................................................................. 18 1.4.3.4 Ajax Control Toolkit Tabs ..................................................................................................................... 19

1.5 Exception Handling ............................................................................................................................ 19 1.5.1 C# ................................................................................................................................................ 19 1.5.2 PL/SQL ........................................................................................................................................ 20

1.6 User Messages .................................................................................................................................... 21 1.6.1 One Time Messages ..................................................................................................................... 22 1.6.2 Error Messages ........................................................................................................................... 22

1.7 Miscellaneous Topics ......................................................................................................................... 22 1.7.1 Web Access Log ........................................................................................................................... 22 1.7.2 PLS File Naming Convention ...................................................................................................... 23



1 Introduction The following document details standards directly related to the VLCWeb application as a whole. All developers should follow these standards to attain a unified look and feel throughout the website as well as add an increased level of code readability and maintainability throughout the team.

1.1 AJAX AJAX (Asynchronous JavaScript and XML), is web development technique used for creating interactive web applications. The main characteristic is the increased responsiveness of web pages achieved by exchanging small amounts of data with the server so that the entire web page does not have to be reloaded each time the user performs an action. This is intended to increase the web page's interactivity, speed, functionality, and usability. Data is requested from the server and loaded in the background without interfering with the display and behavior of the existing page. JavaScript is the scripting language in which AJAX function calls are made. Data is retrieved using the XMLHttpRequest object that is available to scripting languages running in modern browsers.

1.1.1 ASP.NET AJAX ASP.NET AJAX refers to new components in ASP.NET that allow for building rich AJAX styled web applications using the design patterns familiar to ASP.NET developers. ASP.NET AJAX 1.0 is available as a separate add-on for ASP.NET 2.0. AJAX components in ASP.NET integrate cross-browser script libraries with the ASP.NET server side Web application framework. This integrated architecture empowers developers to rapidly create pages with sophisticated, responsive user interfaces and more efficient client-server communication by simply adding a few server controls to their pages. Microsoft’s ASP.NET AJAX Framework (http://asp.net/ajax/) should be used in all VLCWeb applications as it is the direction that ASP.NET is headed. With the release of ASP.NET 3.5, the AJAX components have been integrated into ASP.NET (no separate download required). Also known as AJAX Extensions, it consists of the following controls:

1.1.1.1 Adding ASP.NET AJAX • Follow the installation and configuration instructions found at

http://www.asp.net/AJAX/Documentation/Live/Overview/default.aspx.

• Copy the "System.Web.Extensions" folder under js from PVCS to the js folder on the webserver.



1.1.1.2 Using ASP.NET AJAX In it’s simplest form, the instructions and code below are all that is needed to use AJAX and to keep the page refresh from taking place. A postback still happens, but it takes place asynchronously

• Create a normal aspx page with postbacks. • Surround the section of code you wish to render asynchronously with the UpdatePanel

tag. • Add a ScriptManager control at the top of the page before any UpdatePanels. A patch on

some AJAX JavaScript files was required and applied to allow AJAX to work correctly on the VLCWeb website when a frameset is being used. The ScriptManager must be implemented as shown in the example:



1.1.2 AJAX Control Toolkit In addition to the AJAX Extensions, VLCWeb developers are using the AJAX Control Toolkit (http://asp.net/ajax/control-toolkit/). The AJAX Control Toolkit is a joint project between the community and Microsoft. Built upon the ASP.NET 2.0 AJAX Extensions, the Toolkit aims to be the biggest and best collection of web-client components available. It consists of the following controls:

VLCWeb is currently using AjaxControlToolkit Version 11119.

1.1.2.1 Adding the AJAX Control Toolkit

• Add the following line to the controls tag of the web.config file: <add namespace="AjaxControlToolkit" assembly="AjaxControlToolkit" tagPrefix="ajaxToolkit"/>

• Extract the AjaxControlToolkit.dll to the webserver’s bin directory after downloading the appropriate version of the AJAX Control Toolkit from http://www.asp.net/ajax/downloads/.

• In Visual Studio right click on the Toolbox and "Add Tab" called AjaxControlToolkit • While in the Tab that was just created right click and "Choose Items" • Browse to the webserver’s bin directory and select "AjaxControlToolkit.dll" and click

Open • Click Ok and the Controls should now appear in the Visual Studio Toolbox.



1.1.2.2 Using the AJAX Control Toolkit The AJAX Control Toolkit consists of stand alone controls as well as Extender controls meant to extend the features of standard ASP.NET controls. Stand alone controls can be inserted into the aspx page the same as any other ASP.NET control. The Extender controls have specific properties that associate them with a standard ASP.NET control.

1.1.3 AJAX Loading Image The image used when performing an AJAX operation is called ajax-loader.gif. It is a small circular progress indicator with a transparent background. It should be placed on the page in such a way that the page content does not shift when the image is displayed. However, the recommended approach is to use ModalPopupExtender on a Panel with custom JavaScript at the bottom of the aspx page. Aspx:

JavaScript:



Output during asynchronous postback:

1.2 VLCWeb GridView VLCWeb applications often require the use of the GridView control to display a Multi Record Block (MRB). In the past, developers have spent a significant amount of time adding code around a GridView to create the vertical scrolling MRB effect. This would involve creating a column header table, a scrollable div, a GridView control, a footer table for record navigation, and custom JavaScript to navigate the MRB. Because the GridView control does not have a built-in scrolling mechanism that keeps header placement intact, column headers are separated from the GridView and have to be set as the same width as the columns. This is an attempt at seamlessly merging two objects on the page as one. However, the html generated using this method is rendered differently in various browsers and often negatively alters the page layout. This was unacceptable to the developer who could never quite get their page to look right in different browsers and unacceptable to the manager who could not effectively estimate project timelines.

1.2.1 MRBGridView The MRBGridView is a custom control derived from the GridView control. It has been developed to provide a solution to the issues mentioned above. By utilizing the built-in features of the GridView control combined with a custom pager and custom JavaScript record navigation, the MRBGridView serves as a single control that all developers can use without trying to re-invent the wheel each time a new page is developed. When the MRBGridView is displayed in the browser, the alignment issue is eliminated by rendering columns and column headers as one table.



1.2.1.1 Adding the MRBGridView • Add the following line to the controls tag of the web.config file:

<add tagPrefix="CustomControls" namespace="VLCWeb.Lib.CustomControls.LibCustomControls.MRBGridView" assembly="VLCWeb.Lib.CustomControls.LibCustomControls"/>

• Locate the VLCWeb.Lib.CustomControls.LibCustomControls.dll from the VLCWEB_DOTNET Project in PVCS.

• Put the VLCWeb.Lib.CustomControls.LibCustomControls.dll to the webserver’s bin directory.

• In Visual Studio right click on the Toolbox and "Add Tab" called VLCWeb LibCustomControls.

• While in the Tab that was just created right click and "Choose Items" • Browse to the webserver’s bin directory and select

"VLCWeb.Lib.CustomControls.LibCustomControls.dll " and click Open • Click Ok and the controls should now appear in the Visual Studio Toolbox.

1.2.1.2 Using the MRBGridView The MRBGridView has been developed to rely on ASP.NET AJAX and Session variables. It must be surrounded by an UpdatePanel and it’s datasource can be stored in the Session as a DataTable or Collection identified by the ClientID. Collections stored in the Session will be internally converted to DataTable by means of reflection. Example 1: MRBGridView with default properties. Aspx:



Code Behind using a DataTable:

Output:



Example 2: MRBGridView with columns defined. Aspx:

Code Behind:

Output:



Example 3: MRBGridView using a Collection. Aspx:

Code Behind using a Collection:

Output:



1.2.1.3 Custom Properties

Attribute Type Description MRBWidth string Width of the MRBGridView. (% or px) MRBMinHeight string Minimum height of MRBGridView when the last page has

less records than PageSize (px) MRBHeaderHeight string Height of the MRBGridView header row. (px) MRBRowHeight string Height of the MRBGridView content rows. (px) MRBHorizScroll bool Optional Horizontal Scrollbar. (true or false) MRBAutoResize bool Used in conjunction with MRBHorizScroll for

MRBGridViews that extend past the browser width and are not inside another container (i.e. td cell)

MRBFindOn bool Optional onscreen result search. (true or false). Not yet functional as of 19-Feb-2008.

MRBShowNavigation bool Hide or show record and page navigation (true or false) MRBInContainer bool Allows javascript to work properly when the MRBGridView

is inside a container such as TabPanel. (true or false) MRBSelectedIndex Int Retrieves the selected index of the active datasource.



1.3 VLCWeb Popups Popups should utilize the ModalPopupExtender from the AJAX Control Toolkit. This is done by a creating a Panel on the page where the popup content will be displayed and setting it as the TargetControlD on the ModalPopupExtender. A PopUpControlID and a CancelControlID also are specified to open and close the popup respectively. As the Popup is launched, the specified Panel becomes the only active element on the page, a dropshadow is offset, and a transparent overlay is applied to the background. The header table, background, and close button are all derived from the stylesheet and should be used in all Popups. When popups are implemented in this manner there is no need to launch new browser windows for List of Values, confirmation messages, or large data entry fields. As browser security is increased, inter window communication via JavaScript becomes more difficult and risky. With all the data elements on one page the development effort is decreased.

1.3.1 Confirmation ModalPopup Aspx:



Full View:

Zoom View:



1.3.2 MRBGridView ModalPopup

Aspx:

Full View:



Zoom View:

1.4 User Interface The following section covers key points about the VLCWeb application’s User Interface. A consistent look and feel is imperative when multiple developers are working on the project.

1.4.1 Themes and Styles The VLCWeb application is using the Themes feature of ASP.NET to keep consistency throughout pages. This provides a centralized location that dictates the appearance of controls in your application using stylesheets and template files with a .skin extension. The Theme used is BlueWhiteTheme.

• BlueWhite.css • Button.skin • DropDownList.skin • GridView.skin • HyperLink.skin • Label.skin • Link.skin • LinkButton.skin • ListBox.skin • MRBGridView.skin • PopCalendar.skin • RadioButton.skin • TextBox.skin • MRGridView.skin



1.4.2 Sample Screenshot The following screenshot from the VLCWeb application displays the most common screen.

Most of the application’s look and feel is controlled by the BlueWhiteTheme, but there are situations where the developer will have to add the styles manually. One such situation is detailed below. The table is broken down into a Header, Label, and Field. The main table uses the tbl class, the header uses boxHdr, the table label uses tdLbl, and the table field uses tdFld.

The following section is primarily styled by the MRBGridView. Only the header of the table is manually styled by the developer using boxHdr.



1.4.3 Common Controls The need may arise for a developer to use various UI elements that are common to many VLCWeb screens. The following section lists some of these controls.

1.4.3.1 MRBGridView Detailed in the VLCWeb GridView section of this document.

1.4.3.2 Ajax Control Toolkit ModalPopupExtender http://www.asp.net/AJAX/AjaxControlToolkit/Samples/ModalPopup/ModalPopup.aspx Also detailed in the Popups section of this document.

1.4.3.3 Ajax Control Toolkit Calendar http://www.asp.net/AJAX/AjaxControlToolkit/Samples/Calendar/Calendar.aspx



Example Usage:

1.4.3.4 Ajax Control Toolkit Tabs http://www.asp.net/AJAX/AjaxControlToolkit/Samples/Tabs/Tabs.aspx

1.5 Exception Handling Exceptions need to be caught, logged, and handled in both C# and PL/SQL code. The information below details VLCWeb’s approach.

1.5.1 C# When calling stored procedures from the code-behind, a Generic List collection is declared to store variables specifically for exception handling. These variables hold the sql status, the sql error code, and the sql error message. The Generic List collection is then passed to the Business Layer function by reference. The stored procedure called from Business Layer function must include three additional parameters of ParameterDirection.Output. Immediately after the DBHelper call, the output values are assigned to the Generic List collection. The catch block should first attempt to catch the OracleException and then the ordinary exceptions. This will help determine where the breakdown is occurring. The Generic List declaration: List<object> errValues = new List<object>(); errValues.Add((int)-5); //sql_status errValues.Add((int)-5); //sqlcode errValues.Add((string)string.Empty); //sqlerrm Pass the collection to the function by reference: LibExample objExample = new LibExample(); ds = objExample.GetData(param1, param2, ..., ref errValues); Business Layer function example: public DataSet GetSomeData(int param1, string param2, ..., ref List<object> errValues)



Additional Business Layer parameters: objOracleParameter = new OracleParameter("p_sql_status", OracleDbType.Decimal, ParameterDirection.Output); objOracleParameters[++intCtr] = objOracleParameter; objOracleParameter = new OracleParameter("p_sqlcode", OracleDbType.Decimal, ParameterDirection.Output); objOracleParameters[++intCtr] = objOracleParameter; objOracleParameter = new OracleParameter("p_sqlerrm", OracleDbType.Varchar2, ParameterDirection.Output); objOracleParameter.Size = 2000; objOracleParameters[++intCtr] = objOracleParameter; Assign values after DBHelper: errValues[0] = int.Parse(objOracleParameters[?].Value.ToString()); errValues[1] = int.Parse(objOracleParameters[?].Value.ToString()); errValues[2] = objOracleParameters[?].Value.ToString(); Catch block exceptions: catch (OracleException oe) { errValues[1] = oe.Number; errValues[2] = "Oracle error " + oe.Message + ". Procedure:" + oe.Procedure; } catch (Exception ex) { errValues[2] = "Library error(LibExample.GetData): " + ex.Message; }

1.5.2 PL/SQL Stored procedures called from the code-behind will have similar variables as those in the C# section. Three OUT parameters are declared to correspond to the Generic List Collection. Before the procedure returns control back to the caller, the three variables are populated with values that indicate success (0). The exception block’s WHEN OTHERS condition should populate the three variables with values that indicate failure (-1). An autonomous transaction call to ASP_LIB_COMMON.Write_Log should also be placed in the WHEN OTHERS condition to store the error in the ASP_LOG table. At times the PL/SQL package may return a validation message. In this case the p_sql_status variable is assigned a value of -2 and the p_sqlerrm variable is assigned a meaningful validation message. The same can apply for confirmation messages where the p_sql_status variable is assigned a value of -3 and the p_sqlerrm variable is assigned a meaningful confirmation message. The developer is responsible for handling the particular p_sql_status value once returned from the code-behind.



Three OUT parameters: p_sql_status OUT NUMBER, p_sqlcode OUT NUMBER, p_sqlerrm OUT VARCHAR2 Variable assignment for success: p_sql_status := 0; p_sqlcode := 0; p_sqlerrm := ''; ASP_LIB_COMMON.Write_Log declaration: ASP_LIB_COMMON.WriteLog(p_pgm_name VARCHAR2, p_log_txt VARCHAR2); Variable assignment for failure and database logging: EXCEPTION WHEN OTHERS THEN ASP_LIB_COMMON.Write_Log('procedure name','SQLCODE||','||SQLERRM); p_sql_status := -1; p_sqlcode := SQLCODE; p_sqlerrm := SQLERRM; Variable assignment for validation: p_sql_status := -2; p_sqlcode := 0; p_sqlerrm := 'Date Format is incorrect.'; Variable assignment for confirmation: p_sql_status := -3; p_sqlcode := 0; p_sqlerrm := 'Tranaction saved successfully.';

1.6 User Messages Messages should be displayed with a clear distinction between message types. One time messages should be displayed to the user via a modal popup, so they can be clearly acknowledged and then dismissed by the user. If possible JavaScript alerts should be replaced by one time messages. Error messages that may require the user to take action or review multiple times should be left aligned at the top of the page. The message will consist of a Panel containing a BulletedList styled with txtRedBold.



1.6.1 One Time Messages

1.6.2 Error Messages Zoom View:

Full View:

1.7 Miscellaneous Topics 1.7.1 Web Access Log A file named WebAccessLog.cs is used as a Common class in LibCommon. The WriteLog method of WebAccessLog should be called in the Page_Load event when the Page is not PostBack. To prevent unnecessary logging, the call should be placed only in the



application’s main entry point. WriteLog will call the Web_Common_Pak.WriteLog database procedure to write log records based on user activity. The two parameters accepted by WriteLog are the Request object and the current user’s LogonId. Example: if (!Page.IsPostBack) { WebAccessLog.WriteLog(Request,VLCWebUser.LoginId); }

1.7.2 PLS File Naming Convention The naming convention for all database packages called only from .NET application is as follows.

• First two characters should start with 'wa' to denote 'web' and 'asp'.

• Next two characters can denote the module e.g. 'bk' for 'Booking' 'dc' for 'Documentation’.

• Next two characters should denote package spec or body i.e. 'ps' for spec and 'pb' for body.

• Last two characters will be running serial number .- Asia/ RT to use 01 - 50 , NJ to use

51-99.

• Package Naming convention : All the packages should start with ASP_ . The rest can be a meaningful name.

Example: ASP_BKG_CREATE should contain all the procedures/ functions that are to be used by BKG creation module. The related function names under it can be like BKG_CUST_GET , BKG_CUST_SAVE etc. Please note that the above convention is only true for the packages that will be called from ASP .NET only. These packages will be created in the VLCWEB schema and a PLS folder will be added to the VLCWEB_DOTNET PVCS Project to store these files. If we need a function which can be re-used in Starnet, then that should be defined under a separate package.

vlcweb net application standards...1.1.1 asp.net ajax asp.net ajax refers to new components in...

Documents