Package qm :: Package external :: Package DocumentTemplate :: Module DT_Var
[hide private]
[frames] | no frames]

Module DT_Var
source code

Variable insertion parameters

    When inserting variables, parameters may be specified to
    control how the data will be formatted.  In HTML source, the
    'fmt' parameter is used to specify a C-style or custom format
    to be used when inserting an object.  In EPFS source, the 'fmt'
    parameter is only used for custom formats, a C-style format is
    specified after the closing parenthesis.

    Custom formats

       A custom format is used when outputing user-defined
       objects.  The value of a custom format is a method name to
       be invoked on the object being inserted.  The method should
       return an object that, when converted to a string, yields
       the desired text.  For example, the HTML source::

          <!--#var date fmt=DayOfWeek-->

       Inserts the result of calling the method 'DayOfWeek' of the
       object bound to the variable 'date', with no arguments.

       In addition to object methods, serveral additional custom
       formats are available:

           'whole-dollars' -- Show a numeric value with a dollar symbol.

           'dollars-and-cents' -- Show a numeric value with a dollar
             symbol and two decimal places.

           'collection-length' -- Get the length of a collection of objects.

       Note that when using the EPFS source format, both a
       C-style and a custom format may be provided.  In this case,
       the C-Style format is applied to the result of calling
       the custom formatting method.

    Null values and missing variables

       In some applications, and especially in database applications,
       data variables may alternate between "good" and "null" or
       "missing" values.  A format that is used for good values may be
       inappropriate for null values.  For this reason, the 'null'
       parameter can be used to specify text to be used for null
       values.  Null values are defined as values that:

         - Cannot be formatted with the specified format, and

         - Are either the special Python value 'None' or 
           are false and yield an empty string when converted to
           a string.

       For example, when showing a monitary value retrieved from a
       database that is either a number or a missing value, the
       following variable insertion might be used::

           <dtml-var cost fmt="$%.2d" null='n/a'>

       Missing values are providing for variables which are not
       present in the name space, rather than raising an NameError,
       you could do this:

           <dtml-var cost missing=0>

       and in this case, if cost was missing, it would be set to 0.
       In the case where you want to deal with both at the same time,
       you can use 'default':

           <dtml-var description default=''>

       In this case, it would use '' if the value was null or if the
       variable was missing.

    String manipulation

       A number of special attributes are provided to transform the
       value after formatting has been applied.  These parameters
       are supplied without arguments.

       'lower' --  cause all upper-case letters to be converted to lower case. 

       'upper' --  cause all upper-case letters to be converted to lower case. 

       'capitalize' -- cause the first character of the inserted value
       to be converted to upper case. 

       'spacify' -- cause underscores in the inserted value to be
       converted to spaces.

       'thousands_commas' -- cause commas to be inserted every three
       digits to the left of a decimal point in values containing
       numbers.  For example, the value, "12000 widgets" becomes
       "12,000 widgets".

       'html_quote' -- convert characters that have special meaning
       in HTML to HTML character entities.

       'url_quote' -- convert characters that have special meaning
       in URLS to HTML character entities using decimal values.

       'url_quote_plus' -- like url_quote but also replace blank
       space characters with '+'. This is needed for building
       query strings in some cases.

       'sql_quote' -- Convert single quotes to pairs of single
       quotes. This is needed to safely include values in
       Standard Query Language (SQL) strings.

       'newline_to_br' -- Convert newlines and carriage-return and
       newline combinations to break tags.

       'url' -- Get the absolute URL of the object by calling it's
       'absolute_url' method, if it has one.

    Truncation

       The attributes 'size' and 'etc'  can be used to truncate long
       strings.  If the 'size' attribute is specified, the string to
       be inserted is truncated at the given length.  If a space
       occurs in the second half of the truncated string, then the
       string is further truncated to the right-most space.  After
       truncation, the value given for the 'etc' attribute is added to
       the string.  If the 'etc' attribute is not provided, then '...'
       is used.  For example, if the value of spam is
       '"blah blah blah blah"', then the tag       
       '<!--#var spam size=10-->' inserts '"blah blah ..."'.


Evaluating expressions without rendering results

   A 'call' tag is provided for evaluating named objects or expressions
   without rendering the result.
   



Classes [hide private]
Var  
Call  
Comment Comments

Functions [hide private]
  url_quote(v, name='(Unknown name)', md={})
  url_quote_plus(v, name='(Unknown name)', md={})
  newline_to_br(v, name='(Unknown name)', md={})
  whole_dollars(v, name='(Unknown name)', md={})
  dollars_and_cents(v, name='(Unknown name)', md={})
  thousands_commas(v, name='(Unknown name)', md={}, thou=<built-in method search of _sre.SRE_Pattern object at 0x85341c0>)
  whole_dollars_with_commas(v, name='(Unknown name)', md={})
  dollars_and_cents_with_commas(v, name='(Unknown name)', md={})
  len_format(v, name='(Unknown name)', md={})
  len_comma(v, name='(Unknown name)', md={})
  structured_text(v, name='(Unknown name)', md={})
  sql_quote(v, name='(Unknown name)', md={})
Quote single quotes in a string by doubling them.
  spacify(val)

Variables [hide private]
__doc__  
__rcs_id__  
__version__  
StructuredText  
special_formats  
modifiers  

Function Details [hide private]

url_quote(v, name='(Unknown name)', md={})

source code 

url_quote_plus(v, name='(Unknown name)', md={})

source code 

newline_to_br(v, name='(Unknown name)', md={})

source code 

whole_dollars(v, name='(Unknown name)', md={})

source code 

dollars_and_cents(v, name='(Unknown name)', md={})

source code 

thousands_commas(v, name='(Unknown name)', md={}, thou=<built-in method search of _sre.SRE_Pattern object at 0x85341c0>)

source code 

whole_dollars_with_commas(v, name='(Unknown name)', md={})

source code 

dollars_and_cents_with_commas(v, name='(Unknown name)', md={})

source code 

len_format(v, name='(Unknown name)', md={})

source code 

len_comma(v, name='(Unknown name)', md={})

source code 

structured_text(v, name='(Unknown name)', md={})

source code 

sql_quote(v, name='(Unknown name)', md={})

source code 

Quote single quotes in a string by doubling them.

This is needed to securely insert values into sql string literals in templates that generate sql.

spacify(val)

source code 

Variables Details [hide private]

__doc__

Value:
'''Variable insertion parameters

    When inserting variables, parameters may be specified to
    control how the data will be formatted.  In HTML source, the
    'fmt' parameter is used to specify a C-style or custom format
    to be used when inserting an object.  In EPFS source, the 'fmt'
    parameter is only used for custom formats, a C-style format is
    specified after the closing parenthesis.
...                                                                    
      

__rcs_id__

Value:
'$Id: DT_Var.py 1007 2007-02-10 01:07:28Z stefan $'                    
      

__version__

Value:
'1007'                                                                 
      

StructuredText

Value:
{}                                                                     
      

special_formats

Value:
{'collection-length': <function len_format at 0xb7a44a3c>,
 'comma-numeric': <function thousands_commas at 0xb7a44994>,
 'dollars-and-cents': <function dollars_and_cents at 0xb7a4495c>,
 'dollars-and-cents-with-commas': <function dollars_and_cents_with_com\
mas at 0xb7a44a04>,
 'dollars-with-commas': <function whole_dollars_with_commas at 0xb7a44\
9cc>,
 'html-quote': <function html_quote at 0xb7a99994>,
...                                                                    
      

modifiers

Value:
[('html_quote', <function html_quote at 0xb7a99994>),
 ('url_quote', <function url_quote at 0xb7a447d4>),
 ('url_quote_plus', <function url_quote_plus at 0xb7a448b4>),
 ('newline_to_br', <function newline_to_br at 0xb7a448ec>),
 ('lower', <function lower at 0xb7f0aed4>),
 ('upper', <function upper at 0xb7f170d4>),
 ('capitalize', <function capitalize at 0xb7f175a4>),
 ('spacify', <function spacify at 0xb7a44b1c>),
...