NetQuarry Namespace

The Application context object holds information that is used throughout each page (or server) request. The Application is available to all objects, either as a direct parameter or property on an existing object. The Application object is created as the first object in any request, and when possible it is cached for performance purposes.

See the following classes for more useful utilities:

• EAPConvert - Utility methods for converting data.
• EAPCtrlUtils - Utility methods for working with .Net controls.
• EAPEncode - Utility methods for encoding data.
• HttpUtility - Helper utility class for HTTP based code.
• ImageUtils - Utility functions for manipulating images.
• MailUtils - Various utility methods for working with email.
• MapperUtils - Utility class providing helper methods for working with IMapper objects.
• MathUtils - General-purpose math utilities.
• StringUtils - General-purpose string utilities.
• TagUtils - Utility code for generating HTML element strings.

The basic format for an embedded function inside an expression (e.g. a SQL statement) is !fnXXX[flags](params) where ALL embedded functions must start with "!fn" (case-sensitive), be followed by the function name (also case-sensitive), optionally followed by activation flags (currently only "$" is supported indicating that the result should be AnsiQuoted), followed by an open parenthesis and closing parenthesis between which a set of comma-separated parameters may optionally be specified. For example, !fnBitTest(0x00000002, 1) tests whether or not the 1st bit (0-indexed) is set (which it is in this case) and evaluates to 1 if so, else 0.

The parser includes a set of intrinsic functions:

• fnAppCacheVer - Return the application version number string. The returned format is ver=xxx, where xxx is the application version in production mode, or a timestamp otherwise.
• fnAppProperty - The value of the specified application property.
• fnBitTest - Tests for a bit being set. Evaluates to zero if not set. Format is: fnBitTest(value, bitnum) where bitnum is the 0-based index of the bit to test.
• fnCacheVer - Return a version number for managing included javascript, or style sheets. Ensures the latest versions of files using this function will be up to date and never stale.
• fnCulture - The name of the current Culture for the current user.
• fnCultureBase - The name of the current base Culture for the current user (e.g. 'en' for any English language culture).
• fnDBLookup - Looks up a value in the database. Format is: fnDBLookup(col, table, where). This provides similar functionality to the DBLookup(String, String, String) function.
• fnFormat - Format data. Format is: fnFormat(value, datatype, format) where datatype is currently limited to d=date/time and format is a standard .Net formatting string.
• fnNamedFilter - Takes a string that refers to a name of a named filter.
• fnNewGUID - Generates a new GUID. An optional format parameter may be specified.
• fnNow - The current date/time with optional timezone defaulting to user's local timezone.
• fnNowAdd - The current date/time with the specified offset in the form fnNowAdd(period [,count [,timezone]]) where period is one of y, M, d, H, m, s, or f, and defaulting to user's local timezone.
• fnNowAddUTC - The current date/time in UTC with the specified offset in the form fnNowAddUTC(period [,count]) where period is one of y, M, d, H, m, s, f.
• fnNowUTC - The current date/time in UTC.
• fnProfilesFilter - Returns the IN clause formatted string for all of the current user's profiles.
• fnProxyUserID - The Proxy ID for the current user context.
• fnTenantID - The value of Session.TenantID.
• fnTimePeriod - Takes a datetime column name and required time period keyword (e.g. today, yesterday).
• fnTimePeriodUTC - Takes a UTC datetime column name and required time period keyword (e.g. today, yesterday).
• fnToday - The current date (with 00:00:00 time component) with optional offset and timezone in the form fnToday([period [,count [,timezone]]]) where period is one of y, M, d, H, m, s, or f, and defaulting to user's local timezone.
• fnUserGUID - The GUID for the current user.
• fnUserID - The ID for the current user.
• fnUserName - The name of the current user.

In addition to these intinsic functions, the parser supports application-specific static substitution functions and dynamic functions. Functions can be registered programmatically by calling RegisterFunction(String, String, String) on the parser or by calling RegisterEmbeddedFunction(String, String, String) on the application.

Static substitution functions can be specified in meta-data via the NetQuarry studio by creating Session Properties and setting the GenEmbeddedFunc attribute on each. Dynamic functions can be configured in meta-data as well by setting up FunctionParser Components. FunctionParser components implement the IFunctionParser interface. The IFunctionParser interface allows the platform to interrogate the component in order to determine which functions it supports and to invoke those functions when encountered during embedded function resolution.

Field references can be used throughout platform applications with an expression containing markers for IField values of the form [<flags><key>] where <key> is a field Key and <flags> are zero or more modifier flag characters (see the corresponding FieldExpressionAttrs flags) specifing how the field value is to be represented:

• $ - DisplayText - Use the field's display text rather than its raw value (obtained via DisplayTextGet(DispTextFlags)).
• ' - AnsiQuote - AnsiQuote the value using AnsiQuote(String) (this is a single-tick character).
• ` - DoubleQuote - Enclose the field value in double-quote '"' characters (this is a back-tick character).
• # - Numeric - The value is a numeric value and should be rendered as zero "0" if the value is null/empty.
• < - UseOldValue - Use the OldValue if the field is dirty.
• & - UseCaption - Use the field's Caption instead of its value.
• ? - EscapeForUrl - The field's value should be escaped for use in a URL using ForUrl(String).
• @ - EscapeForHtml - The field's value should be escaped for use in HTML using ForHtml(String).
• ^ - ApplyDefault - Use the field's DefaultValue if the field's value is null/empty.
• + - EscapeForXML - The field's value should be escaped for use in XML using ForXml(String).
• * - RawValue - Use the field's value (obtained via Value), implied if no other option specified.
• ~ - ClientElement - Renders as a javascript expression accessing the field. Often combined with either '$' or '*' attributes to obtain the client-side display or raw values respectively.
• : - Optional - Value is optional and should default to zero or empty string, as appropriate.
• - - Guid - The value is a GUID value and should be rendered as the zero GUID "{00000000-0000-0000-0000-000000000000}" if the value is null/empty.

Field references are sometimes used in conjunction with "!fn" Embedded Functions which are resolved by the EmbeddedParser.

Extensions are called in Priority order from highest Priority number to lowest. Note, however, that Priority is only enforced internally during FireEvent(ExtensionEvents, Object, EAPEventArgs). The extensions in the collection are not organized in any particular order so you should not assume an order when iterating through the collection using foreach or accessing an extension by index.

At a minimum a Caption and Message (or HTML) should be provided.

• Specify a filter in one place that can be used throughout the application.
• Implement role-based filtering where some roles have different data visibility than other roles per Priority.

Examples

Page Overloading can achieved by specifying Device and/or Priority. When a user logs in with roles that allow access to multiple pages with the same MOP then Device and Priority are used to determine which of these pages is to be used. If a particular Device matches the current device then that page is favored. If multiple pages with the same (or no) Device are available then Priority is used to disambiguate with the highest Priority number favored.

Note most objects having Properties collections also have TextItems collections that include named text items localized to the user's culture. As with the Properties collections, TextItems collections are loaded from meta-data and expose meta-data maintained by the studio.

Among the most important objects having Properties collections are:

• IAppContext - The application object.
• PageInfo - Page objects.
• IMapper - Mapper objects.
• IField - Field objects.

SavedFilters may be static or dynamic:

• Dynamic - Dynamic filters are the most common and default filter type. Dynamic filters use a SQL WHERE clause that is applied to the mapper's query. The filter is dynamic because the resulting records may change due to changes in those records' data.
• Static - Static filters always filter on the same set of keys and so the resulting records are always the same. These keys are stored in the xot_saved_filter_keys table in the operational database and associated with a specific SavedFilter. In the case of a static filter, the SavedFilter Filter will be a subquery against that table.

You can obtain a SavedFilter from an IMapper using the FilterSave command. This will cause the mapper to created a SavedFilter reflecting its current filtering including any FullTextSearchValue. It will also include a comprehensive Description for the filter. You can apply a SavedFilter to an IMapper using the SavedFilterApply command. This will apply the Filter clause as well as any FullTextSearchValue.

SavedFilters provide a safe way to include mapper filtering in a URL. You can use one of the RegisterReqFilter overloads to save a filter clause to the operational database and return a unique signature that can be included as the value for the standard flt parameter in a navigation url. Filters referenced in this manner can be included in a URL without risk of a SQL injection attack. You can use one of the ExtractFilterFromReq overloads to obtain a SavedFilter from a registered filter query parameter.

• UNION operator
• INTO clause

One of the most common uses for templates is as the basis for the body of an email message. To see an example of how to use a Template see IEmailService.

The most common format for a template is HTML, but, depending on how it is being used, any text format is supported. Templates support substitution markers whose name/value pairs are typically provided in a NameValueCollection when the template is resolved using one of the various Replace or Expand methods.

The markers may take two forms:

• {{itemName}} - The marker replacement text should be escaped for HTML using TextToHtml(String, TemplateReplaceFlags).
• [[itemName]] - The marker replacement text should not be escaped for HTML.

When populated from a IMapper default markers will, by default, be substitued using the DisplayText of the corresponding IField (obtained via DisplayTextGet(DispTextFlags)). However, an optional marker prefix may be included to specify otherwise (see TemplateNodeMarker). For example, {{&first_name}} would mean that the marker should be replaced with the HTML-escapted text for the "first_name" field's caption.

• & - Caption: Use the field's Caption.
• * - RawValue: Use the field raw value.
• + - ImmediateEdit: Substitute for use with ImmediateEdit. This only applies to page content, but not to email templates and similar.
• / - NavLink: Substitute with a field's NavLink. NavLink marks should not be escaped (that is, always use the '[[]]' delimiters).
• % - Template: Substitute with the expanded content of the specified inner template. Template marks should generally not be escaped (that is, generally use the '[[]]' delimiters). A template marker may optionally include a set of name/value pairs used in expanding the inner template. Any name/value pairs provided will override the corresponding of name/value pairs provided to the outer template. The syntax for a template reference is %<template-name>[:name1=value1;name2=value2...] (wrapped in an outer [[]] or {{}}). A colon is used to separate the optional name/value list, a semi-color separates each name/value pair, and an equals sign separates each name from its value.
• # - Numeric: Substitute with a numeric field's raw value or 0 (zero) when null/empty.
• = - HasValue: Substitute with "1" or "" (empty string) depending on whether or not the field's DisplayText has a non-null/non-blank value.

Templates are commonly used for the following purposes:

• General email body layout and content using IEmailService.
• Email body layout and content via an IMapper using a Send overload such as Send(String, String).
• MiniDetail page element layout, specified via its Template property.
• WizMiniDetail page element layout, specified via its Template property.
• LiteralContent page element layout, specified via its Template property.
• MapperSummary page element layout, specified via its Template property.
• MapperSummary field layout, specified via its SummaryTemplate property.
• Wizard primary summary content and layout, specified via its SummaryTemplate property.
• Programmatic HTML generation using ExpandTemplate with Exec(MapperExecCmds, Enum, Object).
• PDF generation using IPDFDocument.

Templates also support events fired to TemplateExtensionBase components:

• PluginPreRender - Fired when a Plugin template is about to be rendered.

Examples

Dear {{first_name}} {{last_name}},
<br />
Thank you contacting us regarding interest in our {{product_name}} product.  One of our sales people will contact
you shortly to help you with any questions you may have and to aid in ordering.
<br />
Additional information is available at [[product_url]].
<br />
Sincerely,
<br />
{{company_name}}

In order to avoid cluttering up the devlog, it is sometimes desirable to write a timer entry if, and only if, some timing threshold is exceeded. Use the ThresholdLogger for this purpose.

Typically you should obtain a TimeZones collection from the application via TimeZones. That collection is constructed by the application at startup and properly loaded from the registry.

In addition to the timezones loaded from the server's Windows registry, a number of special timezones are predefined in the collection:

• 0 - The Coordinated Universal Time (UTC), or Zulu timezone (like GMT, but does not adjust for Daylight Savings), UTCTimeZone.
• . - User local timezime (if known), UserLocalTimeZone.
• -1 - User local timezime (if known), same as "." used where a numeric value is required.
• -2 - Server local timezime (if known), ServerLocalTimeZone.

To perform a timezone conversion between arbitrary timezones you can use Convert(String, String, DateTime) or Convert(Int32, Int32, DateTime) which will return a date/time even if one or both timezones are unknown (in which case the date/time value is returned without any conversion). For more more control you can first get the source TimeZone and call Convert(TimeZone, DateTime) providing the destination TimeZone.

Remarks

These factilities fall into the following groups:

• Methods for getting and setting UserData values in the instantiated instance:
  • Determine if an item exists using ContainsKey(String).
  • Add/modify a value using SetValue(String, String).
  • Get the value of an item as a boolean using GetBool(String).
  • Get the value of an item as a DateTime using GetDateTime(String) or GetDateTime(String, DateTime).
  • Get the value of an item as a doubler using GetDouble(String, Double).
  • Get the value of an item as an integer using GetInt(String) or GetInt(String, Int32).
  • Get the value of an item as a string using GetString(String).
• Methods for managing selected items in lists by RowKey (with methods for current instance and other instances):
  • Determine if an a particular item is selected using IsSelected(String) or IsSelected(String, String).
  • Add an item to the list of selected items using AddRowKey(String) or AddRowKey(String, String).
  • Clear the list of selected items using ClearRowKeys or ClearRowKeys(String).
  • Remove from the list of selected items using RemoveRowKey(String) or RemoveRowKey(String, String).
  • Get the list of selected items (as an array) using GetRowKeyArray or GetRowKeyArray(String).
  • Get the list of selected items (as semi-colon separated list) using GetRowKeys or GetRowKeys(String).
  • Add multiple items to the list of selected items (as an array) using SetRowKeys(String) or SetRowKeys(String, String).
  • Add multiple items to the list of selected items (as semi-colon separated list) using SetRowKeys(String) or SetRowKeys(String, String).
• Methods for getting and setting UserData values in another instance:
  • Determine if an item exists using ContainsKey(String, String).
  • Add/modify a value using SetValue(String, String, String).
  • Get the value of an item using GetString(String, String) or GetString(String, String, String).
• Tools for programmatic debugging, specifically DebugList.
• List management items primarily intended for internal use:
  • Get the key used to store a particular item in UserData (used to access UserData directly), using Key(String) or Key(String, String).
  • Get the InstanceName of the current WizPageData instance using InstanceName.

The Application context object holds information that is used throughout each page (or server) request. The Application is available to all objects, either as a direct parameter or property on an existing object. The Application object is created as the first object in any request, and when possible it is cached for performance purposes. The application hosts extensions and fires various application ExtensionEvents to those extensions. The normal IAppContext implementation is provided by the AppContext object.

The following properties are commonly accessed:

• Session - Gets the current Session object.
• UserContext - Gets the UserContext object describing the current user.
• DataDB - Gets the primary IDatabase source for operation data.
• Databases - Gets the Databases collection of IDatabase objects for the application.
• Navigators - Gets the Navigators collection of Navigator objects for the application.
• PageInfos - Gets the PageInfos collection of PageInfo objects for the application.
• Picklists - Gets the Picklists collection of Picklist objects for the application.
• Services - Gets the ServiceInfos collection of IServiceInfo objects for the application.
• Templates - Gets the Templates collection of Template objects for the application.

The following methods are commonly used:

• DisplayMessage(Alert) - Displays a message to the user.
• Navigate(String, String, String) - Ends the current request and navigates to a page within the application.
• ResolveEmbeddedFunctions(String, IDatabase, ResolveOptions) - Resolves a string for embedded functions.
• Send(MailMessage) - Sends an email message using the default mail service.

Console pages can generally be of two types:

• Main - Console pages presenting panes filtered relative to the main pane (using each pane's ParentViewKeySource. and ViewKey). An example would be a company page, commonly named somethig like company!main, showing the company detail and list of related items for that company such as employees, clients, and projects.
• Dashboard - Console pages presenting panes not filtered on the main pane. Often dashboard consoles present groups actions and of links to various parts of the application.

By default the console page presents all panes that are visible at one time. However, the console also supports Pane Navigation whereby only one pane marked with the PaneNavigation attribute, the Active Pane, is shown at one time. When Pane Navigation is in use the default Active Pane is specified by the HomePane.

The three most common types of extension, from most to least common are:

• IMapper extensions should typically be derived from the TypedMapperExtensionT base class when used with a single mapper (the most common case for custom extension), or from the MapperExtensionKernel base class if used across various mappers (common with platform extension such as ReadableAudit and ExcelExport). Both base classes derive from MapperExtensionBase. See MapperExtensionKernel for more information about the sequence of events for mappers.
• Page extensions should be derived from PageExtensionBase. See PageExtensionBase for more information about the sequence of events for pages.
• Page extensions should be derived from ApplicationExtensionBase.
• Template extensions should be derived from TemplateExtensionBase.

Some examples of pages implementing this interface, but not IPageTemplate are:

• Find - Provides a mechanism for a finding a single record and relating it to another record.
• MultiFind - Provides a mechanism for a finding one or more records and relating it/them to another record.

By far the most common page templates are:

• TabbedSubformTemplate - Provides a horizontally split screen with a bottom pane presenting multiple tabs related to the data in the top pane.
• ExpandedSubformTemplate - Provides a horizontally split screen with a bottom pane vertically presenting multiple expandable items related to the data in the top pane.
• WizTemplate - Implements IWizardTemplate and provides a multi-page wizard typically used for creating one or more new items.
• ConsoleTemplate - Implements IConsoleTemplate and provides a user console with multiple data panes manipulable by the user (non-Bootstrap applications).
• BootConsoleTemplate - Implements IConsoleTemplate and provides a user console with multiple data panes manipulable by the user (Bootstrap applications).

• dsctrl - The traditional Datasheet.
• ConsoleDatasheet - The Datasheet intended for use in a console page.
• MiniList - A lightweight, static Datasheet.
• phantomdetail - The traditional, editable detail.
• MiniDetail - A Template-driven, mostly read-only detail.
• ConsoleDetail - The detail intended for use in a console page.
• LiteralContent - Static content, possibly from a Template.
• MiniNav - A list of navigation elements.
• BootRepeater - Renders each records as a block in the console page.

There are currently two implementations of IToggler:

• Toggler - The original platform toggler WebControl.
• TogglerB - The new toggler WebControl implemented using standard Bootstrap CSS and javascript.

1. Check in all meta-data changes as the conversion process may alter existing meta-data.
2. Check out all meta-data in prepartion for the conversion.
3. Run the nq_add_pei_permissions.sql script against the repository to perform the conversion.
4. Check in altered .meta files.
5. Set the PageElementPermissionsLevel property of the Compatibility feature and check in the modified .meta file.