Library:

Jam.py can now be deployed on PythonAnywhere. See How to deploy project on PythonAnywhere
Directory of the project can be passed to the create_application function now (jam/wsgi.py module).
Multiprocessing connection pool parameter removed from project Parameters
Bugs related to processing of keyboard events by forms fixed
Some bugs fixed
Documentation:

How to section created. That section will contain code examples that can be useful to quickly accomplish common tasks.

Author: jam-py

.gitignore

@@ -7,7 +7,6 @@ dist/
 build/
 docs/_build/
 *.xml
-*.lock
 /admin/
 /jam_docs/
 /css/
@@ -29,4 +28,5 @@ doc/_build/
 os
 jam*.zip
 wsgi.conf
+langs.lock
 xchanges.txt

demo/admin.sqlite

@@ -27,19 +27,12 @@ On the General tab, you can specify general parameters of the project:
 
 * **Debugging** - if this button is checked, the Werkzeug libarary bebugger will
   be invoked when an error on the server occurs.
+
+* **Persistent connection** - if this checkbox is checked the application creates 
+  a connection pool otherwise a connection is created before executing sql query.
 
 * **Connection pool size** — the size of the server database connection pool. 
 
-* **Multiprocessing connection pool** - if this checkbox is checked the framework 
-  creates connection pool by using multiprocessing python module - the 
-  connections will be created in different processes.
-  
-* **Persistent connection** - if this checkbox is checked and multiprocessing 
-  connection pool is selected, the framework creates connection in the main 
-  process. Before executing any statement, the framework checks if this 
-  connection is busy, if not, the statment is executed by this connection, 
-  otherwise multiprocessing connection pool is used.
-  
 * **Compressed JS, CSS files** - If this button is checked the server returns 
   compressed *js* and *css* files when *index.html* page is loaded.
 
@@ -79,9 +72,8 @@ On the General tab, you can specify general parameters of the project:
 * **Version** — specify the version of the project here.
 
 .. note::
-   When **Connection pool size**, **Multiprocessing connection pool** or
-   **Persistent connection** parameters are changed, the server applicaton must be 
-   restarted for changes to take effect.
+   When **Connection pool size** or **Persistent connection** parameters are 
+   changed, the server applicaton must be restarted for changes to take effect.
 
 
 Interface tab

demo/static/files/tracks.csv

@@ -7,12 +7,13 @@ Jam.py documentation contents
 
     index
 
-.. toctree::
+.. toctree:: 
     :maxdepth: 3
 
     intro/index
     programming/index
     faq/index
+    how to/index
     admin/index
     refs/index
     releases/index

docs/admin/_images/parameters.png

@@ -0,0 +1,128 @@
+=================================
+Export to / import from csv files
+=================================
+
+First, in the client module of the item we create two buttons that execute the 
+corresponding functions when you click on them:
+
+.. code-block:: js
+
+  function on_view_form_created(item) {
+    var csv_import_btn = item.add_view_button('Import csv file'),
+        csv_export_btn = item.add_view_button('Export csv file');
+    csv_import_btn.click(function() { csv_import(item) });
+    csv_export_btn.click(function() { csv_export(item) });
+  }
+
+  function  csv_export(item) {
+      item.server('export_scv', function(file_name, error) {
+          if (error) {
+              item.alert_error(error);
+          }
+          else {
+              var url = [location.protocol, '//', location.host, location.pathname].join('');
+              url += 'static/files/' + file_name;
+              window.open(encodeURI(url));
+          }
+      });
+  }
+
+  function csv_import(item) {
+      task.upload('static/files', {callback: function(file_name) {
+          item.server('import_scv', [file_name], function(error) {
+              if (error) {
+                  item.warning(error);
+              }
+              item.refresh_page(true);
+          });
+      }});
+  }
+  
+These functions execute the following functions defined in the server module. 
+In this module we use the Python csv module. We do not export system fields - 
+primary key field and deletion flag field.
+
+Below is the code for Python 3: 
+
+.. code-block:: py
+
+  import os
+  import csv
+
+  def export_scv(item):
+      copy = item.copy()
+      copy.open()
+      file_name = item.item_name + '.csv'
+      path = os.path.join(item.task.work_dir, 'static', 'files', file_name)
+      with open(path, 'w', encoding='utf-8') as csvfile:
+          fieldnames = []
+          for field in copy.fields:
+              if not field.system_field():
+                  fieldnames.append(field.field_name)
+          writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+          writer.writeheader()
+          for c in copy:
+              dic = {}
+              for field in copy.fields:
+                  if not field.system_field():
+                      dic[field.field_name] = field.text
+              writer.writerow(dic)
+      return file_name
+  
+  def import_scv(item, file_name):
+      copy = item.copy()
+      path = os.path.join(item.task.work_dir, 'static', 'files', file_name)
+      with open(path, 'r', encoding='utf-8') as csvfile:
+          copy.open(open_empty=True)
+          reader = csv.DictReader(csvfile)
+          for row in reader:
+              print(row)
+              copy.append()          
+              for field in copy.fields:
+                  if not field.system_field():
+                      field.text = row[field.field_name]
+              copy.post() 
+          copy.apply()          
+
+For Python 2, this code looks like this:
+
+.. code-block:: py
+
+  import os
+  import csv
+  
+  def export_scv2(item):
+      copy = item.copy()
+      copy.open()
+      file_name = item.item_name + '.csv'
+      path = os.path.join(item.task.work_dir, 'static', 'files', file_name)
+      with open(path, 'wb') as csvfile:
+          fieldnames = []
+          for field in copy.fields:
+              if not field.system_field():
+                  fieldnames.append(field.field_name.encode('utf8'))
+          writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+          writer.writeheader()
+          for c in copy:
+              dic = {}
+              for field in copy.fields:
+                  if not field.system_field():
+                      dic[field.field_name.encode('utf8')] = field.text.encode('utf8')
+              writer.writerow(dic)
+      return file_name
+  
+  def import_scv2(item, file_name):
+      copy = item.copy()
+      path = os.path.join(item.task.work_dir, 'static', 'files', file_name)
+      with open(path, 'rb') as csvfile:
+          item.task.execute('delete from %s' % item.table_name)
+          copy.open(open_empty=True)
+          reader = csv.DictReader(csvfile)
+          for row in reader:
+              print(row)
+              copy.append()          
+              for field in copy.fields:
+                  if not field.system_field():
+                      field.text = row[field.field_name.encode('utf8')].decode('utf8')
+              copy.post() 
+          copy.apply()          

docs/admin/project/parameters.txt

@@ -0,0 +1,37 @@
+==================================================
+How do I write functions which have a global scope
+==================================================
+
+Each function defined in the server or client module of an item becomes an 
+attribute of the item.
+
+Thus, using the 
+:doc:`task tree </programming/task_tree>`,
+you can access any function declared in the client or server module in any 
+project module.
+
+For example, if we have a function ``some_func`` declared in the Customers client 
+module, we can execute it in any module of the project. 
+Note that the task is a global variable on the client.
+
+.. code-block:: js
+
+  task.customers.some_func()
+
+On the server, the task is not global, but an item that triggered / called it is 
+passed to each event handler and function called by the 
+:doc:`server </refs/client/abstr_item/m_server>`
+method. Therefore, if the ``some_func`` function is declared in the Customers 
+server module, it can be executed in a function or event handler as follows:
+
+.. code-block:: js
+
+  def on_apply(item, delta, params): 
+    item.task.customers.some_func()
+
+
+Note that event handlers are just functions and can also be called from other 
+modules.
+
+
+  

docs/contents.txt

@@ -0,0 +1,36 @@
+=============================
+How to add a button to a form
+=============================
+
+The simplest way to add a button to an edit / view from is to use
+:doc:`add_edit_button </refs/client/item/m_add_edit_button>` /
+:doc:`add_view_button </refs/client/item/m_add_view_button>`
+correspondinly. You can call this functions in the
+:doc:`on_edit_form_created </refs/client/item/on_edit_form_created>` /
+:doc:`on_view_form_created </refs/client/item/on_view_form_created>`
+event handlers.
+
+For example the Customers item uses this code in its client module to add 
+buttons to a view form:
+
+.. code-block:: js
+
+  function on_view_form_created(item) {
+      item.table_options.multiselect = false;
+      if (!item.lookup_field) {    
+          var print_btn = item.add_view_button('Print', {image: 'icon-print'}),
+              email_btn = item.add_view_button('Send email', {image: 'icon-pencil'});
+          email_btn.click(function() { send_email() });
+          print_btn.click(function() { print(item) });
+          item.table_options.multiselect = true;
+      }
+  }  
+
+In this code the item's
+:doc:`lookup_field </refs/client/item/at_lookup_field>` 
+attribute is checkув and if it is defined (the view form is not created to select a 
+value for a lookup field) the two buttons are created and for them JQuery click 
+events are assigned to ``send_email`` and ``print`` functions declared in that 
+module.
+
+

docs/how to/export_import_csv_files.txt

@@ -0,0 +1,46 @@
+=======================================
+How to deploy project on PythonAnywhere
+=======================================
+
+* In Application Builder, set the **Persistent connection** attribute in the
+  :doc:`Project parameters </admin/project/parameters>`
+  to ``false``. 
+  
+  You can do this later in the Application Builder after deployment.
+  In this case, you must restart the server.
+
+* Use pip to install Jam.py. To do this, open the bash console and run the 
+  following command (for Python 3.7):
+
+  .. code-block:: console
+  
+    pip3.7 install --user jam.py
+  
+* Create a zip archive of your project folder, upload the archive in the **Files** 
+  tab and unzip it.
+  
+  We assume that you are registered as *username* and your project is now located 
+  in the */home/username/project_folder* directory.
+
+* Open the **Web** Tab. Add a new web app. In the Code section specify
+
+  * Source code: */home/username/project_folder*
+
+  * Working directory: */home/username/project_folder*
+
+  In the WSGI configuration file:/var/www/username_pythonanywhere_com_wsgi.py file
+  add the following code
+
+  .. code-block:: py
+
+    import os
+    import sys
+    
+    path = '/home/username/project_folder'
+    if path not in sys.path:
+        sys.path.append(path)
+    
+    from jam.wsgi import create_application
+    application = create_application(path)
+
+* Reload the server.

docs/how to/global_scripts.txt

@@ -0,0 +1,41 @@
+=================================
+how to execute script from client
+=================================
+
+
+You can use 
+:doc:`server </refs/client/abstr_item/m_server>`
+method to send a request to the server to execute a function defined in the 
+server module of an item.
+
+En the example below we create the ``btn`` button that is a JQuery object. 
+Then we use its click method to attach a function that calls the 
+:doc:`server </refs/client/abstr_item/m_server>`
+method of the item to run the ``calculate`` function defined in the server module
+of the item.
+
+The code in the client module:
+
+.. code-block:: js
+
+  function on_view_form_created(item) {
+      var btn = item.add_view_button('Calculate', {type: 'primary'});
+      btn.click(function() {
+          item.server('calulate', [1, 2, 3], function(result, error) {
+            if (error) {
+              item.alert_error(error);
+            }
+            else {
+              console.log(result);
+            }
+          })
+      });
+  }
+  
+
+The code in the server module:
+
+.. code-block:: py
+
+  def calculate(item, a, b, c):
+      return a + b + c

docs/how to/how_to_add_a_button_to_a_form.txt

@@ -0,0 +1,15 @@
+======
+How to
+======
+
+Here is a useful code that you can use in your applications:
+
+.. toctree::
+    :maxdepth: 2
+
+    global_scripts
+    how_to_add_a_button_to_a_form
+    how_to_execute_script_from_client
+    to_append_a_record_without_view_form
+    export_import_csv_files    
+    how_to_deploy_project_on_pythonanywhere