Mercurial Repository: p/roundup/code: doc/upgrading.txt comparison

comparison doc/upgrading.txt @ 8300:b99e76e76496

Make native date and number elements configurable Now for Number() and Integer() properties the browser-native number format can be configured with the use_browser_number_input config item in seciont [web]. The default is 'yes'. For Date() properties the config item is use_browser_date_input (also in section [web]) but the default is 'no'. In addition when defining Date() properties, these now have a parameter 'display_time' which defaults to 'yes' and a 'format' parameter which defaults to None. These set defaults for the field() method of the DateHTMLProperty which have the same parameters (but the display_time parameter of field() takes a boolean, not 'yes'/'no').

author	Ralf Schlatterbeck <rsc@runtux.com>
date	Wed, 19 Feb 2025 12:38:06 +0100
parents	6445e63bb423
children	3f43db05aa11

comparison

equal deleted inserted replaced

-:43899d99fc4d
+:b99e76e76496
 .. _defusedxml: https://pypi.org/project/defusedxml/
 Enable use of native date inputs (optional)
 -------------------------------------------
-Roundup now uses native date or datetime-local inputs for Date()
+Roundup now can use native ``date`` or ``datetime-local`` inputs for
-properties. These inputs take the place of the text input and
+``Date()`` properties. These inputs take the place of the text input and
-calendar popup from earlier Roundup versions. Modern browsers
+calendar popup from earlier Roundup versions. Modern browsers come with
-come with a built-in calendar for date selection, so the
+a built-in calendar for date selection, so the ``(cal)`` calendar link
-``(cal)`` calendar link is no longer needed. These native inputs
+is no longer needed. These native inputs show the date based on the
-show the date based on the browser's locale and translate terms
+browser's locale and translate terms into the local language.
-into the local language.
+Note that the date format is tied to the language setting in most
-If you do nothing, simple uses of the field() method will
+browsers, with some browsers you need special configurations to make the
-generate date inputs to allow selection of a date.  Input fields
+browser use the operating system date format.
-for Date() properties will not have the ``(cal)`` link
-anymore. Complex uses will not be upgraded and will operate like
+By default the old input mechanism (using type=text inputs) is used.
-earlier Roundup versions.
+To enable native date input you need to set the config variable ::
-To upgrade all date properties, there are four changes to make:
+use_browser_date_input = yes
-1. Replace ``field`` calls with ``field_time`` where needed.
+in section ``[web]`` in the ``config.ini`` file.
-2. Remove the format argument from field() calls on Date()
+If native date input is used, simple uses of the ``field()`` method will
+generate ``datetime-local`` inputs to allow selection of a date and time.
+Input fields for ``Date()`` properties will not have the ``(cal)`` link
+anymore. If fields should only use a date (without time) you can specify
+the parameter ``display_time=no`` in ``schema.py`` for a ``Date()``
+property (the default is ``yes``). This will use ``date`` inputs in the
+generated html to select a date only. If you need this only for a single
+date, the ``field()`` method now has a boolean parameter
+``display_time`` (which by default is set to the ``display_time``
+parameter of ``Date()``)
+Complex uses using a ``format`` specification in ``field()`` will not be
+upgraded and will operate like earlier Roundup versions. In addition the
+``format`` can now also be specified in the ``Date()`` constructor.
+To upgrade all date properties, there are five changes to make:
+1. Configure ``use_browser_date_input = yes`` in section ``[web]`` in
+``config.ini``
+2. Optionally add ``display_time = no`` in the schema for Date()
+properties that should have no time displayed
+3. Remove the format argument from field() calls on Date()
 properties.
-3. Remove popcal() calls.
+4. Remove popcal() calls.
-4. Include datecopy.js in page.html.
+5. Include datecopy.js in page.html.
-Use field_time() where needed
+The ``display_time`` option
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The format used by ``field`` does not include hours, minutes or
+Both the ``Date()`` constructor and the ``field`` call take a
-seconds. If your users need to enter times, you should change
+``display_time`` option which by default is ``yes`` in the ``Date()``
-these calls to use ``field_time``. The arguments are the same as
+constructor and ``True`` in ``field``. The ``display_time`` setting of
-for field.
+``Date()`` is inherited by the html property, so it doesn't need to be
+specified in each ``field()`` call for this property.
+When ``display_time`` is off, the date field does not include hours,
+minutes or seconds.
 Remove format argument
 ~~~~~~~~~~~~~~~~~~~~~~
-Speaking of arguments, avoid setting the date format if you want
+Speaking of arguments, avoid setting the date ``format`` if you want to
-to use native date inputs. The date value needs a specific format
+use native date inputs. If you include the `format` argument in the
-for date or datetime-local inputs. If you include the `format`
+`field` method, it should be removed.
-argument in the `field` method, it should be removed.
+By default using a format argument will show the
-The `field` method uses the format ``%Y-%m-%d``.  The
-``field_time`` method uses the format ``%Y-%m-%dT%H:%M:%S``. If
-you use these exact formats, Roundup will accept them and use a
-native date input.
-.. highlight:: text
-If you use an format that doesn't match, you will see a text
-input and a logged warning message like::
-Format '%Y-%m' prevents use of modern date input.
-Remove format from field() call in template test.item.
-Using text input.
-.. highlight:: default
-The log message will appear if your logging level is set to
-WARNING or lower. (Refer to your tracker's :ref:`config.ini
-logging section <config-ini-section-logging>` for details on
-logging levels.)
-If you want to use a text input for a specific date format, you
-can add ``type="text"`` to the field() argument list to suppress
-the warning. By default using a format argument will show the
 popup calendar link. You can disable the link by setting
 ``popcal=False`` in the field() call. If you have::
 tal:content="structure python:context.duedate.field(
 placeholder='YYYY-MM, format='%Y-%m')"
 changing it to::
 tal:content="structure python:context.duedate.field(
-type='text',
 placeholder='YYYY-MM, format='%Y-%m',
 popcal=False)"
 will generate the input as in Roundup 2.4 or earlier without a
 popcal link.
-.. _revert_input_to_text:
-If you are using a path expression like::
-tal:content="context/duedate/field"
-change it to::
-tal:content="structure python:context.duedate.field(
-type='text')"
-to get the input from before Roundup 2.5 with a popcal link.
 Remove popcal
 ~~~~~~~~~~~~~
-If you use the ``popcal()`` method directly in your templates, you
+if you have enabled date input types in the configuration and you
-can remove them. The browser's native date selection calendar can
+use the ``popcal()`` method directly in your templates, you
+should remove them. The browser's native date selection calendar should
 be used instead.
 Add copy/paste/edit on double-click using datecopy.js
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is no way to copy/paste using a native datetime-local or
+When using date input types,
-date input. With the datecopy.js file installed, double-clicking
+there is no way to copy/paste using a native ``datetime-local`` or
+``date`` input. With the ``datecopy.js`` file installed, double-clicking
 on the input turns it into a normal text input with the ability
 to copy, paste, or manually edit the date.
 To set this up, take either ``datecopy.js`` or the smaller
 version, ``datecopy.min.js``, from the ``html`` folder of the
 double-tap to activate text mode input. Firefox does not.
 Revert native number inputs for Number() and Integer() (optional)
 -----------------------------------------------------------------
-Roundup's field() method for properties of type Number() or
+Roundup's ``field()`` method for properties of type ``Number()`` or
-Integer() now use a native browser number input.
+``Integer()`` now use a native browser number input by default.
-You can use the old style text inputs by calling the field
+This is configurable for *all* ``Number()`` and ``Integer()`` properties
-method with ``type="text"``. You can :ref:`follow the example
+with the config option ``use_browser_number_input`` in section ``[web]``.
-for setting the text argument on a Date()
-property. <revert_input_to_text>` for details.
+You can use the old style text inputs for individual fields
+by calling the field method with ``type="text"``.
-Note that the Integer() type also uses ``step="1"`` by default to
+Note that the ``Integer()`` type also uses ``step="1"`` by default to
 add a stepper control and try to constrain the input to
 integers. This can be overridden by passing a new step
-(e.g. ``step="50"``) to the field() method.
+(e.g. ``step="50"``) to the ``field()`` method.
 Change in REST response for invalid CORS requests (info)
 --------------------------------------------------------
 CORS_ preflight requests that are missing required headers can

Mercurial > p > roundup > code

comparison doc/upgrading.txt @ 8300:b99e76e76496