Re-work the getting started section, and add trigger function support. Fixes #1403

docs/en_US/connecting.rst

@@ -4,21 +4,27 @@
 Connecting to a Server
 **********************
 
-Before you can use the pgAdmin client to manage your Postgres installation, you must define a connection to the server.    
+Before you can use the pgAdmin client to manage the objects that reside on your Postgres server, you must define a connection to the server.  You can (optionally) use the *Server Group* dialog to create server groups to organize the server connections within the tree control for easier management. To open the *Server Group* dialog, right-click on the *Servers* node of the tree control, and select *Server Group* from the *Create* menu.
 
 Contents:
 
 .. toctree::
 
    server_group_dialog
+
+Use the fields on the *Server* dialog to define the connection properties for each new server that you wish to manage with pgAdmin.  To open the *Server* dialog, right-click on the *Servers* node of the tree control, and select *Server* from the *Create* menu. 
+
+Contents:
+
+.. toctree::
+
    server_dialog
+
+After defining a server connection, right-click on the server name, and select *Connect to server* to authenticate with the server, and start using pgAdmin to manage objects that reside on the server.
+
+Contents:
+
+.. toctree::
+
    connect_to_server   
-   connect_error
-
-
-  
-
-
-   
-   
-
+   connect_error

docs/en_US/getting_started.rst

@@ -4,9 +4,31 @@
 Getting Started
 ***************
 
-pgAdmin 4 features a highly-customizable display that features drag-and-drop panels that you can arrange to make the best use of your desktop environment.  
+Pre-compiled and configured installation packages for pgAdmin 4 are available for a number of desktop environments; we recommend using an installer whenever possible.  A standard installation using the pgAdmin installer is a server deployment.
 
-When you install pgAdmin in server mode, you will be prompted to provide a role name and pgAdmin password.  The first role registered with pgAdmin will be an administrative user.  When you authenticate with pgAdmin, pgAdmin displays the server definitions associated with that login role in the tree control. The tree control provides an elegant overview of the managed servers, and the objects that reside on each server. Right-click on a node within the tree control to access context-sensitive menus that provide quick access to management tasks for the selected object.
+In a Server Deployment, the pgAdmin application is deployed behind a webserver or with the WSGI interface.  
+If you install pgAdmin in server mode, you will be prompted to provide a role name and pgAdmin password when you initially connect to pgAdmin.  The first role registered with pgAdmin will be an administrative user; the administrative role can use the pgAdmin *User Management* dialog to create and manage additional pgAdmin user accounts.  When a user authenticates with pgAdmin, the pgAdmin tree control displays the server definitions associated with that login role.  
+
+Contents:
+
+.. toctree::
+
+   server_deployment
+   pgadmin_login
+   pgadmin_user 
+
+In a Desktop Deployment, the pgAdmin application is configured to use the desktop runtime environment to host and display the program on a supported platform. Typically, users will install a pre-built package to run pgAdmin in desktop mode, but a manual desktop deployment can be installed and though it is more difficult to setup, it may be useful for developers interested in understanding how pgAdmin works.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   
+   desktop_deployment
+
+The pgAdmin 4 client features a highly-customizable display that features drag-and-drop panels that you can arrange to make the best use of your desktop environment.  
+
+The tree control provides an elegant overview of the managed servers, and the objects that reside on each server. Right-click on a node within the tree control to access context-sensitive menus that provide quick access to management tasks for the selected object.
 
 The tabbed browser provide quick access to statistical information about each object in the tree control, and pgAdmin tools and utilities (such as the Query tool and the debugger). pgAdmin opens additional feature tabs each time you access the extended functionality offered by pgAdmin tools; you can open, close, and re-arrange feature tabs as needed. 
 
@@ -14,17 +36,20 @@ Use the *Preferences* dialog to customize the content and colors of the pgAdmin
 
 *Help* buttons in the lower-left corner of each dialog will open the online help for the dialog.  You can access additional Postgres help by navigating through the *Help* menu, and selecting the name of the resource that you wish to open. 
 
-An administrative role can use the pgAdmin User Management dialog to create and manage additional pgAdmin user accounts.
-
 Contents:
 
 .. toctree::
 
-   pgadmin_login
    browser
    pgadmin_menu_bar
    pgadmin_tabbed_browser
    pgadmin_tree_control
    preferences
-   pgadmin_user
+   
+Before using pgAdmin to manage objects that reside on a server, you must define a connection to the server; for more information please see *Connecting to a Server*:
+   
+Contents:
 
+.. toctree::
+
+   connecting

docs/en_US/managing_database_objects.rst

@@ -30,6 +30,7 @@ Contents:
    procedure_dialog
    schema_dialog
    sequence_dialog
+   trigger_function_dialog
    type_dialog
    user_mapping_dialog
    view_dialog

docs/en_US/trigger_function_dialog.rst

@@ -0,0 +1,102 @@
+.. _trigger_function_dialog:
+
+***************************
+The Trigger function Dialog
+***************************
+ 
+Use the *Trigger function* dialog to create or manage a trigger_function. A trigger function defines the action that will be invoked when a trigger fires.
+
+The *Trigger function* dialog organizes the development of a trigger function through the following dialog tabs: *General*, *Definition*, *Options*, *Parameters* and *Security*. The *SQL* tab displays the SQL code generated by dialog selections. 
+ 
+.. image:: images/trigger_function_general.png
+
+Use the fields in the *General* tab to identify the trigger function:
+
+* Use the *Name* field to add a descriptive name for the trigger function. The name will be displayed in the *pgAdmin* tree control. Please note that trigger functions will be invoked in alphabetical order.
+* Use the drop-down listbox next to *Owner* to select a role.
+* Select the name of the schema in which the trigger function will reside from the drop-down listbox in the *Schema* field.
+* Store notes about the trigger function in the *Comment* field.
+
+Click the *Definition* tab to continue.
+
+.. image:: images/trigger_function_definition.png
+
+Use the fields in the *Definition* tab to define the trigger function:
+
+* Use the drop-down listbox next to *Return type* to specify the pseudotype that is associated with the trigger function: 
+
+   * Select *trigger* if you are creating a DML trigger.
+   * Select *event_trigger* if you are creating a DDL trigger.
+   
+* Use the drop-down listbox next to *Language* to select the implementation language. The default is *plpgsql*.
+* Use the *Code* field to write the code that will execute when the trigger function is called.
+
+Click the *Options* tab to continue.
+
+.. image:: images/trigger_function_options.png
+
+Use the fields in the *Options* tab to describe or modify the action of the trigger function:
+
+* Use the drop-down listbox next to *Volatility* to select one of the following: 
+
+    * *VOLATILE* indicates that the trigger function value can change even within a single table scan. 
+    * *STABLE* indicates that the trigger function cannot modify the database, and that within a single table scan it will consistently return the same result for the same argument values.
+    * *IMMUTABLE* indicates that the trigger function cannot modify the database and always returns the same result when given the same argument values.
+    
+* Move the *Returns a Set?* switch to indicate if the trigger function returns a set that includes multiple rows. The default is *No*. 
+* Move the *Strict?* switch to indicate if the trigger function always returns NULL whenever any of its arguments are NULL. If *Yes*, the function is not executed when there are NULL arguments; instead a NULL result is assumed automatically. The default is *No*.
+* Move the *Security of definer?* switch to specify that the trigger function is to be executed with the privileges of the user that created it. The default is *No*.
+* Move the *Window?* switch to indicate that the trigger function is a window function rather than a plain function. The default is *No*. This is currently only useful for trigger functions written in C. 
+* Use the *Estimated cost* field to specify a positive number representing the estimated execution cost for the trigger function, in units of cpu_operator_cost. If the function returns a set, this is the cost per returned row. 
+* Use the *Estimated rows* field to specify a positive number giving the estimated number of rows that the query planner should expect the trigger function to return. This is only allowed when the function is declared to return a set. The default assumption is 1000 rows. 
+* Move the *Leak proof?* switch to indicate whether the trigger function has side effects. The default is *No*. This option can only be set by the superuser.
+
+Click the *Parameters* tab to continue.
+
+.. image:: images/trigger_function_parameters.png
+
+Use the fields in the *Parameters* tab to specify settings that will be applied when the trigger function is invoked:
+
+* Use the drop-down listbox next to *Parameter Name* in the *Parameters* panel to select a parameter. 
+* Click the *Add* button to add the variable to *Name* field in the table.
+* Use the *Value* field to specify the value that will be associated with the selected variable. This field is context-sensitive.
+
+Click the *Security* tab to continue.
+
+.. image:: images/trigger_function_security.png
+
+Use the *Security* tab to assign privileges and define security labels.  
+
+Use the *Privileges* panel to assign usage privileges for the trigger function to a role. Click *Add* to to add a role to the table.
+
+* Select the name of the role from the drop-down listbox in the *Grantee* field.
+* Click inside the *Privileges* field. Check the boxes to the left of one or more privileges to grant the selected privilege to the specified user.
+* Select the name of a role from the drop-down listbox in the *Grantor* field. The default grantor is the owner of the database.
+
+Click *Add* to assign additional privileges; to discard a privilege, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Use the *Security Labels* panel to define security labels applied to the trigger function. Click *Add* to add each security label selection: 
+
+* Specify a security label provider in the *Provider* field. The named provider must be loaded and must consent to the proposed labeling operation.
+* Specify a a security label in the *Security Label* field. The meaning of a given label is at the discretion of the label provider. PostgreSQL places no restrictions on whether or how a label provider must interpret security labels; it merely provides a mechanism for storing them. 
+
+Click *Add* to assign additional security labels; to discard a security label, click the trash icon to the left of the row and confirm deletion in the *Delete Row* popup.
+
+Click the *SQL* tab to continue.
+
+Your entries in the *Trigger function* dialog generate a SQL command (see an example below). Use the *SQL* tab for review; revisit other tabs to modify the SQL command. 
+
+**Example**
+
+The following is an example of the sql command generated by user selections in the *Trigger function* dialog: 
+
+.. image:: images/trigger_function_sql.png
+
+The example shown demonstrates creating a trigger function named *emp_stamp* that checks for a new employee's name, and checks that the employee's salary is a positive value.
+
+* Click the *Info* button (i) to access online help. View context-sensitive help in the *Tabbed browser*, where a new tab displays the PostgreSQL core documentation.
+* Click the *Save* button to save work.
+* Click the *Cancel* button to exit without saving work.
+* Click the *Reset* button to restore configuration parameters.
+
+