Metadata-Version: 2.1
Name: pgwui-common
Version: 0.11.0
Summary: Shared files for PGWUI Postgres web interfaces.
Home-page: http://pgwui_common.readthedocs.io/
Author: Karl O. Pinc
Author-email: kop@karlpinc.com
License: AGPLv3+
Description: 
        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
        
Keywords: database front end,interface,Postgres,Postgres user interface,Postgres web interface,PostgreSQL,Postgres front end,user interface,web,web front end
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Pyramid
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/x-rst
Provides-Extra: testing
