From d32bfce8836ef504492ad62eed4a67778fe36733 Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Sat, 19 Nov 2022 21:46:13 -0600 Subject: [PATCH] Add more structure for web layer docs hopefully more content will come sooner than later.. --- docs/conf.py | 1 + docs/web/mainapp/dev/forms.rst | 5 + docs/web/mainapp/dev/grids.rst | 102 ++++++++++++++++++ docs/web/mainapp/dev/index.rst | 15 +++ docs/web/mainapp/dev/overview.rst | 12 +++ docs/web/mainapp/{ => dev}/patterns.rst | 0 docs/web/mainapp/{ => dev}/tasks/index.rst | 0 .../mainapp/{ => dev}/tasks/newmasterview.rst | 0 docs/web/mainapp/dev/views.rst | 5 + docs/web/mainapp/index.rst | 3 +- docs/web/mainapp/overview.rst | 6 +- docs/web/overview.rst | 14 ++- 12 files changed, 159 insertions(+), 4 deletions(-) create mode 100644 docs/web/mainapp/dev/forms.rst create mode 100644 docs/web/mainapp/dev/grids.rst create mode 100644 docs/web/mainapp/dev/index.rst create mode 100644 docs/web/mainapp/dev/overview.rst rename docs/web/mainapp/{ => dev}/patterns.rst (100%) rename docs/web/mainapp/{ => dev}/tasks/index.rst (100%) rename docs/web/mainapp/{ => dev}/tasks/newmasterview.rst (100%) create mode 100644 docs/web/mainapp/dev/views.rst diff --git a/docs/conf.py b/docs/conf.py index f4974fd..eb36601 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,6 +38,7 @@ extensions = [ intersphinx_mapping = { 'rattail': ('https://rattailproject.org/docs/rattail/', None), + 'tailbone': ('https://rattailproject.org/docs/tailbone/', None), } # Add any paths that contain templates here, relative to this directory. diff --git a/docs/web/mainapp/dev/forms.rst b/docs/web/mainapp/dev/forms.rst new file mode 100644 index 0000000..828e415 --- /dev/null +++ b/docs/web/mainapp/dev/forms.rst @@ -0,0 +1,5 @@ + +Forms +===== + +TODO diff --git a/docs/web/mainapp/dev/grids.rst b/docs/web/mainapp/dev/grids.rst new file mode 100644 index 0000000..20b80ef --- /dev/null +++ b/docs/web/mainapp/dev/grids.rst @@ -0,0 +1,102 @@ + +Grids +===== + +A "grid" in Tailbone is just a "displayed table" essentially, but may +have other goodies connected with it, e.g. a set of filters and paging +info. + +The main class is :class:`~tailbone:tailbone.grids.core.Grid` and most +of the time you'll just use that, with no need to subclass it. + +Note that within a :class:`~tailbone:tailbone.views.master.MasterView` +you can get a reference to the ``Grid`` class via +:meth:`~tailbone:tailbone.views.master.MasterView.get_grid_factory()`. + + +Types of Grids +-------------- + +The ``Grid`` class is used for a few different things, as described +below. Some of the features mentioned are described in the next +section. + +Master CRUD w/ DB Table +~~~~~~~~~~~~~~~~~~~~~~~ + +By far the most common type is that used by the ``MasterView`` class, +to expose a given data set for searching, downloading etc. Usually +the data set is just a DB table, so columns map directly between the +table and grid. + +This grid usually allows user to specify filters and sorting/paging +info. + +Master CRUD w/out DB Table +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Less common than the above, some ``MasterView`` classes need to expose +a grid but the data set does not map to a DB table. Examples of this +are the Email Settings grid, and the Tables grid. + +This grid often does not allow filtering or paging, on account of the +relative difficulty to implement (read: author is lazy), but often +does allow basic sorting. + +Master "Rows" CRUD +~~~~~~~~~~~~~~~~~~ + +Similar to the above, this grid is used by ``MasterView`` to show +"child row data" when viewing a particular object record. + +Like the first, this grid usually allows filter/sort/paging. The one +difference in this regard, is the user is not allowed to save default +settings for the grid. This is because (per current logic) each grid +of this type is unique to the parent object, and settings are kept +separate for each such grid. So if settings were saved, they still +would not apply to other grids. + +Field Data +~~~~~~~~~~ + +This type of grid is used to show a small-ish table of data, within a +given form field, when viewing a particular object record. For +example when viewing a Role, this is how the Users field is displayed. + +This grid normally does not allow filters or paging, but in some cases +may allow basic sorting. + + +Grid Features +------------- + +Here we discuss some possible features a grid may have. + +Columns +~~~~~~~ + +Obviously a grid has columns. But a grid may also have some +"invisible" columns, for sake of the data they contain. This +sometimes is needed for other automation etc. in the client-side UI. + +TODO: one of these days, grids should let user choose which, and in +which order, columns are shown. + +Sorting +~~~~~~~ + +This is arguably the simplest enhancement to make to a grid. Only a +visible column may be sorted, but not all of them. (It depends on the +nature of the data set etc.) + +Paging +~~~~~~ + +With sorting comes the possibility of paging the grid data. (Sorting +is required for paging, so the results are deterministic.) + +Filters +~~~~~~~ + +Many grids allow the user to apply a set of filters, to limit which +data is shown in the grid. diff --git a/docs/web/mainapp/dev/index.rst b/docs/web/mainapp/dev/index.rst new file mode 100644 index 0000000..45ae2d8 --- /dev/null +++ b/docs/web/mainapp/dev/index.rst @@ -0,0 +1,15 @@ + +Development Guide +================= + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + overview + views + grids + forms + patterns + tasks/index diff --git a/docs/web/mainapp/dev/overview.rst b/docs/web/mainapp/dev/overview.rst new file mode 100644 index 0000000..25e161c --- /dev/null +++ b/docs/web/mainapp/dev/overview.rst @@ -0,0 +1,12 @@ + +Overview +======== + +Developing features for your web app is meant to be straightforward. +Here we'll document some of the main points. + +Perhaps the most important concepts are: + +* :doc:`views` +* :doc:`grids` +* :doc:`forms` diff --git a/docs/web/mainapp/patterns.rst b/docs/web/mainapp/dev/patterns.rst similarity index 100% rename from docs/web/mainapp/patterns.rst rename to docs/web/mainapp/dev/patterns.rst diff --git a/docs/web/mainapp/tasks/index.rst b/docs/web/mainapp/dev/tasks/index.rst similarity index 100% rename from docs/web/mainapp/tasks/index.rst rename to docs/web/mainapp/dev/tasks/index.rst diff --git a/docs/web/mainapp/tasks/newmasterview.rst b/docs/web/mainapp/dev/tasks/newmasterview.rst similarity index 100% rename from docs/web/mainapp/tasks/newmasterview.rst rename to docs/web/mainapp/dev/tasks/newmasterview.rst diff --git a/docs/web/mainapp/dev/views.rst b/docs/web/mainapp/dev/views.rst new file mode 100644 index 0000000..af533ee --- /dev/null +++ b/docs/web/mainapp/dev/views.rst @@ -0,0 +1,5 @@ + +Views +===== + +TODO diff --git a/docs/web/mainapp/index.rst b/docs/web/mainapp/index.rst index 54907de..ae4bbc0 100644 --- a/docs/web/mainapp/index.rst +++ b/docs/web/mainapp/index.rst @@ -8,5 +8,4 @@ Default Web App :caption: Contents: overview - patterns - tasks/index + dev/index diff --git a/docs/web/mainapp/overview.rst b/docs/web/mainapp/overview.rst index 45595c5..f40e597 100644 --- a/docs/web/mainapp/overview.rst +++ b/docs/web/mainapp/overview.rst @@ -2,4 +2,8 @@ Overview ======== -TODO +Tailbone provides the default web app. It is standalone +(server-rendered), and does not use the web API. + +See :doc:`dev/index` for help with developing new features for your +web app. diff --git a/docs/web/overview.rst b/docs/web/overview.rst index 45595c5..942776d 100644 --- a/docs/web/overview.rst +++ b/docs/web/overview.rst @@ -2,4 +2,16 @@ Overview ======== -TODO +`Tailbone`_ is the Python package which provides most of the web layer +for the Rattail Project. In particular it includes the foundations for: + +.. _Tailbone: https://pypi.org/project/tailbone/ + +* main web app, traditional server-side (see :doc:`mainapp/index`) +* web API for use with client-side apps (see :doc:`webapi`) + +`byjove`_ is the Javascript package which provides "some" of the +components etc. for use with client-side "single-page" apps (see +:doc:`spa`)). + +.. _byjove: https://www.npmjs.com/package/byjove