Better docs and an example for DatetimeCol (#101)

README.md

@@ -221,17 +221,36 @@ with the `na_display` argument.
 More about `DateCol`
 --------------------
 
+[Requires Babel configuration](#babel-configuration)
+
 Formats a date from the item. Can specify a `date_format` to use,
 which defaults to `'short'`, which is passed to
 `babel.dates.format_date`.
 
 More about `DatetimeCol`
 ------------------------
 
+[Requires Babel configuration](#babel-configuration)
+
 Formats a datetime from the item. Can specify a `datetime_format` to
 use, which defaults to `'short'`, which is passed to
 `babel.dates.format_datetime`.
 
+Babel configuration
+-------------------
+
+Babel uses a locale to determine how to format dates. It falls back to
+using environment variables (`LC_TIME`, `LANGUAGE`, `LC_ALL`,
+`LC_CTYPE`, `LANG`), or can be configured
+[within Flask](https://pythonhosted.org/Flask-Babel/#configuration),
+allowing dynamic selection of locale.
+
+Make sure that one of the following is true:
+
+- at least one of the above environment variables is set to a valid locale
+- `BABEL_DEFAULT_LOCALE` is set as config on the Flask app to a valid locale
+- a `@babel.localeselector` function is configured
+
 More about `LinkCol`
 --------------------
 

examples/datetimecol.py

@@ -0,0 +1,38 @@
+import os
+from datetime import datetime
+
+from flask_table import Table, Col, DatetimeCol
+
+# Run this example with LC_TIME=[other locale] to use a different
+# locale's datetime formatting, eg:
+#
+# LC_TIME=en_US python examples/datetimecol.py
+# or
+# LC_TIME=en_GB python examples/datetimecol.py
+os.environ.setdefault('LC_TIME', 'en_GB')
+
+
+class Item(object):
+    def __init__(self, name, dt):
+        self.name = name
+        self.dt = dt
+
+
+class ItemTable(Table):
+    name = Col('Name')
+    dt = DatetimeCol('Datetime')
+
+
+def main():
+    items = [
+        Item('Name1', datetime.now()),
+        Item('Name2', datetime(2018, 1, 1, 12, 34, 56)),
+    ]
+
+    table = ItemTable(items)
+
+    # or {{ table }} in jinja
+    print(table.__html__())
+
+if __name__ == '__main__':
+    main()