docs/source/utilities.rst
changeset 74 d5fa9579f35d
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/source/utilities.rst	Fri Nov 18 16:52:36 2016 +0100
@@ -0,0 +1,57 @@
+.. _utilities:
+
+Custom PyAMS utilities
+======================
+
+PyAMS_utils provides a small set of utilities. You can create some of them as global utilities registered in
+the global components registry; other ones can be created manually by a site administrator and
+are then registered automatically.
+
+
+Server timezone
+---------------
+
+To manage timezones correctly, and display datetimes based on current server timezone, all datetimes should
+be defined and stored in UTC.
+
+PyAMS_utils provides a :py:class:`ServerTimezoneUtility <pyams_utils.timezone.utility.ServerTimezoneUtility>` which
+allows you to assign a default timezone to your server.
+
+To display a datetime with correct timezone, you can use the :py:func:`tztime <pyams_utils.timezone.tztime>` function,
+which assign server timezone to the given parameter:
+
+.. code-block:: python
+
+    from datetime import datetime
+    from pyams_utils.timezone import tztime
+
+    now = datetime.utcnow()
+    my_date = tztime(now)  # converts *now* to server timezone
+
+We could imagine that datetimes could be displayed with current user timezone. But it's quite impossible to know
+the user timazone from a server request. The only options are:
+
+- you ask an authenticated user to update a timezone setting in his profile
+
+- you can include Javascript libraries which will try to detect browser timezone from their computer configuration, and
+  do an AJAX request to update data in their session.
+
+That should require an update of :py:func:`tzinfo` adapter to get timezone info from session, request or user profile.
+
+
+ZEO connection
+--------------
+
+Several PyAMS utilities (like the tasks scheduler or the medias converter) are working with dedicated processes,
+are connected to main PyAMS process through ØMQ, and use ZEO connections for their PyAMS database access.
+
+Clients of these processes have to send settings of the ZEO connections that they should use.
+
+The ZEOConnection utility can be created by the site manager through the web management interface (ZMI) from the
+*Control panel*:
+
+.. image:: _static/zeo-add-menu.png
+
+ZEO connection creation form allows you to define all settings of a ZEO connection:
+
+.. image:: _static/zeo-add-form.png