.. Copyright (C) 2018 The Meme Factory, Inc.  http://www.karlpinc.com/


   This file is part of PGWUI_Common.
  
   This program is free software: you can redistribute it and/or
   modify it under the terms of the GNU Affero General Public License
   as published by the Free Software Foundation, either version 3 of
   the License, or (at your option) any later version.

   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.

   You should have received a copy of the GNU Affero General Public
   License along with this program.  If not, see
   <http://www.gnu.org/licenses/>.

   Karl O. Pinc <kop@karlpinc.com>

.. #End Of Copyright Marker#

PGWUI_Common
============

Short Documentation
-------------------

PGWUI_Common stands for `PostgreSQL`_ Web User Interface, Common files.

Shared files and functionality used by the web interfaces which are a
part of the PGWUI package suite.

The PGWUI package suite is a Python framework for creating
`PostgreSQL`_ web user interfaces, and a collection of user interfaces
built using the framework.  The focus is on interfaces supporting
bulk data upload or download, on execution of batches of arbitrary
SQL, and on transactions.  A distinguishing feature is an emphasis on
discovering and reporting as many errors as is possible per bulk
interaction with the database.

PGWUI_Common provides:

  * Extendable web forms with fields supporting designation of
    database and credentials.  These forms are rendered using
    `Pyramid`_ views.

  * API used to establish `routes`_.  Called during configuration
    after all components are configured.  Called by PGWUI_Server or
    whatever else is used to configure `Pyramid`_.

  * API used to override `assets`_.  Called during configuration after
    all compomponents are configured.  Called by PGWUI_Server or
    whatever else is used to configure `Pyramid`_.

  * API which validates all core PGWUI settings.  Called after
    configuration parsing.  Called by PGWUI_Server or whatever else is
    used to configure `Pyramid`_.

The official PGWUI components based on PGWUI_Common are highly
configurable.  The web page templates used to generate HTML files, the
CSS files, the static HTML files, and the location of the web pages
within the "URL space" can all be altered without programming.

It is relatively easy to create alternate "skins" for the user
interface.  Naturally some exposure to HTML, CSS, and URL concepts are
helpful.  Extensive alterations to error presentation may require some
experience with the Mako HTML templating system and/or the Python
programming language.


Configuration Settings Common to All PGWUI Components
-----------------------------------------------------

PGWUI components all have the following configuration settings:

 menu_label
   The label for PGWUI_Menu to display, when different from the default

Note that the ``menu_label`` setting appears within the settings for
the component, not at top-level.


Usage
-----

This section is of interest to application developers.

When utilizing PGWUI modules in your own `Pyramid`_ application,
modules which require the PGWUI_Common module, PGWUI_Common must be
explicitly configured.  This can be done with any of

`Pyramid's`_ configuration mechanisms,

``pyramid_includes = pgwui_common`` in a ``.ini`` file or
``config.include('pgwui_common')`` in Python code.

Unless PGWUI_Server is used, PGWUI_Common (and PGWUI_Core) expect all
required settings exist, as well as those which have defaults
established by PGWUI_Server.


Common Template Variables
^^^^^^^^^^^^^^^^^^^^^^^^^

The `@base_view` decorator, and it's decendents, makes the following variables
available in templates:

 pgwui
   A dict, containing the following keys:
 
   urls
     A dict, keyed by PGWUI component name.  Each value is the
     URL used to reach the component.  There are the following special
     component names:

     pgwui_home
       The URL to the pgwui.home_page setting.  This key
       is always available.

     pgwui_menu
       The URL to the menu of PGWUI components.  This
       obtains its value from the ``pgwui.menu_page`` configuration
       setting, if present.  Otherwise it is the URL to the PGWUI_Menu
       component, if the component is present.  Otherwise the key
       does not exist.


Configuration By Python Code
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you are writing a complete `Pyramid`_ application, or simply want full
control over configuration you will need to make a Python
distribution.  (Something to be installed, perhaps with ``pip``.)
In this case use pgwui_common to configure your pyramid app by putting
the following into your package's __init__.py::

    from pyramid.config import Configurator

    def main(global_config, **settings):
        config = Configurator()
        config.include('pgwui_common')

Note that you can override any of the assets in this package or any of
the PGWUI packages, any of the templates or css, using Pyramid's Asset
Override API.  See:
`https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/assets.html#overriding-assets
<https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/assets.html#overriding-assets>`_


Establishing Routes
^^^^^^^^^^^^^^^^^^^

To establish `Pyramid`_ `routes`_ to the installed PGWUI components,
after all components are configured, `pgwui_common.routes.add_routes()`
must be called.


Development Status
------------------

Although in use in production systems, and suitable for production
use, PGWUI_Common must be considered Beta code.  There is a reasonable
likelihood that it may undergo some change before final Production
release.  Install a specific version of PGWUI_Common to ensure a
backwards incompatible change does not break your code.


Complete Documentation
----------------------

The complete documentation set can be found on the PGWUI_Common home page at
http://pgwui_common.readthedocs.io/.


License
-------

Except for files otherwise marked, distributed WITHOUT ANY WARRANTY
under the terms of the GNU Affero General Public License, version 3 or
a later version at your option.  See the copyright notices at the top
of each file and the LICENSE.txt file for details.


Acknowledgments
---------------

The PGWUI_Common code is based on the GMI_Pyramid sub-system created for
the `Gombe Mother Infant Database Project
<https://gombemi.ccas.gwu.edu>`_.  Support for extracting PGWUI_Core
from GMI_Pyramid, its Python packaging, and further enhancement was
provided by `The Dian Fossey Gorilla Fund
<https://www.gorillafund.org>`_.


.. _PostgreSQL: https://www.postgresql.org/
.. _Pyramid: https://trypyramid.com/
.. _Pyramid's: `Pyramid`_
.. _routes: https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/urldispatch.html
.. _assets: https://docs.pylonsproject.org/projects/pyramid/en/1.10-branch/narr/assets.html