WuttaWeb 0.10.2__tar.gz → 0.12.0__tar.gz

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to wuttaweb will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## v0.12.0 (2024-08-22)
+
+### Feat
+
+- add "copy link" button for sharing a grid view
+- add initial support for proper grid filters
+- add initial filtering logic to grid class
+- add "searchable" column support for grids
+- improve page linkage between role/user/person
+- add basic autocomplete support, for Person
+
+### Fix
+
+- cleanup templates for home, login pages
+- cleanup logic for appinfo/configure
+- expose settings for app node title, type
+- show installed python packages on appinfo page
+- tweak login form to stop extending size of background card
+- add setting to auto-redirect anon users to login, from home page
+- add form padding, validators for /configure pages
+- add padding around main form, via wrapper css
+- show CRUD buttons in header only if relevant and user has access
+- tweak style config for home link app title in main menu
+
+## v0.11.0 (2024-08-20)
+
+### Feat
+
+- split up base templates into more sections (def blocks)
+- simplify base/page/form template structure; add docs
+
 ## v0.10.2 (2024-08-19)
 
 ### Fix

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: WuttaWeb
-Version: 0.10.2
+Version: 0.12.0
 Summary: Web App for Wutta Framework
 Project-URL: Homepage, https://wuttaproject.org/
 Project-URL: Repository, https://forgejo.wuttaproject.org/wutta/wuttaweb
@@ -35,7 +35,7 @@ Requires-Dist: pyramid-tm
 Requires-Dist: pyramid>=2
 Requires-Dist: waitress
 Requires-Dist: webhelpers2
-Requires-Dist: wuttjamaican[db]>=0.12.0
+Requires-Dist: wuttjamaican[db]>=0.12.1
 Requires-Dist: zope-sqlalchemy>=1.5
 Provides-Extra: docs
 Requires-Dist: furo; extra == 'docs'

wuttaweb-0.12.0/docs/narr/index.rst

@@ -0,0 +1,8 @@
+
+Documentation
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   templates/index

wuttaweb-0.12.0/docs/narr/templates/base.rst

@@ -0,0 +1,251 @@
+
+Base Templates
+==============
+
+This describes the base templates.  When creating a custom page
+template, you most often need to inherit from one of these:
+
+* :ref:`page_base_template`
+* :ref:`form_base_template`
+* :ref:`master_base_templates`
+
+.. note::
+
+   Any of these templates may be overridden; see
+   :ref:`mako-template-override`.
+
+
+Global Base
+~~~~~~~~~~~
+
+There is exactly one "true base template" for the web app, designated
+as: ``/base.mako``
+
+The default base template is ``wuttaweb:templates/base.mako`` and all
+page templates inherit from it.  However they inherit it by *name*
+only (``/base.mako``) - therefore if you override this via custom
+template search paths, effectively you have changed the **theme**.
+
+In addition to general layout/structure, this template is reponsible
+for creating the Vue app which encompasses the whole of every page.
+It also establishes the ``WholePage`` component which is the Vue app's
+one and only child component.
+
+(``WholePage`` in turn will have other children, for page content.)
+
+There is usually no need to define a template which inherits directly
+from ``/base.mako``, rather you should inherit from ``/page.mako``
+(see next section) or similar.
+
+As pertains to Vue component logic, there are 3 blocks which you may
+find a need to override.  These are defined by ``/base.mako`` so will
+apply to *all* templates:
+
+* ``render_vue_templates()``
+* ``modify_vue_vars()``
+* ``make_vue_components()``
+
+Most often it is necessary to customize ``modify_vue_vars()`` but keep
+reading for an example.
+
+
+.. _page_base_template:
+
+Page Base
+~~~~~~~~~
+
+The common base template for pages, designated as: ``/page.mako``
+
+This extends the Vue logic from ``/base.mako`` by establishing
+``ThisPage`` component, which wraps all content within the current
+page.
+
+The final structure then is conceptually like:
+
+.. code-block:: html
+
+   <div id="app">
+     <whole-page>
+       <!-- menu etc. -->
+       <this-page>
+         <!-- page contents -->
+       </this-page>
+     </whole-page>
+   </div>
+
+Simple usage is to create a template which inherits from
+``/page.mako`` and defines a ``page_content()`` block, e.g.:
+
+.. code-block:: mako
+
+   <%inherit file="/page.mako" />
+
+   <%def name="page_content()">
+     <p>hello world!</p>
+   </%def>
+
+The default ``/page.mako`` logic knows where to render the
+``page_content()`` block so that it fits properly into the
+component/layout structure.
+
+Often you may need to customize Vue component logic for a page; this
+is done by defining one of the blocks mentioned in previous section.
+
+Here is a simple example which shows how this works:
+
+.. code-block:: mako
+
+   <%inherit file="/page.mako" />
+
+   <%def name="page_content()">
+     <b-field label="Foo">
+       <b-input v-model="foo" />
+     </b-field>
+     <b-field>
+     <b-button @click="alertFoo()">
+       Alert
+     </b-button>
+     </b-field>
+   </%def>
+
+   <%def name="modify_vue_vars()">
+     ${parent.modify_vue_vars()}
+     <script>
+
+       // nb. this becomes ThisPage.data.foo
+       ThisPageData.foo = 'bar'
+
+       ThisPage.methods.alertFoo = function() {
+           alert("value of foo is: " + this.foo)
+       }
+
+     </script>
+   </%def>
+
+You can see that ``page_content()`` is able to reference things from
+``ThisPage`` component, while the ``modify_vue_vars()`` block is used
+to define those same things on the component.
+
+
+.. _form_base_template:
+
+Form Base
+~~~~~~~~~
+
+The common base template for pages with a form, designated as:
+``/form.mako``
+
+This expects the context dict to contain ``'form'`` which points to a
+:class:`~wuttaweb.forms.base.Form` instance.
+
+This template extends the Vue logic from ``/page.mako`` by
+establishing a Vue component specific to the form object.
+
+The final structure then is conceptually like:
+
+.. code-block:: html
+
+   <div id="app">
+     <whole-page>
+       <!-- menu etc. -->
+       <this-page>
+         <wutta-form>
+           <!-- fields etc. -->
+         </wutta-form>
+       </this-page>
+     </whole-page>
+   </div>
+
+A simple example which assumes one of the form fields exposes a button
+with click event that triggers ``alertFoo()`` method on the form
+component:
+
+.. code-block:: mako
+
+   <%inherit file="/form.mako" />
+
+   <%def name="modify_vue_vars()">
+     ${parent.modify_vue_vars()}
+     <script>
+
+       // nb. this becomes e.g. WuttaForm.foo when component is created
+       ${form.vue_component}Data.foo = 'bar'
+
+       ${form.vue_component}.methods.alertFoo = function() {
+           alert("value of foo is: " + this.foo)
+       }
+
+     </script>
+   </%def>
+
+.. note::
+
+   By default, ``${form.vue_compoment}`` is rendered as ``WuttaForm``
+   but that is not guaranteed.  You should resist the temptation to
+   hard-code that; always use ``${form.vue_component}`` and (where
+   applicable) ``${form.vue_tagname}``.
+
+   The reason for this is to allow multiple forms to exist on a single
+   page, each with a separate Vue component.  (Which is not shown in
+   the above example.)
+
+   See also :attr:`~wuttaweb.forms.base.Form.vue_component` and
+   :attr:`~wuttaweb.forms.base.Form.vue_tagname`.
+
+
+.. _master_base_templates:
+
+Master Base
+~~~~~~~~~~~
+
+These templates are for use with
+:class:`~wuttaweb.views.master.MasterView`.  Each is the default
+template used for the corresponding route/view, unless a more specific
+template is defined.
+
+The "index" template is unique in that it is (usually) for listing the
+model data:
+
+* ``/master/index.mako``
+
+The "form" template is just a base template, does not directly
+correspond to a route/view.  Other CRUD templates inherit from it.
+This inherits from ``/form.mako`` (see previous section).
+
+* ``/master/form.mako``
+
+These CRUD templates inherit from ``/master/form.mako`` and so
+require a ``'form'`` in the context dict.
+
+* ``/master/create.mako``
+* ``/master/view.mako``
+* ``/master/edit.mako``
+* ``/master/delete.mako``
+
+The "configure" template is for master views which have a
+configuration page.
+
+* ``/master/configure.mako``
+
+Usage for these is not significantly different from the ones shown
+above, in cases where you actually need to override the template.
+
+As an example let's say you have defined a ``WidgetMasterView`` class
+and want to override its "view" template.  You would then create a
+file as ``/widgets/view.mako`` (within your templates folder) and
+be sure to inherit from the correct base template:
+
+.. code-block:: mako
+
+   <%inherit file="/master/view.mako" />
+
+   <%def name="page_content()">
+
+     <p>THIS APPEARS FIRST!</p>
+
+     ## nb. the form will appear here
+     ${parent.page_content()}
+
+     <p>MADE IT TO THE END!</p>
+
+   </%def>

wuttaweb-0.12.0/docs/narr/templates/index.rst

@@ -0,0 +1,10 @@
+
+Templates
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   base
+   lookup

wuttaweb-0.12.0/docs/narr/templates/lookup.rst

@@ -0,0 +1,69 @@
+
+Template Lookup
+===============
+
+The discovery of templates is handled by Mako, and is configurable.
+
+WuttaWeb comes with all templates it needs, in the path designated as
+``wuttaweb:templates``.
+
+When the app renders a page, it invokes the Mako lookup logic, which
+searches one or more folders and returns the first matching file it
+encounters.  By default ``wuttaweb:templates`` is the only place it
+looks.
+
+A template is searched for by "name" but it is more path-like, e.g.
+``/page.mako`` or ``/master/index.mako`` etc.  So for example the file
+at ``wuttaweb:templates/home.mako`` is used for home page (using
+lookup name ``/home.mako``) by default.
+
+
+.. _mako-template-override:
+
+Overriding the Search Paths
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The basic idea is to give it a list of paths it should search when
+trying to find a template.  The first template file found for a given
+search name is used and no further search is done for that name.
+
+You can define the Mako lookup sequence in your ``web.conf`` as
+follows:
+
+.. code-block:: ini
+
+   [app:main]
+   mako.directories =
+       /random/path/on/disk
+       poser.web:templates
+       wuttaweb:templates
+
+This setting is interpreted by ``pyramid_mako`` (`docs`_).
+
+.. _docs: https://docs.pylonsproject.org/projects/pyramid_mako/en/latest/index.html#mako-directories
+
+Here ``wuttaweb:templates/home.mako`` would still be used by default
+for home page, *unless* e.g. ``/random/path/on/disk/home.mako``
+existed in which case that would be used.
+
+Each path can have an arbitrary set of templates, they will
+effectively be combined to a single set by the app, with the
+definition order determining search priority.
+
+If you are already using a custom ``app.main()`` function for
+constructing the web app during startup, it may be a good idea to
+change the *default* search paths to include your package.
+
+Setup for custom ``app.main()`` is beyond the scope here, but assuming
+you *do* already have one, this is what it looks like::
+
+   from wuttaweb import app as base
+
+   def main(global_config, **settings):
+
+       # nb. set the *default* mako search paths; however config can
+       # still override with method shown above
+       settings.setdefault('mako.directories', ['poser.web:templates',
+                                                'wuttaweb:templates'])
+
+       return base.main(global_config, **settings)

wuttaweb-0.12.0/docs/narr/templates/overview.rst

@@ -0,0 +1,15 @@
+
+Overview
+========
+
+WuttaWeb uses the `Mako`_ template language for page rendering.
+
+.. _Mako: https://www.makotemplates.org/
+
+There is a "global" base template which effectively defines the
+"theme" (page layout, Vue component structure).  A few other base
+templates provide a starting point for any custom pages; see
+:doc:`base`.
+
+Templates are found via lookup which is handled by Mako.  This is
+configurable so you can override any or all; see :doc:`lookup`.

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "WuttaWeb"
-version = "0.10.2"
+version = "0.12.0"
 description = "Web App for Wutta Framework"
 readme = "README.md"
 authors = [{name = "Lance Edgar", email = "lance@edbob.org"}]
@@ -41,7 +41,7 @@ dependencies = [
         "pyramid_tm",
         "waitress",
         "WebHelpers2",
-        "WuttJamaican[db]>=0.12.0",
+        "WuttJamaican[db]>=0.12.1",
         "zope.sqlalchemy>=1.5",
 ]
 

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/src/wuttaweb/forms/base.py

@@ -25,6 +25,7 @@ Base form classes
 """
 
 import logging
+from collections import OrderedDict
 
 import colander
 import deform
@@ -311,6 +312,9 @@ class Form:
 
         self.set_fields(fields or self.get_fields())
 
+        # nb. this tracks grid JSON data for inclusion in page template
+        self.grid_vue_data = OrderedDict()
+
     def __contains__(self, name):
         """
         Custom logic for the ``in`` operator, to allow easily checking
@@ -750,6 +754,10 @@ class Form:
                     kwargs['appstruct'] = self.model_instance
 
             form = deform.Form(schema, **kwargs)
+            # nb. must give a reference back to wutta form; this is
+            # for sake of field schema nodes and widgets, e.g. to
+            # access the main model instance
+            form.wutta_form = self
             self.deform_form = form
 
         return self.deform_form
@@ -818,6 +826,17 @@ class Form:
         output = render(template, context)
         return HTML.literal(output)
 
+    def add_grid_vue_data(self, grid):
+        """ """
+        if not grid.key:
+            raise ValueError("grid must have a key!")
+
+        if grid.key in self.grid_vue_data:
+            log.warning("grid data with key '%s' already registered, "
+                        "but will be replaced", grid.key)
+
+        self.grid_vue_data[grid.key] = grid.get_vue_data()
+
     def render_vue_field(
             self,
             fieldname,

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/src/wuttaweb/forms/schema.py

@@ -246,6 +246,9 @@ class ObjectRef(colander.SchemaType):
                 values.insert(0, self.empty_option)
             kwargs['values'] = values
 
+        if 'url' not in kwargs:
+            kwargs['url'] = lambda person: self.request.route_url('people.view', uuid=person.uuid)
+
         return widgets.ObjectRefWidget(self.request, **kwargs)
 
 
@@ -321,6 +324,28 @@ class RoleRefs(WuttaSet):
         return widgets.RoleRefsWidget(self.request, **kwargs)
 
 
+class UserRefs(WuttaSet):
+    """
+    Form schema type for the Role
+    :attr:`~wuttjamaican:wuttjamaican.db.model.auth.Role.users`
+    association proxy field.
+
+    This is a subclass of :class:`WuttaSet`.  It uses a ``set`` of
+    :class:`~wuttjamaican:wuttjamaican.db.model.auth.User` ``uuid``
+    values for underlying data format.
+    """
+
+    def widget_maker(self, **kwargs):
+        """
+        Constructs a default widget for the field.
+
+        :returns: Instance of
+           :class:`~wuttaweb.forms.widgets.UserRefsWidget`.
+        """
+        kwargs.setdefault('session', self.session)
+        return widgets.UserRefsWidget(self.request, **kwargs)
+
+
 class Permissions(WuttaSet):
     """
     Form schema type for the Role

{wuttaweb-0.10.2 → wuttaweb-0.12.0}/src/wuttaweb/forms/widgets.py

@@ -44,6 +44,7 @@ from deform.widget import (Widget, TextInputWidget, TextAreaWidget,
 from webhelpers2.html import HTML
 
 from wuttaweb.db import Session
+from wuttaweb.grids import Grid
 
 
 class ObjectRefWidget(SelectWidget):
@@ -83,9 +84,19 @@ class ObjectRefWidget(SelectWidget):
     """
     readonly_template = 'readonly/objectref'
 
-    def __init__(self, request, *args, **kwargs):
+    def __init__(self, request, url=None, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.request = request
+        self.url = url
+
+    def get_template_values(self, field, cstruct, kw):
+        """ """
+        values = super().get_template_values(field, cstruct, kw)
+
+        if 'url' not in values and self.url and field.schema.model_instance:
+            values['url'] = self.url(field.schema.model_instance)
+
+        return values
 
 
 class NotesWidget(TextAreaWidget):
@@ -137,12 +148,17 @@ class RoleRefsWidget(WuttaCheckboxChoiceWidget):
     """
     Widget for use with User
     :attr:`~wuttjamaican:wuttjamaican.db.model.auth.User.roles` field.
+    This is the default widget for the
+    :class:`~wuttaweb.forms.schema.RoleRefs` type.
 
     This is a subclass of :class:`WuttaCheckboxChoiceWidget`.
     """
+    readonly_template = 'readonly/rolerefs'
 
     def serialize(self, field, cstruct, **kw):
         """ """
+        model = self.app.model
+
         # special logic when field is editable
         readonly = kw.get('readonly', self.readonly)
         if not readonly:
@@ -159,10 +175,78 @@ class RoleRefsWidget(WuttaCheckboxChoiceWidget):
                           if val[0] != admin.uuid]
                 kw['values'] = values
 
+        else: # readonly
+
+            # roles
+            roles = []
+            if cstruct:
+                for uuid in cstruct:
+                    role = self.session.query(model.Role).get(uuid)
+                    if role:
+                        roles.append(role)
+            kw['roles'] = roles
+
+            # url
+            url = lambda role: self.request.route_url('roles.view', uuid=role.uuid)
+            kw['url'] = url
+
         # default logic from here
         return super().serialize(field, cstruct, **kw)
 
 
+class UserRefsWidget(WuttaCheckboxChoiceWidget):
+    """
+    Widget for use with Role
+    :attr:`~wuttjamaican:wuttjamaican.db.model.auth.Role.users` field.
+    This is the default widget for the
+    :class:`~wuttaweb.forms.schema.UserRefs` type.
+
+    This is a subclass of :class:`WuttaCheckboxChoiceWidget`; however
+    it only supports readonly mode and does not use a template.
+    Rather, it generates and renders a
+    :class:`~wuttaweb.grids.base.Grid` showing the users list.
+    """
+
+    def serialize(self, field, cstruct, **kw):
+        """ """
+        readonly = kw.get('readonly', self.readonly)
+        if not readonly:
+            raise NotImplementedError("edit not allowed for this widget")
+
+        model = self.app.model
+        columns = ['person', 'username', 'active']
+
+        # generate data set for users
+        users = []
+        if cstruct:
+            for uuid in cstruct:
+                user = self.session.query(model.User).get(uuid)
+                if user:
+                    users.append(dict([(key, getattr(user, key))
+                                       for key in columns + ['uuid']]))
+
+        # grid
+        grid = Grid(self.request, key='roles.view.users',
+                    columns=columns, data=users)
+
+        # view action
+        if self.request.has_perm('users.view'):
+            url = lambda user, i: self.request.route_url('users.view', uuid=user['uuid'])
+            grid.add_action('view', icon='eye', url=url)
+            grid.set_link('person')
+            grid.set_link('username')
+
+        # edit action
+        if self.request.has_perm('users.edit'):
+            url = lambda user, i: self.request.route_url('users.edit', uuid=user['uuid'])
+            grid.add_action('edit', url=url)
+
+        # render as simple <b-table>
+        # nb. must indicate we are a part of this form
+        form = getattr(field.parent, 'wutta_form', None)
+        return grid.render_table_element(form)
+
+
 class PermissionsWidget(WuttaCheckboxChoiceWidget):
     """
     Widget for use with Role