Mercurial > p > roundup > code
view doc/tracker_templates.txt @ 7853:03c1b7ae3a68
issue2551328/issue2551264 unneeded next link and total_count incorrect
Fix: issue2551328 - REST results show next link if number of
results is a multiple of page size. (Found by members of
team 3 in the UMass-Boston CS682 Spring 2024 class.)
issue2551264 - REST X-Total-Count header and @total_size
count incorrect when paginated
These issues arose because we retrieved the exact number of rows
from the database as requested by the user using the @page_size
parameter. With this changeset, we retrieve up to 10 million + 1
rows from the database. If the total number of rows exceeds 10
million, we set the total_count indicators to -1 as an invalid
size. (The max number of requested rows (default 10 million +1)
can be modified by the admin through interfaces.py.)
By retrieving more data than necessary, we can calculate the
total count by adding @page_index*@page_size to the number of
rows returned by the query.
Furthermore, since we return more than @page_size rows, we can
determine the existence of a row at @page_size+1 and use that
information to determine if a next link should be
provided. Previously, a next link was returned if @page_size rows
were retrieved.
This change does not guarantee that the user will get @page_size
rows returned. Access policy filtering occurs after the rows are
returned, and discards rows inaccessible by the user.
Using the current @page_index/@page_size it would be difficult to
have the roundup code refetch data and make sure that a full
@page_size set of rows is returned. E.G. @page_size=100 and 5 of
them are dropped due to access restrictions. We then fetch 10
items and add items 1-4 and 6 (5 is inaccessible). There is no
way to calculate the new database offset at:
@page_index*@page_size + 6 from the URL. We would need to add an
@page_offset=6 or something.
This could work since the client isn't adding 1 to @page_index to
get the next page. Thanks to HATEOAS, the client just uses the
'next' url. But I am not going to cross that bridge without a
concrete use case.
This can also be handled client side by merging a short response
with the next response and re-paginating client side.
Also added extra index markers to the docs to highlight use of
interfaces.py.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Mon, 01 Apr 2024 09:57:16 -0400 |
| parents | 6985f0ff3df3 |
| children | 3614cd64f4c4 |
line wrap: on
line source
========================= Roundup Tracker Templates ========================= The templates distributed with Roundup are stored in the "share" directory nominated by Python. On Unix this is typically ``/usr/share/roundup/templates/`` (or ``/usr/local/share...``) and on Windows this is ``c:\python27\share\roundup\templates\``. The template loading looks in four places to find the templates: 1. *share* - eg. ``<prefix>/share/roundup/templates/*``. This should be the standard place to find them when Roundup is installed running setup.py from source. 2. ``install_dir``/../<prefix>/share/....``, where prefix is the Python's ``sys.prefix``. ``sys.base_prefix`` or `sys.base_prefix/local``. This finds templates (and locales) installed by pip. E.G. in a virtualenv located at (``sys.prefix``): ``/tools/roundup``, roundup would be at: ``/tools/roundup/lib/python3.6/site-packages/roundup``. The templates would be at: ``/tools/roundup/lib/python3.6/site-packages/tools/roundup/share/roundup/templates/``. 3. ``<roundup.admin.__file__>/../../share/roundup/templates/*``. This will be used if Roundup's run in the distro (aka. source) directory. 4. ``<current working dir>/*``. This is for when someone unpacks a 3rd-party template. 5. ``<current working dir>``. This is for someone who "cd"s to the 3rd-party template dir. Templates contain: - modules ``schema.py`` and ``initial_data.py`` - directories ``html``, ``detectors`` and ``extensions`` (with appropriate contents) - optional directory ``lib`` which contains modules used by the other tracker components - optional ``config_ini.ini`` file. It is structured like a tracker's ``config.ini`` but contains only headers (e.g. ``[main]``) and *required* parameters that are different from defaults. For example:: [main] template_engine = jinja2 static_files = static These settings override the default values in the tracker's ``config.ini`` when using roundup-admin to install a template. - template "marker" file ``TEMPLATE-INFO.txt``, which contains the name of the template, a description of the template and its intended audience. An example TEMPLATE-INFO.txt: .. code-block:: text Name: classic Description: This is a generic issue tracker that may be used to track bugs, feature requests, project issues or any number of other types of issues. Most users of Roundup will find that this template suits them, with perhaps a few customisations. Intended-For: All first-time Roundup users