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


   This file is part of PGWUI_Menu.
  
   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_Menu
==========

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

PGWUI_Menu stands for `PostgreSQL`_ Web User Interface, Menu.

Provides a menu for 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_Menu provides:

  * Extendable web forms with automatically generated menu items for
    installed PGWUI components.  These forms are rendered using
    `Pyramid`_ views.

The official PGWUI components based on PGWUI_Menu 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.


Usage
-----

PGWUI components can be automatically added to the menu.  Every
component must have a 'pgwui.components' entry point.  The name of the
component's entry point is used to look up its menu properties; the
name of the configuration directive which configures the pgwui
component is the component name itself.  E.g. To configure the
pgwui_upload component's menu item, "pgwui_upload" is the
configuration directive.  This configuration directive is a map and
must contain the following elements:: menu_label The label of the menu
item

An example configuration directive for PGWUI_Upload::
  
  pgwui.pgwui_upload =
      menu_label = upload -- Upload File Into Database


The pgwui_menu component takes a list of pgwui component names
and matches the menu order to the list order.

  pgwui.pgwui_menu =
      order = pgwui_upload
              pgwui_logout

See the PGWUI_Common documentation if you wish to write your
own `Pyramid`_ application or wish more control and want to
configure using Python code.


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

Although in use in production systems, and suitable for production
use, PGWUI_Menu 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_Menu to ensure a
backwards incompatible change does not break your code.


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

The complete documentation set can be found on the PGWUI_Menu home page at
http://pgwui_menu.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_Menu 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/