doc/06_ir_qweb.rst

   1 .. _qweb:
   2
   3 ====
   4 QWeb
   5 ====
   6
   7 ``t-field``
   8 ===========
   9
  10 The server version of qweb includes a directive dedicated specifically to
  11 formatting and rendering field values from
  12 :class:`~openerp.osv.orm.browse_record` objects.
  13
  14 The directive is implemented through
  15 :meth:`~base.ir.ir_qweb.QWeb.render_tag_field` on the ``ir.qweb`` openerp
  16 object, and generally delegates to converters for rendering. These converters
  17 are obtained through :meth:`~base.ir.ir_qweb.QWeb.get_converter_for`.
  18
  19 By default, the key for obtaining a converter is the type of the field's
  20 column, but this can be overridden by providing a ``widget`` as field option.
  21
  22 Field options are specified through ``t-field-options``, which must be a JSON
  23 object (map). Custom widgets may define their own (possibly mandatory) options.
  24
  25 Global options
  26 --------------
  27
  28 A global option ``html-escape`` is provided. It defaults to ``True``, and for
  29 many (not all) fields it determines whether the field's output will be
  30 html-escaped before being output.
  31
  32 Date and datetime converters
  33 ----------------------------
  34
  35 The default rendering for ``date`` and ``datetime`` fields. They render the
  36 field's value according to the current user's ``lang.date_format`` and
  37 ``lang.time_format``. The ``datetime`` converter will also localize the value
  38 to the user's timezone (as defined by the ``tz`` context key, or the timezone
  39 in the user's profile if there is no ``tz`` key in the context).
  40
  41 A custom format can be provided to use a non-default rendering. The custom
  42 format uses the ``format`` options key, and uses the
  43 `ldml date format patterns`_ [#ldml]_.
  44
  45 For instance if one wanted a date field to be rendered as
  46 "(month) (day of month)" rather than whatever the default is, one could use:
  47
  48 .. code-block:: xml
  49
  50     <span t-field="object.datefield" t-field-options='{"format": "MMMM d"}'/>
  51
  52 Monetary converter (widget: ``monetary``)
  53 -----------------------------------------
  54
  55 Used to format and render monetary value, requires a ``display_currency``
  56 options value which is a path from the rendering context to a ``res.currency``
  57 object. This object is used to set the right currency symbol, and set it at the
  58 right position relative to the formatted value.
  59
  60 The field itself should be a float field.
  61
  62 Relative Datetime (widget: ``relative``)
  63 ----------------------------------------
  64
  65 Used on a ``datetime`` field, formats it relatively to the current time
  66 (``datetime.now()``), e.g. if the field's value is 3 hours before now and the
  67 user's lang is english, it will render to *3 hours ago*.
  68
  69 .. note:: this field uses babel's ``format_timedelta`` more or less directly
  70           and will only display the biggest unit and round up at 85% e.g.
  71           1 hour 15 minutes will be rendered as *1 hour*, and 55 minutes will
  72           also be rendered as *1 hour*.
  73
  74 .. warning:: this converter *requires* babel 1.0 or more recent.
  75
  76 Duration (widget: ``duration``)
  77 -------------------------------
  78
  79 Renders a duration defined as a ``float`` to a human-readable localized string,
  80 e.g. ``1.5`` as hours in an english locale will be rendered to
  81 *1 hour 30 minutes*.
  82
  83 Requires a ``unit`` option which may be one of ``second``, ``minute``,
  84 ``hour``, ``day``, ``week``, ``month`` or ``year``. This specifies the unit in
  85 which the value should be interpreted before formatting.
  86
  87 The duration must be a positive number, and no rounding is applied.
  88
  89 .. [#ldml] in part because `babel`_ is used for rendering, as ``strftime``
  90            would require altering the process's locale on the fly in order to
  91            get correctly localized date and time output. Babel uses the CLDR
  92            as its core and thus uses LDML date format patterns.
  93
  94 .. _babel: http://babel.pocoo.org
  95
  96 .. _ldml date format patterns:
  97     http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns
  98