Format

Transcription

Format

listx - afterall, It's your data
Version 1.9.7
Overview
Enthusiastically heralded as a defacto, must-have
module for DotNetNuke, ListX provides unmatched,
and unparalleled features making it the most useful
and versatile module available on the market.
Providing high-end custom formatted output and
database integration to web projects has always
been a hassle with DotNetNuke. While DNN
provides all the customization abilities provided by
the Module Developers, the layout and control of
these are fixed and rigid, and provide only
capabilities to control the class style used on the
general output. ListX provides the most powerful
universal presentation engine on the market. Not
only can you build fully functional, hierarchical views
of your data, but you can also create multiple ListX
modules which interact with one another, each
configured to perform complex display logic and
runtime actions. Why build your modules from
scratch, or build new modules just to display
formatted reports when you can just use ListX?
The root of ListX originated with the need to develop a universal presentation layer which could act as a complex
data repeater, a single record property view or a completely interactive data editor. The web application required
data grid layouts, search and filter interaction, property sheets as well as drill-down and editable views. Classically
this would have been handled by creating many static modules, with pre-built repeaters and data grids to achieve
formulated output. The system itself needed to be easily customizable by the web designers, capable of tweaking
the User Interface without the need for writing code or recompiling the modules. Hence, ListX was born, pulling all
these possibilities into one easy to use module.
Exceeding Expectations - Since it's conception, ListX has provided extraordinary capabilities to
DNN web designers and developers. Imagine providing any type of data driven output to users
with just a simple configuration, and easy integration.
1.
2.
3.
4.
5.
6.
7.
Elegant and Powerful Web Administration
Customizable Queries with Interactive capabilities
Dynamic Presentation for Viewing and Editing one or many records.
Built in capabilities for o User defined Records-Per-Page
o Optional Page Selection
o Dynamic Alphabetic Filtering
o Custom Free-Text Searching
o Single and Multiple Column Sorting
o Custom Paging Capabilities
o AJAX Interaction for optimal speed
o Microsoft Excel data Exporting / Importing
o Event Driven Interaction
o Truly Intelligent Debugging
o File and image Upload
Grouping Headers and Footers on Column Values
Standard and Alternating Item Rendering
Inline Column Formatting
Business Intelligence Force, Inc. (bi4ce)
1
Version 1.9.7
8. Grouped Checklists with Post-back free Item Selection
9. Simplistic Integration with extreme visual impact
10. Capable of leaping tall buildings in a single bound...(okay, so 9 out of 10)
Break the Mold - While many views are necessary for reading and displaying data, and providing
interactive functionality to users - why be stuck with the same archaic view layouts? With ListX,
you can build new front-end views of all of your database data.
Expand your Horizons - Build new insights, and drill into data easily by scaling ListX integration
across multiple module instances. Expand on all data interaction with limited restrictions.
Build Within Budget - While you could spend hour upon hour building all modules from scratch,
ListX provides real world, proven capabilities that allow you to simply configure ListX modules as
Lists, Views, edit forms and nearly any other display type in one preexisting module. So you can
focus on just the business logic. Leave the presentation to ListX!
Blistering Fast Interaction
Taking the presentation layer further into the future, ListX provides the ability to utilize AJAX,
Asynchronous Javascript and XML, to handle all the paging aspects of your data. With ListX and
AJAX, viewing all the records in your presentation layer is accelerated to maximum speed and
efficiency - posting back only the information necessary to the server for the desired page, and only
updating the region on the browser page that has been affected by the new returned page
information. Since DotNetNuke can sometimes load slower than other ASP.Net based applications, utilizing ListX
with AJAX within DNN increases the overall speed and efficiency of the user experience.
Your Configuration – Anywhere, Anytime!
The entire set of View Options provided on the ListX module are stored for the specific page you are developing. In
situations when you desire to utilize the same basic layout of a ListX Module between multiple instances, or when
you need to duplicate the ListX on multiple installations of DotNetNuke, use the XML option to copy, or load an
entire configuration. Press the
button to load or retrieve the formalized XML structure identifying all properties.
This makes it easy to copy the settings from one module or page into another instance of the ListX. Once clicked,
you can Copy the contents of the XML Source text, or Paste the XML from your clipboard into the Source. To reload
the module using the XML Source Text, click Load.
Build Solutions and Package these in your own Modules
Take your whole solution including Tabs/Pages, Modules, Files and Database schema and build a
single ListX Package (LP) to distribute and reuse. Or, create PA‟s out of your modules and install
them like any other!
Tip: While ListX brings a huge array of functionality to the DotNetNuke world, you can improve your possibilities
further by using ListX with our Toolbar control.
2
Version 1.9.7
Table of Contents
OVERVIEW .................................................................................................................... 1
Table of Contents................................................................................................................................. 3
EULA - Software License Agreement ................................................................................................ 11
CONTROL PANEL ...................................................................................................... 15
General............................................................................................................................................ 15
Search ............................................................................................................................................. 15
Variables ......................................................................................................................................... 15
Query .............................................................................................................................................. 15
Actions ............................................................................................................................................ 15
Format ............................................................................................................................................. 16
Locking ............................................................................................................................................ 16
Unlocking......................................................................................................................................... 16
XML Configuration ........................................................................................................................... 16
Saving Changes .............................................................................................................................. 16
DRAFT MODE ............................................................................................................. 17
RUNTIME ISSUES WARNING .................................................................................... 18
DEFAULT PROPERTIES ............................................................................................ 19
Paging Properties .............................................................................................................................. 19
Filters and Sorting ............................................................................................................................. 20
AJAX Integration ................................................................................................................................ 21
Enabling AJAX Interaction................................................................................................................ 21
When NOT to use AJAX .................................................................................................................. 21
Javascript ........................................................................................................................................... 23
Site Integration ................................................................................................................................... 24
Debugging .......................................................................................................................................... 25
Administration.................................................................................................................................... 27
Version Compatibility ........................................................................................................................ 28
3
Version 1.9.7
Other Properties................................................................................................................................. 29
SEARCH OPTIONS ..................................................................................................... 31
iSearchable Integration...................................................................................................................... 31
QUERY OPTIONS ....................................................................................................... 33
Quote Escaping.................................................................................................................................. 33
Runtime Variables .............................................................................................................................. 33
Custom Connections ......................................................................................................................... 35
Custom Connection (in the ListX Configuration) ............................................................................... 36
Custom Paging................................................................................................................................... 37
Oracle with Custom Paging .............................................................................................................. 37
SQL 2005 with Custom Paging ........................................................................................................ 38
VARIABLES ................................................................................................................ 39
Security .............................................................................................................................................. 41
Protect Against SQL Injection........................................................................................................... 41
Protect Against HTML Injection ........................................................................................................ 41
Protect Against ListX Injection .......................................................................................................... 41
MESSAGE ACTIONS .................................................................................................. 43
Managing Actions .............................................................................................................................. 43
Moving Actions .................................................................................................................................. 44
Editing Message Actions ................................................................................................................... 45
MESSAGE ACTION TYPES........................................................................................ 47
Message ............................................................................................................................................. 47
Action: Execute .................................................................................................................................. 48
Action: Assignment ........................................................................................................................... 51
Action: Redirect ................................................................................................................................. 53
4
Version 1.9.7
Action: Email ...................................................................................................................................... 54
Action: Output .................................................................................................................................... 55
Action: Input....................................................................................................................................... 56
Common Input Scenarios................................................................................................................. 57
XML Based Web Service ............................................................................................................. 57
SOAP Based Web Service........................................................................................................... 59
Action: File ......................................................................................................................................... 63
Condition: If........................................................................................................................................ 68
Condition: Else-If ............................................................................................................................... 69
Condition: Else................................................................................................................................... 70
Action: Comment ............................................................................................................................... 70
Action: Log ......................................................................................................................................... 70
TEMPLATE FORMATTING ......................................................................................... 71
List Groups (Template Hierarchy) ..................................................................................................... 72
Managing Template Groups ............................................................................................................. 73
Editing Templates .............................................................................................................................. 73
Template Syntax .............................................................................................................................. 73
Group Statement ............................................................................................................................. 73
Default Item (No Results) ................................................................................................................. 74
Default Item (No Query) ................................................................................................................... 74
COLUMN VALUES ...................................................................................................... 75
Standard Column Output ................................................................................................................... 75
System Values and Parameters......................................................................................................... 75
Advanced System Values .................................................................................................................. 76
Input File (Form) Values................................................................................................................... 76
File (CSV/SQL) Import Process Values ............................................................................................ 76
Localization/Resource File Values.................................................................................................... 76
Runtime Values (Reflection) ............................................................................................................. 77
FORMAT – CUSTOM VALUE FORMATTING ............................................................ 81
5
Version 1.9.7
Standard .Net Formatters .................................................................................................................. 81
Standard Numeric Formatting .......................................................................................................... 81
Standard Date Formatting ................................................................................................................ 82
Custom Date Formatting .................................................................................................................. 82
Extended ListX Formatters ................................................................................................................ 85
String Manipulation Formatters ........................................................................................................ 85
LEFT ....................................................................................................................................... 85
RIGHT ..................................................................................................................................... 85
MID ......................................................................................................................................... 85
UPPER.................................................................................................................................... 86
LOWER................................................................................................................................... 86
LENGTH ................................................................................................................................. 86
REPLACE ............................................................................................................................... 86
PADLEFT................................................................................................................................ 87
PADRIGHT ............................................................................................................................. 87
TRIM ....................................................................................................................................... 87
TRIMLEFT .............................................................................................................................. 87
TRIMRIGHT ............................................................................................................................ 88
Encoding, Decoding ......................................................................................................................... 88
ENCODEURI ........................................................................................................................... 88
DECODEURI ........................................................................................................................... 88
ENCODEHTML. ...................................................................................................................... 88
DECODEHTML. ...................................................................................................................... 89
ENCRYPT ............................................................................................................................... 89
DECRYPT ............................................................................................................................... 89
Runtime Verification and Validation .................................................................................................. 89
ISEMPTY ................................................................................................................................ 89
ISINROLE ............................................................................................................................... 90
ISSUPERUSER....................................................................................................................... 90
ISNUMERIC ............................................................................................................................ 90
ISDATE ................................................................................................................................... 90
CANEDIT ................................................................................................................................ 91
EXISTS ................................................................................................................................... 91
STARTSWITH ......................................................................................................................... 91
ENDSWITH ............................................................................................................................. 92
CONTAINS ............................................................................................................................. 92
INDEXOF ................................................................................................................................ 92
LASTINDEXOF ....................................................................................................................... 92
Advanced Tab and Custom Look-ups............................................................................................... 93
TABID ..................................................................................................................................... 93
TABID:COLUMN..................................................................................................................... 93
TABNAME .............................................................................................................................. 93
TABTITLE ............................................................................................................................... 94
TABDESCRIPTION................................................................................................................. 94
SQLFIND ................................................................................................................................ 94
COALESCE ................................................................................................................. 95
6
Version 1.9.7
Coalesce Syntax ................................................................................................................................ 95
Examples ............................................................................................................................................ 95
Example 1 – Column, Unassigned Querystring, Unassigned Form ................................................... 96
Example 2 – Column, Unassigned Querystring, Assigned Form ....................................................... 98
Example 3 – Column, Unassigned Querystring, Assigned Empty Form .......................................... 100
Example 4 – Column, Assigned Querystring, Assigned Form ......................................................... 102
COLUMNS AND COLUMN TEMPLATES ................................................................. 105
Columns Syntax ............................................................................................................................... 105
ACTION ITEMS ......................................................................................................... 107
Example ............................................................................................................................................ 107
CHECKBOX AND RADIO LISTS .............................................................................. 109
Check List Syntax ............................................................................................................................ 109
Example ........................................................................................................................................ 109
Singular Check Item Syntax ............................................................................................................ 110
Example ........................................................................................................................................ 110
How to Use Checklists in your Solution ......................................................................................... 111
Example ........................................................................................................................................ 111
Radio Item Syntax ............................................................................................................................ 113
Example........................................................................................................................................ 113
SORTING................................................................................................................... 115
Sorting Syntax.................................................................................................................................. 115
Example ........................................................................................................................................ 115
SUB QUERY .............................................................................................................. 117
Sub query Syntax............................................................................................................................. 117
Example ........................................................................................................................................ 117
ALTERNATE ............................................................................................................. 119
Alternate Syntax............................................................................................................................... 119
Example ........................................................................................................................................ 119
7
Version 1.9.7
AGGREGATIONS ..................................................................................................... 120
Aggregation Syntax ......................................................................................................................... 120
Example ........................................................................................................................................ 120
SET ............................................................................................................................ 121
Set Syntax ........................................................................................................................................ 121
Example ........................................................................................................................................ 121
MATH......................................................................................................................... 123
MATH Syntax.................................................................................................................................... 123
Example ........................................................................................................................................ 123
BITWISE Example ......................................................................................................................... 123
Condition Example......................................................................................................................... 124
Condition Example (Strings) ........................................................................................................... 124
Symbols and Functions ................................................................................................................... 125
Logic Operators ............................................................................................................................... 126
Functions ......................................................................................................................................... 127
IIF (IF AND ONLY IF) ................................................................................................ 129
IIF Syntax.......................................................................................................................................... 129
Example In Rendering.................................................................................................................... 129
Example In Query .......................................................................................................................... 129
ESCAPING ................................................................................................................ 131
CLIENT SCRIPTS AND UTILITIES ........................................................................... 133
AJAX Library .................................................................................................................................... 133
lxFetch........................................................................................................................................... 133
lxModule ........................................................................................................................................ 134
Utilities Library ................................................................................................................................. 135
lxExpander..................................................................................................................................... 135
lxToggle ......................................................................................................................................... 136
lxContainer .................................................................................................................................... 138
lxContainerGroup........................................................................................................................... 139
lxSetValue ..................................................................................................................................... 140
8
Version 1.9.7
lxComboSelect............................................................................................................................... 140
VALIDATION LIBRARY ............................................................................................ 141
Group Validation .............................................................................................................................. 144
TEXTEDITOR – RICH TEXT WITH FTB ................................................................... 145
EXAMPLES ............................................................................................................... 147
Standard - Data Grid ........................................................................................................................ 147
The Process .................................................................................................................................. 147
Query ........................................................................................................................................ 148
Options ...................................................................................................................................... 148
Format ....................................................................................................................................... 149
List Item ................................................................................................................................ 150
Variables ................................................................................................................................... 151
Actions ...................................................................................................................................... 151
Message Action – DeleteEmployee........................................................................................ 151
Execute Action ...................................................................................................................... 152
Examples – Files and Images .......................................................................................................... 157
The Process .................................................................................................................................. 157
Default Properties ...................................................................................................................... 158
Query ........................................................................................................................................ 158
Format ....................................................................................................................................... 159
Format – Add Form (Header / Footer) .................................................................................... 159
Format – File Gallery (Detail) ................................................................................................. 160
Functionality .............................................................................................................................. 162
Query Variable - Description .................................................................................................. 162
Query Variable – Open File ................................................................................................... 163
Query Variable – Delete File .................................................................................................. 163
Actions ...................................................................................................................................... 164
Action – Condition: If.............................................................................................................. 164
Action – Execute ................................................................................................................... 165
Action – File .......................................................................................................................... 166
Action – File (Image Transformation) ..................................................................................... 167
Action – Execute ................................................................................................................... 168
Message – Open File............................................................................................................. 168
Action - Execute .................................................................................................................... 168
Action – File (Response)........................................................................................................ 169
Message – Delete File ........................................................................................................... 169
Action - Execute .................................................................................................................... 170
Examples – Web Service Integration .............................................................................................. 171
The Process .................................................................................................................................. 171
9
Version 1.9.7
Formatting ................................................................................................................................. 171
Actions ...................................................................................................................................... 172
Action - Message ................................................................................................................... 172
Action - Assignment ............................................................................................................... 172
Action - Input ......................................................................................................................... 173
Demonstration ........................................................................................................................... 176
EXAMPLES (EXTENDED) ........................................................................................ 177
LISTX SKIN OBJECTS ............................................................................................. 178
BUILDING LISTX PACKAGES (LP) ......................................................................... 179
BUILDING CUSTOM MODULES (PA) ...................................................................... 181
Build your Modules .......................................................................................................................... 181
Create your Custom Controls.......................................................................................................... 183
Build the PA (.dnn) file ..................................................................................................................... 185
REPOSITORY ........................................................................................................... 189
LOG ........................................................................................................................... 191
QUICK BUILDER ...................................................................................................... 192
APPENDIX I - MIME TYPES ..................................................................................... 195
APPENDIX II - CONNECTION STRINGS (OLE/ODBC.NET) ................................... 199
APPENDIX III - VERSION HISTORY ........................................................................ 201
QUICK REFERENCE ................................................................................................ 209
10
Version 1.9.7
Business Intelligence Force, Inc. (Bi4ce)
EULA - Software License Agreement
IMPORTANT! Do not install this SOFTWARE before you have read this license agreement. By proceeding to
install this SOFTWARE you are indicating your acceptance of all the terms and conditions stated in this
agreement.
This is a legal agreement between you (either as an individual or a single entity) and Business Intelligence Force,
Inc. (Bi4ce) for this software product which includes computer software and may include associated media, printed
materials, and "online" or electronic documentation (the "SOFTWARE"). By installing, copying or otherwise using
this SOFTWARE you are agreeing to be bound by the terms of this agreement. If you do not agree to the terms of
this Agreement, do not install or use the SOFTWARE and if it is a non-evaluation version, return it together with
physical materials and media to the place you obtained them for a full refund.
1 GRANT OF LICENSE. This agreement grants you the following rights.
(i) EVALUATION LICENSE
You may install and use an unlimited number of copies of the SOFTWARE on an unlimited number of instances;
however these website instances must not be available to the public and cannot be used for commercial purposes.
(ii) SINGLE INSTANCE LICENSE
You may install and use one copy of the SOFTWARE on a single website instance. The primary user of the
computer on which the SOFTWARE is installed may make a second copy for his or her exclusive use on a portable
computer.
(iii) MULTI INSTANCE LICENSE
You may use as many copies of the SOFTWARE as your multi instance license entitles you to, in the manner
specified above. You are also entitled to make a corresponding number of secondary copies for portable computer
use as specified above.
2. COPYRIGHT. The SOFTWARE is owned by Business Intelligence Force, Inc. (Bi4ce) and is protected by
copyright laws and international treaty provisions, as well as other intellectual property laws and treaties. The
SOFTWARE is licensed, not sold. You must therefore treat the SOFTWARE like any other copyrighted material.
3. TERM OF LICENSE. The license will continue until you physically destroy all copies of the SOFTWARE and
merged portions thereof, and return any original program media and documentation to Business Intelligence Force,
Inc. (Bi4ce).
4. OTHER RESTRICTIONS.
(i) TRANSFER
You may not rent or lease the SOFTWARE, but you may transfer the SOFTWARE and accompanying written
materials on a permanent basis provided you retain no copies and the recipient agrees to the terms of this
Agreement. If the SOFTWARE is an update, any transfer must include the update and all prior versions.
11
Version 1.9.7
(ii) REVERSE ENGINEERING
You may not reverse engineer, decompile, or disassemble the SOFTWARE.
(iii) SEPARATION OF COMPONENTS
The SOFTWARE is licensed as a single product. Its component parts may not be separated for use on more than
one instance, or accessed in any way other than through the provided user interface.
(iv) TERMINATION
Without prejudice to any other rights, Business Intelligence Force, Inc. (Bi4ce) may terminate this agreement if you
fail to comply with the terms and conditions of this agreement. In such event, you must destroy all copies of the
SOFTWARE and all of its component parts.
5. ENHANCEMENTS AND UPDATES. From time to time, at its sole discretion, Business Intelligence Force, Inc.
(Bi4ce) may provide enhancements, updates, or new versions of the SOFTWARE on its then standard terms and
conditions thereof. This Agreement shall apply to such enhancements.
6. DISTRIBUTION. Distribution by the user of any designers, components or other component parts (EXE's, DLL's,
OCX's, Stored Procedures), executables, source code, or on-line help files distributed by Business Intelligence
Force, Inc. (Bi4ce) as part of this product is prohibited.
You may not remove any proprietary notices, labels, trademarks from the SOFTWARE or associated
documentation.
You may not modify, de-compile, disassemble, reverse engineer or translate the software.
LIMITED WARRANTY
You assume all responsibility for the selection of the SOFTWARE as appropriate to achieve the results you intend
and for the installation of, use of, and results obtained from the SOFTWARE. Business Intelligence Force, Inc.
(Bi4ce) warrants that the media on which you obtained SOFTWARE shall be free of manufacturing defects for a
period of (60) sixty days from date of purchase. Except for the limited warranty set forth herein, the SOFTWARE is
provided "as is." to the maximum extent permitted by applicable law, Business Intelligence Force, Inc. (Bi4ce)
disclaims all warranties, either express or implied, including but not limited to implied warranties of merchantability,
fitness for a particular purpose, and no infringement with respect to the SOFTWARE and the accompanying
documentation. Without limiting the foregoing provisions, Business Intelligence Force, Inc. (Bi4ce) makes no
warranty that the SOFTWARE will be error-free or free from interruptions or other failures or that the SOFTWARE
will meet your requirements. Some states and jurisdictions do not allow limitations on implied warranties, so the
above limitation may not apply to you. The foregoing provisions shall be enforceable to the maximum extent
permitted by applicable law.
CUSTOMER REMEDIES. Business Intelligence Force, Inc. (Bi4ce) and its suppliers' entire liability and your
exclusive remedy shall be, at Business Intelligence Force, Inc. (Bi4ce) option, either (a) return of the price paid or (b)
repair or replacement of the SOFTWARE that does not meet Business Intelligence Force, Inc. (Bi4ce) Limited
Warranty and which is returned to Business Intelligence Force, Inc. (Bi4ce) with a copy of your receipt or proof of
purchase. This Limited Warranty is void if failure of the SOFTWARE has resulted from accident, abuse, or
misapplication. Any replacement SOFTWARE will be warranted for the remainder of the original warranty period or
thirty (30) days, whichever is longer.
12
Version 1.9.7
NO LIABILITY FOR CONSEQUENTIAL DAMAGES. In no event shall Business Intelligence Force, Inc. (Bi4ce) or
its suppliers be liable for any damages whatsoever (including, without limitation, damages for loss of business
profits, business interruption, loss of business information, or other pecuniary loss) arising out of use of or inability to
use this Business Intelligence Force, Inc. (Bi4ce) product, even if Business Intelligence Force, Inc. (Bi4ce) or its
dealer have been advised of the possibility of such damages. Some countries do not allow the exclusion or limitation
of certain implied warranties or the limitation of the foregoing warranty or the exclusion or limitation of incidental or
consequential damages, in which case and to the extent such exclusion or limitation is not allowed some of the
foregoing limitations and exclusions may not apply to you.
HIGH RISK ACTIVITIES. The SOFTWARE is not fault-tolerant and is not designed or intended for use in hazardous
environments requiring fail-safe performance, including without limitation, in the operation of nuclear facilities,
aircraft navigation or communication systems, air traffic control, weapons systems, direct life-support machines, or
any other application in which the failure of the SOFTWARE could lead directly to death, personal injury, or severe
physical or property damage (collectively, "High Risk Activities"). Business Intelligence Force, Inc. (Bi4ce) expressly
disclaims any express or implied warranty of fitness for High Risk Activities.
GENERAL PROVISION. You shall have no right to sub-license any of the rights of this agreement, for any reason.
In the event of the breach by you of this Agreement, you shall be liable for all damages to Business Intelligence
Force, Inc. (Bi4ce), and this Agreement shall be terminated. If any provision of this Agreement shall be deemed to
be invalid, illegal, or unenforceable, the validity, legality, and enforceability of the remaining portions of this
Agreement shall not be affected or impaired thereby. In the event of a legal proceeding arising out of this
Agreement, the prevailing party shall be awarded all legal costs incurred.
This Agreement constitutes the entire agreement between the parties for the supply of the SOFTWARE and its
associated documentation and supersedes all prior arrangements, agreements, representations, and undertakings.
This Agreement may not be changed or modified except by a written instrument duly executed by each of the parties
hereto.
MISCELLANEOUS. This Agreement shall be governed by and construed in accordance with the laws of the United
States and the state of Maryland, without reference to conflict of laws principles. If any provision of this Agreement is
held invalid, the remainder of this Agreement shall continue in full force and effect.
You shall be responsible for the payment of all taxes, duties, or levies that may now or hereafter be imposed by any
authority upon this Agreement for the supply, use, or maintenance of the SOFTWARE, and if any of the foregoing
taxes, duties, or levies are paid at any time by Business Intelligence Force, Inc. (Bi4ce), you shall reimburse
Business Intelligence Force, Inc. (Bi4ce) in full upon demand.
ACKNOWLEDGEMENTS. You acknowledge that you have read this Agreement, understand it, and agree to be
bound by its terms and conditions.
13
Version 1.9.7
14
Version 1.9.7
Control Panel
Our first step in the process of developing a ListX based solution, is a complete understanding over the different
aspects of the configuration administration. To enhance the user interface, and to make the system easier to
manage and utilize, a Control Panel interface has been provide which lets the user quickly move from one section of
the configuration to another.
Screenshot: The Control Panel interface as it appears within the standard ListX release version.
General
The General properties tab provides the ability for a developer to specify the general parameters of the
configuration. The settings include the number of records per page, basic control structure, including whether or not
to display the default alphabetic filter. Additional options for Ajax, Validation, Debug and Security are provided.
Search
ListX provides a simple handling method for a basic search control mechanism. When a simple search is
required, you may specify the Column to be searched and the display name to use for these search options.
This method provides a drop-down selection of the column to be searched and a text entry box for entering the
search value.
Variables
To make queries easier to develop and then used within the main rendering query, execute actions and
subqueries, the ability to create and control variables is provided. These variables act as a simple text replacement
values which when placed in a query will be replaced with the appropriate assigned value, and optionally, with a
SQL Injection security verification. For example, you may prefer to replace the value @frmName within your SQL
scripts with the value of the Form variable „frmName‟.
Query
To control the query used for rendering the HTML content of your ListX configuration, use the Query area of
the View Options. This section also provides the ability to specify an external, ODBC connection and the handling
methodology for Filters.
Actions
ListX provides a robust attribute driven script functionality referred to as „Actions‟. These scripts can have
any number of steps which include listening for module communication messages, handling conditional
15
Version 1.9.7
statements, executing sql statements, assigning variables, sending emails, sending and receiving files, importing
and exporting delimited data and more.
Format
ListX is formulated as a standard template based User Interface tool. This template is bound to the result of
the query specified, and can contain any number of headers and footers, as well as the detail, alternate detail, and
default responses when no results are returned, or when no query is provided. Finally, the option to completely hide
the module from the tab when the result is empty or not query is provided.
Locking
To provide a Source Control method with ListX, the ability to Lock and Unlock the configuration from other
DotNetNuke Users is provided through the Locking and Unlocking of the configuration. Clicking on the Unlocked link
will Lock the configuration from other user edits.
Unlocking
To provide a Source Control method with ListX, the ability to Lock and Unlock the configuration from other
DotNetNuke Users is provided through the Locking and Unlocking of the configuration. Clicking on the Unlocked link
will Lock the configuration from other user edits. Pressing the Locked link will affectively unlock the configuration.
XML Configuration
While ListX provides the ability to Import and Export content, as well as install from ListX Packages (LPs), it
also provides a very easy transport method which lets you read the existing configuration, or load another very
rapidly.
Saving Changes
To save your configuration at any time, press the Save Configuration link. If you would prefer to Save the
configuration, but continue within the View Options page, press Save & Continue. Finally, to leave the configuration
without saving the changes yet, press Cancel.
16
Version 1.9.7
Draft Mode
A completely new addition to the ListX concept, draft mode means that you are working on a draft copy of the
configuration at all times, never making changes directly against the runtime version- until you physically press
Save. In older versions of ListX, the draft was retained within the View State. This meant that it existed within the
browser and server. The new version provides a complete draft mode technology, meaning that your draft exists
within the database, and can continue to be edited indefinitely until you feel that it has been crafted properly.
It is important to note that the draft is stored by the ModuleID and UserID, so you cannot work on a configuration as
a user that is common between multiple users without having a conflict. Meaning, don‟t work with a team on the
same configurations while logging in under the host user account. Separating your User logic provides many
enhancements for change tracking, as well as the Locking and Unlocking and Drafting.
To working with your draft, you will notice three variations of the draft bar located at the bottom of the control panel
interface. The first, Current Draft: Loaded from Source, identifies that your version was created off the current
release version, and therefore, only contains your changes. The second, you configuration was changed AFTER the
latest
release version, which will specify the date of the load, and let you press the provided date link to reload the current
source version.
Finally, the Draft Warning – which appears in deep red, identifies that your draft is outdated, meaning it was created
prior to the current release version. In most cases, you will want to clear your current draft whenever the Draft
Warning appears.
17
Version 1.9.7
Runtime Issues Warning
Because the DotNetNuke platform continue to grow and change, and also because some Third Party installed
application may cause adverse affects within other modules, it is important for each module to police their own
structures to verify that everything will continue to work as advertise, and to let the user know if there is a conflict.
This issue presented itself within older versions of DNN as well as the DNN 4.4.x release platform due to overly
aggressive HTTP Compression handlers. The problem occurs when these compression libraries attempt to
compress the White Space occurring within Text Areas. The issue identifies itself by the loss of Carriage Returns,
Spaces, tabs and other text considered as White Space. While this IS something which should be filtered to improve
performance of the site – this should never be stripped out of Text Areas, because in general this text should be
considered AS IS.
The warnings presented within the Runtime Issues Warning region identify the behavior problem, and possible
general recommendations.
For example, to correct this issue within the DNN 4.4.0 releases. Open the Compression.Config file, in the root of
your website. Then, strip the value contained within the White Space filter.
Change From<whitespace>
<![CDATA[(?<=[^])\t{2,}|(?<=[>])\s{2,}(?=[<])|(?<=[>])\s{2,11}(?=[<])|(?=[\n])\s{2,}]]>
</whitespace>
To –
<whitespace>
</whitespace>
18
Version 1.9.7
Default Properties
While the formatted properties of the ListX control allow a user to display most content, in any way possible - there
are a several restraints we like to apply for extending some of the usability of the interactive content. The majority of
the basic options are provided within the Default Properties region of the Administrative View Options. Aside from
the sorting options, which can be displayed in any manner desired, the page selection, number of records per page,
searching and alphabetic filtering are provided in a static layout at the top and bottom of the report whenever those
options are enabled.
Paging Properties
Tip: While the options provided here are a bit restrictive in their display, it is key to use your own special technique
whenever possible. If you don't like the page selection method, the search option method or the quick filtering - you
can always use session variables within your queries to format the output however you desire. You can even use
multiple ListX modules in combination to produce report and page selection manually. The possibilities are endless.
Records Per Page
To control the default number of records to appear on each page of the ListX output, an integer value can be placed
in the Records Per Page form field. A non-numeric entry, or an entry which is less than or equal to zero will result in
all records returned.
Show Records Per Page
This allows the designer to specify whether or not to allow the consumers of the ListX to display a physical drop
down list selection of the number of records to show per page. The standard list of items is identified within the Ascx,
and can manually be modified if necessary. The default Records Per Page value will be automatically added to the
standard records per page list. Checking this option will force the drop-down and related functionality to become
visible.
Show Page Selection
When not operating in AJAX mode, the paging functionality can be hidden from view by leaving this box unchecked.
If you would like the same capacity in AJAX mode, you will need to check the box labeled “Ajax Interaction –
Custom Paging”.
Use Custom Paging
Many table scenarios may be crossed in which the classing SQL paging mode, employed by default by ListX, needs
to be manually controlled. Manual Control means that as the developer, you will handle the physical selection of the
data for a specific page of records. This type of capability supports a much improved capability, but requires the
knowhow and understanding of the database systems. For a complete breakdown of the Custom Paging and
samples of its use, check the chapter on Custom Paging
19
Version 1.9.7
Filters and Sorting
Show Alphabetic Filter
Similar to the familiar alphabetic filter selections in many available products, we have provided a preformatted
Alphabet for filtering your queries. Checking the Show Alphabetic filter will force the letters to render, and can be
utilized within your query by specifying a valid SQL statement within the Filter Query.
Allow Multi-column Sorting
ListX supports multiple columns to be sorted simultaneously, meaning that your first column may be sorted
ascending, while the last two are sorting descending. Leaving this value unchecked forces the list for allow only one
column to sort at a time.
20
Version 1.9.7
AJAX Integration
Enabling AJAX Interaction
The concept of requesting only a portion of data from the website server instead of requesting an entire
page is not new, but it has become extremely popular lately. The best of breed technology on which this
is based, called AJAX, refers to the blending of Javascript and the XML Http Request objects provided
by the browser. Javascript creates and maintains the interaction with the server and the client so that
the results can be integrated directly into the existing page. This greatly improves performance,
especially with web applications like DotNetNuke because much of the overhead of building the page is not
necessary. ListX provides a separated Rendering engine, which can be paged easily and automatically handled
through AJAX. It is important to note, up through version 1.5.2, AJAX only supports session variables for utilization.
Form, QueryString, and ViewState variables are not passed back using AJAX.
When NOT to use AJAX
AJAX functionality works great in almost any scenario, barring a few identified structural requirements. Because the
functionality issues a request on a separated XML Http object, the document received via the request, and the
document displayed in the browser are two separated entities, which have no direct correlation. This definition
identifies that while you can easily pull content from one document and push it into another, which is essentially
what AJAX is doing, you cannot parse certain document based objects, nor can you transmit objects which require
custom transmission facilities.
What does this mean in English? While AJAX functionality can support nearly any content, it cannot support, or has
limited support for specific tags which require extra, or integrated handling with the client browser object. The
following tags are either ignored, or have limited functionality within AJAX requests, and should most often be
avoided within AJAX enabled content:
<LINK> - the standard embedded LINK functionality, which will import the content of one url into the current system.
This link tag, not to be confused with the A or Anchor tag, is normally found in the HEAD section of an HTML page,
and is generally used for importing CSS Style sheets. This tag is unsupported in both IE and Firefox via AJAX
requests.
<INPUT type=FILE> – when you are need to transfer a file via the Input type=file HTML Element, the file body must
be transferred via a Form Post, with Multi-part support. The AJAX library cannot support the multi-part approach,
and therefore, Files should not be transmitted via the AJAX postback. This tag is unsupported in both IE and Firefox
via AJAX requests.
<STYLE> – inline style tags (style defined within a Tag Attribute like style=”color: #dddddd;” work perfectly within
AJAX. However, you CANNOT use the <STYLE></STYLE> tag structure for defining new classes, or redefining
classes within AJAX driven content. There are reports, however, that Firefox may support this directly, and IE may
support the <STYLE> tag if a Form element is present within the AJAX content.
21
Version 1.9.7
<SCRIPT> - As of version 1.9.5 of ListX, SCRIPT tags and SCRIPT SRC= tags are now supported. In this past this
was not the case, however, advancements in the ListX rendering engine and client-side runtime have provided this
ability.
AJAX Interaction – Manual Load
The ability to force your module to load ONLY when another module specifically calls the AJAX functionality to load
its source (lxFetch) is provided through this open. This is particularly useful when you have multiple entities which
are displayed via a Toolbar. Clicking the Toolbar should both Display your ListxX module and execute the lxFetch
function against this module.
AJAX Interaction – Custom Paging
If you are using the Ajax Interaction provided within ListX, the default placement of the Page Links is provided below
the rendering area of the page, and below the standard Status region. If you prefer to locate the paging elsewhere
within the page, or within the specified ListX Item Formatting, the capability is handled quickly and easily through
this setting. Check the box, and ListX will no longer automatically render the Paging functionality. Instead, it leaves
the location and style up to you. To place the Ajax Paging elsewhere on the module, place a DIV tag defined similar
to the minimum syntax provided here:
<div id=lxP[*ModuleID]></div>
AJAX Interaction – Custom Status
If you are using the Ajax Interaction provided within ListX, but do not like the location or look and feel of the status
messages, you can control the style and position of the status element by checking this box, and adding the DIV tag
elsewhere within your module format logic. To place the Ajax Status elsewhere on the module, place a DIV tag
defined similar to the minimum syntax provided here:
<div id=lxS[*ModuleID]></div>
22
Version 1.9.7
Javascript
Javascript - Include Utilities Library
ListX supports and provides a set of Utilities for using and maintaining you solutions. The Utilities library adds the
ability to handled Expand and Collapse and Toggle functionality as well as a variety of other functions.
See Client Scripts
Javascript - Include Validation Library
The default Validation libraries which are shipped with the .Net framework are not very versatile, and don‟t support
todays browsers properly. Use the Validation library to provide inline validation for your entities.
See Client Scripts
23
Version 1.9.7
Site Integration
Module Communication - Message Type
For better coverage, and integration, ListX provides the ability to broadcast messages for listeners to receive,
identifying the current action taken by the ListX Module. These messages consist of either Filter, PageSize, or the
Current Page command.
Javascript Function – On Load Complete
When in AJAX mode, or when the page itself loads it is important to know when the results have been posted to the
page. Execution of a javascript function at this conclusion will aid in your goals. Place the Name of the function in
the provided textbox. Upon load completion when defined, the provided javascript function nme will be executed..
24
Version 1.9.7
Debugging
Display Query Debugging Information
When difficulties arise in the development, or error trapping of a specific module configuration it is always important
to view the information that the module is interpreting. By checking this option, the resulting output will include six
additional reporting divisions.
Actions – provides a complete readout of all the actions that were executed, including the diagnostic and
debug results for each action.
AJAX Actions – provides the same list as the Actions, except it identifies which actions were executed
during the AJAX request.
Original - provides the original syntax of the query before any translation occurs. This helps you diagnose
if the original statement was formulate correctly.
Actual - displays the post transformation of the query, the physical query text that will be executed against
the connection to your database server. Any errors within this query will result in an empty result set, so it
can easily be executed within other environments to determine the errors reported.
Exceptions - displays any fatal errors experienced by the runtime debugger which causes the executing
query to fail. If AJAX is enabled this feature is not visible. To debug your statements, you may need to
temporarily disable the AJAX paging features.
Runtime - the statistics of the tables returned, the number of records, the number of columns as well as the
breakdown of the columns by name and type are provided. Additionally, the current Filter, Alphabetic Filter
value, Sorting syntax Current Page, Page Size and Total records are also reported. If AJAX is enabled this
feature is not visible. To debug your statements, you may need to temporarily disable the AJAX paging
features.
Because the information returned from the debugger could pose a security risk as it may contain information or
directives about your solution that could expose your handling and management of the data, ListX provides the
ability to Hide and Show the debugging only to specific groups of users.
25
Version 1.9.7
Dislay for All Users
The debugging information will be globally displayed to all users who are interacting with the module. This is
generally only helpful if you need to diagnose a problem for Unauthenticated of Registered Users that you do not
witness as an Administrator.
Display for Edit Users
All users which are granted Edit access to the Module via the Module Settings are granted the display of the
Debugging.
Display for Admin Users
Only Administrative users (users marked as Portal Administrators) have access to the display of the debugging
information.
Display for Super Users
This is the recommended setting for the debugging when working and designing your configurations. Once
complete, the setting should be turned off and debugging left disabled unless a problem occurs.
Trace (Log) all Interaction
Checking this option will place the familiar Debug information directly into the ListX Log. This should be used
sparingly as it will generate a large amount of information in the log very quickly.
Trace (Log) when Query Fails
Checking this option will place the Query Failure information directly into the ListX Log. It is common place to turn
this on in production mode, and leave this on to track any ill performing modules or special cases.
Skip Redirect Actions
Because at times it becomes difficult to debug the Actions that are executed within an action loop, when a redirect
action is involved – this setting allows you to ignore the Redirect actions and remain on the same page after the
actions conclude. This way, you can disable your redirects while debugging and re-enable them once the problem is
rectified.
Skip Subquery Debugging
When you have debugging enabled and Subquery Debugging is not disabled, you will see a set of debugging panels
for each execution of a subquery in that configuration. At times this becomes a nuisance and can be disabled by
checking this option.
26
Version 1.9.7
Administration
You can lock down the configuration for each ListX module separately from external user modifications based on the
specific groups of users who should have the ability to edit the module. This can be done by selecting one of the
three options provided.
Edit Users – Grants the ability for All users granted Edit permission to the module access rights to the
configuration and View Options. This includes Administrator and Super Users.
Admin Users –Grants the ability for All Administrators to modify and interact with the development of the
configuration and View Options. This includes Super Users
Super Users – Grants the ability for ONLY Super Users to have modification and configuration rights to the
module.
If you are in need of a maximum security solution which will block all users the ability to edit all configurations unless
they are Super Users on a global (DNN Instance) scale, this can be done by adding the following line to the
AppSettings region of your Web.Config file.
<add key="ListX.Maximum.Security" value="True" />
27
Version 1.9.7
Version Compatibility
In order to maintain the backwards compatibility of the ListX modules between older version which handle some
parsing and capabilities slightly differently, optional enhancements have been designated which *may or may not*
cause backwards compatibility issues. In most cases, the standard user base has not achieved a level of complexity
in which any of the options should be disabled, but at times, you may experience problems when these options are
enabled.
Use Explicit System Variables – Using explicit system variables means, that when using a tag like
[UserID] instead of the system designated value of [*UserID] or [UserID,System] the column value of the
UserID will be returned. If the UserID is not available within the query, no result will be displayed. This
means that any system variable will require the “,System” or * formatting. This is not a compatibility
concern, but can cause problems if you did not create your configurations with this enabled, and then,
chose to enable it.
Enable Compound IIF Statements – Version 1.9 provided the ability to use compound mathematical and
logic statements within the standard IIF tag. When enabled, the standard parsing logic is no longer used,
and the new enhanced logic is provided. Certain configurations, specifically those with date formatted
values may have issues with the new structure, because \ and / are division symbols. Support for this will
be added in 2.0, and will no longer be a concern.
Use Advanced Parsing Techniques – Version 1.8 provided a new parsing technique, which is
automatically used in every new configuration created after 1.8, and is hidden from view. When the version
is less than 1.8, the checkbox is visible, and can safely be checked unless “Escaping” was required within
the Queries contained in the configuration. Older versions had a flaw which required excessive escaping of
symbols, regardless of depth.
Force Query Command Separation on GO – not all DBMS applications support the GO command, or do
not support the return of more than one table within each script execution. For example, if you desire
custom paging in ListX, and use ORACLE as your Database System, you could not return two tables due
to a limitation within ORACLE. To support this, enabling the forced separation provides this ability. For
example in ORACLE:
SELECT ordered.*
FROM (
SELECT
FROM (
ROWNUM as RowPosition,original.*
SELECT *
FROM MY_SOURCE_TABLE
ORDER BY [SORTTAG]
) original
) ordered
WHERE
RowPosition BETWEEN
(([PAGENUMBER]-1) * [PAGESIZE]) + 1
and
( [PAGENUMBER]
* [PAGESIZE])
GO
SELECT count(*)
28
Version 1.9.7
Other Properties
Enable Excel Export
It is very common to need to export the contents of a datagrid or table directly to a popular, non web based
application. We have answered the call here by providing a quick and simple mechanism for exporting the
rendered data directly into an excel spreadsheet. Just check this box, and follow the link provided on the bottom
right of the module.
Master Template
For times when importing and exporting isn't quite enough, the Master Template option identifies to all ListX
instances created as copies of the current instance that the configuration from the current instance is to act as
the template. If you make a change to the Master, all instances within the same DNN install will
automatically utilize the new changes. Just check the box and use the Import/Export Content or portal template.
29
Version 1.9.7
30
Version 1.9.7
Search Options
To enable the developer to enhance the usability of the data the ListX is reporting, we have provided a searching
mechanism for easily adapting a specific search filter into the query. Any number of search options can be supplied.
The resulting display will provide a drop-down box for selecting the preferred search option, and entering some text
to be searched. To add an option, click on the Add Search Option link. Enter the display value for the Search
Option, and the Name of the Field utilized within the Filter.
Search Option Actions - The display below provides full control for developing your search options. Use
the following actions to build your search drop down to your own specifications.
Edit - Click the edit link to change the values for this search option.
Up - Moves the selected search option upwards in the drop-down list selection.
Down - Moves the selected search option downwards in the drop-down list selection.
Delete - Removes the entry from the search option list.
iSearchable Integration
Supporting search capabilities which integrate within the DNN standard search capacity, while providing the
flexibility to control how the integration occurs, and more importantly, where the search link results drive your users
is a fantastic, and simple feature of ListX. You will want to review the documentation and examples on fulfilling your
search needs, but to get started, take the following steps.
1.
2.
3.
4.
5.
6.
7.
First, assume you will want your users to view a detail form of the record they are driven towards. This
means if you create both a list and detail view of your data, the module implementing the iSearchable
functionality should be your detail.
Your search results will be directed from the default search page to the current tab with a specific set of
querystring variables you identify in the options below, so craft your detail form to accept incoming
querystring variables to identify the appropriate target record.
Specify the Query which will be used to identify ALL records which will be submitted to the integrated
search engine.
Next, fill in the format of the Title (just as you would any other template), this title will appear as the title of
each search result.
If provided, set the Author value to the UserID of the creator of your record.
Set the Published Date to the value identifying the date each record was created.
Use Link Parameters to set the querystring which will be added to your result record when the user clicks
on the result.
31
Version 1.9.7
8.
Set the Search Key to the unique value of your record, meaning the value of the key or keys which make
up the primary key of the result.
9. Use the Description to provide more information in the search result. The Description appears below the
title of each result item.
10. Finally, set the Content of the records, this content will be indexed and used for the search lookup, along
with the Title and Description.
Once completed, verify that your search is working. To do this, navigate to the Host Search Admin interface and
press the Re-Index Content option. This will force your content to re-index and automatically include your new
content into the searched content. Check your search and verify that your records and directions have been
followed.
32
Version 1.9.7
Query Options
ListX can bind to any available data, as long as it can execute the statement against your source server. Since the
source server is anticipated as SQL Server, ListX is capable of doing more than a simple selection - in fact, you can
have entire conditional statements as well as stored procedures, functions and other extended T-SQL features. The
statement can utilize any number of Session, Query String, Form and ViewState variables, and also a few added
system variables for convenience.
It has been asked - 'Why use shared variables?'. The answer is quite simple actually: you want to make the system
completely interactive, so you can specify one ListX to populate a variable, and many other modules (ListX or other)
to utilize the variable.
Screenshot: The Query Options layout as it appears within the View Options menu item in ListX
Quote Escaping
Besides the standard usage of replacing single quotes with two single quotes for escaping and securing against
SQL Injection, it is necessary at times to replace the formatted single quote results with additional replaced quotes.
This occurs when you are using a variable to store a list of selected items, an array list containing single entities.
Since ListX automatically renders the output string to a comma delimited value, single quotes will be used to pad the
left and right of non-numeric array members. There are times where you may need to use this list in a query and
need to provide escaping of these single quotes.
Escaping is easily provided by calling the escape function within the Target setting of the Query Option - like so:
escape([VARIABLENAME])
NOTE: See the entire section on Escaping to discover when and where escaping is truly required for all ListX
variables.
Runtime Variables
The physical handling of the Query execution begins with translating the Query Variables within the SQL Query
Statement. Once completed, the next step is to identify and transform any of the runtime variables which occur
33
Version 1.9.7
within the Statement. These variables provide the true meat of the interaction, handling the filtering and sorting of
the control.
Provided below, the breakdown and usage of the Runtime variables:
[FILTERTAG] - renders a fully qualified filter fragment for your query, this item is necessary for any of the
custom filtering options. The FilterTag should always follow or be contained within a WHERE clause.
[FILTER] - renders the specific letter selected in the alphabetic filter selection.
[SORTTAG] - renders the complete sorting statement fragment. This statement provides a list, comma
delimited, of the columns sort enabled within you list. The order of each of these columns is handled via the
interaction, and can be forced to allow multi-column sorting, or single column.
The default operation of SORTTAG is to automatically return 1, representing the ordinal position of the first
column in your result when no sort is yet assigned. There are problems with this syntax during specific
situations. For example, when using Custom Paging for SQL 2005 you cannot use an ordinal here because
column positions are not allowed in Windowed Functions. Essentially, because no columns have yet been
returned, SQL is unable to sort on that column. To work around this problem, and also to control the default
sorting SORTTAG has an additional functional consideration.
[SORTTAG,optional default sort] – when this is used, you may specify the default column name to use for
the sort. For instance – [SORTTAG,TabID]. If no sort has yet been defined, TabID will be the default value.
Refer to the Custom Paging examples for this scenario.
The following example, used later to demonstrate interaction with the DotNetNuke EventLog utilizes both of the
Runtime Variables:
SELECT l.LogGUID, l.LogTypeKey, l.LogConfigID, l.LogUserID,
isnull(l.LogUserName,'System') LogUserName, l.LogPortalID,
isnull(l.LogPortalName,'_default') LogPortalName,l.LogCreateDate,l.LogServerName,
elt.LogTypeFriendlyName, elt.LogTypeCSSClass from EventLog l join EventLogTypes elt
on elt.LogTypeKey = l.LogTypeKey WHERE [FILTERTAG] ORDER BY [SORTTAG]
34
Version 1.9.7
Custom Connections
There are many reasons for employing ListX for your solution, but one of the best reasons is for developing modules
which integrate with your backend or side-by-side systems which are either not web enabled, or reside in different
web applications. This situation in most cases drives to a requirement of connecting to these systems, either remote
or local, and either within SQL Server or other ODBC/OLEDB enables Database Systems. ListX supports this
behaviour, and can be configured to use a separate connection for just its rendering queries, or for any subquery or
action individually.
The power of Custom Connections is seen time after time, because you can integrate you disparate systems into on
DNN interface, without affecting those systems.
To use Custom Connections, simply provide a properly formatted connection string with the specifications suited to
your system. Review the Appendix in the back of this manual for a set of Connection String definitions which may
meet your needs.
ListX also employs the CommandTimeout property within Connection Strings, regardless of your particular system. If
you are executing long running connections – those which will take longer than the default (90 seconds), you may
need to specify the CommandTimeout property within your Connection String. For example:
Provider=OraOLEDB.Oracle;Data Source=lmydata.mydata.com;User
Id=frontend;Password=superpass;CommandTimeout=9000;
It is important to note, when using Connection Strings, it is often useful to store the Connection String in your
web.config file under App Settings. For instance, the above connection – if it was provided within the App Settings of
the Web Config, under OracleConnection:
Web.Config
<appSettings>
<add key="OracleConnection" value=" Provider=OraOLEDB.Oracle;Data Source=lmydata.mydata.com;User
Id=frontend;Password=superpass;CommandTimeout=9000;
" />
35
Version 1.9.7
Custom Connection (in the ListX Configuration)
[OracleConnection,Configuration]
It is also important to note that the timeout experienced by your system could also be limited by a specification in
your website administrative settings. To change the ASP timeout, which controls how long a request operation can
run before IIS terminates the connection – you must change the ASP Script timeout value. To do this – in IIS – right
click your Site. Then – under the Home Directory Tab – click the Configuration button. From there fill in the following
value with your personal preference.
36
Version 1.9.7
Custom Paging
ListX supports the concept of Custom Paging, which means that the developer will take control of how the paging is
handled from the system, rather than letting the default paging handler take place. The benefit of this – on very large
sets of data, or complex long running queries, providing information to the SQL script to only select the information
you require out of the database is important. For instance, if you only want the records which occur in order from row
75 to 100, because you are paging 25 records per page and are on page 4 of 10,000 – only requesting page 4 from
the database would be useful.
In order to implement your own custom paging your must adhere to the following specifications:
1.
2.
The query must utilize the current page number, as well as the page size variables.
o [PAGENUMBER] - Is replaced with the current page number
o [PAGESIZE] - Is replaced with the current page size
Finally, instruct the ListX about the physical size of the query itself. This is done by reporting the total
number of records returned by the query within a secondary table. The first selection returned to the ListX
control will be your display data, the first column of the first row of the second table returned will be
identified as the total number of records.
Provided here are two simple examples, one for Oracle, the other for SQL Server 2005. In both scenarios, the
request returns two tables. First – the results for the current page, and second – the total number of records with the
same applied filter. You can easily perform the same requests on your own.
Oracle with Custom Paging
As discussed in a previous chapter regarding the GO statement. The Oracle OLEDB connection handler doesn‟t
support the use of the common GO statement, used to separate the physical queries from one another. Additionally,
Oracle doesn‟t support the ability to return more than one table result from your query. To correct this, ListX has
been improved to handle both the syntax check for GO as well as custom handling of the multiple table result return.
Note that in the scenario for Oracle as well as SQL 2005, the query is fundamentally the same. Essentially, you
populate the PAGENUMBER, PAGESIZE and other tags like SORTTAG directly into your query, allowing ListX to
handle the rest.
SELECT ordered.*
FROM (
SELECT
FROM (
ROWNUM as RowPosition,original.*
SELECT *
ORDER BY [SORTTAG,SourceRowID]
) original
) ordered
WHERE
RowPosition BETWEEN
and
( [PAGENUMBER]
* [PAGESIZE])
GO
SELECT count(*)
37
Version 1.9.7
SQL 2005 with Custom Paging
The previous solution for Oracle is very similar to that of SQL 2005. With 2005 comes the ability to execute
“Windowed Functions”. These functions structures provide the means to perform paged queries. Compare the
following SQL syntax to that of Oracle to see the similarities.
WITH ordered AS
(
SELECT *,
ROW_NUMBER()
OVER (order by [SORTTAG,UserID] ) as RowNumber
FROM users
)
SELECT
*
FROM
ordered
WHERE
RowNumber BETWEEN
and
( [PAGENUMBER]
* [PAGESIZE])
Select count(*) as TotalCount from users
38
Version 1.9.7
Variables
Adding new Query Variables to the SQL is very simple. First, click the Add Query Variable link button.
Query Variable Actions - The display below provides full control for developing your query variables. Use the
following actions to build your query to your own specifications.
Edit - Click the edit link to change the values for this query variable.
Delete - Removes the entry from the query variable list.
The resulting display provides the ability to specify the variable type from the following list:
<Session> - Identifies a custom session variable value.
<Query String> - Identifies a querystring variable value.
<Form> - Identifies a form variable value.
<ViewState> - Identifies a viewstate variable value.
<Message> - Identifies a Message variable value.
<Custom> - Identifies that custom, ListX based tag structure fulfills the Source value. Place your complex ListX
string in the Source area, in place of a variable name.
<Action> - Identifies an action variable value.
ModuleId - Returns the Id of the ListX Module as it exists within the DotNetNuke Portal environment.
Owner - Return the database owner defined in the web.config, followed by a decimal point.
PageNumber - Gets the number of the current data result page.
PageSize - Gets the total number of records to display per page.
PortalAlias - Returns the full domain link to the current portal.
PortalId - Gets the Id of the current Portal.
39
Version 1.9.7
Qualifier - Returns the database qualifier defined in the web.config, followed by an underscore.
UserId - Fetches the Id of the currently logged in user.
Once the type has been selected, a Source and Target are necessary, and optionally, additional format handling is
provided for padding the resulting data, when it is not empty, or provisioning a specific Empty syntax when the result
is empty.
Source is necessary when any <Type> is the selected type. Source is used to identify the name of the variable
to return from the type entries.
Target is the string representation to locate within the Query and replace with the Source value.
Target Left is placed to the left of the resulting target replacement, whenever the target result is not an empty
string. (Read the following example accompanying the screen shot for a better understanding).
Target Right is placed to the right of the resulting target replacement, whenever the target result is not an
empty string. (Read the following example accompanying the screen shot for a better understanding).
Target Empty is used automatically whenever the resulting target value is empty. The Target Left, Target
Right and Target Empty parameters are particularly useful when you need to handle NULL values within your
database.
Example
As seen in the previous screen shot we are expecting an incoming Form variable, which is named txtDescription.
Assuming that we will be using this variable within an Update statement, and that when txtDescription is left within
no value we want to store NULL within the target database. The query would need to look something like this:
UPDATE myTable Set Description = @txtDescription
IF txtDescription has the value of “ListX Description Example” the resulting statement would be:
UPDATE myTable Set Description = „ListX Description Example‟
Otherwise, if the txtDescription has the value of “” (an empty string), the resulting statement would be:
UPDATE myTable Set Description = NULL
40
Version 1.9.7
Security
There are three possible types of user interaction which could cause “Injection” security issues with the ListX engine:
SQL, HTML and LISTX
Protect Against SQL Injection
Remember that variables passed from a browser to the web server and then to the database server have the
potential of being tampered with, allowing the client user to gain access to some vital database information through
a concept known as SQL Injection. To protect against this behavior, you should leave the Protect Against SQL
Injection option checked. When checked, all values are automatically replaced with escape characters whenever
quotes are contained within the string. This breaks the possibility for SQL Injection Attacks to transpire.
For instance, if the Type is <Session>, with a Source of 'MySource', and a Target of '[PlaceMySourceHere]', each
occurrence of [PlaceMySourceHere] within the Query will be automatically swapped with the Session variable
contained within Session.Item('MySource').
Protect Against HTML Injection
Another common type of injection is typically seen in input forms, which allows an end user to type HTML content,
like INPUT tags and SCRIPT statements directly into the content, and have those render as HTML whenever the
content is regurgitated into the browser. For instance, a user may type <SCRIPT language=javascript>alert(„Hacked
by Kevin!‟);</SCRIPT> directly into a forum post, and this would be stored and returned when viewed as it is written
here, executing on the incoming browser request. The HTML Injection replacement will automatically replace all
brackets and standard HTML syntax with the escaped (HTML Encoded) version of the text. If you ever need to get
the actual value back, you can safely use [$Value,{HTMLDECODE}].
Protect Against ListX Injection
Since ListX is a powerful runtime script language, you may have users who type syntax, like a SUBQUERY tag
directly into a form entry field. It is important to handle these values as hostile, so that you don‟t have problems with
your data. There are three types of escaping of ListX content, which use the familiar backslash character.
Do Not Escape LISTX Tags – means we will leave them intact.
Escape LISTX Tags Once – the default option, escapes ListX tags with one backslash, so that the incoming content
is simply stored in the database as it was entered. If you escape only once, the review of the data, as in [VALUE] will
result in the execution of the physical tag stored within the content.
Escape LISTX Tags Twice – the most secure option, escapes all tags twice, meaning that they are not executed
when stored in the database, and whenever they are pulled out of the database they appear exactly as they were
typed.
41
Version 1.9.7
42
Version 1.9.7
Message Actions
To provide a simplistic approach to event management and processing, ListX provides built-in capability to listen for
and react to any set of defined module communication messages. With the added feature of Conditional statements,
Message Actions provide the ability to control most any operation. Through this feature, any type of interaction can
be performed easily, and implemented through the use of a few simple actions: Conditionals, Input and Output,
Variable Assignments, Queries and Redirections.
Screenshot: The Message Actions layout as it appears within the View Options menu item in ListX, with the
Message Action entry form expanded.
Managing Actions
Building the set of Messages and Actions is managed using the Message Actions table. Any number of Messages
and associated actions can be supplied. The resulting message handling will occur in the order that the actions are
provided. Administration is simple, identified through the tasks provided by the table below:
Delete - Removes the specified Action or Message
Edit - Click the edit link to change the values for this Message or Action
Add – Click the Add link to add a new item directly below the current line.
Copy – Click the Copy link to duplicate the current item, and Add the new copy directly below.
43
Version 1.9.7
Up - Moves the selected item upwards in the process order.
Down - Moves the selected item downwards in the process order.
Move – Allows you to move a specific item to another location.
Left - Moves the selected item back one level.
Right - Moves the selected item in one level to become a child of the above item.
To add a Message or Action, click on the Add Message Action link.
The Message / Action column provides a quick overview of the defined parameters for the Message or Action.
Actions are always processed when the parent Message event occurs. Meaning - All Actions appearing beneath the
Message will be processed in the order which they are defined. If another Message is defined, the actions complete
processing at the last action defined for the previous Message definition. Actions occurring before the first Message
listener definition will be processed at the time this module is loaded.
Moving Actions
The capability to move elements within the action list up and down within the hierarchy is made extremely easy.
First, Pressing the Up and Down arrows move the selected item UP one or DOWN one within the list. You can make
items act as child steps of an evaluation step within the action list (Like Conditions and Message Listeners) by
pressing Left and Right to change the indent factor of the step. If an item is indented beyond one level of its parent
(meaning you pressed RIGHT one too many times) the step will be ignored. This is a quick and easy way for you to
control which steps will be executed when you are in debugging mode.
When you want to move an Action UP or DOWN within your list and it will be more than one step up or down, a
Move Toggle button provides this ability. To move the entry:
1.
Press the Move Toggle Button
on the row you would like to move. This will highlight the row in pink,
identifying that this is the row to be moved. In the following screen, the row at line 179 has been pressed.
44
2.
Version 1.9.7
Next, click the Move Toggle Button
on the row that will be the target Index of the highlighted row. If the
goal was to move line 179 to line 2, pressing the move toggle button on line 2 will move the currently
selected row into that position, in turn moving the row that resided at line 2 to line 3.
Editing Message Actions
Adding new Message listeners and Actions is very simple. First, click the Add Message Action link button. The
resulting display provides the ability to specify the type of the item from the following list:
Message - Identifies the receiver of the specific message, and all actions below the message will process
when the event is fired.
Action: Execute - Executes a specific Query, utilizing all the defined Query Options and storing the results
for use by other Actions.
Action: Assignment - Provides the ability to assign a variable, either Session or ViewState, a specific
value.
Action: Mail - Automatically Sends an Email, based on the dynamic parameters.
Action: Output - Use for rendering the grid somewhere other than the page.
Action: Input - Utilize the ListX runtime to interact directly with other web sources for input.
Action: File – ListX supports file transfer, file and path modifications, Image manipulation, uploading,
downloading and CSV to SQL or SQL to SQL or SQL to CSV transportation.
Action: Redirection - Performs a redirection to a Link or Page/Tab.
Condition: If - Evaluates an expression and if it is TRUE, then process the actions below.
Condition: ElseIf - This condition will only be evaluated if all preceding conditions evaluated to FALSE.
Condition: Else - All of the following actions will be processed only if all preceding conditions evaluated to
FALSE.
When working with your actions, you may find that certain items, like the Execute and Assignment actions will
commonly take up far greater space during the edit process and display of your Action list. To compact down the list
of actions, limiting the visual description to a shorter summary is made easy by checking the Compact View
checkbox.
45
Version 1.9.7
46
Version 1.9.7
Message Action Types
Message
Since DotNetNuke provides the capability to communicate messages back and forth between module instances,
ListX provides the ability to listen for these messages and react to them through a defined set of actions. To begin
listening for a message, provide the Type of the message to listen for, and optionally the specific Value of the
message. If you are using Toolbar and ListX together, this concept is truly simple and provides immediate usability
of your interface.
Type - The Type of the message to listen for. Required to limit the messages to which this control will
respond.
Value - The Value of the message. If not provided, the Event will process when ANY message of the
defined type is received.
Two possible examples are provided by this scenario:
a. Standard Toolbar types of events, where the Type and Value are both provided. This is common when dealing
with interfaces with events that require no true parameter other than the name of the command. For instance, you
may have a list of commands like “Save”, “Cancel”, “Clear” on an edit screen. Each of these would be configured
under the same Type, something like:
Type: myToolbar1
Type: myToolbar1
Type: myToolbar1
Value: Save
Value: Cancel
Value: Clear
In this scenario, pressing he Save button would alert the message that myToolbar1 raised a message with a value
of “Save”.
b. Record events, where the Type is a specific event type, and the Value is an identifier of the record for which you
want to handle the action. For example, you may have a list of records, and on each one, you may have defined an
Action tag which raises a Message to the ListX module. This message may be something like:
Type: Delete
Value: [ProductID]
In this scenario, you would specify the Type of the message as “Delete” and leave the Value blank, so all messages
with the type “Delete” would trigger the event. Within your action script, the very next step may be to perform a
query. In that case you would fetch the actual value like this:
Delete from Products where ProductID = „[Delete,Message]'
47
Version 1.9.7
Action: Execute
Within your script logic, you may need to execute a query against the connection configured for ListX. With the
Action: Execute action you may specify the Query to execute, and provide a name for the query to process a return
result. Additionally, if you check the box labeled “Run as Process (Name)”, you can spin this query off into its own
processing thread. With that setting, all child actions will also execute in the separate thread, allowing you to truly
create self reliant applications which do not live with the timeouts that typically occur with other systems.
For
example, you may want to provide an Editor interface of ListX and a Button which when clicked will Save the record.
The interface may define a few form fields, frm1 through frm3 which have been defined within the Query Options.
Your query may read: Update MyTable Set Value1 = '[frm1]', Value2 = '[frm2]', Value3 = '[frm4]' Where ID = [ID]
Beyond this functionality, you may need to return a specific value or record to be utilized by an Action:Assignment
step. For instance, you may have performed a Query ending with: Select @@IDENTITY MyID. This statement
returns a Table to the requesting Table, and can be used through some extended Syntax within the
Action:Assignment. Each step that returns a value adds the first returned table into an array. The value of a column
of the first record within the resulting table can be identified within the Action:Assignment value as
[COLUMNNAME,QueryName] where the QueryName would be whatever is specified as the name, and the column
name would be the name of the column within that first row. For the provided example: [MyID,Update]
In the provided Picture, the execute statement does not return a result – but it does perform an update on the table
based on two parameters defined as query variables.
If your Execute action contains child actions, they will be executed once for each record in the query result, like a
for-each loop. In this case, the row index that is pulled from [MyID,Update] would be polled from the MyID column
first at row 1 then row 2 and so on and so forth within your module.
Connection
If your execute query needs to be pulled from a database connection other than the standard Dotnetnuke
connection provided for your instance, you can specify the ODBC connection string to use for the connection by
adding a connection string. For example:
Connection = Provider=sqloledb;Data Source=MyOtherDatabase;Initial Catalog=pubs;Integrated
Security=SSPI;
A complete breakdown of connection string is provided in the appendix titled: Connection Strings.
Example – Execute
A common scenario for this utilization is the email functionality of listx, sending an email per record in the result.
For instance, if you want to send an email to every person in the user list of your database – you may have an action
structure which looks like this:
48
Version 1.9.7
Another probable, simple, yet extremely useful solution is a website keep-alive module, meant to keep both the
runtime database alert, as well as keep IIS from hibernating the site whenever it has been inactive for longer than a
specific period of time. In the following demonstration, the Execute is not meant to produce a result, but rather
simply force the thread to wait fifteen (15) minutes prior to executing the Action:Input tag, which simply hits a specific
URL. For this module, the target URL is of course the URL of itself. (The screenshots should have used
http://[ALIAS,System]/default.aspx?tabid=[TabID,System] to be more generic.
49
Version 1.9.7
50
Version 1.9.7
Action: Assignment
As discussed in the previous section, you may utilize Action:Assignment to assign to a runtime or system variable.
This can be used for assigning values to any of the following supported types:
Session – utilized by most system to support the state of the current users session information. This
collection of information is the most widely used destination, but you must be cautious when utilizing this
when in a web farm environment.
View State – The view state, once utilized in a standard manner, the variable exists within the physical
transferred page request objects, and does not exist when the path of the page is not tracked directly
Action – To provide a local variable aspect to ListX, Action variables exist within the context of the module
and its request. This means that you can safely create as many Action variables as necessary and these
will automatically be cleaned out whenever the request concludes.
Module Setting – the standard storage location for all Module settings. This is retained for the module and
is utilized by the system whenever the module loads.
Tab Module Setting – the standard storage location for all Module settings. This is retained for the module
and is utilized by the system whenever the module loads. The difference between this and the Module
Setting is that this setting value exists only for this module on the current tab.
UserInfo – facilitating the ability for you to Edit and Create Users for your system, with easy attribute
assignment, and without the need to worry about the physical database structures. Assignment is very
simple:
o To Load a User Info object: Leave the Name property empty, and set the Value to the ID of the
target user. This will automatically set this as the currently loaded userinfo record.
o To Create a New User – Leave the Name Property empty, and set the Value to -1. This will
automatically set the current userinfo object to a new object, which will create the user upon Save.
o To Save the UserInfo – Leave the Name Property empty, and set the Value to Save. If you would
like to use the resulting UserID for other purposes within the Action scripts, you can set the Name
of the Action (Collection) variable to which you want the value stored: Save,myNewContactID.
This will assign the value to the [myNewContactID,Action] variable.
o To Assign a Property – Set the Name of the Property as it appears within the UserInfo object, or
within the Membership or Profile structures. All properties are automatically propogated by name.
For instance, Email is used in all three tables, and will be automatically assigned, even though you
only set the property by name once. (THIS IS CASE SENSITIVE).
Page Size – Allows you to clear our or adjust the size of the page (number of records perpage) from within
the action script)
Page Number – Allow you to control the current page number to display programatically
Search – Allows you to override the current Search Option setting
Filter – Allows you to control the Search option programmatically as which filter (search) text has been
applied.
51
Version 1.9.7
Sort – Allows you to control the Sort option itself, most of the time you would simply assign this to an empty
value.
Variable Type - The type of the variable, which will be assigned.
Name - The specific Key Name of the variable within the Variable Type to be assigned.
Value - The new value to store within the variable. You may use the Rendering tags at any time within any
section of the ListX administration. Leaving the variable Value empty will result in a nullification of the Variable
value, useful for clearing out a configured Checklist.
Note: Action is a new variable assignment which identifies that variable as existing only within the Action context of
the current session, meaning, the variable exist temporarily within the current request context.
52
Version 1.9.7
Action: Redirect
A redirection is used to complete the action message processing, navigating the users page to a different URL. The
Value of the redirection can be either of the following:
Link – Identifies that the target of the redirection will be a fully qualified domain address, or internal page
address used for the navigation. This can contain any standard ListX tag verbage. When the result of the
Value is a number, a TabID is assumed, and a lookup will automatically adjust for the correct tab url. As in
– the provided screenshot could be just as easily assigned as:
[FORMAT,Survey Edit,{TABID}]
Tab - A selected TabID provided by choosing a tab contained within the drop-down list.
53
Version 1.9.7
Action: Email
An email is send automatically using ListX, and consuming the DNN SMTP Settings. The parameters are well
known, standardized, and yet provide the eternal capabilities of ListX, with variable driven values.
From - a source for the email address must be provided, or no email will be sent.
To/Cc/Bcc - Each of these three target email types utilize standard ListX formatting parameters, and can
be completely data driven.
Subject - The subject of the email.
Body Format - The body format can be either Text or Html
Body - The actual body of the email
Result Variable Type – when you need to know if your email action succeeded, you may specify the
Variable Type that you would like the variable stored into. The result is either True or the Failure message.
Result Variable Name – based on the Result Variable Type, the name is the name of the variable (above,
the variable would be [EmailResult,Action].
54
Version 1.9.7
Action: Output
Choose a format in which to download the results of the query. This provides a means to export the entire rich user
interface you created, or to export the underlying data via a CSV file format. There are a few important things to be
aware of when exporting to a rich UI format. First, in order for the style class names used within your HTML content
to export properly, you cannot utilize a LINK tag for importing the CSS, or the export will not have direct access to
the link. It is recommended that all styles used within an export be assigned via the inline style=”” attribute.
Additionally, the export will contain all the HTML tags you created within the ListX configuration, including any
javascript. This javascript must be crafted in a way as to not adversely affect the target file type which may attempt
to execute the script without the context of the surrounding page structure. Finally, when your export target is Excel,
the actual exporting to excel requires appropriate spreadsheet structure. This means that the HTML content you are
attempting to export to the Excel format, must be present in an HTML Table structure, or it may be difficult to render
an appropriate spreadsheet.
Output Type- identifies the type of the output file. Items marked (Complete) will return the entire bound
source, regardless of current page selection. Possible values are:
o Excel
o Excel Complete
o Word
o Word Complete
o Delimited (CSV)
o Delimited Complete.
Delimiter - select a delimiter to use when exporting the data (CSV only).
Export Filename - the name to utilize for the output file. You can use any ListX formatting tags within this
and any other element.
55
Version 1.9.7
Action: Input
Choose a format in which to download the results of the query. The Action: Input type provides the ability to pull
information from External sources, via a standard URL driven web request. This can be used for fetching data from
external sites, triggering specific external actions, or most commonly, interaction with Web Services.
URL - Identifies the URI/URL source of the web request.
Authentication Type – specify whether a specific, or general authentication is required to communicate
with your external source.
Query String- specifies any information passed within the formatted querystring request on the URL.
Data - specifies any information passed within the formatted data request on the URL.
Content Type - The content type feature is required when interacting with web services.
Method (GET/POST/SOAP) - Identifies how the interaction with the Input request will operate.
Soap Action – dependant on the SOAP method, communication with an external SOAP resource require
specification of the SOAP action. This setting is provided in the content of your Soap Header – and can be
identified through the WSDL interface for the particular system.
Soap Result Tag – when SOAP is employed, the content of the envelope is contained within a specific tag
in the XML result. Review the SOAP result from WSDL. The Result tag is easily identified as the tag which
56
Version 1.9.7
contains XML data that has been encoded. Setting the SOAP Result Tag specifies which tag contains this
content, and is automatically digested as the Result XML value.
Response Format (TEXT/XML) - Identifies whether the returning content will be XML or TEXT. Text
values will be assigned directly to the provided variable. XML content will utilize the additional XML Path
(XPATH Expression) text value, formatting the incoming data to obtain just the most required information.
Variable Type - The type of the variable assignment.
Name - The name of the variable within the Variable Type.
XML Path - The XPATH expression utilized to get the specified XML Tag value to be stored within the
Variable.
Common Input Scenarios
There are two common approaches to working with Input calls, one, the XML Service which is demonstrated in the
Example for the Yahoo Geo Coding. This would involve no SOAP interaction, and therefore more linear. The
second type of input uses the Web Service approach via SOAP. Provide below are samples of each configuration.
XML Based Web Service
In the following scenario, taken from the GEO Coding Web Service later in this documentation, we are integrating
with the Yahoo Maps Geocode service which returns XML structured results for the physical Latitude and Longitude.
To do this, add an Action:Input action. The following variables will need to be assigned for the Yahoo service to work
appropriately.
URL – this will be assigned to the documented API Maps Service call provided by Yahoo:
http://api.local.yahoo.com/MapsService/V1/geocode
Content Type – as stated within the documentation, the Content Type parameter can at times be tricky to set
correctly, many times depending on the exact formulation of the service to which you are cooresponding. However,
this sample is a perfect solution for persons who are communicating directly with standard web service interfaces.
For most situations, including this one use:
application/x-www-form-urlencoded
Query String – depending on the target communication, as well as the Method, you may or may not need to use the
query string, but rather, the Data region of the Input action. For the Yahoo API, the Request Query String is straight
forward and easy to use. The first thing you will need before using the form, is a correct App Id, which you can
create via the provided Yahoo link above. The additional parameters are strung directly within the parameter, so
they are easy to see, and configure:
appid=[frmAppId,Form]&zip=[frmZip,Form]&street=[frmStreet,Form]&city=[frmCity,Form]&state=[frmState,Form]
Method – the provision requires the GET method, for the standard URL request.
57
Version 1.9.7
Response Format – the resulting response from Yahoo, atleast at the time of this documentation, is XML formatted,
and looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:yahoo:maps"
xsi:schemaLocation="urn:yahoo:maps
http://api.local.yahoo.com/MapsService/V1/GeocodeResponse.xsd">
<Result precision="address">
<Latitude>37.416384</Latitude>
<Longitude>-122.024853</Longitude>
<Address>701 FIRST AVE</Address>
<City>SUNNYVALE</City>
<State>CA</State>
<Zip>94089-1019</Zip>
<Country>US</Country>
</Result>
</ResultSet>
Variable Type – the target location where the incoming result parsing will be stored, for our demonstration, this is:
<Session>
Name – this identifies either the name of the target variable, when the path is explicitly defined, or may be a
variation of multiple possible values, which is the case here. Our XML Path will set the location to be on the node
reading “<Result precision=address>” Since we need more than one of the parameters – in our case, we need both
the Latitude and the Longitude, we will need to use some special additional formatting on the Name of the storage
variable. The possible additional values are [*Child], meaning we will be assigning multiple variables, with the
[*Child] tag replaced by the name of the child nodes, ie. ResultLatitude,ResultLongitude,ResultAddress et al. The
other possibility, is the [*Index] tag, which means that each result will be placed with an index attached, for all child
records. Our sample does not use this structure, nor does it need it, but if you had multiple Result tags within the
58
Version 1.9.7
Result Set, and wanted to keep all the returned values, that is what you would need to use also. In our case, the
following is provided:
Result[*CHILD]
XML Path - Finally, the actual XML Path of the result will be used. Because the incoming result assigned a default
namespace to the document, a namespace urn is required for parsing the incoming content. ListX automatically
builds a Names table of all the possible namespaces, but when the default is overridden, the specified name is not
possible. However, the default namespace has been given a fixed name within ListX, and is by design to allow for
easy checking of XML values. To use the root namespace, when this is the case, use “default” as the namespace
name. With that said, for this example:
.//default:Result
SOAP Based Web Service
Working with the more popular SOAP web service protocols is also possible with the Input action, and requires only
a few modifications to the previous scenario. For this sample we created a dummy web service which simply returns
the information about the incoming TabID requested.
First, access the WSDL (Discovery Page) for the target web service. For our case the WSDL was accessible via our
development url of : http://dnn.bi4ce.com/Services/DemoService.asmx?op=GetInfo
This is exactly as you would access your own web service call. Once executed, review the package request for the
SOAP (1.1) as defined as:
POST /Services/DemoService.asmx HTTP/1.1
Host: dnn.bi4ce.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://tempuri.org/ListXWebService/Service1/GetInfo"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetInfo xmlns="http://tempuri.org/ListXWebService/Service1">
<TabID>int</TabID>
<StraightPass>string</StraightPass>
</GetInfo>
</soap:Body>
</soap:Envelope>
Looking in the configuration for the calling web service, all aspects of this Request SOAP data are handled:
59
Version 1.9.7
URL
The URL of the web service itself – http://dnn.bi4ce.com/services/demoservice.asmx
Authentication Type
Our server requires no Authentication for this action, but you may require this setting for your target server,
depending on the security of your data and the library.
Content Type
Executing this SOAP web service requires:
SOAP envelope
text/xml; charset=utf-8 as defined within third line of the required
QueryString
No querystring is required for this webservice call, but if Querystring Parameters are required, add them here in
name=value& format.
Data
The data follows the requirements of the package envelope specifically, with the parameters filled in as required by
the configuration. So referring to the envelope itself the data value is:
<soap:Body>
<GetInfo xmlns="http://tempuri.org/ListXWebService/Service1">
<TabID>1179</TabID>
<StraightPass>Also a Test</StraightPass>
</GetInfo>
60
Version 1.9.7
</soap:Body>
</soap:Envelope>
Method
The method selected here is SOAP because we are using that protocol for this request.
SOAP Action
Also provided in the SOAP Envelope is the required SOAP Action parameter. This should appear exactly as
requested in the envelope itself. For our sample it is designated as (including quotes):
"http://tempuri.org/ListXWebService/Service1/GetInfo"
SOAP Result Tag
The GetInfoResult tag, identified by the SOAP Result Tag option provides the ability to automatically open the
envelope and extract the contents of the result you require. For our sample, the Result Envelope structure provided
by the WSDL request was as follows:
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Body>
<GetInfoResponse xmlns="http://tempuri.org/ListXWebService/Service1">
<GetInfoResult>string</GetInfoResult>
</GetInfoResponse>
</soap:Body>
</soap:Envelope>
As provided here, we will want to extract the contents of the GetInfoResult element which will contain the result
value we desire.
Response Format
For this sample, the GetInfoResult string will contain an HTML Encoded representation of the XML serialized Tab
Information, appears as the following and is specified as XML format -
<Result>
<ResultItem>
<Tab>
<Name>TinyMCE example</Name>
<Title>TinyMCE example</Title>
<PortalID>0</PortalID>
<isSystem>False</isSystem>
</Tab>
<Tab>
<PassThrough>Also a Test</PassThrough>
</Tab>
</ResultItem>
</Result>
61
Version 1.9.7
Name / Variable Type
The variable type identifies which variable we are assigning the value we are pulling from the result into. This is
handled through the NAME and VARIABLE TYPE settings
XML Path
When reading the XML path, we are identifying the Path which contains the value, or values we are interested in.
For this sample, the Result tag is what we are using, but this is dependent on your physical web service call.
62
Version 1.9.7
Action: File
The ability to manipulate files, store files within the system, receive incoming files, and handle more advanced
conceptual tasks of transforming a file like Images and CSV files within ListX makes its capability advance far
beyond all other tools on the market. Within the ListX environment you can take an incoming file and store it directly
within your system, either within the DNN context, or external to that, additionally you can take a file which resides
outside the DNN environment and return it directly to the client browser, making file storage and handling much
better. Image files can be automatically scaled through manipulation and CSV files can be imported directly from
your CSV file to a target SQL structure or advanced execution seamlessly and in real-time, without the adverse
worries of request timeouts.
Additionally, the actions presented as children of the Action:File message action will execute upon the completion of
the Action:File tag parent. This means, if you need to execute a query, or send an email or perform other threaded
tasks after the completion of the File CSV import, you can do that easily. Just add a few actions as children of the
file, and check out the possibilities.
The interface provides the following structures, and possible attributes:
Source Type – The source of the file will be coming from one of three possible sources
o
o
Path – Identifies that the source will be coming from the server directly via a path, this path may
be either a relative path “~/images/file.gif” for instance, or a fixed path like
“C:\wwwroot\images\file.gif”.
Variable – Identifies that the source will be receive via a runtime variable which can be received
from the following sources:

Form – Identifies that the incoming Form contains a file, typically handled via the Input
type of “File”. The Source will be assigned to the name of the incoming tag.
When interacting with Form variables, you must not that you can access the incoming
information about the form variable through a few extended ListX tags. Assume that the
name of the incoming form field is frmFile.
[frmFile.Path,Form] – returns the full directory name of the file that is received
through the form, from the source machine.
[frmFile.Name,Form] – returns the full file name, including the extension of the
file.
[frmFile.NameOnly,Form] – returns the name, without the extension for the
file.
[frmFile.Extension,Form] – returns the extensions of the file.
63
o
Version 1.9.7
[frmFile.Type,Form] – returns the MIME type (discussed in the appendix)
[frmFile.Length,Form] – returns the physical byte length of the incoming file.

QueryString – Identifies that the incoming QueryString contains text that will be used as
a file source. This means that you can handle files sent via encoded query variables, and
work with them as files directly. The source will map to the name of the variable.

Cookie - Identifies that the incoming Cookie contains text that will be used as a file
source. This means that you can handle files sent via encoded Cookie variables, and
work with them as files directly. The source will map to the name of the variable.

Session – Identifies that the Session contains a text value that will be used as a file, or
that the Session contains a binary file specifically. The source will map to the name of the
session variable.

View State – Identifies that the View State contains a text value that will be used as a
file, or that the View State contains a complete binary file specifically. The Source will
map to the name of the View State variable.

Action – Identifies that the Action array, a temporary array of variables utilized only by
the ListX instance and evaporating after the rendering completes for any specific request,
contains a variable which is either a text value, or a complete binary file that will be the
source of the file action. The Source will map to the name of the Action variable.

Custom – Identifies that the source of the variable is convoluted, and will need to be
achieved through rendering of a complex ListX tag structure. This may mean that either
the source can switch between two variable types or that the Source name is too difficult
to manage within the simple drop down.
SQL – The Source of the file resides in a single column value, or that the destination will be
formatted to migrate one SQL instance into another directly. This can be used when you need to
pull a file out of the database, and send it back to the client. In this case, the SQL response will
only pull from column 0 row 0 of the returned table.
Source – Identifies the textual name, path, or query of the source, depending on the requirements from
the Source Type, and defined above.
Destination Type – The destination of the file, either a path, or other variable context will be
utilized here. The following types of destination are provided:
o Path - Identifies that the destination will be on the server directly via a path, this path may be
either a relative path “~/images/file.gif” for instance, or a fixed path like
“C:\wwwroot\images\file.gif”.
o Variable - Identifies that the destination will be assigned via a runtime variable which can be
placed into the following destinations:

Session – Identifies that File will be placed into the users Session array

View State – Identifies that the View State will be the target repository of the outgoing
file.

Action – Identifies that the Action array, a temporary array of variables utilized only by
the ListX instance and evaporating after the rendering completes for any specific request,
will store the resulting file.
o Response – Identifies that the Source file will be sent directly to the awaiting client browser. This
allows you to handle a file Download aspect of your site, and lets you provide an online file
management scenario quite easily.

Response Type – The response type of the outgoing data – you can choose to use a
general response type of application/octet-stream, or a specific value – (See MIME
Types within the Appendix).
If you would like the file to return within the same window, rather than opening a new
window or providing the “Save As..” prompt, add “-noattach” to the Response Type value,
for example: text/plain-noattach
64
Version 1.9.7
Destination – Obviously, the destination is the response, but you will want to possibly
control the outgoing name of the file. This identifies the file name that will be assigned to
the outgoing file.
Email Attachment – to attach files to an outgoing email action, you must first create your Email
action, then make the File action a child of the Email action. Finally – set Email Attachment as the
Destination Type. For more complex types of scenario, for instance when you need to send
multiple files based on a Query result – you may set an Execute Action as the child of your Email
Action, and then a File Action as the Child of the Execute Action, attaching a file per record in your
Query to the outgoing Email.
SQL – This is the essence of CSV importing at its greatest. The SQL destination identifies that the
SOURCE is an incoming CSV formatted file. If it is not – this will not work as planned. You then
have a number of options to pick through for the CSV file, its destination, and the mapping to
utilize.

o
o
65



Version 1.9.7
First Row Contains column names – check this box if the file contains the headings at
the top, used to skip the first row, but allow the developer to map the records columns by
name
Run as Process – This is a combination of two values, and for full understanding, you
will want to review Demonstration Four : CSV Imports. Essentially – if you are inserting a
large number of records, the standard CSV import routines would probably take longer
than the allotted time for the request and you would end up with an ugly timeout error. If
you check this box, the import process spins off a separate thread and runs the import
from there, keeping track of the status in an action variable which you can pull from in an
automatic fashion. The demonstration does this with a friendly status bar and record
count in real time – so a very good review. In general you have three options with the
Name at runtime.
Name - The name of the variable to use in order to gain access to the current
runtime status of the import – these can be accessed in three ways.
o [Name.Complete,Action] – Returns a true or false indicator that the
action has completed. You must always check this before checking the
percentage and status. If the task has completed, and you already
popped the status and percentage off the stack, the complete will
return false.
o [Name.Status,Action] – Returns the number of records processed
thus far in the CSV file.
o [Name.Percent,Action] – Identifies the percentage of completion for
the process. The sample demonstrates a real-time progress bar for
this.
SQL Column Mappings –The SQL Column mappings allows you to control how the
CSV Columns map to variables consumed within the Destination SQL Query. IT MUST
BE UNDERSTOOD that these placeholders within the destination query are replaced by
standard SQL values, with formatting depending on the outgoing data type specified
here. For instance, a Number will be replaced directly, but a Text value will be encased in
single quotes. Additionaly, the convention of naming the variables is completely up to the
developer, and does not need to following any standard syntax – it‟s a simple find and
replace methodology.
To begin, simply press the familiar footer button, Add Column Mapping – then assign the
following values.
Position – Optional, either the Name or Position is required. This identifies the
Index (zero based) of the column. So if you want to always use the first column
(0), set that here. The value will be pulled from that index within the current row.
Name – Optional, either the Name or Position is required. This identifies the
Name of the column to pull the value from. This can only be possible if the First
Row contained column names, otherwise there is nothing to map against. If the
third column is “TabType”, you can simply put “TabType” here and assign the
mapping directly.
Target – the target text that will be replaced within the destination for instance, if
the Target is specified as “@TabType” anywhere “@TabType” appears in the
destination query – the actual value of the row will be replaced.
Type – identifies the type of incoming variable. This is a simplistic Type
checking method, to avoid complications within CSV data scrubbing or errors on
invalid formatting conversions from Text to Integer. Choose a simply type here:
Number, Decimal, Text, Date, Time, DateTime and the action will automatically
“correct” the value based on the Default setting.
Format – A specific format to use for formatting the Value. Use standard
formatters supplied within ListX – Like {0:C} for currency. This is not used very
often because in most cases, the Type suffices.
66

Version 1.9.7
Default – The value to use whenever the Type verification fails. For instance, if I
am trying to convert “ABC” to a number, the verification for Number will fail, and
I will use the default value. In this case lets assume “0”.
Null – Each CSV format may vary on what represents a Null value for a column.
For instance if you are importing a numeric value, and determine that -1 should
be mapped to NULL and will therefore be NULL in the Destination statement.
Destination – The destination is the query to execute “PER ROW” from the incoming
CSV file, with the appropriate Target values in place. For example:
INSERT INTO myTable(MyID,MyName,MyDescription)
VALUES (@MyID,@MyName,@MyDescription)
Transformation – This controls additional transformations on the file, which is either Image
transformation or File manipulations:
o Image - Image transformation allows you to control the scaling of the target image. So you can
actually save images scaled to different sizes for managing clips and other variations of incoming
image files.

Width / Height – Setting the Width or Height variables identify the actual size to use on
either the Width or Height. When both are provided, the resulting image will be stretched
to fit the dimensions, regardless of the aspect ration. However, when only ONE of the two
are specified the other will automatically set to the correct ratio value. When the incoming
image is smaller than the target image in both width and height, the resulting image will
remain the same size, and no scaling will occur. Finally – you can specify either a fixed
pixel size or a variable percentage size for the width and height values.
o
File - You may choose one of the following options for handling the Destination and Source files.
This only works against files when both the Source and Destination are Paths.

Copy – Source to Destination

Move – Source to Destination

Delete – Deletes the Source file.
67
Version 1.9.7
Condition: If
The expression must evaluate to either TRUE or FALSE. All variables will be replaced prior to evaluation, so all
session, query string, form and system variables are usable. If the expression does evaluate to TRUE, then all child
actions will be processed. It is possible to further nest IF conditions to gain more control of what gets processed,
and what does not.
Compound Conditions provide the ability to combine multiple statements together, the evaluation will result in either
a True or a False operation, like this:
68
Version 1.9.7
Condition: Else-If
The expression in this condition will only be processed if all preceding conditions evaluated to FALSE. It is
otherwise ignored. Again, an expression must be declared and it must be possible to evaluate to either TRUE or
FALSE. Should it evaluate to TRUE, then all child actions will be processed.
69
Version 1.9.7
Condition: Else
There is no expression associated with this condition. It will only process if all preceding conditions (IF... and
ELSEIF...) evaluated to FALSE. Then, it will allow all child actions to process.
Action: Comment
At times you may desire the ability to place inline content into you action script. To do this, add an Action Comment
and place your comments directly into this action.
Action: Log
Throughout the process of working with your Configurations, and running testing and debugging you may find that
you need to log specific information into the database. ListX provides a convenient logging solution, specific for each
module – without the confines or ill suited layout of the standard DotNetNuke Event Log. Within the ListX package is
a Log database table which supports the ability to add Log entries at any time. Simply add a Log action and fill in the
two settings.
Group – provides the ability to customize and categorize the list of events – enter whatever you prefer for each
event here. If you have items which should be grouped together, you may desire setting this value specifically for
each type of event.
Content – Enter the physical content you want to see within the log for each entry.
70
Version 1.9.7
Template Formatting
The roots of ListX originated with the need to develop a spectacular front-end reporting system. The report
structures were nearly static, driven by specific variables assigned by clicking on items within the reports.
Classically this would have been handled by creating many static modules, with prebuilt repeaters and data
grids to achieve formulated output. The system itself needed to be easily customizable by the web designers,
and capable of tweaking the User Interface without the need for a recompile. Hence, ListX was born.
Screenshot: The List Formats layout as it appears within the View Options menu item in ListX, with the
Group Editor entry form expanded.
71
Version 1.9.7
List Groups (Template Hierarchy)
Providing a Microsoft Access Style report formatting engine, capable of building extremely complex hierarchical
formatted output is made easy through the List Groups. The main detail element of the report, the List Item Detail,
is always visible as the last hierarchical item in the List Groups table. To provide the ability to repeat bounding
headers and footers based on changes in columns, you must add new List Groups and control the order of these
groups through the List Group table.
Tip: You can be extremely creative with you formatting because of the rendering behavior of ListX. As ListX renders
its output, it loops through the list of columns provided in the data result, replacing occurrences within your List
Formats with the values in the columns. You can have completely dynamic result structures by placing occurrences
of Column Values within the results, therefore nesting one inside another. This is particularly useful in instances
where you display is dynamically based on parameters you are passing in to your SQL. Keep in mind, the columns
are replaced in the order which they occur, so when you attempt this behavior only columns occurring after the
nested column can be replaced within the nesting.
Headers and Footers for List Groups always occur around the List Item Detail. For Instance if you have the
following List Groups defined in the screenshot above:
Main Group
Site Group
List Item Detail
Would result in the follow output structure depending on the incoming data:
Main Group Header
o Site Group Header
 List Item Detail
 Alternate Item Detail
o Site Group Footer
o Site Group Header
o Site Group Footer
Main Group Footer
Main Group Header
o Site Group Header
o Site Group Footer
o Site Group Header
o Site Group Footer
Main Group Footer
72
Version 1.9.7
Managing Template Groups
Building the set of List Groups is managed very simply using the List Group table. Any number of List Groups can be
supplied. The resulting output will be structured exactly as the Groups identify. Administration is simple, identified
through the actions provided by the table below:
Edit - Click the edit link to change the values for this List Group.
Up - Moves the selected List Group upwards in the hierarchy.
Down - Moves the selected List Group downwards in the hierarchy.
Delete - Removes the entry from the List Groups.
To add a Group, click on the Add List Group link.
Editing Templates
Template Syntax
Some extremely specialized syntax is included in the rendering process for handling all type of interaction with the
ListX module. From just simple Column Values and formatting, through Sorting, Check and Radio lists and
Actionable items, follow the links and descriptions provided below to gather understanding on each of these
features.
Group Statement
The Group statement is similar to the usage of the Header, Footer and Detail values in regards to the replaceable
Column Values. Upon iteration of each record in the resulting table, the Groups are checked in their hierarchy based
73
Version 1.9.7
on the formatted Group Statement. If the resulting value of the Group Statement changes, the Headers and Footers
for the Group in question, and its sub-groups will render. Group statements are not visible to the actual user, and are
only used for this purpose. Since the Header and Footer in question can be extremely large, it is far more efficient to
detect changes in a relatively short value rather than a large one. In the example above, we are checking whether
the Column Value for MainGroup or SiteGroup have changed. The Header and Footer may contain many other
formatted Column Values, but only when either of those columns change will the Header/Footer combinations be
rendered.
Default Item (No Results)
The Default Item utilizes that standard syntax parameters of Header, Footer and Detail - however, it is only
displayed when the bound data source contained no records. If you want to hide the module completely whenever
no results are returned from the query, check the Hide Module box.
Default Item (No Query)
The Default Item utilizes that standard syntax parameters of Header, Footer and Detail - however, it is only
displayed when the bound data source contained no records and the Query was not defined, or resulted in an empty
string. If you want to hide the module completely whenever the query is empty – press the Hide Module checkbox.
74
Version 1.9.7
Column Values
Replacing cell values from your columns with the actual value from the cell during the output generation is made
simple by using the built in syntax. Two styles of handling are provided for column data output. The basic output is
made simplistic, it simply requires you to place your column name in square brackets - [...]. An advanced, yet
extremely useful feature provides the ability to format you values using either date, or numeric formatters supplied
by the .Net Framework environment. Formatting is done by using the [$...] syntax, with the Column Name as the first
variable, and a second variable containing the format attributes. Follow the syntax definitions provided to assist in
building the appropriate output block.
Since the onset of the 1.7.6 release, it is more appropriate to use the [FORMAT,Value,{Formatter}] functionality for
all format tags. Additionally, the use of system variables like UserID, Alias, et al, should be handled by using the
explicit naming of the variable – ie. [UserID,System].
Tip: The output functionality examines the resulting table from your query and replaces occurrences of the Column
Values with those identified in your table. If you are having trouble diagnosing occurrences of Column Names not
effectively replacing, turn the debug feature on and take a look at names of the columns.
Standard Column Output
[ColumnName]
System Values and Parameters
[ALIAS]
[LOCALHOSTALIAS] – ie: localhost/Demo32 would be /Demo32, dnn.bi4ce.com/Demo32 remains.
[MODULEID]
[TABID]
[TABMODULEID]
[CLIENTID]
[ID]
[MODULEPATH]
[PAGENUMBER]
[TOTALPAGES]
[TOTALRECORDS]
[USERNAME]
[FIRSTNAME]
[LASTNAME]
[FULLNAME]
[USERID]
[DATE]
[LOCALE]
[URLREFERRER] – returns the “previous” link, or the url that drove the user to this page.
[FORM] – returns the entire form, in textual format
[RESPONSESTATUS] - returns the response status value (from the browser)
[RESPONSETEXT] – returns the physical response in textual format
[OBJECTQUALIFIER] – returns the configured objectQualifier from DotNetNuke database setting
[DATABASEOWNER] – returns the configured databaseOwner from the Dotnetnuke settings
75
Version 1.9.7
Advanced System Values
Along with the provided system variables, you may also pull from many runtime and environmental values which are
available. These variables may be contained within the requesting Form, QueryString, ViewState, Cookies, Session
and ModuleSettings using the following structures.
[ItemName,Session]
[ItemName,QueryString]
[ItemName,Form]
[ItemName,ViewState]
[ItemName,Cookie]
[ItemName,ModuleSetting]
[MessageType,Message]
[ItemName,Action]
Input File (Form) Values
[frmFile.Path,Form] – returns the full directory name of the file that is received through the form, from the source
machine.
[frmFile.Name,Form] – returns the full file name, including the extension of the file.
[frmFile.NameOnly,Form] – returns the name, without the extension for the file.
[frmFile.Extension,Form] – returns the extensions of the file.
[frmFile.Type,Form] – returns the MIME type (discussed in the appendix)
[frmFile.Length,Form] – returns the physical byte length of the incoming file.
[frmFile.Height,Form] – Returns the vertical height of the file if the file is an Image
[frmFile.Width,Form] – Returns the horizontal width of the file if the file is an Image
File (CSV/SQL) Import Process Values
[processName.Complete,Action] – returns true or false
[processName.Status,Action] – returns the number of records imported so far.
[processName.Percent,Action] – returns the overall percentage of completion for the import.
Localization/Resource File Values
Many times you may desire to pull values from the standard Localization files, or from custom Localization resource
files. The [LOCALE] tag has been extended to allow just this behavior. To use Locale, you must specify either the
[LOCALE] tag, which will return the current Language selections - ex: en-US. Or, to load key information from a
specific resource file, you would need to provide the path of the file, as well as the key - like this:
[LOCALE,Session/App_GlobalResources/GlobalResources.resx,MESSAGE_PORTAL_TERMS.Text]
76
Version 1.9.7
Runtime Values (Reflection)
The physical runtime has now been exposed within ListX, so you can gain access directly to any of the properties,
functions and variables which require no parameters. This means, that you can get access to all the deeper
knowledge of the runtime system, without getting your code hands dirty. An example of this is provided in as simple
a logic as the [Request.UserAgent,System] information, which will return the users browser information. Or, as
conceptual as [UserInfo.Membership.LastLoginDate,System]
The engine is completely intelligent in the parsing, so you can easily access any level of depth within the current
architecture or may expand to any depth required, simply by using the tag [NAME.NAME.NAME,System] – The
following list is a representation of most of the runtime values you currently have access to, based on the
DotNetNuke runtime which you are running.
o
o
Context - includes all aspects from the httpContext model provided by ASP.NET, please refer to
the HttpContext documentation.

Context.AllErrors

Context.Application

Context.ApplicationInstance

Context.Cache

Context.Current

Context.Error

Context.Handler

Context.IsCustomErrorEnabled

Context.IsDebuggingEnabled

Context.Items

Context.Request

Context.Response

Context.Server

Context.Session

Context.SkipAuthorization

Context.Timestamp

Context.Trace

Context.User
PortalSettings – Provides all the DotNetNuke runtime Portal Settings, as they are defined within
the DotNetNuke architecture.

PortalSettings.ActiveTab
PortalSettings.ActiveTab.AdministratorRoles
PortalSettings.ActiveTab.AuthorizedRoles
PortalSettings.ActiveTab.BreadCrumbs
PortalSettings.ActiveTab.ContainerPath
PortalSettings.ActiveTab.ContainerSrc
PortalSettings.ActiveTab.Description
PortalSettings.ActiveTab.DisableLink
PortalSettings.ActiveTab.EndDate
PortalSettings.ActiveTab.FullUrl
PortalSettings.ActiveTab.HasChildren
PortalSettings.ActiveTab.IconFile
PortalSettings.ActiveTab.IsAdminTab
PortalSettings.ActiveTab.IsDeleted
PortalSettings.ActiveTab.IsSuperTab
PortalSettings.ActiveTab.IsVisible
PortalSettings.ActiveTab.KeyWords
PortalSettings.ActiveTab.Level
77
Version 1.9.7
PortalSettings.ActiveTab.Modules
PortalSettings.ActiveTab.Panes
PortalSettings.ActiveTab.PortalID
PortalSettings.ActiveTab.SkinPath
PortalSettings.ActiveTab.SkinSrc
PortalSettings.ActiveTab.StartDate
PortalSettings.ActiveTab.TabID
PortalSettings.ActiveTab.TabName
PortalSettings.ActiveTab.TabOrder
PortalSettings.ActiveTab.TabPath
PortalSettings.ActiveTab.TabPermissions
PortalSettings.ActiveTab.TabType
PortalSettings.ActiveTab.Title
PortalSettings.ActiveTab.Url
PortalSettings.AdministratorId
PortalSettings.AdministratorRoleId
PortalSettings.AdministratorRoleName
PortalSettings.AdminTabId
PortalSettings.BackgroundFile
PortalSettings.BannerAdvertising
PortalSettings.Currency
PortalSettings.DefaultLanguage
PortalSettings.Description
PortalSettings.DesktopTabs
PortalSettings.Email
PortalSettings.ExpiryDate
PortalSettings.FooterText
PortalSettings.HomeDirectory
PortalSettings.HomeDirectoryMapPath
PortalSettings.HomeTabId
PortalSettings.HostFee
PortalSettings.HostSpace
PortalSettings.KeyWords
PortalSettings.LoginTabId
PortalSettings.LogoFile
PortalSettings.PortalAlias
PortalSettings.PortalId
PortalSettings.PortalName
PortalSettings.RegisteredRoleId
PortalSettings.RegisteredRoleName
PortalSettings.SiteLogHistory
PortalSettings.SplashTabId
PortalSettings.SuperTabId
PortalSettings.TimeZoneOffset
PortalSettings.UserRegistration
PortalSettings.UserTabId
PortalSettings.Version
o

































UserInfo

UserInfo.AffiliateID

UserInfo.FirstName

UserInfo.FullName

UserInfo.IsSuperUser

UserInfo.LastName
UserInfo.Membership.Approved
UserInfo.Membership.CreatedDate
78

o


Request



























Version 1.9.7
UserInfo.Membership.Email
UserInfo.Membership.LastLockoutDate
UserInfo.Membership.LastLoginDate
UserInfo.Membership.LockedOut
UserInfo.Membership.Password – Supported only in versions of DNN
preceeding 4.3x and 3.3x
UserInfo.Membership.Username
UserInfo.PortalID
UserInfo.Profile.Cell
UserInfo.Profile.City
UserInfo.Profile.Country
UserInfo.Profile.Fax
UserInfo.Profile.FirstName
UserInfo.Profile.FullName
UserInfo.Profile.IM
UserInfo.Profile.LastName
UserInfo.Profile.PostalCode
UserInfo.Profile.PreferredLocale
UserInfo.Profile.Region
UserInfo.Profile.Street
UserInfo.Profile.Telephone
UserInfo.Profile.TimeZone
UserInfo.Profile.Unit
UserInfo.Profile.Website
UserInfo.UserID
UserInfo.Username
Request.AcceptTypes
Request.ApplicationPath
Request.Browser
Request.ClientCertificate
Request.ContentEncoding
Request.ContentLength
Request.ContentType
Request.Cookies
Request.CurrentExecutionFilePath
Request.FilePath
Request.Files
Request.Filter
Request.Form
Request.Headers
Request.HttpMethod
Request.InputStream
Request.IsAuthenticated
Request.IsSecureConnection
Request.Item
Request.Params
Request.Path
Request.PathInfo
Request.PhysicalApplicationPath
Request.PhysicalPath
Request.QueryString
Request.RawUrl
Request.RequestType
79
o
o
o
o
Version 1.9.7

Request.ServerVariables

Request.TotalBytes

Request.Url

Request.UrlReferrer

Request.UserAgent

Request.UserHostAddress

Request.UserHostName

Request.UserLanguages
Response

Response.Buffer

Response.BufferOutput

Response.CacheControl

Response.Charset

Response.Clear

Response.ClearContent

Response.ClearHeaders

Response.Close

Response.ContentType

Response.Expires

Response.ExpiresAbsolute

Response.IsClientConnected

Response.RedirectLocation

Response.Status

Response.StatusCode

Response.StatusDescription

Response.SuppressContent
Session

Session.Abandon

Session.Clear

Session.CodePage

Session.Count

Session.IsCookieless

Session.IsNewSession

Session.IsSynchronized

Session.LCID

Session.Mode

Session.SessionID

Session.Timeout
ViewState

ViewState.Clear

ViewState.Count
Engine – The basis class that physically renders the ListX output, there are a few properties which
can be utilized to a better advantage when necessary

Me.ClearCache – clears the web and module cache when executed

Me.GetRequestForm – returns a string representation of the entire incoming form request
object.
80
Version 1.9.7
Format – Custom Value Formatting
[$ColumnName, FORMAT]
Example: [$ColumnName,{0:$#,##0.00;($#,##0.00);Nothing}]
[$VariableName:VariableType, FORMAT]
Example: [$frmValue:Form,{0:$#,##0.00;($#,##0.00);Nothing}]
Format
The FORMAT option is defined by the syntax provided within the .Net Framework. The syntax was created and is
provided in such a way as to work as a culture specific syntax. All format tokens begin and end with a curly brace
{...}. Utilization of the format element can be simplistic, or provide a compound and deterministic statement which is
much more advanced. After reviewing the options provided, a more advanced format provides the ability to vary the
format depending on the value of the data. For example
{0:$#,##0.00;($#,##0.00);Nothing}
The resulting output would be $1,234.50 if the data value was 1234.50. Or, ($1,234.50) if the value had been
negative. If the item is zero, the output would result in Nothing.
This format structure has been extended, improved and modified to use a friendly format, and to provide formatting
of not only COLUMN values, but form and other system type variables as well. There are two possible syntax
structures for this, depending on whether you want to perform the Formatting “before” or “after” replacement – as will
be demonstrated.
The new structure is similar to the last – but provides far better coverage:
[$VariableName:VariableType, FORMAT]
Example: [$frmAmount:Form,{0:$#,##0.00;($#,##0.00);Nothing}]
That example is defined as “before” replacement formatting. Meaning, which works at all times, unless you need to
combine variables or types of variables within one format tag. This tag is far more expansive:
[FORMAT, Value, FORMAT]
Example: [FORMAT,[frmAmount,Form],{0:$#,##0.00;($#,##0.00);Nothing}]
That is an example of “after” replacement. This means that [frmAmount,Form] has already been rendered, before
the FORMAT is even evaluated. Additionally, you may also use the FORMAT tag with “before” replacement:
[FORMAT, VariableName, VariableType, FORMAT]
Example: [FORMAT,frmAmount,Form,{0:$#,##0.00;($#,##0.00);Nothing}]
Use the tables provided below to assist in building the appropriate format filter parameters for your output.
Standard .Net Formatters
Standard Numeric Formatting
Specifier
Type
c currency
d decimal
FORMAT
{0:c}
{0:d}
Sample (1.2345)
$1.23
FormatException
Sample (-12345)
-$12,345.00
-12345
81
e
f
g
n
r
x
exponent / scientific
fixed point
general
number
round trippable
hexadecimal
Version 1.9.7
{0:e}
{0:f}
{0:g}
{0:n}
{0:r}
{0:x4}
1.234500e+000
1.23
1.2345
1.23
1.23
FormatException
-1.234500e+004
-12345.00
-12345
-12,345.00
FormatException
ffffcfc7
Custom Numeric Formatting
Specifier
Type
zero placeholder
digit placeholder
decimal point
.
placeholder
, thousand separator
% percentage
0
#
FORMAT
{0:00.000}
{0:#.##}
Sample (1234.56)
1234.560
1234.56
{0:0.0}
1234.6
{0:0,0}
{0:0%}
1,235
123456%
Standard Date Formatting
Specifier
d
D
t
T
f
Type
short date
long date
short time
long time
full date/time
FORMAT
{0:d}
{0:D}
{0:t}
{0:T}
{0:f}
F
long full date/time
{0:F}
g
G
M
r
s
u
Y
general
long general
day / month
RFC1123 date
sortable date/time
universal
month/year
{0:g}
{0:G}
{0:M}
{0:r}
{0:s}
{0:u}
{0:Y}
Sample (January 2, 3456 7:08:09 PM)
1/2/3456
Wednesday, January 2, 3456
7:08 PM
7:08:09 PM
Wednesday, January 2, 3456 7:08 PM
Wednesday, January 2, 3456 7:08:09
PM
1/2/3456 7:08 PM
1/2/3456 7:08:09 PM
January 1
Wed, 1 Jan 3456 19:08:09 GMT
3456-01-02T19:08:09
3456-01-02 19:08:09Z
January, 3456
Custom Date Formatting
Specifier
dd
ddd
dddd
hh
HH
mm
MM
MMM
MMMM
ss
tt
yy
Type
day
short day
long day
2 digit hour
2 digit hour
2 digit minute
month
short month name
long month name
seconds
am/pm
2 digit year
FORMAT
{0:dd}
{0:ddd}
{0:dddd}
{0:hh}
{0:HH}
{0:mm}
{0:MM}
{0:MMM}
{0:MMMM}
{0:ss}
{0:tt}
{0:yy}
Sample (January 2, 3456 7:08:09 PM)
02
Wed
Wednesday
07
19
08
01
Jan
January
09
PM
56
82
yyyy
:
/
4 digit year
separator
separator
Version 1.9.7
{0:yyyy}
{0:hh:mm:ss}
{0:dd/MM/yyyy}
3456
07:08:09
01/02/3456
83
Version 1.9.7
84
Version 1.9.7
Extended ListX Formatters
While the standard .Net formatters provide the ability to handle most any type of generic data type, and layout the
data precisely how you want it to appear, it doesn‟t provide the facility to enhance your abilities to format the data in
an “as you see fit” scenario.
ListX provides an enhanced FORMAT library with a variety of additional values which are identified in the following
list. These formatters provide simple tasks like specific Tab look-ups by the Name of the tab, through advanced
dynamic look-ups against any specific table to encoding, decoding and runtime verifications.
String Manipulation Formatters
LEFT – Used to return only the first N characters from the value
Format:
[FORMAT,VALUE,{LEFT:LENGTH }]
Example:
[FORMAT,My Tab,{LEFT:2}]
Result:
My
RIGHT – Used to return only the last N characters from the value
Format:
[FORMAT,VALUE,{RIGHT:LENGTH }]
Example:
[FORMAT,My Tab,{RIGHT:2}]
Result:
ab
MID – Used to return the characters from the middle of the value starting at character X and ending at
character Y.
Format:
[FORMAT,VALUE,{MID:FROM,TO}]
Example:
[FORMAT,My Tab,{MID:3,5}]
Result:
Ta
85
Version 1.9.7
UPPER – Convert the entire value to upper case
Format:
[FORMAT,VALUE,{UPPER}]
Example:
[FORMAT,My Tab,{UPPER}]
Result:
MY TAB
LOWER – Convert the entire value to lower case
Format:
[FORMAT,VALUE,{LOWER}]
Example:
[FORMAT,My Tab,{LOWER}]
Result:
my tab
LENGTH – return the length of the value
Format:
[FORMAT,VALUE,{LENGTH}]
Example:
[FORMAT,My Tab,{LENGTH}]
Result:
6
REPLACE – replace a specific character combination from the value with another
Format:
[FORMAT,VALUE,{REPLACE:LOOKFOR,REPLACEWITH}]
Example:
[FORMAT,My Tab,{REPLACE:My,Our}]
Result:
Our Tab
86
Version 1.9.7
PADLEFT – Add a specific character to the Left of the value to reach a specific length for the entire text
Format:
[FORMAT,VALUE,{PADLEFT:LENGTH,CHARACTER}]
Example:
[FORMAT,My Tab,{PADLEFT:10,#}]
Result:
####My Tab
PADRIGHT
- Add a specific character to the Right of the value to reach a specific length
Format:
[FORMAT,VALUE,{PADRIGHT:LENGTH,CHARACTER}]
Example:
[FORMAT,My Tab,{PADRIGHT:10,#}]
Result:
My Tab####
TRIM – remove whitespace characters from the Left and Right of the value
Format:
[FORMAT,VALUE,{TRIM}]
Example:
([FORMAT,” My Tab ”,{TRIM}])
Result:
(My Tab)
TRIMLEFT – remove whitespace characters from the Left of the value
Format:
[FORMAT,VALUE,{TRIMLEFT}]
Example:
([FORMAT,” My Tab ”,{TRIMLEFT}])
Result:
(My Tab )
87
Version 1.9.7
TRIMRIGHT – remove whitespace characters from the Right of the value
Format:
[FORMAT,VALUE,{TRIMRIGHT}]
Example:
([FORMAT,” My Tab ”,{TRIMRIGHT}])
Result:
( My Tab)
Encoding, Decoding
ENCODEURI – convert the value to a ANSI standard URI formatted value for query string pass through
from a real ASCII value
Format:
[FORMAT,VALUE,{ENCODEURI}]
Example:
([FORMAT,”!@#$ %^&*()<>=&”,{ENCODEURI}])
Result:
!%40%23%24+++%25%5e%26*()%3c%3e%3d%26
DECODEURI – convert the value from the ANSI standard URI formatted query string value to a real
ASCII value
Format:
[FORMAT,VALUE,{DECODEURI}]
Example:
([FORMAT,”!%40%23%24+++%25%5e%26*()%3c%3e%3d%26”,{DECODEURI}])
Result:
!@#$ %^&*()<>=&
ENCODEHTML – convert the ASCII value containing HTML formatting to a standard, non-HTML
handled format. In real terms, replacing the HTML formatting with escaped HTML formatting, for example: „<‟
becomes „<‟.
Format:
[FORMAT,VALUE,{ENCODEHTML}]
Example:
([FORMAT,”<li>This is a test & it works</li>”,{ENCODEHTML}])
Result:
<li>This is a test & it works </li>
88
Version 1.9.7
DECODEHTML – convert the escaped HTML format with the true ASCII value, for example: „<‟
becomes „<‟.
Format:
[FORMAT,VALUE,{ DECODEHTML}]
Example:
([FORMAT,”<li>This is a test & it works </li>”,{DECODEHTML}])
Result:
<li>This is a test & it works</li>
ENCRYPT – At times you may require the ability to Encrypt your value using a specific Key value for the
encryption itself. To do this, use the Encrypt formatter with the desired Key as the parameter.
Format:
[FORMAT,VALUE,{ENCRYPT:KEY}]
Example:
([FORMAT,”<li>This is a test & it works</li>”,{ENCRYPT:12341253214321FA}])
Result:
JSFhfhiapfahpifwPIip2ip5fip%
DECRYPT – At times you may require the ability to Decrypt your value using a specific Key value for the
decryption itself. To do this, use the Decrypt formatter with the desired Key as the parameter.
Format:
[FORMAT,VALUE,{DECRYPT:KEY}]
Example:
([FORMAT,”JSFhfhiapfahpifwPIip2ip5fip%”,{DECRYPT:12341253214321FA}])
Result:
<li>This is a test & it works</li>
Runtime Verification and Validation
ISEMPTY – evaluate the value to determine if the value is empty, having a length of zero. In which case, a
default value can be utilized in its place.
Format:
[FORMAT,VALUE,{ISEMPTY:DEFAULT}]
Example:
([FORMAT,”My Tab”,{ISEMPTY:No Tab Name provided }])
([FORMAT,””,{ISEMPTY:No Tab Name provided }])
Result:
My Tab
No Tab Name provided
89
Version 1.9.7
ISINROLE – returns a Boolean True or False value, identifying whether the current user is a member of a
specific role (by name or id).
Note: Super Users are ALWAYS True in this scenario. Additionally, IsInRole supports a check if the user is in
ANY of the roles specified by delimiting the Role Names with semicolon: Administrators;Registered Users;
Format:
[FORMAT,VALUE,{ISINROLE}]
Example:
([FORMAT,”Administrators”,{ISINROLE}])
Result:
True
ISSUPERUSER – returns a Boolean True or False value, identifying whether the current user is a super
user within the environment. (NEW)
Format:
[FORMAT,,{ISSUPERUSER}]
Example:
([FORMAT,,{ISSUPERUSER}])
Result:
True
ISNUMERIC – returns a Boolean True or False value, identifying whether the value is a numeric format, or
if it is a string value (non-numeric)
Format:
[FORMAT,VALUE,{ISNUMERIC}]
Example:
([FORMAT,”Not a Number”,{ISNUMERIC}])
([FORMAT,”12.435”,{ISNUMERIC}])
Result:
False
True
ISDATE – returns a Boolean True or False value, identifying whether the value is a date format, or if it is a
non date format.
Format:
[FORMAT,VALUE,{ISDATE}]
Example:
([FORMAT,”Not a Date”,{ISDATE}]) ([FORMAT,”12/4/1935”,{ISDATE}])
Result:
False True
90
Version 1.9.7
CANEDIT – returns a Boolean True or False value, identifying whether the current user has been granted
Edit access to the specific module.
Format:
[FORMAT, ,{CANEDIT}]
Example:
([FORMAT,,{CANEDIT}])
Result:
True
EXISTS – identifies whether the value, evaluated as a file path, points to an existing file, or a non existing
file. This value is returned as a Boolean True or False.
Format:
[FORMAT,VALUE,{EXISTS}]
Example:
([FORMAT,”C:/inetpub/item4/test.txt”,{EXISTS}])
([FORMAT,”~/images/xml.gif”,{EXISTS}])
Result:
True
True
STARTSWITH – returning a Boolean True or False value, identifies whether the value begins with the
designated character value. (NEW)
Format:
[FORMAT,VALUE,{STARTSWITH:SEARCH}]
Example:
([FORMAT,”My Tab”,{STARTSWITH:My}])
([FORMAT,”My Tab”,{STARTSWITH:Our}])
Result:
True
False
91
Version 1.9.7
ENDSWITH – returning True or False, identifies if the value ends with the designated value.
Format:
[FORMAT,VALUE,{ENDSWITH:SEARCH}]
Example:
([FORMAT,”My Tab”,{ENDSWITH:ab}])
([FORMAT,”My Tab”,{ENDSWITH:abs}])
Result:
True
False
CONTAINS – returns True or False, identifies whether the value contains the designated character value
Format:
[FORMAT,VALUE,{CONTAINS:SEARCH}]
Example:
([FORMAT,”My Tab”,{CONTAINS:ab}])
([FORMAT,”My Tab”,{CONTAINS:abs}])
Result:
True
False
INDEXOF – returns the first index (position) of the item for which you are searching within the string
Format:
[FORMAT,VALUE,{INDEXOF:SEARCH}]
Example:
([FORMAT,”My Tab”,{INDEXOF:ab}])
([FORMAT,”My Tab”,{INDEXOF:abs}])
Result:
4
-1
LASTINDEXOF – returns the last index (position) of the item for which you are searching within the
string
Format:
[FORMAT,VALUE,{INDEXOF:SEARCH}]
Example:
([FORMAT,”My Tab Tabs”,{LASTINDEXOF:ab}])
([FORMAT,”My Tab Tabs”,{LASTINDEXOF:abs}])
Result:
8
8
92
Version 1.9.7
Advanced Tab and Custom Look-ups
TABID – replaces the provided Tab Name value with the associated TabID
Format:
[FORMAT,TABNAME,{TABID}]
Example:
[FORMAT,My Tab,{TABID}]
Result:
318
TABID:COLUMN
- replaces the provided value with the TabID based on a lookup on the provided
Column name.
The Column provided within the syntax identifies which column is used as the lookup or search field within
the Tabs table for the designated TabId. The result is always the First occurring value within the designated
lookup. (NEW)
Format:
[FORMAT,VALUE,{TABID:COLUMN }]
Example:
[FORMAT,My Tab,{TABID:Title}]
Result:
318
TABNAME – replaces the provided value with the TabName of the tab, given the specified TabId
value.
Format:
[FORMAT,TABID,{TABNAME}]
Example:
[FORMAT,318,{TABNAME}]
Result:
My Tab
93
Version 1.9.7
TABTITLE – replaces the provided value with the Title of the tab, given the specified TabId value.
Format:
[FORMAT,TABID,{TABTITLE}]
Example:
[FORMAT,318,{TABTITLE}]
Result:
My Tab
TABDESCRIPTION – replaces the provided value with the Description of the tab, given the
specified TabId value.
Format:
[FORMAT,TABID,{TABDESCRIPTION}]
Example:
[FORMAT,318,{TABDESCRIPTION}]
Result:
My Tab – used for locating all my modules
SQLFIND – provides a rapid, integrated, and simple look-up ability against any of the provided tables
within the database with a specified value contained in a specific column, and returns the value of the
identified return column.
You can use this to look up any value within any table and return the first result identified quickly and
easily.
Format:
[FORMAT,VALUE,{SQLFIND: TABLENAME, SEARCHCOLUMN, RESULTCOLUMN }]
Example:
[FORMAT,[email protected],{SQLFIND:employee,email_address,employee_id}]
[FORMAT,Home,{SQLFIND:Tabs,Title,TabId}]
[FORMAT,Maryland,{SQLFIND:UserProfile,Value,UserID}]
94
Version 1.9.7
Coalesce
The COALESCE tag provides extensive capabilities, acting as a first available determination conditional as well as
providing the ability to apply multiple formatters to the resulting value. The COALESCE tag can be used for one or
more values, and can act as a complete replacement for the FORMAT tag which only provides a single formatter
possibility.
The basic concept of COALESCE is simple; iterating through the provided Name and Variable Type values, the
system identifies the first value which is NOT EMPTY and assigns that as the source. Then once discovered, it
applies the formatters, in order left to right, as prescribed. The structure of the tag consists of Name VariableType
pairs, separated by a comma. Optionally, you may use a Name of a column as the value, or, when text is required, a
Quoted value can be assigned directly and Text can be used as the Variable Type. Finally, you may optionally
append as many formatters as you desire to the COALESCE value (see Format tag).
When is this useful?
Whenever developing modules which act as edit forms, and employ AJAX calls to populate items within the form
you will require a determination of which value you want to use for your form value. For instance, if you loaded
contact information out of the database by a specific ContactID value the determination of whether the [FirstName]
column value or the [frmFirstName,Form] form value should be utilized. This comes into question if you are posting
back the form when the user selects the Country list to populate the Region selection. In classic ListX you would
need to check if the Form element existed in the incoming form postback – if so you would want to use the form
value, otherwise you would want to use the column value.
Additionally, you may find times that you want to execute multiple Formatters against a single value. In classic ListX
you would need to Nest Format tags into one another to produce the same result as the COALESCE.
Coalesce Syntax
Syntax
[COALESCE,Name,VariableType…, FORMAT…]
Example
[COALESCE,frmName,Form,ColumnName,,”Default Value”,Text,{ENCODEHTML},{LEFT:5}]
Examples
The following eight examples are repeated three times with different incoming parameters, specified prior to the
executions by the Current Settings tag. If the field doesn‟t exist in the request, the value is displayed as
“Unassigned”. If it is assigned, but it has a zero length value – it is displayed as “Assigned but Empty”. Check the LP
area of the website to download this example set.
95
Version 1.9.7
Example 1 – Column, Unassigned Querystring, Unassigned Form
Column - TabName: Host
Querystring - Tab: Unassigned
Form - frmTabName: Unassigned
Multiple Values with Empty Form element and Single Formatter
Example:[COALESCE,Tab,Querystring,frmTabName,Empty Form,Tabname,,{ENCODEHTML}]
1. If the Tab value from the Querystring contains a value which is not Empty it is the Source of the
COALESCE. Otherwise, go to next element.
2. If the frmTabName value from the Form exists in the form (even if it has no content) it is the Source of the
COALESCE. Otherwise, go to next element. (This only fails if the form element doesnt exist yet).
3. If the Tabname column from your query contains a value with a length greater than zero, it is the source of
the COALESCE.
4. Finally, if the Source has been identified, it will be passed through the ENCODEHTML formatter.
Result: Host
Multiple Values with Standard Form and Single Formatter
Example:[COALESCE,Tab,Querystring,frmTabName,Form,Tabname,,{ENCODEHTML}]
2. If the frmTabName value from the Form is not Empty, it is the Source of the COALESCE. Otherwise, go to
next element. (Unlike Empty Form, if this value is empty it Fails to be assigned as the Source).
the COALESCE.
Result: Host
Multiple Values
Example:[COALESCE,Tab,Querystring,frmTabName,Form,Tabname,]
the COALESCE.
4. Finally, if the Source is returned with no formatters.
Result: Host
Multiple Values including Default Text value and Single Formatter
Example:[COALESCE,Tab,Querystring,frmTabName,Form,Tabname,,Some <> Value,Text,{ENCODEHTML}]
the COALESCE.
4. Otherwise, Some <> Value is set as the Default Source as it is returned as plain text.
Result: Host
Multiple Values including Default Text value and Multiple Formatters (Encode then Left)
Example:[COALESCE,Tab,Querystring,frmTabName,Form,Tabname,,Some <>
Value,Text,{ENCODEHTML},{LEFT:6}]
96
Version 1.9.7
2.
If the frmTabName value from the Form is not Empty, it is the Source of the COALESCE. Otherwise, go to
the COALESCE.
5. Next, the Source has been identified, it will be passed through the ENCODEHTML formatter.
6. Finally, the Source will be passed through the LEFT:6 formatter to return the first six characters of the
HTML Encoded value.
Result: Host
Multiple Values including Default Text value and Multiple Formatters (Left then Encode)
Value,Text,{LEFT:6},{ENCODEHTML}]
the COALESCE.
5. Next, the Source has been identified and will be passed through the LEFT:6 formatter to return the first six
characters of the Source.
6. Finally, the First six characters of the original Source will be passed through the ENCODEHTML formatter.
Result: Host
Multiple Values including Default Text value and Multiple Formatters (Left then Right)
Example:[COALESCE,Tab,Querystring,frmTabName,Form,Tabname,,Some <> Value,Text,{LEFT:6},{RIGHT:1}]
the COALESCE.
6. Finally, the First character of the resulting value will be returned from the RIGHT:1 formatter
Result: t
Single Value and Multiple Formatters
Example:[COALESCE,Tab,Querystring,{LEFT:6},{RIGHT:3}]
1. The Tab value from the Querystring is the Source of the COALESCE.
Result:
97
Version 1.9.7
Example 2 – Column, Unassigned Querystring, Assigned Form
Form - frmTabName: ABCDEFGHIJKLMNOP
the COALESCE.
Result: ABCDEFGHIJKLMNOP
the COALESCE.
Multiple Values
the COALESCE.
the COALESCE.
98
Version 1.9.7
1.
If the Tab value from the Querystring contains a value which is not Empty it is the Source of the
the COALESCE.
HTML Encoded value.
Result: ABCDEF
the COALESCE.
Result: ABCDEF
the COALESCE.
Result: F
Result:
99
Version 1.9.7
Example 3 – Column, Unassigned Querystring, Assigned Empty Form
Form - frmTabName:
the COALESCE.
Result:
the COALESCE.
Result: Host
Multiple Values
the COALESCE.
Result: Host
the COALESCE.
Result: Host
100
Version 1.9.7
1.
the COALESCE.
HTML Encoded value.
Result: Host
the COALESCE.
Result: Host
the COALESCE.
Result: t
Result:
101
Version 1.9.7
Example 4 – Column, Assigned Querystring, Assigned Form
Querystring - Tab: 1234567890
Form - frmTabName: ABCDEFGHIJKLMNOP
the COALESCE.
Result: 1234567890
the COALESCE.
Result: 1234567890
Multiple Values
the COALESCE.
Result: 1234567890
the COALESCE.
Result: 1234567890
102
Version 1.9.7
1.
the COALESCE.
HTML Encoded value.
Result: 123456
the COALESCE.
Result: 123456
the COALESCE.
Result: 6
Result: 456
103
Version 1.9.7
104
Version 1.9.7
Columns and Column Templates
To facilitate the ability for quick layout and structural definition of your output, especially when dealing with dynamic
structures, or when simple grids are employed for layout, the COLUMNS tag provides the ability to bind a template
directly to the columns contained within the query result.
Tip: Even when you will want an advanced layout, fixed specifically for the output of your queries, it is very useful to
execute your query against the COLUMNS tag initially to produce a template you can use for your fixed columns.
Just setup the tag, then copy the output and paste it back in as your Detail / Header and Footer template.
Columns Syntax
The example below provides a demonstration of the COLUMNS tag structure, for use within your template structure.
The tag is rather straight forward – it simply loops through the list of columns provided within result of your query,
and generates the output based on your template requirements. You may provide the Template per column, a
separator to use between column template, a flag identifying whether or not to place the separator before the first
column and after the last column, and a list of columns to ignore from the result set, if there are columns you desire
to hide from view.
Syntax
{COLUMNS,ColumnTemplate,SeparatorTemplate,SeparatePrePost,Optional Ignored Columns}
Example
The provided sample below is an extremely simple ListX configuration, which displays the list of Users from the User
table. To use this sample, first create a new ListX module, and under the general settings, set the AJAX to enabled,
and the number of records per page to 10. Next, add a Header/Footer template to the List Item templates, then use
the settings provided below to round out the configuration.
Query
Select * from Users
Group Item Header
<Table width=100%>
<tr>
{COLUMNS,
"<th>[Column.Name,System]</th>",
"",
False,
UserID,AffiliateID}
</tr>
Detail Item
<tr>
{COLUMNS,
"<td>[[Column.Name,System]]</td>",
"",
False,
UserID,AffiliateID}
</tr>
Group Item Footer
</table>
105
Version 1.9.7
Note: In the above sample, the Detail Item format uses two brackets surrounding the Column.Name system tag.
This is not a typo. The reason for the double bracket is simple. The rendering engine will first replace the inner tag
[Column.Name,System] with the physical column name contained in your table. For instance – Username. The
result would be [Username], which would then be rendered with the actual value of the Username column for the
current record in your result.
Column Template
To provide the basic template for your column output, the Column Template is used for the physical output to be
rendered for each Column. Two variables are available during Column and Separator Template Rendering.
[Column.Name,System] renders the Name of the column; [Column.Index,System] renders the Index of the column
(its visible position).
Example: "<td>[[Column.Name,System]]</td>"
Separator Template
Occasionally, a separator is required to appear between each of your columns. The Separator template identifies
the physical output to be rendered between your columns.
Example: "|"
Separate Pre Post
If you require output that also places your separator BEFORE the first column AND AFTER the last column, set this
parameter to TRUE, otherwise leave it empty or set it to FALSE.
Optional Ignored Columns
Since you may want to ignore specific columns in the resulting table, we provide the ability to output all of your
columns EXCEPT for a distinct list. You may add as many Ignored columns, by name, to your parameter list. This
columns may either appear in a comma delimited list:
Example: {COLUMNS......,"ColumnA,ColumnB,ColumnC"}
Or, they may appear as direct parameters to the tag structure:
Example: {COLUMNS......,ColumnA,ColumnB,ColumnC}
106
Version 1.9.7
Action Items
Setting session variable values to specific column values and immediately transporting to the Tab/Page associated
with consuming those values is made simple with out Action syntax. All runtime actions like Sorting, Interactive Lists
and Actions utilize the similar formatting structures contained within curly braces {...}. Actions require four
parameters. The first is simply the type of interaction performed, in this case ACTION. The second parameters, the
name of the column (inside or out of square brackets) passed to the session variable. Third, the name of the
Session Variable where the Column Value will be stored. And finally, the link or TabId which the Action will be
directed towards. The block for action will render a formulated HREF tag which is required for Anchor tag elements.
The action tag will execute a javascript function built in to ListX, so the ACTION element should always occur within
an ANCHOR tag. Follow the syntax definitions provided to assist in building the appropriate output block.
Tip: Actions do not always need to leave the current page when clicked. Sometimes you will simply be drilling
deeper into a query, or changing the information provided on other modules in the same page. Leaving the Link
blank or setting it to the current tab will easily provide this behavior.
Action Syntax:
{ACTION,ColumnValue,SessionVariableName,Link,Optional Variable Type,Option render HREF }
You may also use the ACTIONS syntax to execute multiple variable assignments at once.
{ACTIONS,ColumnValue1,SessionVariableName1,Variable Type1,ColumnValue2,SessionVariableName2,Variable
Type2...,Optional Link}
Example
<a {ACTION,[EventLogId],CurrentEventLogId,62}/>...<a/>
Additionally, you could send Module Communication Messages through the same Action tags - the following sample
broadcasts a Message with a Type of "DeleteItem" and a value appearing in the EventLogId column:
<a {ACTION,[EventLogId],DeleteItem,,Message}/>...<a/>
Suppose you had a listing with a column that was an edit button. You need the button to assign the primary key value from the
row to a session variable. What if your primary key were a composite key, as is the case with ModuleSettings? Use the
ACTIONS tag:
<a
{ACTIONS,[ModuleID],SettingModuleID,Session,[SettingName],SettingSettingName,Session,
85}/>...<a/>
Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Action Items are always contained
within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element,
ACTION will be the first parameter. Other types of actions include SORT,SORTHEADER, and other types including
CHECKLIST.
Column Name
The value from the column column which will be placed in the Session Variable assigned as the next parameter.
The variable may be a single column name, or could utilize the Column Value syntax to build combined - or
formatted values. (See Column Values)
Variable Name
The core of interactive elements on the web is provided by utilizing some type of shared variable which can be
107
Version 1.9.7
assigned or read from different modules within your overall system. ListX is capable of reading and writing to
variable located in the Session, QueryString, Cookie and ViewState. Place the name of the variable which will store
the value of the column chosen in this interactive element.
Link
Finally, once you have specified which variable you will utilize in your action, and where that variable should be
stored, you must provide a link which will be followed upon completion of the variable assignment. This value is
normally the Id of a Tab, or could be the tab name, URL, or value from a module setting. In the case of the
ACTIONS tag, the Link is optional, but you MUST have the , in place anyway.
Optional Variable Type
ListX is capable of reading and writing to variable located in the Session, QueryString, Cookie and ViewState. The
default value to which ListX binds is Session, but it is simple to bind to any of the other types, just provide the name
of the type in this position.
Optional Render HREF
ListX generates the standard href=”javascript:__doPostBack” logic, so, if you want to use an action tag within an
onclick, or a physical javascript tag – set the last parameter to False, as True is the default. When false, just the
__doPostBack section will be generated.
108
Version 1.9.7
Checkbox and Radio Lists
Providing the added interaction of check lists, or radio lists with automatic selection of all items under a group
header checkbox item is made simple using the integrated syntax. All runtime actions like Sorting, Interactive Lists
and Actions utilize the similar formatting structures contained within curly braces {...}. Check Lists, Radio Lists,
Check List Items, and Check Items all have slightly different syntax - so follow the links to learn more about each of
the syntax elements. Follow the syntax definitions provided to assist in building the appropriate output block.
Tip: Sometimes the easiest way to provide visual affect of the sorting, besides the actual rendered output is to show
a flag indicating the direction of the sort. While this can be done in a complex manner of rendering special images
per column, or changing a variety of visual indicators, it is easiest to simply define a background image within a CSS
class definition, and simply change the name of the class in the anchor tag on each of the sort orders.
Check List Syntax
Check Lists are generally made up of a header and or footer group checkbox, providing the ability to check all child
items or detail items currently visible by checking or unchecking the grouped header checkbox. Check Lists require
a Check List Header which provides the group name and session variable name. The child items of that group
should be defined as Check List Items, which provide the group name to which they belong, and the name of the
column to place in the session variable array.
Header/Footer Check List Syntax:
{CHECKLIST,GroupName,SessionVariableName,Optional Boolean Value}
Detail Check List Item Syntax:
{CHECKLISTITEM,GroupName,ColumnName,Optional Boolean Value}
Example
Group Item Header
<table>
<tr>
<th>{CHECKLIST,Select,CurrentEventLogIDs}</th>
</tr>
Detail Item
<tr>
<td>{CHECKLISTITEM,Select,[EventLogID]}</td>
</tr>
Group Item Footer
</table>
Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Check lists and Check list Items are
always contained within curly braces {...} with the first parameter identifying the type of interaction. In the case of
this element, CHECKLIST or CHECKLISTITEM will be the first parameter. Other types of actions include
SORT,SORTHEADER, and other types including CHECKLIST.
109
Version 1.9.7
Group Name
To provide automated checking facilities within ListX, automatically checking all visible items within a specific group,
a Group Name must be provided. The Group name can be anything - and in cases where you will have nested
groups, the Group Name should contain a Column Value from the parent so that Outer Groups can be checked in
unison with inner groups (cascading).
Session Variable Name
variable located in the Session array. Place the name of the session variable which will store the value of the column
chosen in this interactive element. The variable in this case will contain an array list of elements. The array list is
automatically transformed when used within Queries as a comma delimited representation. Values that were
defaulted to Checked or Unchecked will be placed into either the Checked array, identified by the Session Variable
Name, or in the Unchecked array, in the Session Variable Name, prefaced by "Un", as in "CheckedItemList" and
"UnCheckedItemList".
Column Name
The name of the column which will be placed in the Session Variable assigned to the group. The variable may be a
single column name, or could utilize the Column Value syntax to build combined - or formatted values.
Optional Boolean Value
Using standard column formatting, this value optionally allows you to specify the default value for this check item.
The value can either be true/false, or 0/1. The default value specifies whether the item is defaulted to checked, or
unchecked.
Singular Check Item Syntax
Check boxes which are provided in the output, but are not related to any specific group header, or check list header
are defined as CHECKITEM elements. Check Items require a session variable name and the name of the column to
place in the session variable array.
Check Item Syntax:
{CHECKITEM,SessionVariableName,ColumnName,Optional Boolean Value }
Example
Detail Item
<tr>
<td>{CHECKITEM,CurrentEventLogIDs,[EventLogID]}</td>
</tr>
Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Check Items are always contained
within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element,
CHECKITEM will be the first parameter. Other types of actions include SORT,SORTHEADER, and other types
including CHECKLIST.
110
Version 1.9.7
automatically transformed when used within Queries as a comma delimited representation. Values that were
Column Name
unchecked.
How to Use Checklists in your Solution
For the sake of understanding and utilizing the Checklists, and an overview of how the checklists operate within your
variable values, this section of the documentation is provided. The reasoning behind the operation of the Checklist,
in terms of what items physically appear within your Checked and Unchecked variables, is at times a bit complicated
to understand, because these variables do not physically store all items that *ARE CHECKED*, but rather, those
items which are *NOW CHECKED*, based on their original unchecked state. So generally, this concept is missed
because you need the big picture. Instead of assuming you have items 1 through 10 in a list, let‟s say you have
items one through 2 million in a list. If your idea is to let the user add and remove items from their list by checking
and unchecking them - you are in the right. The problem is that we had to throw a curve ball into the mix.
If you are dealing with 2 million records (or even 10 pages of records), checking each entry in the box will setup the
indicator as to whether an item was Checked or Unchecked. Meaning - we aren't physically recording everything
that is checked in the database into your runtime session - that would be crazy - what if you checked everything.
Instead - we are checking the state of what has changed.
Also - before we break down this sample – it‟s important to know that the items are Checked and Unchecked
immediately via AJAX, so as soon as you check the box – its change of state is now recorded in your variable on the
web server.
Now for the proper handling of this scenario and others which may vary from your initial reason for using the
checklist, please continue to read below this even if this doesn't sound like it makes sense for your needs. I will give
another solution for smaller sets of data (like subqueries directly after this sample section).
Example
Assume are attempting to use a checkbox list for a list of 2 thousand attributes. The user will be checking and unchecking the items that are associated with their specific Location. For example - your table structure may be
something like this:
Table: Attribute
AttributeID int
Name varchar(50)
Table: AttributeLocation
AttributeID int
LocationID int
111
Version 1.9.7
Table: Location
LocationID int
Name varchar(50)
Assuming the information about the tables above, the AttributeLocation table will contain the list of locations per
attribute (one attribute can have many locations and one location may have many attributes – many-to-many). So
the user is presented with the Attribute Detail and a paged checklist of 2000 Locations left joined against the
AttributeLocation table. The box next to each location is defaulted to “checked” when the AttributeID is not null
(thanks to the left join).
To begin, assume that we are using the CheckedAttributeLocations Session variable for runtime storage of the
changed states. This means that there will be a physical variable called UnCheckedAttributeLocations also containing any LocationID that was Unchecked (meaning it was originally defaulted to checked, so the state is dirty
and now unchecked).
At the time of rendering there may be 100 of the 2000 boxes checked and the remaining 1900 left unchecked. At
that moment, our Session variables look like this:
CheckedAttributeLocations: Empty
UnCheckedAttributeLocations: Empty
Assume that Locations “1”, “2” and “3” are checked by default, with “4”, “5”, “6” left unchecked by default. If we
uncheck “1”, “2”, “3” and check “4”, “5”, “6” our variables look like this:
CheckedAttributeLocations: 4, 5, 6
UnCheckedAttributeLocations: 1, 2, 3
Technically, by the understanding of this temporary state - of the original 100 entries that were checked, we have
removed three checks and added three unchecks.
Let's say you change your mind - and now Uncheck “5”. This is what the variable now contains:
CheckedAttributeLocations: 4, 6
UnCheckedAttributeLocations: 1, 2, 3
Notice – “5” is now not in either list - because it's state has not changed from the original request.
With that said - how do we fold the changes back into the database? Within the actions - when you want to save
your changes you simply do this.
First - delete everything that was UnChecked from your AttributeLocation table, because it is void from the system
now that it has been unchecked officially:
Assume @AttributeID is your AttributeID
Assume @UnCheckedItems is equivalent to your [UnCheckedAttributeLocations,Session] object
Delete from AttributeLocation where AttributeID = @AttributeID and LocationID in (@UnCheckedItems)
Next, insert the newly checked records into your AttributeLocation table Assume @AttributeID is your AttributeID
Assume @CheckedItems is equivalent to your [CheckedAttributeLocations,Session] object
112
Version 1.9.7
Insert into AttributeLocation(AttributeID,LocationID) select @AttributeID,LocationID from Location where LocationID
in (@CheckedItems)
That's it - you only made changes to the ones that physically were altered, the rest remained as they were in the
original state.
With all that said, if you have a very short list, it's actually more useful to use a standard checkbox approach - as
long as you do not need to page through your data. This is because if you add the following hypothetical items to
your template you will automatically receive the delimited list of checked items by checking on the form variable:
<Input type=checkbox name=chkValue id=chkValue value=”1” checked>
<Input type=checkbox name=chkValue id=chkValue value=”3”>
The result of the form variable would mean that [chkValue,Form] would equal a comma delimited list of 1,2,4,5
Radio Item Syntax
Radio buttons which are provided in the output and are related to specific selections in groups are defined as
RADIO elements. Radio Items require a group name, session variable name and the name of the column to place in
the session variable array.
Radio Item Syntax:
{RADIO,SessionVariableName,ColumnName}
Example
Detail Item
<tr><td>{RADIO,Select,[EventLogID],CurrentEventLogIDs}</td></tr>
Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Radio Items are always contained
within curly braces {...} with the first parameter identifying the type of interaction. In the case of this element, RADIO
will be the first parameter. Other types of actions include SORT,SORTHEADER, and other types including
CHECKLIST.
Group Name
To provide automated grouping facilities within ListX, automatically deselecting related radio items visible items
within a specific group, a Group Name must be provided. The Group name can be anything - and in cases where
you will have nested groups, the Group Name should contain a Column Value from the parent so that Outer Groups
can be combined in unison with inner groups (cascading).
Column Name
unchecked.
113
Version 1.9.7
automatically transformed when used within Queries as a comma delimited representation. . Values that were
114
Version 1.9.7
Sorting
Sorting your results by utilizing the built in syntax provided for controlling not only the rendered data order, but also
for dynamically modifying the standard, ascending and descending display headers is easy with our syntax
specification. All runtime actions like Sorting, Interactive Lists and Actions utilize the similar formatting structures
contained within curly braces {...}. The Sort syntax requires seven parameters. The Type of the action - SORT, the
name of the column used in the sort, the Standard display formatting, the Ascending display formatting, the
Descending display formatting, the default order (ASC,DESC or nothing), and the Index of the Sort relative to the
list. The sort Index is used to replace the occurrence(s) of any {SORTHEADER,Index} tag where the Index would be
the Sort Index contained in the sort tag.
Tip: The output functionality examines the resulting table from your query and replaces occurrences of the Column
Values with those identified in your table. If you are having trouble diagnosing occurrences of Column Names not
effectively replacing, turn the debug feature on and take a look at names of the columns. The names of these
columns are dire to the success of your sorting mechanisms - so double check those columns, and take a look at
the actual values stored within the sort tag.
Sorting Syntax
Sorting handlers are made up of a pair of syntax element. The first provides the ability to identify the structure of the
actual sorting configuration and handles all of the sort parameters including the sort index. The second is simply a
placeholder for the output of the sort configuration called the Sort header. The sort configuration element will render
a formulated HREF tag which is required for Anchor tag elements. The action tag will execute a javascript function
built in to ListX, so the SORT element should always occur within an ANCHOR tag. The SORTHEADER tag would
then be placed as the contents of the ANCHOR.
The sorting is a three click approach, iterating through the options of none, ascending and descending upon each
click from the mouse.
Sort Syntax:
{SORT,ColumnName,StandardText,AscendingText,DescendingText,DefaultOrder,SortIndex}
Sort Header Syntax:
{SORTHEADER,SortIndex}
Example
<tr>
<th><a {SORT,EventDate,Date,"Date <img src=asc.gif>", "Date <img
src=desc.gif>",ASC,7}>{SORTHEADER,7}</a></th>
</tr>
Interaction Type
All interaction elements for ListX utilize similar formatting to keep things uniform. Check lists and Check list Items are
always contained within curly braces {...} with the first parameter identifying the type of interaction. In the case of
this element, SORT or SORTHEADER will be the first parameter. Other types of actions include ACTION,RADIO,
and other types including CHECKLIST.
Column Name
The name of the column which will be sorted. The variable may be a single column name, or could utilize the
Column Value syntax to build combined - or formatted values.
115
Version 1.9.7
Note: If you are using table aliases within your query, the resulting sort will probably require these aliases as well.
Make sure you place the complete name of the column within the confines of the sort tag, otherwise your query will
cause errors upon execution.
Standard Text
The visible text displayed in place of your SORTHEADER placeholder when no sorting is currently enabled.
Ascending Text
The visible text displayed in place of your SORTHEADER placeholder when the column is marked as rendering is
Ascending order.
Descending Text
The visible text displayed in place of your SORTHEADER placeholder when the column is marked as rendering is
Descending order.
Default Order
The default order of the data sorting upon first entry. Possible values are empty, ASC, ASC TOGGLE (Toggle only
between ASC and DESC) DESC, and DESC TOGGLE (Toggle only between DESC and ASC).
Sort Index
The sort Index is used to replace the occurrence(s) of any {SORTHEADER,Index} tag where the Index would be the
Sort Index contained in the sort tag.
116
Version 1.9.7
Sub query
ListX now allows the use of embedded sub queries to get details of information that are otherwise unavailable to
your primary query. An example may be if you are using ListX to design an entry form and you need a <select>
list. This is easily achievable with the Sub query action structure. All runtime actions like Sorting, Interactive Lists
and Actions utilize the similar formatting structures contained within curly braces {...}. The Sub query syntax has a
varying set of parameters, depending on the task that needs to be achieved. The Type of the action - SUBQUERY,
followed by Name to name the sub query. This way, a sub query may be re-referenced by name and the query will
not be processed again, saving valuable database access time. The Query must be defined only if it's the first time
this named sub query is encountered. There are several parameters dictating formatting and pre-selection of
values.
Tip: Use the Name parameter to prevent re-querying the database unnecessarily.
Sub query Syntax
A Sub query is used to render the output of a query other than the primary query into the item holders for an HTML
element. Some examples include as options in a select element, line items in an order list, or any other HTML
element which repeats.
Sub queries have several parameters, most of which are optional.
Sub query Syntax:
{SUBQUERY,Name,[Query],[Format],[AlternateFormat],[SelectedFormat],[SelectedField],[SelectedItems],[UseCach
e],[CustomConnection]}
Example
<select name="cboWidgets">
{SUBQUERY, Name="qryWidgets", Query="SELECT * FROM Widgets", Format="<option
value= '[ID]'>[Name]</option>", SelectedFormat="<option value='[ID]'
SELECTED>[Name]</option>", SelectedField="ID",
SelectedItems="6",UseCache=False}
</select>
NOTE: If your Sub query contains columns which are you referencing which match names of column in the
Rendering query, or names of variables which exist in the System Information (like TabID, ModuleID, FirstName,
LastName etc. You will need to escape the column values if you are attempting to display them from the Sub Query.
For instance:
<select name="cboTabs">
{SUBQUERY, Name="qryTabs", Query="SELECT * FROM Tabs", Format="<option value=
'\[TabID\]'>\[TabName\]</option>", SelectedFormat="<option value='\[TabID\]'
SELECTED>\[TabName\]</option>", SelectedField="TabID",
SelectedItems="18",UseCache=False}
</select>
Name
Name the sub queries on a page so that if the query needs to be used in more than one place, it can be referenced
without the [Query] parameter and not have to re-query the database.
Query
117
Version 1.9.7
Optional if this named sub query has been declared earlier in the page. The query accepts all Query Options and
will perform the replacement prior to execution. If the query is designed to use a value from the main query for the
current row (i.e., "SELECT * FROM Tabs WHERE ParentID = [TabID]", where [TabID] comes from the primary
query), then the query will execute every time the [TabID] value changes.
Format
This is the HTML that will be repeated for each row, or every first row if [AlternateFormat] is implemented. This
works just like the ListX List Item Detail element. Column and variable values will be replaced with actual values.
AlternateFormat
This is the HTML that will be repeated for every other row. This works just like the ListX Alternate Item Detail
element. Column and variable values will be replaced with actual values.
SelectedFormat
This is the HTML that will be repeated for each row matching the [SelectedField] to [SelectedItems]. This works
just like the ListX List Item Detail element, except it is only rendered on rows in the [SelectedItems] list. Column
and variable values will be replaced with actual values.
SelectedField
The field name in the query for which the [SelectedItems] list applies.
SelectedItems
A comma-delimited list of values for the [SelectedField] column. Anytime the rendering engine encounters a row
where [SelectedField] IN ([SelectedItems]) then the [SelectedFormat] item is what gets rendered.
UseCache
To save time and performance on servers, it is occasionally wise to use the cache for storing sub query information
– for instances where the data will not change frequently, ie. A List of Countries. Since ListX is a completely dynamic
engine, you maybe filtering your Sub Queries via means located within the site, and will, therefore, not be able to
use the cache. To keep the sub query data current – set UseCache=False. The default is always True, so, if you are
missing this tag and discover that your query results are not changing – you need to add this option.
Connection
If your subquery needs to be pulled from a database connection other than the standard Dotnetnuke connection
provided for your instance, you can specify the ODBC connection string to use for the connection by adding a
connection string. For example:
Connection=” Provider=sqloledb;Data Source=MyOtherDatabase;Initial Catalog=pubs;Integrated
Security=SSPI;”
A complete breakdown of connection string is provided in the appendix titled: Connection Strings.
118
Version 1.9.7
Alternate
The need to alternate between specific values at any given position within the ListX engine arose, and the
ALTERNATE tag was added to provide just that capability. This is useful in scenarios where you need to switch
between two class names to alternate background colors on Group rows, rather than detail, but this is not the only
solution. Since it can alternate between as many items as you want – you can alternate between 100 different colors
or text values if you desire.
Alternate Syntax
The syntax is fairly straightforward. The definition includes the first parameter, used to uniquely identify the
Alternate item key. This key will be unique to control the current index within the alternating list. The additional
parameters make up the list of alternates.
Alternate Syntax:
{Alternate,AlternateName,Value,Value,Value,Value…}
Example
<span class=”{ALTERNATE,myAlt,GroupItem,GroupItemAlt}”></span>
<span>{ALTERNATE,aplhaList,a,b,c,d,e,f,g,h,I,j,k,l,m,,o,p,q,r,s,t,u,v,w,x,y,z}.
[TabName]</span>
119
Version 1.9.7
Aggregations
Because you always need to provide summary information within websites, grids and other interfaces, it become
apparent that it would be far easier to control the tallies within the rendered UI rather than provide additional
complex query joins to support them. The concept provided by ListX is quite simple, it can SUM or COUNT values
contained within records in your query, and provide a means of pulling the current tally at any time in the interface,
either at grouping levels or within your global footer.
Aggregation Syntax
All aggregation tags contain the same logical structure. One tag, the physical SUM or COUNT tag provides a way to
tally your values without physically rendering any actual output. The second, a simple Variable to poll to grab the
total, uses an Action variable tag, pulling from the Action collection.
SUM Syntax:
{Sum,VariableName,Value}
COUNT Syntax:
{Count,VariableName,Value}
Example
(Detail)
<span>[Dollars]{SUM,totalDollars,[Dollars]}{COUNT,totalisActive,[isActive]}</span>
(Group Footer)
<span>[totalDollars,Action] [totalisActive,Action]</span>
120
Version 1.9.7
Set
There are times within your content that your may need a customized way of calculating or tallying a variable value
within the runtime of your page. This is made possible through the use of the SET tag. With this tag, you can specify
the Name of the value, Value which you want to assign, and the Collection which houses the value.
Set Syntax
The syntax is familiar, because it is based off of the standard tag for handling page post backs, called ACTION. This
tag, requiring fewer parameters, is easy to maintain.
{Set,VariableName,Value,Collection}
Variable Name
The name of the value, as it exists within your environment. The typical variable used by the Set command would be
a temporary storage variable, stored within the Action collection, a data store specifically for temporary request
parameters.
Value
The value which will be placed in the Variable assigned as the next parameter. The physical value may come from a
existing ListX column or other calculated value.
Collection
ListX is capable of reading and writing to variable located in the Action (temporary variable collection), Session,
QueryString, Cookie and ViewState. It is simple bind to any system type; just provide the name of the type in this
position.
Example
{SET,myCount,{MATH,”[myCount,Action]+[Price]/2”},Action}
121
Version 1.9.7
122
Version 1.9.7
MATH
The MATH tag provides the ability to render and display any evaluation quickly and easily within any portion of the
ListX engine. The provided math library functionality is extensive, and provides the ability to use not only the Math
tag, but to also use Mathematical logic in any provided IIF condition Sometimes, it's necessary to have conditions
directly in your list. MATH can be used in any of the rendering areas or in the query itself.
Tip: If you find yourself doing deep comparisons with many „flags‟ within your system, try simply combining these
into a bit array and using standard bitwise logic operations, provided with the AND:BIT, OR:BIT, XOR:BIT and
NOT:BIT operations.
MATH Syntax
The syntax is fairly straightforward. Ensure that your mathematical formula is solvable; that is, a value can be
determined no matter what the physical operations are. As most people are familiar, the standard mathematical
order of operations applies – and standard parenthetic logic is provided. The following order of operations is utilized
by the ListX engine (review the Math library symbols and functions provided further in this section):
FIRST: ( )
SECOND: * ^ % / \
THIRD: + FOURTH: AND OR XOR AND:BIT OR:BIT XOR:BIT
MATH Syntax:
{MATH,”Equation”}
Example
<span>The resulting value is: {MATH," ABS((7 % 14)/Sin(0.05) + pi() / 12)"}
</span>
Result:
The resulting value is: 140.320149739507
BITWISE Example
<span>The resulting value is: {MATH,"NOT:BIT 1000 AND:BIT 1011"}
</span>
Result:
The resulting value is: 0011
123
Version 1.9.7
Condition Example
<span>The resulting value is: {MATH,"12+17=29 AND 1+4=6-2"}
</span>
Result:
The resulting value is: False
Condition Example (Strings)
<span>The resulting value is: {MATH,"12+17=29 AND te=test-st"}
</span>
Result:
The resulting value is: True
Note: You can use any, if not all of the mathematical operations within the same question, without fail. For instance:
Sin(35/100) + 12/18 % 4 <= ABS(16*(3-6)) AND SQRT(55123) = 55123^0.5
124
Version 1.9.7
Symbols and Functions
ListX supports an extensive array of mathematical functions, symbols and logical operators in order to fulfill nearly
any requirement. Review the list of definitions below to get a full grasp of the functionality provided within the ListX
Mathematical Library.
Symbols
()
Parenthesis – The appropriate grouping and enforcement of “out of order” operations
requires the need for the use of parenthesis. Group your mathematical statements within
parenthesis to force their evaluation before other items contained outside of the grouped
equation.
*
Example: (5 + 6) / 11
Multiplication – Standard multiplication is handled within ListX by using the asterisk symbol.
Since the asterisk is a standard symbol, it can occur with or without spaces.
^
Example: 5 * 6
Exponents – Raising a value to the power of another, is easily handled by the familiar
Exponent symbol.
%
\/
+
<
>
=
<=
Example: 5 ^ 6
Modulus – When you would like the identify the remainder of a division of two numbers, the
Modulus (mod) operator is available
.
Example: 15 % 4
Division – To determine the number of time one value is contained within another, division is
used.
Example: 5 /6
Addition – The simplest of operations, use the plus symbol, with our without spacing, to add
one value to another.
Example: 5 + 6
Subtraction – To subtract one value from another, simply use the standard dash operator.
Example: 5 - 6
Less Than – When used in comparison logic, the result of this equation, when the left hand
value is less than the right hand value, the result will be True, otherwise, the result will be
False.
Example: 5 < 6
Greater Than – When used in comparison logic, the result of this equation, when the left
hand value is greater than the right hand value, the result will be True, otherwise, the result
will be False.
Example: 5 > 6
Equal – When used in comparison logic, the result of this equation, when the left hand value
is equal to the right hand value, the result will be True, otherwise, the result will be False.
Example: 5 = 6
Less or Equal – When used in comparison logic, the result of this equation, when the left
hand value is less than or equal to the right hand value, the result will be True, otherwise,
the result will be False.
125
Version 1.9.7
Example: 5 <= 6
Greater or Equal – When used in comparison logic, the result of this equation, when the left
hand value is greater than or equal to the right hand value, the result will be True,
otherwise, the result will be False.
>=
<> !=
Example: 5 >= 6
Unequal – When used in comparison logic, the result of this equation, when the left hand
does not equate to the right hand value, the result will be True, otherwise, the result will be
False.
Example: 5 <> 6
Logic Operators
AND
OR
XOR
NOT
AND:BIT
OR:BIT
XOR:BIT
When you would like to combine multiple Boolean based comparisons into one
physical statement, in which both requirements are necessary to result in a True
Value, use the AND operator. When used against numeric values, the end operator
acts as a bit comparison.
Example: 5+1=6 AND 7 >= 6
physical statement, in which either of the requirements is necessary to result in a
True Value, use the OR operator. When used against numeric values, the end
operator acts as a bit comparison.
Example: 5+1=6 OR 7 >= 6
physical statement, in which only one of the requirements but never both is necessary
to result in a True Value, use the AND operator. When used against numeric values,
the end operator acts as a bit comparison.
Example: 5+1=6 XOR 7 >= 6
When you would like to return the opposite of a Boolean variable, the NOT operator
should be use
Example: 5+1=6 AND NOT 7 >= 6
To perform a bitwise comparison of two values in which you want all the bits to result
in 1 whenever both the left and right hand bits are one, is the AND:BIT operator.
Numbers and text values will automatically cast directly to bit arrays before handling.
The end result will be a bit array.
Example: 01101011 AND:BIT 11100010 = 01100010
o perform a bitwise comparison of two values in which you want all the bits to result in
1 whenever either the left or right hand bits are one, is the OR:BIT operator. Numbers
and text values will automatically cast directly to bit arrays before handling. The end
result will be a bit array.
Example: 01101011 OR:BIT 11100010 = 11101011
To perform a bitwise comparison of two values in which you want all the bits to result
in 1 whenever either the left or right hand bits are one but never both, is the XOR:BIT
operator. Numbers and text values will automatically cast directly to bit arrays before
handling. The end result will be a bit array.
126
NOT:BIT
Version 1.9.7
Example: 01101011 AND:BIT 11100010 = 00001000
To perform a bitwise inversion of your variable by toggling all contained Boolean
values, the NOT:BIT operator should be used. Numbers and text values will
automatically cast directly to bit arrays before handling. The end result will be a bit
array.
Example: NOT:BIT 11100010 =00011101
Functions
ABS
Returns the absolute value of a number, meaning casting aside its defined sign and
producing the same value, but always positive.
ACOS
Example: ABS(-4)
Returns the angle whose cosine is the specified number.
ASIN
Example: ACOS(0.35)
Returns the angle whose sine is the specified number.
ATAN
Example: ASIN(0.35)
Returns the angle whose tangent is the specified number.
CEIL
COS
COSH
EXP
FLOOR
LN
LOG
PI
ROUND
SIGN
Example: ATAN(0.35)
Returns the largest integer greater than or equal to the specified double-precision floatingpoint number.
Example: CEIL(1.1)
Returns the cosine of the specified angle.
Example: COS(0.35)
Returns the hyperbolic cosine of the specified angle.
Example: COSH(0.35)
Returns e raised to the specified value.
Example: EXP(27)
Returns the largest integer less than or equal to the specified double-precision floatingpoint number.
Example: FLOOR(1.1)
Returns natural log of the specified value
Example: LN(27)
Returns the log (base 10) of the specified value
Example: LOG(27)
Returns the value of PI
Example: PI()
Returns the value closest to the nearest integer from the provided value.
Example: ROUND(1.1)
Returns a value indicating the sign of a number.
127
SIN
Example: SIGN(1.1)
Returns the sine of the specified angle.
SINH
Example: SIN(0.35)
Returns the hyperbolic sign of the specified angle.
SQRT
Example: SINH(0.35)
Returns the square root of the specified value.
TAN
Version 1.9.7
Example: SQRT(27)
Returns the tangent of the specified angle.
Example: TAN(0.35)
128
Version 1.9.7
IIF (IF And Only IF)
IIF (read "if and only if") provides the ability to utilize inline conditional checking within your queries and formatting to
support nearly any requirement specified. Sometimes, it's necessary to have conditions directly in your list.
Perhaps you want to show a column only if the record meets a certain criteria. Using simple Boolean logic, the IIF
statement will render one string if the condition is true and the other string if false. IIF can be used in any of the
rendering areas or in the query itself.
Tip: You can never go wrong with quotes. They really help in developing more complex statements. Also, don't
forget about the escape (\) character.
IIF Syntax
The syntax is fairly straightforward. Ensure that your Boolean formula is solvable; that is, a value can be determined
no matter what other conditions are true.
IIF Syntax:
{IIF,"Condition",TrueText,FalseText}
Example In Rendering
<span>Your permissions are {IIF,"[RoleID,Session]=2 AND
[UserID,System]=1","<b>Sufficient</b>","<b>Insufficient</b>"}
</span>
Example In Query
SELECT Person.* FROM Person LEFT JOIN PersonAddress ON Person.PersonID =
PersonAddress.PersonID
WHERE Person.LastName LIKE '[Filter_LastName]' AND
{IIF,"'[Filter_State]'<>''","PersonAddress.State='[Filter_State]'","1=1"}
Condition
This is a true / false statement used to determine which string to render. All column values are available for use.
Additionally, the condition supports the complete MATH library, as well as compound statements.
Because of the utilization of the Double Quotes within the tag structures, it is recommended that string comparisons,
like „This‟=‟That‟ be placed within single quotes within your content. Although this is not entirely required, it does
provide the ability to easily compare two terms which might be confused as another data type by the mathematics
engine.
TrueText
The second parameter, know as TrueText, of the IIF statement contains the resulting value of your IIF condition IF
the condition results in a True value. This can be a simple statement or something very complex, so whenever the
content must contain either other ListX tags, or possibly double quotes you must be sure to ESCAPE the key
symbols contained within – please review the next section, labeled “Escaping” for instructions and samples.
129
Version 1.9.7
FalseText
The third parameter, know as FalseText, of the IIF statement contains the resulting value of your IIF condition IF the
condition results in a False value. This can be a simple statement or something very complex, so whenever the
content must contain either other ListX tags, or possibly double quotes you must be sure to ESCAPE the key
symbols contained within – please review the next section, labeled “Escaping” for instructions and samples.
Note: Be sure to enclose HTML tags in quotes (") and escape keywords that should not be evaluated.
130
Version 1.9.7
Escaping
ListX is a tag based language, which provides the ability for each tag value to contain multiple attribute values. ListX
tags are enclosed with either Brackets or Curly Braces ([,{.}.]) and may contain tags within tags. The result of this, at
times, is the desire to either ignore tags within conditions which will not be displayed, and therefore should not be
rendered or executed unless the condition were to pass. Another possible reason, and more common, is when the
inner tag, or inner content contains a symbol (like the Bracket or Curly Brace, or more frequently, a double quote)
which will cause the tag to fail to render properly, because the characters cause the format of the tag to be invalid.
Whenever any of these conditions apply, you can simply avoid the ill behaviour by escaping the content which
invalidates your statement. This is done quite easily. Take the syntax which you would like to avoid rendering, and
escape the contained symbols which will cause the invalid statement.
For example:
The most frequent cause of invalid statements, or broken ListX tags is the existence of an ACTION tag, which
results in an href=”…” value to be rendered, contained within a bounding IIF tag.
{IIF,”[frmMyValue,Form]=1”,”<a {ACTION,”Save”,”Toolbar”,,M}>Save</a>”,”Incomplete.”}
It is important to note here, that ListX renders from the inside out, meaning that – since it must handle appropriate
conversion, it must essentially render the inner-most tags before it renders the bounding tags. This means that the
previous structure will first render the {ACTION… prior to the rendering of the IIF, which will cause a very bad
problem:
{IIF,”1=1”,”<a href=”__doPostBack(…);”>Save</a>”,”Incomplete.”}
Obviously this is not good for business, because the IIF tag will not be able to appropriately parse its parameters,
because the offending double quotes will fail to allow the TrueText parameter from evaluating.
One more note, before the solution is provided, is the other reason why escaping is a very good practice. Looking at
the previous result, what if [frmMyValue,Form] results in 0? Why should the rendering engine be forced to handle
the evaluation of the ACTION tag, even when that tag will not be visible due to the failed condition?
Both of these reasons identify the need for escaping. To do so, you simply need to place a backslash character
directly preceding each offending symbol.
{IIF,”[frmMyValue,Form]=1”,
”<a \{ACTION, \”Save\”,\”Toolbar\”,,M\}>Save</a>”,
”Incomplete.”}
That will provide the ability for our statement to work perfectly.
Sometimes you must escape more than once
It can‟t be said more obviously to the user base, because lets face it – escaping can sometimes be difficult. As a
best-practice, I tend to write the content which will need escaping first, then copy and paste it into my favorite text
editor, and perform a find and replace on all the offending characters – Replacing { with \{, } with \}, [ with \[, ] with \]
and “ with \”. So, when do you need to escape more than once? That‟s easy! Whenever your value needs to be
embedded more than one layer into a statement. For instance, take the existing example, only stuff the IIF into a
SUBQUERY tag. Escapes are processed and removed ONCE for each bounding tag. Below is an example of the
physical syntax, and then how the tag would be rendered to provide insight into the reasoning and handling of
escaped values. From the previous example, I am replacing the [frmMyValue,Form] tag with the [EntryID] column
value, for better demonstration further.
131
Version 1.9.7
{SUBQUERY,
Name=”myQuery”,
Query=”Select * from Lists”,
Format=”\{IIF, \”[EntryID]=1\”,
\”<a \\{ACTION, \\”Save\\”,\\”Toolbar\\”,,M\\}>Save</a>\”,
\”Incomplete. \”\}”}
See? If we had not escaped, the inner most tags would have rendered first, which would have initially failed the
bounding IIF because of the double quote result in the ACTION tag, but moe troubling, if you don‟t escape the IIF,
you will render it first, the [EntryID] column would fail to parse, and therefore the False condition would immediately
replace the content, leaving Format=”Incomplete”. The following steps identify how ListX sees and renders the
previous statement.
{SUBQUERY,
Name=”myQuery”,
Query=”Select * from Lists”,
Format=”\{IIF, \”[EntryID]=1\”,
\”<a \\{ACTION, \\”Save\\”,\\”Toolbar\\”,,M\\}>Save</a>\”,
\”Incomplete. \”\}”}
First – the Subquery is executed, so lets say the first result, EntryID happens to be 1 from the Lists table. Because
the Subquery has been evaluated, the Format tag, which is the result of the Subquery will be immediately
unescaped once.
{IIF, ”[EntryID]=1”,
”<a \{ACTION, \”Save\”,\”Toolbar\”,,M\}>Save</a>”,
”Incomplete. ”}
Next, the inner tags are processed. First [EntryID] is evaluated as 1 , which renders the TrueText, unescaping it
once.
<a {ACTION, ”Save”,”Toolbar”,,M}>Save</a>
Finally, the ACTION tag is rendered, leaving us with the appropriate __doPostBack link to broadcast our message.
Tip: You can never go wrong with quotes. They really help in developing more complex statements. Also, don't
forget about the escape (\) character.
132
Version 1.9.7
Client Scripts And Utilities
The Client Script Utilities are provided as an inclusive javascript function set which provide some typical runtime
essentials for use with ListX. These utility functions provide aspects of visual appeal, as well as utilitarian
functionality. These functions currently consist of Expand/Collapse logic, meant to prevent easy layout functionality
for hiding and showing group levels at runtime. Additionally, a set of functions are used for automatically selecting
Combo items and settings Text values through javascript. Along with the Utilities scripts, support for Microsoft.Net
style form validation has been added. Both of these libraries can be added or removed at any time by Checking and
Unchecking their inclusion in the View Options.
Tip: When using the lxExpander functionality, be sure to pay close attention to the custom Attribute which is utilized
to provide identification of all tag elements which should be hidden or displayed. Additionally, the STYLE DISPLAY
attribute MUST be set in order to avoid javascript errors. A display style left un-set will result in an undefined
javascript error.
AJAX Library
lxFetch
Instead of calling a form submit whenever you want to post information to the server, or whenever you want to
refresh a module based on configuration or value changes in another – WITHOUT – refreshing the entire page. You
may call the lxFetch function, whether or not you are using AJAX within the module originally. This is handled very
simply. lxFetch forces the module to post back to our ajax library, and update itself without affecting the rest of the
page. Two specific examples are provided for Status bars and for event driven Country/Region selection – so refer
to them for complete functionality.
lxFetch takes three parameters – the first – the ModuleID of the module you want to refresh. If you are refreshing
ListX module, you can just use [ModuleID,System]. The second parameter, the CURRENT page of the module – if
you are refreshing a form, its probably safe to use 0. If you don‟t want to lose context, use the existing page
information for the target module CURRENTPAGE[ModuleID] (like CURRENTPAGE445), a javascript variable. The
final parameter consists of any additional query variables you would like to append to the URL when the lxFetch
requests the new page results. We typically use this when we want some actions to ONLY execute whenever the
page is requested via AJAX.
Target Object – Pump data from one ListX into any object on your page
An optional 4th parameter exists that allows you to specify the id value of any element on the page, within which you
would like the AJAX result to be rendered. Without this parameter, the content will be displayed with the standard
container for the module. For instance, take the following statement.
Onchange=”lxFetch([ModuleID],0,‟‟);”
If I had desired that that lxFetch pumped data into a specifically targeted tag, I could do so like this:
<div id=myDiv></div>
<a onclick=‟”lxFetch([ModuleID],0,‟‟,‟myDiv‟);return false;” href=”#”>Refresh</a>
For the described Country/Region selection, here is the resulting conceptual HTML:
<select onchange="document.getElementById('frmRegion').selectedIndex = 0; lxFetch([ModuleID],0,'r=1');"
id="frmCountry" name="frmCountry" class="SearchNormalText" >
133
Version 1.9.7
<option value="">Select</option>
{SUBQUERY,
Name="frmCountry",
Query="Select EntryID,Text from Lists where listName ='Country' order by text ",
Format="<option value='\[EntryID\]'>\[Text\]</option>",
SelectedFormat="<option value='\[EntryID\]' SELECTED>\[Text\]</option>",
SelectedField="EntryID",
SelectedItems="[FORMAT,[frmCountry,Form],{ISEMPTY:221}]",
UseCache="False"}
</select>
<select id="frmRegion" name="frmRegion" class="SearchNormalText">
<option value="">Select</option>
{SUBQUERY,
frmRegion,
Query=" Select EntryID,Text
from Lists where listName ='Region' and
ParentID='[FORMAT,[frmCountry,Form],{ISEMPTY:221}]' order by text ",
Format="<option value='\[EntryID\]'>\[Text\]</option>", SelectedFormat="<option value='\[EntryID\]'
SELECTED>\[Text\]</option>",
SelectedField="EntryID",
SelectedItems="[frmRegion,form]",
UseCache="False"}
</select>
NOTE: ListX will execute the Action script on EVERY request. So – when you are using AJAX, the request will
execute first when the page loads initially (module load), then when the AJAX executes the lxFetch (data load). Be
very aware of this, and you will craft the proper handling methods with ease.
lxModule
The lxModule function allows you to either Hide or Show an entire Module, either ListX or non-ListX based, by
simply passing the ID of the module, and a Boolean variable identifying that you either Do or Do Not want the
module to be visible on the page:
lxModule Syntax:
lxModule(ModuleId,isVisible)
ModuleId – The physical ID of the module which should be displayed or hidden.
isVisible – a true or false value, identifying whether the module should be visible or not.
Example:
<A onclick="lxModule(122,false);">Hide the Module</A>
<A onclick="lxModule(122,true);">Show the Module</A>
134
Version 1.9.7
Utilities Library
lxExpander
The lxExpander Script provides the ability to quickly and easily add expand and collapse DHTML capabilities to your
website. With the lxExpander function - the Object which is to be expanded or collapsed must provide a style
attribute value for "display:". To set it to expanded - "display: block;" and collapsed - "display: none". Finally, with
the attributeName and value parameters for the script, you can easily expand and collapse at a nested level,
because you can have multiple attributes which control the expand/collapse abilities.
lxExpander Syntax:
lxExpander(SourceText, ParentElementID, TagType, AttributeName, AutoCollapse, All)
SourceText - the Text Value that is checked against the attributes of each of the child elements to
determine if the expand/collapse action is meant for them.
ParentElementID - the HTML Tag ID of the base element where the expand/collapse will be initiated.
TagType - identifies the type of tags which will contain the specified attribute. You can use * which means
all tags below this parent, or a specific element name, which in our sample was *TR*, this simply limits the
focus of the function, so that not all elements need processing.
AttributeName - identifies the name of the custom attribute which is to be checked for the value specified
by *SourceText* - when a match is located, the item is flagged as requiring action, and the item is
therefore expanded (if collapsed) or collapsed (if expanded)
AutoCollapse - identifies that the item will automatically Collapse if a different item is expanded,
collapsing everything that is not the currently expanded group.
All - identifies that you want to perform the action on All items - meaning that instead of performing the
expand/collapse on items matching the SourceText, it will be performed on all items containing the attribute
and identified with the assigned TagType.
Example:
<table width=100% ID="tblMain">
<TR onclick="lxExpander('Group
A','tblMain','TR','mygroup',false,false);"><td>GROUP A</td></TR>
<TR mygroup="Group A" style="display: none;"><td>ITEM 1</td></TR>
<TR onclick="lxExpander('Group
B','tblMain','TR','mygroup',false,false);"><td>GROUP B</td></TR>
<TR mygroup="Group B" style="display: none;"><td>ITEM 4</td></TR>
</table>
135
Version 1.9.7
lxToggle
Because lxExpander had its limitations at times because it was unable to remember the expansion or collapse state
between each request, lxToggle was created.
lxToggle Syntax:
lxToggle(objectid, trackingType, trackingName, trackOn, trackOff, visualObjectId, visualAttribute, visualOn,
visualOff)
objectId – the object that will be shown or hidden based on the current module selection..
trackingType –tracking the result of the item which was clicked is simple, and provides two options. First,
“F” would provide the ability to store th e current status in a form variable. “C” would allow the variable to be
stored more permanently with the cookie collection.
trackingName – based on the trackingType, the trackingName identifies the Name of the element or
cookie which will contain the value (either TrackOn or TrackOff).
trackOn – the representation of the selected Track item.
trackOff – the representation of the unselected Track Item.
visualObjectId - If you are used to dealing with expandable and collapsible objects, the visualObjectId is
the name of the physical web object which displays the current current state of the item, either via Text of
by Image.
visualAttribute - When set or unset the trigger will assign the value to the attribute itself. Typical use of
this would include visual change. Inb general you would need to change an image based on he status (like
the expand collapse butons). For images, src is the visualAttribute value. For replacing the content, use
innerHTML:. Additionally, when the visualAttribute is assigned as Script the visualOn and visualOff will be
executed.
visualOn - the physical value to be written into the visualObjects.visualAttribute value when the item is
turned on..
visualOff turned off..
the physical value to be written into the visualObjects.visualAttribute value when the item is
Example:
In the following sample – vis is the visual object which will be modified by changing its src value, ob1 is the
targetobjectid and fob1 is the form variable which will contain the current status. Notice that IIF checks the
state of fob1 whenever rendering occurs.
<img id=vis src="http://[ALIAS,System]/images/{IIF,"'[fob1,F]'='1'","dn","up"}.gif">
<span
onclick="lxToggle('ob1','F','fob1','1','0','vis','src','http://[ALIAS,System]/images/dn.gif','http://[ALIAS,System]/images/u
p.gif');">Click Me!</span>
<input type=hidden id=fob1 name=fob1 value="[fob1,F]">
<div id=ob1 style='display: {IIF,"'[fob1,F]'='1'","block","none"};'>TEST</div>
In the following sample – vis2 is the visual object which will be modified by changing its src value, ob2 is
the targetobjectid and fob1 is the cookie variable which will contain the current status. Notice that IIF
136
Version 1.9.7
checks the state of fob1 whenever rendering occurs.
<img id=vis2 src="http://[ALIAS,System]/images/{IIF,"'[fob1,C]'='1'","dn","up"}.gif">
<span
onclick="lxToggle('ob2','C','fob1','1','0','vis2','src','http://[ALIAS,System]/images/dn.gif','http://[ALIAS,System]/images/
up.gif');">Click Me!</span>
<div id=ob2 style='display: {IIF,"'[fob1,C]'='1'","block","none"};'>TEST2</div>
In the following sample – vis3 is the visual object which will be modified by changing its innerHTML value,
ob3 is the targetobjectid and fob2 is the cookie variable which will contain the current status. Notice that IIF
checks the state of fob2 whenever rendering occurs.
<span id=vis3>{IIF,"'[fob2,C]'='1'","(Expanded)","(Collapsed)"}</span>
<span
onclick="lxToggle('ob3','C','fob2','1','0','vis3','innerHTML','(Expanded)','(Collapsed)');">Click Me!</span>
<div id=ob3 style='display: {IIF,"'[fob2,C]'='1'","block","none"};'>TEST3</div>
137
Version 1.9.7
Dynamic Aggregators within ListX
There are times which require you to create a specific structure for display a set of sub items, based on clicking
options buttons on the toolbar, or elsewhere on your site. The lxContainer function provides the ability for you to
identify a module by one or more Container flags, and through this, provide the ability to Hide and Show entire
modules and containers, by groups and by name, quickly and easily. It is important to note that these aggregated
modules DO NOT need to be ListX modules, but in fact can be anything at all. To identify the name, group and
moduleID of the target modules, the following tag structure must be provided for each of your elements:
<lxContainer ModuleId=”MODULEID” Name=”NAME” Group=”GROUP” Marker=”MARKER”
ActiveCSS=”ACTIVECSS” InactiveCSS=”INACTIVECSS”/>
Whenever the lxContainer or lxContainerGroup functions are called, they automatically look for all the lxContainer
objects on the page, and identify the appropriate functionality. Additionally, the hiding and showing of the modules is
remembered within the Users Cookie, so you can show a specific module, leave the page and return, and that
module will be the default (when lxContainerGroup is called to initialize the page).
The examples provided for these functions are generalized, but provide the true functionality you would ordinarily
see within the ListX Aggegation capacity. To reflect this structure into your own site, you would want to do the
following:
In the Module-Settings-Header of each your of Modules, place the lxContainer tag which cooresponds to the module
itself. When using ListX, you can specificy the ModuleID as [ModuleID,System], or can hard code the ModuleID if
the module is either Non-ListX, or a hard coded value is preferred.
In the Toolbar or Links you would like to Hide and Show the modules from. The onclick functionality should simply
be the call to lxContainer for the cooresponding names. Follow the example to see how we normally call the
functions.
The lxContainerGroup function should be called for the Groups whenever the modules appear on the page, so that
only one is displayed by default.
The Marker identifies the NAME of the object or objects within your page which act as the Marker for the current tab,
meaning – if you have an element which is clicked in order to show the current tabbed items, the name of that
element is your Marker. This allows the system to automatically set the ACTIVECSS and INACTIVECSS classes to
the elements, depending on which Aggregated Group is currently Activated.
lxContainer
Execution of the lxContainer function will automatically locate the lxContainer tag within the page which containes
the Name identified, then, locate all other lxContainer tags with the same Group setting. The lxContainer object will
automatically SHOW the module matching the ModuleId setting for the lxContainer tag. All other Modules matching
the Group assignment will be hidden.
lxContainer Syntax:
lxContainer(Name)
Name – The Name of the lxContainer object, identified by the aforementioned lxContainer Tag. Within your
lxContainer object tag you can use the following attributes:
ModuleId – the ModuleID that is the target module to be hidden or displayed
Name – the name as you will refer to this item within the lxContainer executions
Group – the name of the Group of elements which will be hidden when this item is shown.
Marker – to help aid the use of this tag, the Market tag identifies which Object will change visually when
this item is hidden or shown, the lxContainer logic supports the automatic change of the following Class
assignments based on the state.
ActiveCSS – the name of the CSS class which will be assigned to the Marker when the state changes to
the Active element in the Group
138
Version 1.9.7
InactiveCSS – the name of the CSS class which will be assigned to the Marker when the state changes to
the the unselected element in the Group
OnInit –especially when manual loading is assigned to the general settings, the OnInit function fires the
first time lxToggle is executed for the current page. The value should be a javascript name.
OnLoad – Operates the same as the OnInit attribute, only this execute each an every time the module is
displayed, instead of only when requrested
OnUnload – when the object is switched to another, the javascript value assigned to the OnUnLoad tag will
be executed.
Example:
<lxContainer ModuleId="122" Name="Projects" Group="EmployeeItems"
Marker=”tabProjects” ActiveCSS=”Selected” InactiveCSS=”Unselected”/>
<lxContainer ModuleId="156" Name="Tasks" Group="EmployeeItems" Marker=”tabTasks”
ActiveCSS=”Selected” InactiveCSS=”Unselected”/>
<A onclick="lxContainer(‘Projects’);return false;" name=tabProjects
href=#>Projects</A>
|
<A onclick="lxContainer(‘Tasks);return false;" name=tabTasks href=#>Tasks</A>
<script language=javascript>
lxContainerGroup(‘EmployeeItems’);
</script>
lxContainerGroup
Execution of the lxContainerGroup function will automatically locate the lxContainer tags which contain the specific
Group attribute value provided. The javascript will then automatically Hide all modules which contain the group
name. Either the FIRST defined lxContainer of that Group will be displayed, or the item identified by the Cookie
value, matching that group name, will be displayed. The typical utilization of this function is to call the function as an
initialization function, as seen in the example.
lxContainerGroup Syntax:
lxContainerGroup(Group,optional SkipCookies)
Group – The Name of the lxContainer Group which cooresponds to one or more lxContainer objects,
identified by the aforementioned lxContainer Tag.
SkipCookies – at times you may want to keep the assigned value out of the cookie. For this scenario, you
will want to specify the SkipCookies as true.
Example:
<lxContainer ModuleId="122" Name="Projects" Group="EmployeeItems"
Marker=”tabProjects” ActiveCSS=”Selected” InactiveCSS=”Unselected”/>
<lxContainer ModuleId="156" Name="Tasks" Group="EmployeeItems" Marker=”tabTasks”
ActiveCSS=”Selected” InactiveCSS=”Unselected”/>
<A onclick="lxContainer(‘Projects’);return false;" name=tabProjects
href=#>Projects</A>
|
139
Version 1.9.7
<A onclick="lxContainer(‘Tasks);return false;" name=tabTasks href=#>Tasks</A>
lxContainerGroup(‘EmployeeItems’);
</script>
lxSetValue
The LxSetValue Script sets the value of an input element.
lxSetValue Syntax:
lxSetValue(objectName, Value, emptyValue)
lxComboSelect
The lxComboSelect Script sets the value of a combo box element.
lxComboSelect Syntax:
lxComboSelect(objectName, CurrentValue)
140
Version 1.9.7
Validation Library
To incorporate validation within ListX, without the need for post backs for verification, we started with the notion of
simply piggy-backing the provided validation logic from Microsoft .Net. However, as many people are aware, the
validation on the client-side fails to work for any browser that is not Internet Explorer. To solve this issue, we took
the time to delve into the logic of the javascript library, and make a few corrections to the code, then added a few
additional features which makes the logic far more intelligent, and much more usable within an AJAX driven
scenario.
To utilize the validation library within ListX, you need to first Check the Validation Library checkbox within the
General Settings of the View Options administration. With that initial step completed, you can use the standard
Microsoft Validation attributes with the HTML form, as provided by the following example as well as their support
knowledgebase: Client-Side Functionality in a Server Control.
With the option checked, you can now utilize the validation scripts just as they would be rendered by the asp.net
code. For each element you desire validation, you will need to add the custom validation, typically by using a SPAN
tag which will act as both the definition of the validation, as well as the location of the error message on validation
failure.
The basic validation attributes for the tag are as follows:
controltovalidate - identifies the ID of the input value which this evaluator is validating.
errormessage - defined the error message to display when the value fails validation.
display - identifies the default display behavior. Values are Dynamic or None.
evaluationfunction - maps to one of the predefined evaluation functions provided by the Validation library:
o CompareValidatorEvaluateIsValid
o CustomValidatorEvaluateIsValid
o RegularExpressionValidatorEvaluateIsValid
o RequiredFieldValidatorEvaluateIsValid
o RangeValidatorEvaluateIsValid
validationexpression - utilized by the RegulardExpressionValidator, this expression performs string
structure verification.
initialvalue - can be used to Get or Set the value that is the initial value for the validation target.
group – to facilitate the need to allow some validators to work only on specific areas of your page, a group
name can be specified that will execute the validators only against a specific group whenever you would
like to attempt validation.
Follow along in the sample and see just how our script utilizes the functionality. Items appearing in Orange are ListX
tags for Column values and Actions:
<table cellspacing="0" cellpadding="0" width="95%" border="0" class="Normal"
align="center">
<tr>
141
Version 1.9.7
<td width="200"><span class="normalBold">First Name:</span></td>
<td><input name=FirstName id=FirstName type="text" value="[FirstName]"/><span
id="vFirstName"
controltovalidate="FirstName"
errormessage="This is a required field"
display="Dynamic"
evaluationfunction="RequiredFieldValidatorEvaluateIsValid"
initialvalue=""
style="color:Red;display:none;">This is a required field</span></td>
</tr>
<tr>
<td width="200"><span class="normalBold">Last Name:</span></td>
<td><input name=LastName id=LastName type="text" value="[LastName]" /><span
id="vLastName"
controltovalidate="LastName"
display="Dynamic"
initialvalue=""
</tr>
<tr>
<td width="200"><span class="normalBold">Address 1:</span></td>
<td><input name=Address1 id=Address1 type="text" value="[Address1]"/><span
id="vAddress1"
controltovalidate="Address1"
display="Dynamic"
initialvalue=""
</tr>
<tr>
<td width="200"><span class="normalBold">City:</span></td>
<td><input name=City id=City type="text" value="[City]"/><span
id="vCity"
controltovalidate="City"
display="Dynamic"
initialvalue=""
</tr>
<tr>
<td width="200"><span class="normalBold">Email Address:</span></td>
<td><input name=Email id=Email type="text" value="[Email]"/><span
id="vEmail"
controltovalidate="Email"
display="Dynamic"
initialvalue=""
</tr>
<tr>
<td><span class="normalBold">Phone:</span></td>
142
Version 1.9.7
<td><input name="Phone" type="text" id="Phone" value="[Phone]"/><span
id="vPhone"
controltovalidate="Phone"
errormessage="Enter Phone number in the proper format"
display="Dynamic"
evaluationfunction="RegularExpressionValidatorEvaluateIsValid"
validationexpression=
"(($\d{3}$ ?)|(\d{3}-))?\d{3}-\d{4}"
style="color:Red;display:none;">Enter Phone number in the proper
format</span></td>
</tr>
<tr>
<td colspan="2" align="center"><a
onclick="if (typeof(Page_SmartValidate) == 'function') return
Page_SmartValidate();"
language="javascript"
{ACTION,Save,Action,,Message}>Save</a> | <a
{ACTION,Cancel,Action,,Message}>Cancel</a></td>
</tr>
</table>
Originally, you would have needed a snippet of code to set up the javascript handler to identify all the built in
validation controls. This would have been used through a direct call of the Page_ClientValidation function, which we
initially utilized in 1.6.1. Now, however, the Validation has been greatly improved, allowing you to control a much
more powerful library through the simple Page_SmartValidation call provided in the above sample.
You may also desire the ability to display the standard Summary error list, which is populated by the associated
errormessage attribute of the SPAN tags. To do this, you need to simply add a SPAN tag that identifies itself as a
Summary as in the following example:
<span
showsummary="True"
displaymode="BulletList"
headertext="The following errors were identified:"
style="color:Red;display:none;"></span>
The possible properties of this summary span tag are:
showsummary – True displays it, False hides it.
showmessagebox – Displays the output in a Message box alert.
displaymode – Controls the look and feel of the output, the possibilities are: List; BulletList;
SingleParagraph.
headertext – identifies text to display at the top of the list, whenever errors occur.
143
Version 1.9.7
Group Validation
IF you require validation within groups of elements on your page, not every element all together – set a group
attribute on your validator span tags, as defined previously. Once set, pass the name of the group as the single
parameter to the Page_SmartValidate function.
Validation with Submit Button
<input type=text name='frmEmail' id='frmEmail' style="width:100px" />
<input type=button value='go' name='go' id='go' language="javascript"
onclick="if (typeof(Page_SmartValidate) == 'function') if (Page_SmartValidate())
{ACTION,Save,Save,,Message,False}" />
<span id="vEmail" controltovalidate="frmEmail"
display="Dynamic"
initialvalue=""
style="color:Red;display:none;">This is a required field</span>
<span displaymode="BulletList"
headertext="The following errors were identified:"
style="color:Red;display:none;"></span>
144
Version 1.9.7
TEXTEDITOR – Rich Text with FTB
Using FreeTextBox (FTB) as a form element
Thanks to popular demand, using the FreeTextBox has been added as a capability in ListX. In its current form, ListX
can ONLY support FTB, and not a different rich text provider – this is because the provider model does not currently
make dynamic rendering feasible. This will hopefully in the future not be the case. Regardless, the tag and utilization
will not change at all.
To place a Rich Text (FTB) editor in your ListX form, you need to follow a few simple steps.
1. FTB Javascript Library References – Add the following Javascript references to your page. This can be
done at the page level, or, more frequently, the Module-Advanced Settings-Header area. To do this,
expand the Advanced Settings of the Module and Enter the following Text into the Header:
<script type="text/javascript" src=" /Providers/HtmlEditorProviders/Ftb3HtmlEditorProvider/ftb3/FTBUtility.js"></script>
<script type="text/javascript" src="/Providers/HtmlEditorProviders/Ftb3HtmlEditorProvider/ftb3/FTBFreeTextBox.js"></script>
<script type="text/javascript" src="/Providers/HtmlEditorProviders/Ftb3HtmlEditorProvider/ftb3/FTBToolbarItems.js"></script>
<script type="text/javascript" src="/Providers/HtmlEditorProviders/Ftb3HtmlEditorProvider/ftb3/FTBPro.js"></script>
NOTE: If you are using the TextEditor tag from a Child portal, on a local host scenario – the /Providers link in the src
attribute of the Javascript Library references would need to contain the child portal name. For instance – if you are
running a localhost child portal like http://localhost/Demo32 - the src attribute would read
/Demo32/Providers/HtmlEditorProviders…
2. Text Editor ListX Tag – A special ListX tag has been created which will let you place the FTB within your
form as an HTML element. To do this – simple add the following Tag wherever you need Rich Text support:
{TextEditor, [ID],[CONTENT] }
ID – Set this as the identify of the object as you want it to appear within your form. For instance, if you want
this object to appear as frmDescription, use that.
CONTENT – This will be the place where your content actually resides within the form element. An
example of this is to use ListX to edit the data commonly found within the TextHTML DotNetNuke module.
When working with the data, you will ALWAYS want to escape the data so that TextEditor has appropriate
access to the un-modified data at the point of rendering. What this means is – if you place [DesktopHTML]
as the value for the Content, ListX will render DesktopHTML prior to rendering the TextEditor control –
which is bad, if the DesktopHTML contains a curly brace – which would cause the TextEditor tag to exit
early. For all cases where this is possible, simply escape the Content – like this:
\[DesktopHTML\]
Example:
{TextEditor,lxFTB[ModuleID],\[DesktopHTML\]}
145
Version 1.9.7
3. Form Submit Handling – Since FTB adds some slight handling to the Form, you will need to add the same
functionality to your form submit tag. Instead of an action with a simple Form submit – you will need to first
call StoreHtml() for the FTB that you have created in step 2.
<a href="javascript:FTB_API['frmDescription'].StoreHtml();document.forms[0].submit();">Save</a>
146
Version 1.9.7
Examples
Standard - Data Grid
The first example of using ListX is an obvious one, and it is where ListX originated. The Data Grid, or Data List,
depending on your region of the world, is easy to configure using the interface provided by ListX, providing the best
advantage of the layout and handling of your data. After completing this demonstration, you will have a data display
grid which provides Sorting on the columns; Actions for driving the user to Detail information, a record Editor or
Form, and a Delete functionality, with associated client confirmation of the requested delete.
Finally, a filter is added which allows the user to filter on any of the provided columns in an advanced and
completely customized fashion.
Concepts: The following concepts are covered within this Example:
1. Formatting
 Variables
 Sort, SortHeader
 Form
2. Query
 Query Variables
 Custom Filters
 SortTag
3. Variables
 Session
 Form
4. Actions
 Action: Message
 Action: Redirect
 Action: Execute
5. Client Scripts
 AJAX (lxFetch)
The Process
For this sample, we will ultimately conclude with two modules, the first, a filter module, and the second, the physical
data grid.
147
Version 1.9.7
Our priority takes us first to the Grid itself, we will provide the advanced filter directly after, starting small. To begin,
create a tab, and add a ListX module. Open the view options and begin you development efforts.
Query
First, setup the initial query we will be using. For this example, we will use the standard Microsoft Northwind
database. The Employee Table is simple enough for an all purpose example, and will be the target of our query.
The Initial Query starts with just a standard Select statement –
Select * from Northwind..Employees
Since sorting is part of our requirement for this demonstration, we will extend the query to include the SORTTAG:
Select * from Northwind..Employees order by [SORTTAG]
Options
In most cases, only a few of the General options are required for providing the full end result, whether we are
referring to a Grid, Detail, Form or other advanced functionality. For this demonstration we will use the following
options:
Records Per Page – 10
Enable Ajax Interaction – True
148
Version 1.9.7
Format
For this example, and for most standard grid structures, we will need one List Group, beyond the default Detail
entity. A List Group provides the ability to repeat grouping structures around the detail structure. To begin, add a List
Group – then setup the format structure:
Group Statement – While this is not required, since we will only generate one Header and Footer combination
around the entire list of data, for this example, and most other configurations developed by Bi4ce, we tend to specify
a Group Statement for display purposes. For this demonstration – “Header/Footer” will be the assigned value.
Header – While the footer contains no intelligent ListX tags, the Header contains tags which support the Sort
functionality. As you have already learned, the SORT tag provisions six parameters:
Column - The Name of the column as it should appear within the Order By clause of your query.
Default Format – the display value to show when the sort is currently turned off.
Ascending Format – the display value to show when the sort is currently ascending.
Descending Format – the display value to show when the sort is currently descending.
Default Value – In this demonstration we default all columns to not sorted.
Sort Index – The sort index provides the ability to control both a unique handling for all custom sorting, but
also the actual default position of the column within the resulting Order by clause.
The SORTHEADER tag is explicitly used to act as the target position of the physical rendered text for the sort
tag, meanind the Default, Ascending or Descending format attributes.
<TABLE WIDTH=100% BORDER=0 CELLPADDING=0 CELLSPACING=0>
<TR class=DataGrid_Header>
<TD> </TD>
<TD><a {SORT,LastName,"Name","^ Name ^","v Name v",,0}>{SORTHEADER,0}</a></TD>
<TD><a {SORT,Title,"Title","^ Title ^","v Title v",,1}>{SORTHEADER,1}</a></TD>
<TD><a {SORT,Address,"Address","^ Address ^","v Address v",,2}>{SORTHEADER,2}</a></TD>
</TR>
149
Version 1.9.7
Footer –
</TABLE>
As you can see from the aforementioned Sort tags, the example contains 4 columns, three of which provide sorting
methodology. The resulting layout provides a column for the delete action, followed by a column to show the
persons Name (with sorting on the LastName), Title and Address.
The detail provides an example of using the ListX Action tag, which demonstrates both the ability to communicate
messages as well as assign variables and perform an automatic redirection.
List Item
<TR class=DataGrid_Item>
<TD><a
onclick="return window.confirm('Are you sure you want to delete this Employee?');"
{ACTION,[EmployeeID],DeleteEmployee,,Message}>
<img border=0 src="http://[ALIAS,System]/images/delete.gif">
</a>
</TD>
<TD><a {ACTION,[EmployeeID],CurrentEmployeeID,Employee Detail,Session}>
[FirstName] [LastName]
</a>
</TD>
<TD>[Title]</TD>
<TD>[Address]<br>[City], [Region] [Country] [PostalCode]</TD>
</TR>
As demonstrated within the List Item, there are two defined actions. The first, broadcasts a Module Communication
message with the Type “DeleteEmployee”, and the Value which is the EmployeeID column from the source record.
Additionally, an Onclick attribute, defined from the anchor tag for the Delete functionality provides the ability to abort
the message whenever the user decides not to delete the target record.
The second Action tag assigns the Session variable “CurrentEmployeeID” to the value of the EmployeeID for the
record clicked. Then, it redirects to the (yet to be demonstrated) tab named “Employee Detail”.
The physical record displayed consists of the delete column, followed by the First Name and Last Name columns
from the record, which when clicked redirects to the Employee Detail tab. This is followed by the Employee Title.
Finally, the full address is properly formatted with the Address, City, Region, Country and Postal Code.
150
Version 1.9.7
Alternating List Item – The Alternating List Item is exactly the same as the List Item, with one caveat, the class
attribute assignment for the row in the Alternating item is DataGrid_AlternatingItem, rather than DataGrid_Item.
Variables
For the deletion process, we will declare one query variable which will handle the physical ID of the deleted
employee record.
The visible settings here provide that we will replace the value @DeleteEmployee within every query with the
physical value from the message with a type of DeleteEmployee. If the record is not Empty – it will be replaced with
a result padded by the single quotes, otherwise, it will be assigned as zero, which is this system will return no
records.
Actions
As this grid is very simplistic, the module will only need to react to two actions. The first, a message action which will
listen for the raises Message identifying a record which should be deleted. The second, the physical processing of
that deletion query. While this is more required for physically deleting records, because of binding relationships, we
will ignore that for the demonstration. For your own system it will be important to recognize when deletions are
failing due to indexes and relationships which are dependant on the record.
Message Action – DeleteEmployee
First, add the action for listening for the incoming DeleteEmployee message. This is done by pressing the Add
Action link, and populating the required attributes First, the Type, which will be set to „DeleteMessage‟. Second, the
Value – which will be left as empty, which means we want to react to every message with a type set to
„DeleteEmployee‟.
151
Version 1.9.7
Execute Action
Now that the requirement for raising the delete message is handled, the child action will be execute to delete the
physical value. The delete statement, identifying a very crude deletion will result in the removal of the record. We
give it a Name of “DELETE EMPLOYEE” just for simple visible recognition within the configuration. The statement
itself is very straight forward, consuming the existing query variable which will contain the physical value.
Delete from Northwind..Employees where EmployeeID = @DeleteEmployee
Now with everything in place, you will be able to review, browse, delete and view the records within the Employee
table. Since filtering is also a general requirement, we will add that in quickly.
To begin, add another ListX module. We will not be binding this particular ListX to any specific requirement, but
rather using it just for adding the appropriate filter structure, consisting of a few filter input boxes, text and labels.
Detail Item (No Query) <TABLE WIDTH=100% BORDER=0 CELLPADDING=0>
<TR>
<TD width=100px>First Name</TD>
<TD><input name=fltFirstName onchange="lxFetch(GridModuleID,0,'');"></TD>
</TR>
<TR>
<TD width=100px>Last Name</TD>
<TD><input name=fltLastName onchange="lxFetch(GridModuleID,0,'');"></TD>
</TR>
</TABLE>
As you can plainly see, the html contains two input elements, fltFirstName and fltLastName. The Onchange attribute
is fired whenever the text value of the input element is modified. The javascript function, lxFetch, executes the ajax
request on the module with the moduleid specified here as GridModuleID, a global javascript variable.
152
Version 1.9.7
We have not yet added this variable to the grid module, nor the handling for the filter itself, so lets get that going
next.
First, Save this configuration, then click on the Module Settings of the Grid Module which we already setup.
Under Advanced Settings, we will be assigning a custom Javascript header element, which will declare the
GridModuleID variable to the module id of the grid. This is important so that you never need to bind a physical ID
value anywhere within your architecture. With this setting, I can easily copy this module to other DNN instances with
both the Filter and Grid and not have anything bound specifically to the original Module ID value.
To do this, add the following script tag:
var GridModuleID = [ModuleID,System];
</script>
This will be automatically handled by the ListX Engine, and the end result will set the physical value. Now, save the
module settings. Whenever the textbox values are altered, you will see the Grid refresh automatically. All that is left,
simply adding the filter into the original grid query, and declaring the query variables.
First, declare the Query variables. Click on the View Options of the grid, and add the two variables:
153
Version 1.9.7
Notice, we have chosen to place the entire Field name within the Target Left. This is because we want to easy our
strain a bit on designing the query. The simplest way, either formulate a query that will result in “FirstName like
„Value%‟” or “1=1” so that we don‟t have to put any extra logic in to see if there was a variable, and to decide
whether we need to add the conjuctive “AND” syntax to the query.
The second variable assignment is almost exactly the same, switching only the First name definition with that of the
Last Name.
Finally, to adjust the query – we simply need to include the AND parameters and the declared variable names to
result in the following query:
Select * from Northwind..Employees
WHERE
@FirstName_Filter AND
@LastName_Filter
order by [SORTTAG]
It may seem a little to easy, but that‟s entirely the point. Easy integration of your data structures into a front-end, as
simple or advanced as you would like to make it. Check out the end result! Set the FirstName and LastName to
different values, and you will see the query immediately displays the end result.
It is very important to note that, with ListX enabling AJAX, whenever there are No results returned, the interface will
remain with the last result, rather than displaying the No Result syntax. Additionally, you can automatically refresh
the grid whenever the key is pressed within the form elements, simply by assigning the attribute “onkeyup” rather
than “onchange”. Finally, if you would prefer to use a standard Post Back action for performing your filter because
you are using a non-ajax grid, or need the information for some other purpose, but yet would like to retain the data
between postbacks, and display it within the form, even after the postback. An additional attribute is required for the
154
Version 1.9.7
FirstName and LastName input tags. “Value” must be specified for the text entries, and can easily be handled like
this (including the onkeyup syntax):
<TABLE WIDTH=100% BORDER=0 CELLPADDING=0>
<TR>
<TD width=100px>First Name</TD>
<TD><input name=fltFirstName onkeyup="lxFetch(GridModuleID,0,'');"
value="[fltFirstName,Form]"
></TD>
</TR>
<TR>
<TD width=100px>Last Name</TD>
<TD><input name=fltLastName onkeyup="lxFetch(GridModuleID,0,'');"
value="[fltLastName,Form]"
></TD>
</TR>
</TABLE>
155
Version 1.9.7
156
Version 1.9.7
Examples – Files and Images
ListX supports both File manipulation and Image resizing automatically through the configuration interface. The
provided sample demonstrates the ability to both accept the incoming file, but to handle the information provided
with the data as well as extended form information. The provided sample is useful as a gallery module, and can be
reused on any page.
1. Formatting
a. Variables
b. Form
2. Query
a. Query Variables
3. Variables
a. Session
b. Form
4. Actions
a. Action: Message
b. Action: Redirect
c. Action: Execute
d. Action: Condition: If
e. Action: File
The Process
This sample creates a simple FileGallery, module driven interface, with any folder provides as the target file storage
location. First, you will need to create the database table, using the following TSQL statement:
if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[FileGallery]') and OBJECTPROPERTY(id,
N'IsUserTable') = 1)
drop table [dbo].[FileGallery]
GO
CREATE TABLE [dbo].[FileGallery] (
[FileID] [int] IDENTITY (1, 1) NOT NULL ,
[ModuleID] [int] NOT NULL ,
[Path] [varchar] (255) NOT NULL ,
[Description] [varchar] (1000) NULL ,
[Name] [varchar] (255) NOT NULL,
[Extension] [varchar] (255) NOT NULL,
[Size] [int] NOT NULL,
[MimeType] [varchar] (255) NOT NULL,
[CreatedBy] [varchar] (100) NOT NULL ,
157
Version 1.9.7
[CreatedByUserID] [int] NOT NULL ,
[CreatedDate] [datetime] NOT NULL
) ON [PRIMARY]
GO
The provided database structure sets up the File Gallery table. The structure supports the ability to keep as many
separate File Gallery modules as you prefer, by using the ModuleID within the table. The schema also provides
storage from the physical Path name of the file, its Description, which will be provided within the front end interface
as a text box. Additionally, storage for the original Name of the file, its file Extension, Size (in bytes) and Mime Type.
Finally some extended tracking information is provided for determining which user is the owner of which files.
Default Properties
The layout which we prefer to display provides only 5 records per page, but allows a friendly layout of the
information. Obviously, if you will use this module within your site, you will probably want to display more than 5
records per page. But for our requirements, we will use this setting.
Additional settings which we utilize, and are our normal defaults, are displayed above (in an abridged fashion).
These include, Enabling AJAX Interaction, Edit User provisions for Administration, and forcing the system to require
Explicit System Variables.
Query
The sample is quite simple in its query utilization, just requiring that you select everything from the FileGallery table,
providing that it has the same ModuleID as our current module.
Select * from FileGallery where ModuleID = '[ModuleID,System]'
Note that we use Explicit Naming of our system variables, this is the best approach in most cases, so that you never
run into variable name confusion.
158
Version 1.9.7
Format
The target layout provides a simple Add form at the top, followed by a list of files. An associated image provides a
brief clip of the uploaded file (when the file source is an image), or a default file image. The format layout provides a
Item Group to provide the Edit Form header, and a defined List Item, and List Item (No Result) format.
Format – Add Form (Header / Footer)
The form, providing the file upload interface, provides three form elements, contained within a bounding table
structure. The elements, used within the associated queries are txtDescription, frmFile and frmSave
Header:
<TABLE Width=100% border=0 cellpadding=0 cellspacing=2>
<TR>
<TD width=100%>
<input type=text name=txtDescription id=txtDescription style="width: 100%;">
</TD>
<TD>
<input type=file name=frmFile id=frmFile>
</TD>
<TD>
<input type=submit id=frmSave name=frmSave value="Save">
</TD>
</TR>
</TABLE>
<HR>
<TR>
Footer:
</TR>
</TABLE>
159
Version 1.9.7
Format – File Gallery (Detail)
The detail entry itself is straight forward. The optimal display, for this example, provides a layout where there is a clip
image to the left of each entry, and the description, and meta information about the file is displayed to the right of the
image. This is achieved through the simple declaration of the TD tags which will span horizontally across the page.
Again, this sample is meant to provide a quick idea on a gallery system, so we can get away with only displaying 5
entries on a page.
List Item:
<TD style='width: 100px;' align=right valign=middle>
<a {ACTION,[FileID],OpenFile,,Message}>
<img src="{IIF,"[IsImage]=True",
"[PORTALPATH,System]FileGallery/[FileID].[Path].png",
"http://[ALIAS,System]/images/File.gif"}"
style='border: 1px solid black;' ALT='[Description]'>
</a>
</TD>
<TD class=Normal>
<b>Name:</b> [Name]<br>
<b>Description:</b> [Description]<br>
<b>Type:</b> [MimeType] <br>
<b>Size:</b> [Size] <br>
<a {ACTION,[FileID],DeleteFile,,Message}>Delete</a>
</TD>
List Item (No Results):
<TR>
<TD width=100%>
<input type=text name=txtDescription id=txtDescription style="width: 100%;">
</TD>
<TD>
<input type=file name=frmFile id=frmFile>
</TD>
<TD>
<input type=submit id=frmSave name=frmSave value="Save">
</TD>
</TR>
</TABLE>
<HR>
<TR>
<TD><CENTER>Upload a file to the Gallery</CENTER></TD>
</TR>
</TABLE>
When you begin to review the format structure, take note of the information provided in the detail, as well as the
extended tags used within ListX. The functionality provided in this interface is relatively simple. First – the Action tag:
<a {ACTION,[FileID],OpenFile,,Message}>
This provides the ability to raise a message to the page whenever we click on the Image itself. The message is
broadcast as OpenFile type, with a physical value of the primary key of the table, the FIleID.
160
Version 1.9.7
Next, the interface needs to know whether the file that was uploaded contains a cropped image, which means it will
have a custom file value for the image source, or a non-image file, which will utilize a general image. The IIF tag
used here handles the check quite readily:
<img src="{IIF,"[IsImage]=True",
"[PORTALPATH,System]FileGallery/[FileID].[Path].png",
"http://[ALIAS,System]/images/File.gif"}"
style='border: 1px solid black;' ALT='[Description]'>
This identifies that the column IsImage from the source query will contain a value of 1 when the image is a file, and
that image will be stored under the path:
[PORTALPATH,System]FileGallery/[FileID].[Path].png
Otherwise, the image is to be displayed from the default File.gif image for the standard DotNetNuke core site. Note –
you will not have to worry about the existence of the FileGallery folder, it will be created automatically.
A number of columns are then displayed in the meta information region of the display – which is provided via the
format:
<b>Name:</b> [Name]<br>
<b>Description:</b> [Description]<br>
<b>Type:</b> [MimeType]
<b>Size:</b> [Size] <br>
Finally, the action required for raising the message of a Delete request. When pressed, the link will issue a Message
of type DeleteFile and contain a value of the physical FileID.
<a {ACTION,[FileID],DeleteFile,,Message}>Delete</a>
161
Version 1.9.7
Functionality
Now, to begin handling the functionality, as we deem necessary within the specification, we must start with creating
the three primary variables which make up the possible query actions. These contain the Description, which will be
yielded from the incoming Form object. Plus, two Message actions, which will be handling the aforementioned
Action tags (Open and Delete).
Query Variable - Description
The first Query variable added consumes the incoming Description from the defined form structure. As you saw
previously, the Description variable has the ID and Name set to “txtDescription”. Within the Update query, we will be
consuming this form object through the variable “@txtDescription”. Using the Target Left, Target Right, and Target
Empty settings, we will control the assignment so that when the Description is left empty, a NULL will be stored
within the database table.
162
Version 1.9.7
Query Variable – Open File
The second query variable will consume the value of the Open File Message. The front-end display broadcasts the
Open File message whenever the detail item image is clicked.
Query Variable – Delete File
The final query variable will consume the value of the Delete File Message. The front-end display broadcasts the
Delete File message whenever the detail item “Delete” link is clicked.
163
Version 1.9.7
Actions
A total of eleven actions are required to complete the Upload, View and Delete functionality of the File Gallery
example. The functionality covers the following logical concepts:
1. If the Save button on the form was clicked
a. Insert a record of this file into the File Gallery table, returning the new identity.
b. Store the incoming file into the target destination path, consuming the identity within the stored file
name.
c. If the incoming file is an image
i. Save a scaled clip of the file 100px wide (preserving the ratio for the height), consuming
the identity. (The clip will be stored in png format, at that is the recommended format for
scaling to retain the best quality.
ii. Update the record in the File Gallery, setting the flag identifying that this file has a image
clip.
2. Listen for the incoming message with the type “OpenFile”, identifying that the user would like to open the
full file.
a. Fetch the information for the target file, to identify the full original name of the file.
b. Send the file back through the response, with appropriate name and Mime Type.
3. Listen for the incoming message with the type “DeleteFile”, identifying that the user would like to delete the
file record.
a. Delete the information for the target file from the database table.
The actions will be laid out exactly as you see in the previous image, and following the defined structure designated
for this example. Now that we have identified the actual tasks at hand, follow the actions defined below to configure
the module.
Action – Condition: If
First, create the Action condition to determine if the Save button has been pressed. The form contains the submit
button with the name “frmSave” and the value “Save”. Whenever a submit button is pressed, the value of the
element is assigned, so you can safely identify that the button was pressed by checking the value of the element.
164
Version 1.9.7
Left Hand – The left hand portion of the conditional will be the evaluation of the frmSave form element:
„[frmSave,Form]‟. It is important to note that whenever you are identifying a condition which will evaluate a text
value, instead of a number, the text should be placed within single or double quotes.
Right Hand – The form element value has been set to “Save”, so „Save‟ will be the actual value of the frmSave
button, whenever it is pressed, triggering a passing of this condition.
Action – Execute
The first child of the conditional provides the ability to insert a record of this file into the File Gallery table, returning
the new identity. The Name of the execute statement will be “INSERT”, and can be used later within the syntax to
get the resulting Identity value.
Query INSERT INTO FileGallery
(
ModuleID,
Path,
Description,
Name,
Extension,
Size,
MimeType,
IsImage,
CreatedBy,
CreatedByUserID,
CreatedDate)
VALUES
(
[ModuleID,System],
'[frmFile.Name,Form]',
@txtDescription,
'[frmFile.NameOnly,Form]',
'[frmFile.Extension,Form]',
'[frmFile.Length,Form]',
'[frmFile.Type,Form]',
0,
'[UserName,System]',
'[UserID,System]',
getdate() )
SELECT SCOPE_IDENTITY() FileID
165
Version 1.9.7
Action – File
Store the incoming file into the target destination path, consuming the identity within the stored file name. The
standard utilization of the Action: File, storing a file from an incoming variable, is perfectly demonstrated here.
Source Type - Select the Variable as the source type, as our source is coming from a form variable.
Source Variable Type – Select <Form> as the source variable type.
Source – the source of this variable is the frmFile input element, so frmFile is the source value.
Destination Type – Select Path as the destination type, as we will store the incoming file into the designated path.
Destination – For this demonstration, we will store the files into the current portal directory, under a child directory
called FileGallery. If this directory fails to exist, the engine will automatically create the directory to store the file. The
file itself is named with the FileID, generated in the previous execution statement, and available through the tag
[FileID,INSERT], which means to render the FileID column from the result of the INSERT execution. We attach the
FileID to the header of the file name to be completely sure that the file itself is unique, regardless of the true name of
the file. The full path is identified as:
~/Portals/[PortalID,System]/FileGallery/[FileID,INSERT].[frmFile.Name,Form]
Transformation – No transformation is required for this purpose, as we are storing the complete file, regardless of
type at this time.
166
Version 1.9.7
If the incoming file is an image, now that we have save the physical file, we want to generate a thumbnail or clip of
the incoming image, for better visual representation. To do this, we simply check the Mime Type of the incoming file,
so we can pay less attention to the physical name of the file, and more attention to the actual type.
Left Hand – the easiest check for file of the type Image, we can check the first 5 characters of the incoming MIME
type. To to this, we use the following rendering tag structure:
„[FORMAT,[frmFile.Type,Form],{LEFT:5}]‟
Right Hand - The MIME type is always in lower case, based on the ANSI standard, and will always start with “image”
for files that are truly images.
Action – File (Image Transformation)
A perfect demonstration of the scaling of the images through ListX is provided by this example. For this sample we
will want to save a scaled clip of the file 100px wide (preserving the ratio for the height). The clip will be stored in
png format, at that is the recommended format for scaling to retain the best quality. The reason for this is simply a
lack of support by Microsoft for the GIF format, and retaining of transparency an such is far better in PNG than in the
standard .Net framework for GIF.
To begin – set the Source Type and Source Variable Type to Variable and <Form>. Then specify the Source of the
image as frmFile, exactly as we did previously.
The path for storage of this image is exactly the same as the previous file action also, with the addition of a specific
extension following the form name of .png. So set the Destination to:
~/Portals/[PortalID,System]/FileGallery/[FileID,INSERT].[frmFile.Name,Form].png
Finally, setup the physical transformation of the file. ListX maintains compatibility and visual aspect appeal of all
images based on the following rules. Whenever you chose to complete an Image transformation, the Width and
Height will be automatically adjusted based on the aspect ratio of the incoming source file. This means that if I
specify only one of the two dimensions, the other dimension will automatically be calculated based on the actual file
dimensions and scaling rules. Two specific rules come into play after the initial size calculation though. First, if only
one dimension is specified, and the other is meant to be auto calculated, and the resulting scaled image will be
Larger than the incoming source file, the dimensions will remain at the orginal size. Meaning, for this example, if I
am uploading an image that is 32px by 32px, and I specify 100px width, the resulting file will still be 32px by 32px.
167
Version 1.9.7
This is always the case unless both the Width and Height are specified, and in that scenario, the output file will be
the exact specified size.
Specify that the Width of the file wil be 100px, to provide a nice UI interface, and that the height will be automatic.
Action – Execute
Update the record in the File Gallery, setting the flag identifying that this file has an image clip. This is important so
that result query is much faster to identify whether to display the standard file image, or the intelligent thumbnail
image. While we could do this processing within the query, or within the detail rendering, it is easier to identify here
since we have already performed the required condition.
The Name of the query is not truly necessary here, but it is always good to have a simple representation of the
query, so we set it to “SET IMAGE”.
The query is relatively straight forward, setting isImage to 1 for the file that was previously inserted.
UPDATE FileGallery SET isImage = 1 WHERE FileID = „[FileID,INSERT]‟
Message – Open File
Listen for the incoming message with the type “OpenFile”, identifying that the user would like to open the full file.
The Type of the message will be OpenFile, and since the actual value varies because it is set to the physical ID of
the requested file, we will leave the Value blank. Meaning, we will react to all message of this type, regardless of
value.
Action - Execute
To fetch the information about the requested file, including the MIME type, which will be used for the response type,
and the physical path of the file, we first need to execute a query. We will Name the Execution “FETCH” and refer to
it by name in the File (Response) Action following. The query is very simple, consuming the predefined @OpenFile
query variable as such:
SELECT * FROM FileGallery where FileID = „@OpenFile‟
168
Version 1.9.7
Action – File (Response)
Send the file back through the response, with appropriate name and Mime Type. This is done through setting up our
Action:File structure in nearly the opposite setting used previously for storing the file.
Source Type – First, set the Source Type to Path, as the file has bee stored physically within the web server file
system, under the FileGallery folder within our current Portal root folder.
Source - The source of the file is mapped through the existing path information, and folder directives we used for
storing the file. We store just the file name, so the entire structure is movable very easily into other folders or storage
locations, without requiring changes to the database records. The source we will be using:
~/Portals/[PortalID,System]/FileGallery/[FileID,FETCH].[Path,FETCH]
Consumes the PortalID from the system runtime, and the FileID and Path columns resulting from the FETCH query
which we just recently defined.
Destination Type - in order to send the file back the client browser set the Destination Type to the Response.
Response Type – to help the browser identify which application should handle the physical opening of the incoming
file which we are sending, the Response Type is utilized. Since we stored the MIME type on the initial upload, the
MIME Type can be specified as the Response Type. This is handled through the MimeType column from the
previous FETCH query: [MimeType,FETCH]
Destination – The destination attribute allows you to specify the name of the outgoing file. While we house the file in
the local system, it is named with an arbitrary FileID value as well as its original name, but on the output, we will
want to send just the physical information which we received originally with the file request. For this, we will use the
Path column from the FETCH statement: [Path,Fetch]
Message – Delete File
Listen for the incoming message with the type “DeleteFile”, identifying that the user would like to delete the file
record. The Type of the message will be DeleteFile, and since the actual value varies because it is set to the
physical ID of the requested file, we will leave the Value blank. Meaning, we will react to all message of this type,
regardless of value.
169
Version 1.9.7
Action - Execute
Delete the information for the target file from the database table. This is done through a simple query which will
delete the file gallery value where its ID matches the value of the predefined@DeleteFile query variable. No name is
required here, but we tend to add them anyway just to keep things visually simplistic within the action interface.
The query is quite simple indeed:
DELETE FROM FileGallery WHERE FileID = „@DeleteFile‟
170
Version 1.9.7
Examples – Web Service Integration
The ListX module provides the inherent ability to pull and push data to and from externally linked sources,
via HTTP Post and Get requests. This is all handled through the usage of out Action:Input message action,
and allows you to completely control the usability, and extend the functionality of your module extensively.
The provided sample is based on logic utilized originally by our popular GoMap product, and extended to the Yahoo
GeoCoding service, provided by the Yahoo API, rather than the Google API, so as to diversify the logic as much as
possible.
1. Formatting
f. Variables
g. Action
h. Form
2. Variables
i. Session
j. Action
k. Form
3. Actions
l. Action: Message
m. Action: Assignment
n. Action: Input
The Process
To begin, create a tab, and add a ListX module. Open the view options and begin you development efforts. For this
sample, the task is to create a module which can take an incoming address location, and convert it to a target
longitude and latitude geographic position.
The form structure, and handling are simplified, and easy to manage with ListX, while the physical geocoding can
be handled through many available services. For this sample, we are consuming the yahoo geocoding service
provided by http://developer.yahoo.com/maps/rest/V1/geocode.html
To begin, it is important to understand the initial loading of the ListX configuration. From there, we will go over the
requirements of the actual web service call.
Formatting
First, set-up the form to allow the street, city, state and zip provisions. Additionally, Yahoo requires an approved
parameter known as an AppID. The following form structure will be used:
<table width=300px border=0 cellpadding=0 cellspacing=0>
<tr><td style="width: 100px;" class=SubHead>AppId</td><td class=Normal><INPUT
name=frmAppId></td>
</tr>
<tr><td style="width: 100px;" class=SubHead>Street</td><td class=Normal><INPUT
name=frmStreet></td>
</tr>
<tr><td style="width: 100px;" class=SubHead>City</td><td class=Normal><INPUT
name=frmCity></td></tr>
<tr><td style="width: 100px;" class=SubHead>State</td><td class=Normal><INPUT
name=frmState></td></tr>
<tr><td style="width: 100px;" class=SubHead>Zip</td><td class=Normal><INPUT name=frmZip></td></tr>
<tr><td colspan=2 align=center><a {ACTION,,Lookup,Geocoder,,Message}>Find It!</a></td></tr>
171
Version 1.9.7
</table>
<div>[Result,Action]</div>
Actions
Action - Message
Once the form is ready, you will need to add a few actions for processing the incoming message. As demonstrated
within the ListX tag structure, a module communication message will be raised whenever the user presses the “Find
It!” link, with a type of “Geocoder”, and a value of “Lookup”.
Action - Assignment
Next, to make things simple, and easy to maintain, we will want to provide information for displaying the result. First,
let set the result to a standard “Try Again” method. The result is to be stored within an Action variable, and will be
consumed within the interface. Be sure to note here, that Action variables survive only within the request that
manufactured them. This means, that when AJAX is enabled, and the Action is created by the Message handling
script, it truly occurs within the initial page request, NOT the secondary AJAX request.
Action - Assignment
Because we will be storing the incoming data result, within session variables, all starting with the “result” prefix, we
need to verify that the incoming result in fact exists. When the Yahoo geocoding service cannot identify the correct
location, it fails to return an appropriately formatted result, and therefore, the session variables are never reassigned
to the failure. To force the
172
Version 1.9.7
situation ahead of time, lets specifically assign one of the primary variables, which we can then check after the Input
completes. For this, we will manually assign the incoming Latitude placeholder to 0.00.
Action - Input
Now for the actual dirty work, calling the web service. To do this, add an Action:Input message action. The following
variables will need to be assigned for the Yahoo service to work appropriately.
URL – this will be assigned to the documented API Maps Service call provided by Yahoo:
http://api.local.yahoo.com/MapsService/V1/geocode
Content Type – as stated within the documentation, the Content Type parameter can at times be tricky to set
correctly, many times depending on the exact formulation of the service to which you are cooresponding. However,
this sample is a perfect solution for persons who are communicating directly with standard web service interfaces.
For most situations, including this one use:
application/x-www-form-urlencoded
Query String – depending on the target communication, as well as the Method, you may or may not need to use the
query string, but rather, the Data region of the Input action. For the Yahoo API, the Request Query String is straight
forward and easy to use. The first thing you will need before using the form, is a correct App Id, which you can
create via the provided Yahoo link above. The additional parameters are strung directly within the parameter, so
they are easy to see, and configure:
appid=[frmAppId,Form]&zip=[frmZip,Form]&street=[frmStreet,Form]&city=[frmCity,Form]&state=[frmState,Form]
Method – the provision requires the GET method, for the standard URL request.
173
Version 1.9.7
Response Format – the resulting response from Yahoo, atleast at the time of this documentation, is XML formatted,
and looks something like this:
<?xml version="1.0" encoding="UTF-8"?>
<ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="urn:yahoo:maps"
xsi:schemaLocation="urn:yahoo:maps
http://api.local.yahoo.com/MapsService/V1/GeocodeResponse.xsd">
<Result precision="address">
<Latitude>37.416384</Latitude>
<Longitude>-122.024853</Longitude>
<Address>701 FIRST AVE</Address>
<City>SUNNYVALE</City>
<State>CA</State>
<Zip>94089-1019</Zip>
<Country>US</Country>
</Result>
</ResultSet>
Variable Type – the target location where the incoming result parsing will be stored, for our demonstration, this is:
<Session>
Name – this identifies either the name of the target variable, when the path is explicitly defined, or may be a
variation of multiple possible values, which is the case here. Our XML Path will set the location to be on the node
reading “<Result precision=address>” Since we need more than one of the parameters – in our case, we need both
the Latitude and the Longitude, we will need to use some special additional formatting on the Name of the storage
variable. The possible additional values are [*Child], meaning we will be assigning multiple variables, with the
[*Child] tag replaced by the name of the child nodes, ie. ResultLatitude,ResultLongitude,ResultAddress et al. The
other possibility, is the [*Index] tag, which means that each result will be placed with an index attached, for all child
records. Our sample does not use this structure, nor does it need it, but if you had multiple Result tags within the
174
Version 1.9.7
Result Set, and wanted to keep all the returned values, that is what you would need to use also. In our case, the
following is provided:
Result[*CHILD]
XML Path - Finally, the actual XML Path of the result will be used. Because the incoming result assigned a default
namespace to the document, a namespace urn is required for parsing the incoming content. ListX automatically
builds a Names table of all the possible namespaces, but when the default is overridden, the specified name is not
possible. However, the default namespace has been given a fixed name within ListX, and is by design to allow for
easy checking of XML values. To use the root namespace, when this is the case, use “default” as the namespace
name. With that said, for this example:
.//default:Result
With those settings specified, we now must simply handle the incoming result, to determine whether we should
display the result of not. To do that, add an If Condition action, and set it to check to see if the “resultLatitude” is
greater than zero. If so, we will move forward, otherwise, exit the action list.
Action - Assignment
Finally, if this condition passes muster; we finally want to create the formalized result statement. To do this, add a
final Assignment action, the content of which will assign the Result Action variable, to the format:
Location found:<br>
Latitude: [resultLatitude,Session]<br>
Longitude: [resultLongitude,Session]
The result of this message, is displayed whenever the content is rendered, and now the resulting page will display
all the information you require.
The end result of these additions will be a properly handled message list, like the following. As you can see easily
from the screen shot, the Message is the root action, and all child actions stem from this initial step. The Final
assignment is a child of the verification condition.
175
Version 1.9.7
Demonstration
Now that all the connections have been made, we just need to provide the information we requested within the ListX
form. For the demonstration, I identified that yahoo.com, while both an obvious choice, as well as a quick AppId for
the sample, works for the App Id, if you have not yet registered an App Id.
Now – just press “Find It!” – and the truth will be revealed!
176
Version 1.9.7
Examples (Extended)
Provided on our website, two basic configurations were created for displaying the simple usage of the ListX module.
Since we anticipate growing this number in the future to support more user requests, and enhanced demonstrations,
we have opted to leave the physical location of these examples on the site itself. Follow the link provided to view the
standard marketing page for ListX. Locate the links to the specific examples and copy the configuration settings, as
well as any provided SQL scripts which may be necessary.
ListX Information with Future Examples
o Event Log Example - Provides all the aspects you would need for interact with, and maintaining
the Event Log which is provided by DNN. The Event Log Sample provides a list view similar to the
likes of the core display. Additionally, it provides a checklist delete functionality as well as single
property sheets and a property editor for the Event Logs. A complete a robust sample to use for
any of your ListX projects.
o Member Directory Example - If you have ever wanted to expose the member directory, or contacts
contained within your DotNetNuke user table, this module provides everything you need for finding
the record you are looking for, and providing a sleek interface that invites interaction.
o Northwind Example – To make a more versatile, full featured example, usable from a complete
solution standpoint, we have provided a feature-rich demonstration of the full NukeDK product
package, including lists, grids, details, property sheets, searching, filtering and forms.
o Package Downloads – We have added a Package download area to our site where we will add
many additional packages for use on your own website, or for examples of development with
NukeDK.
Note: You must be a registered member on our website to obtain the configuration XML for each of the
demonstrations. Registration is free, and immediate. Happy Nuking!
177
Version 1.9.7
ListX Skin Objects
You can now use your existing ListX modules as Skin objects directly within your skins. Its really easy to do – first
create your ListX module – then, within the same portal skin, setup the appropriate tag definition pointing to your
skin.
<%@ Register TagPrefix="b4" TagName="LISTX" Src="~/DesktopModules/ListX/xListingSkin.ascx" %>
<b4:LISTX runat="server" id="b4ListXVersion" TabID="202" ModuleID="641" TabModuleID="333"
useCurrent="False" />
These settings are very straight forward. In order to load the correct settings for your skin ListX module, it needs to
know the TabID, ModuleID, TabModuleID and whether to use the Current Tab or the source Tab for the current Tab
ID. Change these settings – and start flying!
NOTE: The useCurrent flag seems to be a bit foolish at times, and does not always return the current TabID when
[TabID,System] is requested. Instead, use the reflection parameters of ListX –
[PortalSettings.ActiveTab.TabId,System]
178
Version 1.9.7
Building ListX Packages (LP)
Since ListX provides the ability to export files directly to the requesting browser, a list of known MIME types
expected as the outgoing type was essential to aid our developers in export processes. While this list is not
completely up to date, it does give a pretty accurate list to go from initially:
When you click on the Module Settings of the ListX modules, you see a ListX Package Installation area. To install a
Package, or turn your existing portal into a package, use this area. Packages consist of full site definitions of ALL
Tabs and ListX/Toolbar modules, and will automatically install these Tabs and Modules into the target site based on
the structure tab names within the package. Additionally, the package can place resource files, load the current
module configuration, and execute any number of SQL scripts to install the required portions.
To generate your existing solution portal into an Installable Package you can SELL or SHARE to other ListX users,
simply press the Generate Package link, then Check the box next to each of the tabs you would like to include – the
resulting Zip file is already a FULL Package, all you need to do is add any custom sql scripts, and resource files and
you will be ready to roll. We also conveniently document the structure of the .install XML file within the file, so you
can follow the guidelines for setting it up – here is an example:
<installer name="My Website" version="3.2.0" generated="07/27/2006 05:47:20" creator="SuperUser Account"
company=”” uniqueid=””>
<!-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NUKEDK - PACKAGE CONFIGURATION INSTRUCTIONS:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ListX Installation Package supported the following types of tags:
SCRIPT: Executes provided SQL Scripts against the target site database. These
Files should be placed in the order which they will be executed. Like
standard DotNetNuke Scripts, the {databaseOwner} and {objectQualifier}
179
Version 1.9.7
tags are supported, as are standard ListX variables like [PORTALID].
EXAMPLE:
<script name="Tables.sql"/>
<script name="UserDefinedFunctions.sql"/>
<script name="StoredProcedures.sql"/>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FILE: Takes the incoming file by Name within the Package and stores it at the
target location within the Dotnetnuke instance. All ListX tags are
supported within the path attribute, so you can place simple things
within the target path such as [PORTALID].
EXAMPLE:
<file name="paypal.html" path="~/items/paypal.html"/>
<file name="banner.gif" path="~/Portals/[PORTALID]/banner.gif"/>
<file name="spacer.gif" path="~/Portals/[PORTALID]/spacer.gif"/>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TAB: The heart of the ListX Package installation routines, the Tab element
identifies the tab file which will be used to building the target
pages and modules. ONLY NUKEDK MODULES ARE SUPPORTED HERE!!! So other
third party modules will be completely ignored on the export. No indent
is required, but it does aid in visual identification of parent child
tab relationships between the target entities.
EXAMPLE:
<tab name="Shipping Methods.tab"/>
<tab name="Edit Ship Methods.tab"/>
<tab name="PPP.tab"/>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CONFIG: When the Package is meant to only overwrite the current modules ListX
Configuration, the Configuration tag lets you identify the source file
containing the actual XML settings.
This is generally not used when additional tabs are created, and is not
required.
EXAMPLE:
<configuration name="Repository.config"/>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<tab name="Home.tab"/>
<tab name="Search Results.tab"/>
<tab name="Calendar .tab"/>
<tab name="LXSample.tab"/>
<tab name="Management.tab"/>
<tab name="Shipping Methods.tab"/>
<tab name="Edit Ship Methods.tab"/>
<tab name="Categories.tab"/>
<tab name="Edit Categories.tab"/>
<tab name="Packages.tab"/>
<tab name="PackagesEdit.tab"/>
<tab name="PPP.tab"/>
<tab name="xList Repository.tab"/>
<tab name="New Test.tab"/>
<tab name="File.tab"/>
<tab name="Vendor List.tab"/>
<tab name="Vendor Details.tab"/>
<tab name="Vendor Material.tab"/>
<tab name="x.tab"/>
</installer>
180
Version 1.9.7
Building Custom Modules (PA)
Many of our users have asked for the ability to create PA‟s, installable Assembly ZIP files which act and react like
the other modules within the system. Therefore, taking your ListX configurations and turning them into custom
modules which can be dropped on any page, and remove the ListX Options from the menu, providing you‟re the
ability to create whatever you want and distribute your modules anywhere.
To provide this ability, you will need a little knowledge of how PA‟s work, which we provide here – as well as a
guideline for how to physically manage your module structures to handle this.
Build your Modules
Create your modules, just as your ordinarily would with ListX. The only limitation you must keep in mind is that –
unlike standard ListX configurations, you will only have ONE module added to the page when you drop on your
Custom Control. Other Controls will be embedded into the Module and appear on the Action menu, similar to the
way ListX has a front-end View Control, and a View Options control which appears on a separate interface.
Additionally, you will possibly desire the ability to create a module that appears on the Module Settings page, and
bind this to the Update click which appears at the base of that page. This is possible – and made very easy through
the ListX environment.
For example – take the Repository LP, which is familiar to most users. We have created a PA version of this module
configuration, allowing you to Drop the module onto any page you desire. To demonstrate the Module Settings page
also, we provide the ability to set the Instructions which appear on this page. Don‟t worry, we have a number of
other PA samples coming out which will provide even more insight into the capabilities. And rest assured, if you
have created ListX configurations – creation of your custom PA is easy and very rapid.
The repository module, in all its glory – is made up of two ListX configurations. The first, the Repository interface,
provides the standard behavior you are already used to. To implement the Instructions through the Module Settings,
we first change the interface to display the [Instructions,ModuleSettings] property:
181
Version 1.9.7
Next, we need to create the interface which will be used for Saving the Module Settings. This is broken into two
conceptual parts. First – the interface for displaying and Editing the value is a simple Text Area.
Default Item (No Query)
<table width=100%>
<tr>
<td width=150 nowrap class=SubHead>Instructions</td>
<td>
<textarea id=txtInstructions name=txtInstructions
style='width: 100%; height: 150px;'>
[Instructions,ModuleSettings]
</textarea>
</td>
</tr>
</table>
Next, we need to handle the Update Settings button, which appears on the Module Settings page. To make this
simple, we have modified the ListX runtime to tree the Update Settings click in the same way we handle the
Message Actions. To do this, you simply need to decide what you are listening for. When we go on to the next
182
Version 1.9.7
section, creating the controls, we will map the Type/Name assignment we are listening for to the Options in the ascx
text file. So it is arbitrary and doesn‟t truly matter. For our purposes, we will stick to Settings/Update:
Yes, we are ready for the next step – placing the controls into your ascx files.
Create your Custom Controls
To create the custom controls, you will need to create text files which define the ascx control, and will either need an
XML editor for assigning the XML Configuration to your resource (resx) files, or you can use Visual Studio‟s
Resource File Editor. There are others available on the market, and again – this is very simple to do:
Each Control will be built with TWO files – an ASCX and an RESX.
For our sample, we begin with the Repository ListX front-end module.
Create a File – Repository.ascx – with your text editor
Set the contents of the file to the following:
<%@ Control Language="vb" Inherits="Bi4ce.Modules.ListX.Module.PortalModuleBase"
TargetSchema="http://schemas.microsoft.com/intellisense/ie5" %>
<%@ Register TagPrefix="BI4CE" Namespace="Bi4ce.Modules.ListX.Module" Assembly="Bi4ce.Modules.xList"
%>
<BI4CE:Configuration runat="server"
ResourceKey="CustomModule"
/>
For this module, the only portion which will change depending on your preferences, is the ResourceKey attribute.
This Key will tie into the resource keys defined in your resx file.
Create your RESX file, named Repository.ascx.resx. These resource files are typically named the same as the
ascx, followed by the resx extension.
Open the RESX file and add the resource key. The structure of the file is provided, and the key is the only important
part. If you need help with the resource files, take a quick look at the sample – and you can just copy and paste from
there.
Add the your ResourceKey to the RESX file. The key must be followed with a .Text extension. Meaning – the full key
for us is CustomModule.Text
Open your ListX Configuration, Copy the XML directly out of the interface, and paste it as the VALUE of your Key.
183
Version 1.9.7
Now
save
the
Resx
file.
The
second module is the Modules Settings module, this will be handled in the same way, with only one slight change to
the ASCX.
Create a File – RepositorySettings.ascx – with your text editor
Set the contents of the file to the following:
<%@ Control Language="vb" Inherits="Bi4ce.Modules.ListX.Module.ModuleSettingsBase"
TargetSchema="http://schemas.microsoft.com/intellisense/ie5" %>
<%@ Register TagPrefix="BI4CE" Namespace="Bi4ce.Modules.ListX.Module" Assembly="Bi4ce.Modules.xList"
%>
<BI4CE:Configuration runat="server"
ResourceKey="CustomModule"
SystemMessage_UpdateSettings="Settings|Update"
/>
For this module, the only portion which will change depending on your preferences, is the ResourceKey attribute.
This Key will tie into the resource keys defined in your resx file. Additionally, set SystemMessage_UpdateSettings
to match the Message Listener we created in our module, the Type and Name are delimited by a Pipe character.
This Listener is used to handle the Update Settings link click within the Module Settings interface.
Create your RESX file, named RepositorySettings.ascx.resx. These resource files are typically named the same as
the ascx, followed by the resx extension.
Open the RESX file and add the resource key. The structure of the file is provided, and the key is the only important
part. If you need help with the resource files, take a quick look at the sample – and you can just copy and paste from
there.
Add the your ResourceKey to the RESX file. The key must be followed with a .Text extension. Meaning – the full key
for us is CustomModule.Text
Open your ListX Configuration, Copy the XML directly out of the interface, and paste it as the VALUE of your Key.
184
Version 1.9.7
Now,
save
the
Resx
file.
Build the PA (.dnn) file
The final step required for your module is the .dnn file. This file defines which modules are included in your PA, and
where they should be installed. There is very good documentation on this from dotnetnuke, so we will not get in
depth. The basics are covered directly by this sample. Here are the contents of the file for our sample – Repository
PA.
<?xml version="1.0" encoding="utf-8" ?>
<dotnetnuke version="2.0" type="Module">
<folders>
<folder>
<name>ListX_Repository</name>
<description>Custom ListX Repository Module.</description>
<version>00.00.01</version>
<modules>
<module>
<friendlyname>ListX_Repository</friendlyname>
<controls>
<control>
<src>Repository.ascx</src>
<type>View</type>
</control>
<control>
<key>Settings</key>
<title>Repository Settings</title>
<src>RepositorySettings.ascx</src>
<type>Edit</type>
</control>
</controls>
</module>
</modules>
<files>
<file>
<name>Repository.ascx</name>
</file>
<file>
185
Version 1.9.7
<name>RepositorySettings.ascx</name>
</file>
<file>
<name>00.00.01.SqlDataProvider</name>
</file>
<file>
<path>App_LocalResources</path>
<name>Repository.ascx.resx</name>
</file>
<file>
<path>App_LocalResources</path>
<name>RepositorySettings.ascx.resx</name>
</file>
</files>
</folder>
</folders>
</dotnetnuke>
That‟s about all you need. Notice the 00.00.01.SqlDataProvider. This file provides the installation script required for
the installation use of your module. If your module has no support SQL structures, it‟s not required, but if you need
to create any tables, procedures or functions, you will want to create this file.
Once you are ready, select your files, and zip them into one compressed file. This file is your PA – and will install on
any instance of DNN. Remember, you created your module with ListX, so it will be required for you runtime.
The End Result
186
Version 1.9.7
187
Version 1.9.7
188
Version 1.9.7
Repository
A complete source and version repository is built directly into the ListX runtime. Each change to the configurations
immediately triggers a backup of the current runtime version, and replacement of that runtime with the new
configuration. Each of these versions is tracked within the ListX Repository, and can be restored immediately,
without worry. Additionally, each item contained within the Repository can be marked with a Label. This means that
if you have a version which is a known stable configuration, you may desire setting a mark on that item and Labeling
the configuration as such. This provides a robust, yet simple way of managing your repository on each module.
To access the repository, navigate to the module actions, Extended and press Repository Menu item.
Working within the repository is easy. Each column is sortable, so you can review the list of entries quickly. Each
column provides a bit more information about the specific configuration. You can see the Date it was updated, the
Comment (or Label) that has been associated with the entry, and the Length of the physical configuration text.
To label an item, press the Edit link in the Comment column. An inline editor will appear providing the edit
textbox. Enter your text and press Save.
189
Version 1.9.7
To restore a configuration, rolling it back to a prior version, simply press the Rollback link. The text will change to a
Confirmation prompt. Click a second time to perform the Rollback.
190
Version 1.9.7
Log
Providing a higher level of capacity, and a more flexible interface for the ListX environment, the latest version are
provided with a Log mechanism that is both Automated, as well as configurable. You can automatically add full
Debugging Log entries via the Default Properties interface, and can manually append custom entries via the Actions
(Action:Log) settings. To review the log, navigate to the Action menu for the module, Extended >> Log
Working within the Log entries is easy. Sort the resulting log by clicking on the Date,SettingName (Group) and
Username columns. The entries automatically record the Username of the person who caused the entry to occur.
Displayed in the screenshot is Automated Debug, which occurs when Trace is turned on for all interaction. Clicking
on the View icon or the Group name will return the content of the entry.
191
Version 1.9.7
Quick Builder
Getting started quickly within the ListX environment is very easy to do thanks to the Quick Builder interface. With
Quick Builder you can provide a few key pieces of information, which include your table name, primary key of the
table and custom query for selecting out of the table. Then, choose your layout and generate your configuration and
interface automatically. To get to the Quick Builder, navigate to Extended >> Quick Builder.
The interface is simple and easy to use. In the Select Your Source section, provide the name of the table, Primary
key and Select statement. It is important to note that the you MUST have data in the target table for the generator to
work. This is because the Rendering functionality used for the builder cannot determine that exact column
information without an initial result. Additionally, you MUST contain the Primary Key column, designated within the
provided textbox within your query. If it is missing, the Detail and Edit forms will be incapable of appropriate
functionality. Within the following screen, we are selecting information directly out of the DNN Users table. Clicking
on the Test your Query link as seen provides the results of the first five (5) rows of the executed query.
Now that you have entered the SQL information, choose the Layout for your configuration. Currently there are three
options – List, View and Edit.
192
Version 1.9.7
The List or Grid view provides an configuration which will include redirection and ajax driven delete for each record
in the list. If you choose to provide the Edit and View links within the List, you can pick the destination page for the
target. For both links, a Querystring parameter is generated for the target page which consists of the primary key
column.
Example: /tabid/213/UserID/4/Default.aspx
The Edit and View configurations will automatically digest the incoming Primary Key value to select out of your
custom query. Again – it is important to stress that your query MUST return data, or no generation will take place.
The Edit form also comes pre-populated with appropriate utilization of the COALESCE for the editable values, as
well as Messages for handling the physical Save of your data. Check out the resulting Actions for your configuration
and see what was created automatically!
193
Version 1.9.7
194
Version 1.9.7
Appendix I - MIME Types
Since ListX Provides the ability to export files directly to the requesting browser, a list of known MIME types
expected as the outgoing type was essential to aid our developers in export processes. While this list is not
completely up to date, it does give a pretty accuate list to go from initially:
.ai - application/postscript
.aif - audio/x-aiff
.aifc - audio/x-aiff
.aiff - audio/x-aiff
.asc - text/plain
.au - audio/basic
.avi - video/x-msvideo
.bcpio - application/x-bcpio
.bin - application/octet-stream
.c - text/plain
.cc - text/plain
.ccad - application/clariscad
.cdf - application/x-netcdf
.class - application/octet-stream
.cpio - application/x-cpio
.cpt - application/mac-compactpro
.csh - application/x-csh
.css - text/css
.dcr - application/x-director
.dir - application/x-director
.dms - application/octet-stream
.doc - application/msword
.drw - application/drafting
.dvi - application/x-dvi
.dwg - application/acad
.dxf - application/dxf
.dxr - application/x-director
.eps - application/postscript
.etx - text/x-setext
.exe - application/octet-stream
.ez - application/andrew-inset
.f - text/plain
.f90 - text/plain
.fli - video/x-fli
.gif - image/gif
.gtar - application/x-gtar
.gz - application/x-gzip
.h - text/plain
.hdf - application/x-hdf
.hh - text/plain
.hqx - application/mac-binhex40
.htm - text/html
.html - text/html
.ice - x-conference/x-cooltalk
.ief - image/ief
.iges - model/iges
.igs - model/iges
.ips - application/x-ipscript
195
Version 1.9.7
.ipx - application/x-ipix
.jpe - image/jpeg
.jpeg - image/jpeg
.jpg - image/jpeg
.js - application/x-javascript
.kar - audio/midi
.latex - application/x-latex
.lha - application/octet-stream
.lsp - application/x-lisp
.lzh - application/octet-stream
.m - text/plain
.man - application/x-troff-man
.me - application/x-troff-me
.mesh - model/mesh
.mid - audio/midi
.midi - audio/midi
.mif - application/vnd.mif
.mime - www/mime
.mov - video/quicktime
.movie - video/x-sgi-movie
.mp2 - audio/mpeg
.mp3 - audio/mpeg
.mpe - video/mpeg
.mpeg - video/mpeg
.mpg - video/mpeg
.mpga - audio/mpeg
.ms - application/x-troff-ms
.msh - model/mesh
.nc - application/x-netcdf
.oda - application/oda
.pbm - image/x-portable-bitmap
.pdb - chemical/x-pdb
.pdf - application/pdf
.pgm - image/x-portable-graymap
.pgn - application/x-chess-pgn
.png - image/png
.pnm - image/x-portable-anymap
.pot - application/mspowerpoint
.ppm - image/x-portable-pixmap
.pps - application/mspowerpoint
.ppt - application/mspowerpoint
.ppz - application/mspowerpoint
.pre - application/x-freelance
.prt - application/pro_eng
.ps - application/postscript
.qt - video/quicktime
.ra - audio/x-realaudio
.ram - audio/x-pn-realaudio
.ras - image/cmu-raster
.rgb - image/x-rgb
.rm - audio/x-pn-realaudio
.roff - application/x-troff
.rpm - audio/x-pn-realaudio-plugin
.rtf - text/rtf
.rtx - text/richtext
196
Version 1.9.7
.scm - application/x-lotusscreencam
.set - application/set
.sgm - text/sgml
.sgml - text/sgml
.sh - application/x-sh
.shar - application/x-shar
.silo - model/mesh
.sit - application/x-stuffit
.skd - application/x-koan
.skm - application/x-koan
.skp - application/x-koan
.skt - application/x-koan
.smi - application/smil
.smil - application/smil
.snd - audio/basic
.sol - application/solids
.spl - application/x-futuresplash
.src - application/x-wais-source
.step - application/STEP
.stl - application/SLA
.stp - application/STEP
.sv4cpio - application/x-sv4cpio
.sv4crc - application/x-sv4crc
.swf - application/x-shockwave-flash
.t - application/x-troff
.tar - application/x-tar
.tcl - application/x-tcl
.tex - application/x-tex
.texi - application/x-texinfo
.texinfo - application/x-texinfo
.tif - image/tiff
.tiff - image/tiff
.tr - application/x-troff
.tsi - audio/TSP-audio
.tsp - application/dsptype
.tsv - text/tab-separated-values
.txt - text/plain
.unv - application/i-deas
.ustar - application/x-ustar
.vcd - application/x-cdlink
.vda - application/vda
.viv - video/vnd.vivo
.vivo - video/vnd.vivo
.vrml - model/vrml
.wav - audio/x-wav
.wrl - model/vrml
.xbm - image/x-xbitmap
.xlc - application/vnd.ms-excel
.xll - application/vnd.ms-excel
.xlm - application/vnd.ms-excel
.xls - application/vnd.ms-excel
.xlw - application/vnd.ms-excel
.xml - text/xml
.xpm - image/x-xpixmap
.xwd - image/x-xwindowdump
197
Version 1.9.7
.xyz - chemical/x-pdb
.zip - application/zip
198
Version 1.9.7
Appendix II - Connection Strings (OLE/ODBC.Net)
ListX provides the ability to use external connections from standard .Net ODBC supported databases via the
Connection property of the Rendering, Action:Execute and Sub queries. The provided list below is a breakdown of
example Connection Strings from well known Database Management Systems.
Access
Default
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=\path\dabasename.mdb;User Id=admin;Password=;
Password Protected
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=\path\dabasename.mdb;Jet OLEDB:Database
Password=passwordValue;
Active Directory
Provider=ADSDSOObject;User Id=Username;Password=PasswordValue;
AS/400 (iSeries)
PROVIDER=IBMDA400; DATA SOURCE=SOURCE_SYSTEM;USER
ID=Username;PASSWORD=PasswordValue;
DBF / FoxPro
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=c:\path;Extended Properties=dBASE IV;User
ID=Admin;Password=OptionalPasswordValue;
DSN
Default
DNS=DsnName;Uid=Username;Pwd=OptionalPasswordValue;
File DSN
FILEDSN=C:\Path\File.dsn;Uid=Username;Pwd=OptionalPasswordValue;
Excel
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Path\FileName.xls;Extended Properties=""Excel
8.0;HDR=Yes;IMEX=1
Firebird
User=Username;Password=PasswordValue;Database=DatabaseFileName.fdb;DataSource=ServerName;
Port=3050;Dialect=3;Charset=NONE;Role=;Connection
lifetime=15;Pooling=true;MinPoolSize=0;MaxPoolSize=50;Packet Size=8192;ServerType=0;
IBM DB2
Provider=DB2OLEDB;Network Transport Library=TCPIP;Network Address=IP ADDRESS;Initial
Catalog=SourceCatalog;Package Collection=SourceCollection;Default Schema=Schema;User
ID=Username;Password=OptionalPasswordValue;
Informix
Provider=Ifxoledbc.2;password=OptionalPasswordValue;User ID=Username;Data
Source=DatabaserName@Server_Name;Persist Security Info=true;
Ingres
Provider=MSDASQL.1;DRIVER=Ingres;SRVR=SERVER;DB=DATABASE;Persist Security Info=False;
uid=UserName; pwd=OptionalPasswordValue; SELECTLOOPS=N; Extended
Properties="SERVER=SERVERNAME; DATABASE=DATABASENAME; SERVERTYPE=INGRES"
199
Version 1.9.7
Interbase
provider=sibprovider;location=server:;data source=c:\path\dabasename.gdb;user
id=UserName;password=OptionalPasswordValue
MySQL
Provider=MySQLProv;Data Source=DatabaseName;User
Id=Username;Password=OptionalPasswordValue;
Oracle
Default (Microsoft)
Provider=msdaora;Data Source=OracelDatabaseName;User Id=Username;
Password=OptionalPasswordValue;
Default (Oracle)
Provider=OraOLEDB.Oracle;Data Source=OracelDatabaseName;User Id=Username;
Password=OptionalPasswordValue;
Trusted Connection
Provider=OraOLEDB.Oracle;Data Source=OracelDatabaseName;OSAuthent=1;
Paradox
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=c:\DatabaseName;Extended Properties=Paradox 5.x;
Pervasive
Provider=PervasiveOLEDB;Data Source=C:\Path
SQL Server
Provider=sqloledb;Data Source=DataSourceName;Initial Catalog=DatabaseName;User
Id=Username;Password=OptionalPasswordValue;
Provider=sqloledb;Data Source=IPADDRESS,1433;Network Library=DBMSSOCN; Initial
Catalog=DATABASENAME; User ID=Username; Password=OptionalPasswordValue;
Sybase
Adaptive Server Anywhere (ASA)
Provider=ASAProv;Data source=ASADataSourceName
Adaptive Server Enterprise (ASE)
Provider=Sybase.ASEOLEDBProvider;Srvr=SERVERNAME,5000; Catalog=DATABASENAME;User
Id=Username; Password=OptionalPasswordValue
Text
Delimited Columns
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=c:\Path\;Extended Properties="text; HDR=Yes;
FMT=Delimited”
Fixed Columns
Provider=Microsoft.Jet.OLEDB.4.0;Data Source=c:\Path\;Extended Properties="text; HDR=Yes;
FMT=Fixed"
Visual FoxPro
Database
Provider=vfpoledb.1;Data Source=C:\Path\FileName.dbc;Collating Sequence=machine
Table Directory
Provider=vfpoledb.1;Data Source=C:\Path\;Collating Sequence=general
ODBC DSN
Provider=vfpoledb.1;DSN=DSNNAME
200
Version 1.9.7
Appendix III - Version History
ListX has gone through a variety of revisions, dating back to its original development as an internal tool at Business
Intelligence Force, up through its first commercial and now to the current release which you are now reviewing.
Below is a brief establishment of the release timeline, and a full breakdown of the revisions contained in each
version.
Release Timeline
0.1.0 Alpha - May 2005
0.1.1 Alpha - May 2005
0.1.2 Alpha - May 2005
0.2.0 Alpha - June 2005
0.2.1 Alpha - June 2005
0.3.0 Alpha - June 2005
0.4.0 Alpha - June 2005
0.5.0 Alpha - June 2005
0.5.1 Alpha - June 2005
1.0.0 Beta - June 2005
1.0.1 Beta - July 2005
1.0.2 Beta - July 2005
1.0.3 - July 2005
1.0.4 - July 2005
1.0.5 - August 2005
1.0.6 - August 2005
1.0.7 - September 2005
1.3.0 - October 2005
1.3.1 - October 2005
1.4.0 - October 2005
1.4.1 - November 2005
1.4.2 - November 2005
1.4.3 - November 2005
1.5.0 - November 2005
1.5.1 - November 2005
1.5.2 - December 2005
1.6.0 - December 2005
1.6.1 - January 2006
1.6.2 - February 2006
1.6.3 - February 2006
1.6.4 - February 2006
1.6.5 - March 2006
201
Version 1.9.7
1.6.6 - April 2006
1.6.7 - April 2006
1.6.8 - April 2006
1.6.9 - May 2006
1.7.0 - May 2006
1.7.1 - June 2006
1.7.2 - June 2006
1.7.3 - June 2006
1.7.4 - June 2006 (Release to Trusted Developers)
1.7.5 – July 2006 (Release to Trusted Developers)
1.7.6 - July 2006
1.7.7 - August 2006
1.7.8 – August 2006
1.7.9 – August 2006
1.8.1 – September 2006
1.8.7 – October 2006
1.8.8 – October 2006
1.8.9 – October 2006
1.9.0 - October 2006
1.9.1 – November 2006
1.9.2 - November 2006
1.9.3 – November 2006
1.9.4 – November 2006
1.9.5 – December 2006
1.9.6 – February 2007
1.9.7 – April 2007
1.0.4 - July 2005
First commercial release.
1.0.5 - August 2005
1.
2.
3.
Provided the ability to use external connection strings.
Provided the ability to use Query, Form and ViewState variables.
Corrected the handling of Sort Columns for better runtime handling.
1.
2.
Bug corrections for handling of the Group Levels, and Session variables.
Provided the ability to export the report to Excel.
202
Version 1.9.7
1.
2.
Provided the ability to use a TabID stored within a ModuleSetting variable for the ACTION.
Reformatted the Code base to provide better grouping.
1.
2.
Changed Query Field handled to replace single quotes with doubled single quotes.
Refined the Debug display, making each section expand and collapse on user click.
1.5.0 - November 2005
Complete revision to code base, including new format options, capabilities and administration. Including Message
Handling for event driven actions and Ajax integration for improved speed and performance.
1.5.1 - November 2005
1.
2.
Correction to Variable replacement when no entry was provided for a selected column name.
Added ability to have a default display rendered when the Query is not assigned, or was generated as an
empty string. This can happen when the user is generating the query in a different module and passing it to
the ListX instance.
1.5.2 - December 2005
1.
2.
3.
4.
5.
6.
7.
Modified Administration screen to improve usability and addition of Module Communication Type branding.
Added Message Action for the sending of Email via the dynamic ListX formatting.
Corrected runtime error when the format contained only a Column Value followed by a trailing space which
resulted in "index out of range" errors.
Corrected Message value Format replacement, allows the developer to utilize Module Communication
messages for which the module is configured as a listener.
Added new Optional parameters for the Checked and Selected items within the CHECKLISTITEM,
CHECKBOX and RADIO tags.
Added the ability for 3rd party developers to listen and react to the ListX events of SORT,SEARCH,FILTER
and PAGING.
Modified the Paging functionality to support reassignment of Page 1 whenever the Current page index is
outside of the valid range of pages for the module.
1.6.2 - February 2006
1.
2.
3.
4.
Completely revamped rendering engine, increasing speed and performance, as well as providing far more
flexibility within each of the runtime values, allowing any feature to support integrated ListX formatting tags.
Added temporary variables through the definition of the Action name/value pair.
Added new formatters providing a variety of runtime capabilities and cleaner output capacity.
Added new message actions:
203
Version 1.9.7
1.
2.
3.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
Conditional - If then else
Message Input - for external web/url data source integration.
Modified the scripting capabilities to provide execute any actions which are provided prior to the
first Message Action listener upon each request.
Added new Export capabilties for exporting Excel, Word and CSV files, each with either current page, or
Complete output.
Modified AJAX runtime to pass all runtime QueryString, and Form values.
Corrected Paging issue when filter reduced page count to 1 and paging never reappeared.
Modified the Query Execute Message Action, allowing a table name in place of a table index for better
utilization and coverage within other actions.
Modified the Checklist - Checked and UnChecked array list values. For checklists, the Name of the storage
value stores the Checked entries, the name prefixed with Un provides the unchecked entries, for all entries
which were defaulted as Checked.
Corrected malfunctioning search options.
Corrected malfunctioning AJAX sorting / default sorting.
Provided additional Utility functions for providing Expand/Collapse grouping, and automatic form variable
selection out of the box.
Added item formatter for IIF (if and only if) conditionals.
Added item formatter for SubQueries, essentially - ListX definitions within ListX definitions.
1.6.3 - February 2006
1.
2.
3.
4.
5.
6.
Corrected issue with executing conditions in uncaptured messages
Corrected potential issue with some new variable replacements
Added the ability to include Microsoft style Validation controls within ListX with support for non-microsoft
browsers.
Added the ability to choose whether or not to include the xUtilities.js library
Added the ability to choose whether or not to include the xValidation.js library
Corrected potential issue with the Action Script execution stack
1.6.4 - February 2006
1.
2.
3.
4.
5.
6.
The Action - Assignment now executes the RenderString against the Parameter name
New Formatter provided for converting to TabID from TabName, or from TabName to TabID
Localization tag provided for getting language of the current session.
Corrected Check Item issue, checked was not rendering properly after assigned.
Added Master template ability to force ListX modules to share one main configuration across portals and
tabs.
Eliminated Command Text not initialized Error.
1.6.5 - March 2006
1.
2.
3.
Fixed issue with SORTTAG doubling columns
Added ACTIONS tag for allowing multiple assignments using the SmartSplitter object
Improved module Import / Export and Master Template implementations
1.6.6 - April 2006
1.
Corrected an Issue with DNN4/Ajax functionality for PostBack
204
2.
3.
4.
5.
Version 1.9.7
Corrected issue for Header/Footer not matching on the same initial record.
Corrected issue with System variable replacement occurring before Column Value replacement.
Added TextEditor tag for using FreeTextBox as a Rich Text Editor within ListX forms.
Revised Help Documentation for PDF and Word formats.
1.7.6 - July 2006
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
Added New Control Panel Interface
Added Draft Mode Capabilities
Added Locking, Unlocking and Version control
Added Package capabilties
Enhanced Action Management
Enhanced User Interaction
Added Delete Controls
Enhanced Text Area Management
Extended Javascript library
Added Reflection values
Added Extended Security
Added Maximum Security Setting
Added Role based debugging
Added Universal AJAX capabilities
Enhanced and Extended Documentation
Corrected Condition management
Corrected DNN 4.x and 3.3 compatibility
Added File Manipulation
Added CSV Import
Added Run As Process for CSV Import
Enhanced AJAX functionality
1.7.7 - August 2006
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
Extended Validation library
Added Smart Validation
Added Smart Textarea and Confirm Delete functionality through lxUtilities.js
Added Run As Process for Execute Actions
Corrected Image Path issues
Added ability to Loop through the results of an Action:Execute
Added ability to execute statements after the Run As Process CSV File Import
Added Alternate tag
Added Sum Aggregations
Added Count Aggregations
Corrected Action:Input and provided sample
Extended Documentation
1.7.8 - August 2006
1.
2.
3.
4.
Revised Query parsing to provide better coverage of variables
Enhanced Variables to provide better control over empty values
Added ability to change Page Title dynamically
Added ability to change Module Title dynamically
205
1.
2.
3.
4.
5.
6.
7.
8.
9.
Version 1.9.7
Message Action:Input Base Address rendering has been corrected
Corrected TabName lookup error identified within Event Log whenever the Action target URL is not
assigned.
Corrected Execution Action when Run As Process is requested.
Added ability to Create and Assign directly to the User Info object within the Action list. Allows you to more
readily replace the existing Registration process with one created completely with ListX.
Corrected CSV Import failure issues and extended the CSV import debugging. The debugging now
provides information on a record by record basis during all transports, so it is only advised to debug on
smaller sets, rather than on large files.
Added ability to use the File Action for SQL to CSV and SQL to SQL actions.
Corrected Query Variable replacements, so that when two variables are used (like @Desc and @Desc2),
the larger of the two variables will be replaced first, avoiding replacement conflicts.
Enhanced the Session debugging to display information contained within all Collection based objects, like
Arrays, Stacks and iLists.
Enabled the ability to Hide the Module, when no results are returned – within AJAX.
1. Added additional Javascript utilities, aiding in the ability to use Toolbar and ListX as Aggregated
regions. These functions include: lxModule; lxContainer; lxContainerGroup.
1.9.0 – October 2006
1.
2.
3.
4.
5.
6.
7.
8.
MATH tag added to allow for any type of mathematical statement and calculation within the LISTX engine.
SET tag added to allow for the ability to assign to any type of variable at any time within the rendering.
Corrected a number of issues with the javascript engine, involving an array of issues including Child portal
security log-off issues.
Enhanced AJAX library to improve performance, and add capabilities for specific object content population.
Enhanced javascript library for working within administrative text areas, shortcut key combinations for
automatic escaping and unescaping of content.
Enhanced security for Query Variable definitions, providing checks for SQL Injection, HTML Injection and
LISTX Injection.
Enhanced Condition engine, allows for compound and mathematical conditions.
Corrected non AJAX paging issue which caused the paging display to disappear on alternating requests.
1.9.2 – November 2006
1.
2.
3.
4.
5.
6.
7.
8.
9.
Corrected Query Variable SQL replacement of single quotes
Added AJAX driven sorting
Added FORMAT – SQLFIND for rapid lookup of any table through a few simplistic parameters
Added FORMAT – TABID: for a rapid lookup of the first record in the dotnetnuke tabs table against any
other column in the table (even custom columns)
Corrected MATH tag handling of non numeric variables
Corrected PortalID on LP import
Expanded LP functionality for history and reapplication of existing LP structure.
Corrected Single Selection Box Javascript issue.
Added New Formatters:
TRIM
TRIMLEFT
TRIMRIGHT
ISSUPERUSER
STARTSWITH
ENDSWITH
CONTAINS
TABID:BYCOLUMNNAME
206
Version 1.9.7
SQLFIND (Look-up any value from any table based on a specific search column)
10. Added New Tags
APPLICATIONPATH
VALUE.WIDTH (Image Width)
VALUE.HEIGHT (Image Height)
VALUE.RAWFORMAT (Image Format)
VALUE.PIXELFORMAT (Image Format)
VALUE.DIMENSIONS (Image WidthxHeight)
VALUE.VERTICALRESOLUTION (Image Vertical Resolution)
VALUE.HORIZONTALRESOLUTION (Image Horizontal Resolution)
RESPONSESTATUS
RESPONSETEXT
11.
12.
13.
14.
15.
Added External (Custom) Connections for all Actions, and SubQueries
Improved Package Installer to provide the ability to Install and Create Packages easily.
Added Action:Comment for Commenting ability with large action lists
Added visual cues for Actions which are being Skipped due to excessive indenting.
Corrected FILTERTAG and SORTTAG error when used in places other than Queries.
1.9.3 – November 2006
1.
2.
3.
4.
Modified Action:File for download (non CSV) to correct IE issue with file names.
Corrected lxExpander Javascript Utilties
Corrected Password Assignment support for DNN 4.3 and greater/
Corrected LP installation with Header/Footer objects.
1.9.4 – November 2006
1.
2.
3.
4.
5.
Corrected Missing Fetch Status display from AJAX request.
Corrected CHECKBOX handling – NOTE: If you are using standard built in behaviours for the calls to
xListing.IM.aspx, this change will harm nothing in your code base, however, if you have previously hacked
calls to the IM, passing specific variables (like S, M, V,G et al), all ListX Query Variables now begin with the
prefix „lx‟.
Corrected DOWNLOAD handling for HTTP/HTTPS requests. Note: SSL may still have certain issues,
specifically with IE.
Corrected LP Installation process – the LP failed to complete on version of DNN running on the 2.0 Dotnet
framework, because modifications to the DesktopModule/Path directory caused the application to restart.
ListX automatically deletes the Package temporary files upon installation, and this caused the threads to
recycle without warrant.
Provided Install instructions for each of the provided NukeDK examples.
1.9.5 – December 2006
1.
2.
3.
Added Javascript support in AJAX requests.
Corrected Group validation issue in firefox.
Expanded and revised documentation.
1.9.6 – February 2006
207
Version 1.9.7
1.
2.
Refined the AJAX library to support a larger variety of older browsers
Expanded the Utility libraries to include better front end behavior when grouping multiple containers and or
modules together into cohesive units
3. Added the ability to create Custom PA modules off existing ListX Configurations
4. Added the ability to override the Command Timeout and Custom Connections for any ODBC and OLEDB
data source.
5. Corrected a variety of Javascript issues, occurring within DNN 4.4 as well as paging issues specifically
within AJAX
6. Added a runtime check to identify and recommend corrections to the web.config which could cause the
administrative interface to operate incorrectly.
7. Enhanced the Module Settings tabs for all ListX Modules to allow for advanced (ListX Style) editing of the
Module Header and Footer
8. Expanded the ListX Editor to include Increasing and Decreasing of the Width of the editor within the
environment.
9. Added SOAP operations to the Action:Input tag. The soap operations allow you to communicate with
external SOAP based Services easily.
10. Added a COLUMNS tag, allowing your to more quickly create templates for your configurations by applying
a template to each column in the returned query result.
11. Added an INDEXOF and LASTINDEXOF formatter to the list of String Manipulation formatters.
12. Corrected FILE Output operations which would at times fail to cache the file on the client side.
1.9.7 – February 2006
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
Added support for forced query separation on the GO keyword within queries. This provides the ability to
execute statements against DBMS systems, like ORACLE, which do not support the return of more than
one table within a SQL script.
Added COALESCE tag to support conditional variable utilization and unlimited formatter application
Added iSearchable Interface to support complete end-to-end DNN Search integration
Added lxToggle javascript functionality to enhance and replace the older lxExpanded capability
Extended lxContainer to provide event driven javascript functionality for onInit, onLoad and onUnload of
each Container for better performance and site optimization capabilities.
Extended lxContainerGroup functionality to provide the ability to ignore the stored Cookie value and always
default to the original main container.
Correct Paging and Sorting on custom paged scenarios which caused SQL 2005 custom paging with
sorting to fail. This was done by extending the [SORTTAG] to include the default sort when no current sort
is assigned.
Added DECRYPT and ENCRYPT formatters to provide encryption capabilities.
Added Menu based toggling for configurations to turn on and off Debugging and Redirections without
requiring the opening of the physical configuration interface.
Added Header/Footer (Module Setting) capacities into the custom PA controls.
Added File Attachments to Email Actions
Added Action Log to provide instant logging into the Event Log
Added Module Repository for ListX Modules
Added Module Log for ListX Modules
Revised Actions interface for better usability – including Scrolling, Copy and Add functions and a more
compact layout.
Added Quick Builder interface to automate the process of creating List,View and Edit interfaces against
exists table structures.
Updated the File Transformations to include the Deletion of Folders
Greatly extended and restructured the Documentation to provide more samples, more information and
better definitions
208
Version 1.9.7
Quick Reference
Action
Action: Execute ....................................................... 48
Actions..... 15, 31, 39, 43, 44, 45, 107, 109, 115, 117,
141, 147, 151, 157, 164, 171, 172, 182, 205, 207
Action: Redirect....................................................... 53
Action:Assignment .................................................. 48
Administration ...................................................... 27
AJAX 1, 2, 19, 21, 22, 24, 25, 95, 105, 133, 134, 141,
147, 154, 158, 172, 204, 205, 206, 207, 208
AJAX Interaction.................................. 1, 21, 22, 158
Alphabetic Filter .......................................... 1, 20, 25
Alphabetic Filtering ................................................. 1
ASP.NET ............................................................. 77
Check Lists ........................................................ 109
Coalesce.............................................................. 95
Collapse........................................ 23, 133, 135, 204
Columns ................................ 66, 105, 106, 200, 202
Combo ............................................................... 133
Compatibility ........................................................ 28
Compound Conditions .......................................... 68
Conditions .......................................................44, 68
Configuration
Draft........................................................................ 17
Connections
Custom Connection .................................................. 36
Contains .............................................................. 66
Cookies...........................................................76, 79
CSS ......................................... 21, 55, 109, 138, 139
CSV ..... 45, 55, 63, 65, 66, 67, 76, 204, 205, 206, 207
Custom Filters .................................................... 147
Custom Paging........................... 1, 19, 22, 34, 37, 38
Debugging ................................................ 1, 25, 208
Decrypt ................................................................ 89
Detail .. 72, 73, 74, 105, 106, 109, 110, 113, 118, 120,
147, 148, 149, 150, 152, 160
DHTML .............................................................. 135
Edit ...... 31, 39, 43, 51, 53, 73, 91, 158, 159, 180, 185
Email ............................. 45, 51, 54, 78, 79, 142, 203
Encrypt ................................................................ 89
Examples ............................... 95, 147, 157, 171, 177
Excel.................................... 1, 29, 55, 199, 202, 204
Expand ............................................. 2, 23, 133, 204
Export ............................................... 16, 29, 55, 204
External ........................................................ 56, 207
Files.............................................2, 21, 79, 157, 179
Filter ................. 20, 24, 25, 31, 51, 79, 129, 153, 154
Filtering .................................................................. 1
Format .. 16, 54, 57, 58, 61, 66, 81, 85, 86, 87, 88, 89,
90, 91, 92, 93, 94, 95, 117, 118, 132, 134, 149,
159, 160, 174, 203, 207
Grid .................................................... 147, 148, 153
Grouping ................................................................ 1
HTML ..... 15, 21, 41, 55, 61, 88, 89, 97, 99, 101, 103,
117, 118, 130, 133, 135, 141, 145, 206
HTML Injection ............................................. 41, 206
IIF 28, 123, 129, 130, 131, 132, 136, 137, 160, 161,
204
Image Transformation ......................................... 167
Images ......................................................... 63, 157
Input 21, 43, 45, 49, 56, 57, 59, 63, 76, 171, 173, 204,
205, 206, 208
Integration ..................................... 1, 21, 24, 31, 171
Interaction .. 1, 2, 19, 21, 22, 107, 109, 110, 113, 115,
148, 158, 205
iSearchable .................................................. 31, 208
Left..... 40, 44, 87, 96, 97, 98, 99, 100, 101, 102, 103,
154, 162, 165, 167
Lists ......................... 2, 107, 109, 115, 117, 132, 134
Localization .................................................. 76, 204
Logic .................................................................. 126
Lookup ....................................................... 171, 172
LP 2, 95, 181, 206, 207
Math................................................................... 123
Message .............................................................. 47
Microsoft Access................................................... 72
Module . 1, 2, 24, 39, 51, 74, 107, 134, 138, 145, 150,
153, 179, 181, 182, 183, 184, 185, 203, 205, 206,
208
Multiple Column Sorting .......................................... 1
MySQL ............................................................... 200
ODBC ........................ 15, 35, 48, 118, 199, 200, 208
OLEDB.................................... 35, 37, 199, 200, 208
Oracle ............................................... 35, 37, 38, 200
Output ......................................... 43, 45, 55, 75, 208
PA ........................................... 2, 181, 185, 186, 208
Packages ...................................... 16, 179, 180, 207
Page1, 19, 22, 24, 25, 45, 51, 59, 107, 143, 144, 148,
203, 205
Paging.................1, 19, 22, 34, 37, 38, 203, 204, 208
Profile............................................................. 51, 79
Query String ......................................................... 39
QueryString ............ 21, 60, 64, 76, 79, 108, 121, 204
Radio Lists ......................................................... 109
Records Per Page ........................................ 19, 148
Reflection ..................................................... 77, 205
Repository
Locking ................................................................... 16
Unlocking................................................................ 16
Right ..40, 44, 87, 88, 97, 99, 101, 103, 162, 165, 167
Search ................................. 15, 31, 32, 51, 180, 208
Security .............................. 15, 41, 48, 118, 199, 205
Skin Objects ....................................................... 178
Sort ........................ 52, 115, 116, 147, 149, 150, 202
Sorting .... 1, 20, 25, 73, 107, 109, 115, 117, 147, 208
209
SQL 15, 19, 20, 33, 34, 35, 37, 38, 39, 41, 45, 63, 64,
65, 66, 72, 76, 177, 179, 186, 200, 206, 208
SQL 2005.......................................... 34, 37, 38, 208
SQL Server 2005.................................................. 37
Stored Procedures ............................................... 12
String Manipulation........................................ 85, 208
Style ....................................................... 21, 72, 208
Support ................................................................ 28
Tab . 36, 45, 51, 53, 61, 85, 86, 87, 88, 89, 91, 92, 93,
94, 96, 97, 98, 99, 100, 101, 102, 103, 107, 108,
178, 180
Transformation .............................................. 67, 166
Transport ........................................................... 199
Validation ............ 15, 23, 89, 141, 143, 144, 204, 205
Variables.............................................................. 15
Action 39, 43, 44, 45, 47, 48, 49, 51, 52, 53, 54, 55, 56,
57, 61, 63, 64, 65, 66, 70, 76, 107, 120, 121, 134,
Version 1.9.7
143, 147, 150, 151, 152, 157, 160, 162, 164, 165,
166, 167, 168, 169, 170, 171, 172, 173, 175, 181,
199, 203, 204, 205, 206, 207, 208
Form .. 15, 21, 33, 39, 40, 57, 63, 64, 76, 79, 81, 95, 96,
97, 98, 99, 100, 101, 102, 103, 131, 134, 146, 147,
148, 155, 157, 159, 162, 165, 166, 167, 171, 173,
202, 204
Message . 24, 39, 43, 44, 45, 47, 76, 107, 143, 144, 147,
150, 151, 157, 160, 161, 162, 163, 168, 169, 171,
172, 175, 182, 184, 203, 204, 206
Query String ................................... 33, 39, 56, 57, 173
Session . 33, 39, 41, 45, 51, 58, 64, 76, 77, 80, 107, 108,
110, 111, 113, 114, 121, 129, 147, 150, 157, 171,
174, 175, 202, 206
ViewState ............. 21, 33, 39, 45, 76, 80, 108, 121, 202
Web Services ....................................................... 56
Word ..................................................... 55, 204, 205
210

Format

Transcription

Similar documents

customer intelligence through new eyes through

Quick Start Guide for Power Users (Java)

Monster Jobs - by Carpe Data

1. Go to ezlm.adp.com and click the

Multiple Intelligence Survey for Kids

VDF User Guide

Angola Pennysaver Angola Pennysaver

Get to know more about the benefits of

Enterprise - Platform Modernization Alliance

Emotions - IATEFL-H