Updated internals doc-dc
authorDamien Correia
Fri, 21 Dec 2018 15:48:43 +0100
branchdoc-dc
changeset 140 df3106def670
parent 139 d632f8d6140b
child 141 9ab9f762abed
Updated internals
src/source/dev_guide/internals.rst
--- a/src/source/dev_guide/internals.rst	Fri Dec 21 15:20:06 2018 +0100
+++ b/src/source/dev_guide/internals.rst	Fri Dec 21 15:48:43 2018 +0100
@@ -194,7 +194,7 @@
 ^^^^^^^^^
 
 - oid
-	*oid*(value)
+	*oid*\(value)
 
 Return the **oid** of the value
 
@@ -230,7 +230,7 @@
 	- square
 
 [lg, md, sm, xs]*_width
-	[1-12] boostrat column size
+	[1-12] bootstrap column size
 
 css_class
 	add a css class to the container of this illustration (<picture>)
@@ -334,7 +334,8 @@
 
 For example:
 
-.. code-block::
+
+.. code-block:: genshi
 
 	<tal:var define="tales:need_resource('pyams_content.zmi:pyams_content')" />
 
@@ -360,3 +361,44 @@
 Search engines
 --------------
 
+.. _utilities:
+
+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.
+
+