#COLUMN_WIDTH# in Apex report templates

Always check out the original article at http://www.oraclequirks.com for latest comments, fixes and updates.

Even if the topic is no breaking news, there are some references about it in the Apex OTN forum, it may be still worth spending a few words, especially because, up to date (Apex 4.2.1), there is no trace of it in the official Oracle Application Express documentation.

I am talking of the #COLUMN_WIDTH# substitution string which is not mentioned anywhere (neither in the online attribute help, nor in the manuals), even if it is perfectly supported in certain template attributes.

This substitution string is the resulting value of the information you specify in the following places:

snapshot taken from report column attributes page

snapshot taken from report attributes

You won't see the effects of the width set above unless you modify the report templates to include the #COLUMN_WIDTH# substitution string. As this attribute made its way into Apex with version 4.0, if your application is using a report template earlier than Apex 4.0 it won't certainly include it by default, so you need to modify the template as shown in the picture:

snapshot taken from the edit report template page

The substitution string will result in an HTML code fragment like the following: style="width:64px" (the actual value comes from the example above).
Note that #COLUMN_WIDTH# is also accepted in the Column Template Attributes numbered 1-4, not only in the column headings however bear in mind that it can make sense to specify it here only if you omit the headings altogether otherwise it will be most likely ignored by the browser in virtue of the algorithm used to calculate the column width.

I also updated the substitution string cross reference chart I wrote several years ago to reflect the new situation, in case someone stumbles upon it for the first time.

Apex substitution strings cross reference chart

This is a tentative (and hopefully definitive) cross reference chart telling you at a glance if you can use a certain substitution string inside a given template definition and it is supposed to apply to APEX 3.0, although most of these definitions should work on older versions.

Template substitutions are defined as #UPPERCASE_TEXT# strings, however there are a number of useful substitution strings that can be used inside templates and must be specified in the alternate format delimited by & and . (period), like &BROWSER_LANGUAGE., &SESSION. or any user-specified global substitution strings stored in the Application Definition.

Please note that using uppercase is mandatory.

While compiling this chart i found a few mistakes and omissions in the online help of Apex 3.0.
For instance in the report template section of the help guide #ALIGN# is mentioned but the real substitution string, as you can see in some of the built-in templates is #ALIGNMENT#.
The same happens with #ROW_NUM#, whose real counterpart is #ROWNUM#.

It took also some time to test hierarchical lists and calendar templates that are almost undocumented.
Concerning calendar templates i had to introduce the yellow color as you can see at the bottom of the table, because a calendar template is made up of an awful number of subtemplates and certainly there can be one or two where the substitution doesn't work but also where it makes little sense to use it.
May be that in version 2.0 i come up with a fine-grained calendar cross reference chart, but don't expect this to happen any time soon ;-)



Updates:
2009/03/27: #COLUMN_HEADER_NAME# can be used inside any of the "Column Template n" attributes in the report template page.
2012/12/20: #COLUMN_WIDTH# added, available since APEX 4.0.
2013/06/12: changed #APP_VERSION# map, removed support from Page Body Template.