z3ext.formatter 1.4.2

Extensible TALES fomratter expression.

Detailed Dcoumentation
======================


===============
z3ext.formatter
===============

This package adds extensible tales expression for various formatters.
You can change formatter setting per site basis (z3ext.controlpanel).

For configure default settings, add following code to zope.conf


timezone UTC


Values for timezoneFormat are:
1: No timezone

We need register controlpanel configlet

>>> from zope.configuration import xmlconfig
>>> context = xmlconfig.string("""
... 
...    
...  
... """)

We'll try emulate 

>>> from zope.app.appsetup import product
>>> product._configs['z3ext.formatter'] = {
...   'timezone': u'UTC', 'timezoneFormat': '2', 'principalTimezone': 'true'}

Let's check this

>>> product.getProductConfiguration('z3ext.formatter')
{'timezone': u'UTC', 'timezoneFormat': '2', 'principalTimezone': 'true'}


Usually initFormatter() function is colled during IDatabaseOpenedEvent event,
we simply call it directly:

>>> from z3ext.formatter.config import initFormatter
>>> initFormatter(None)

Now we can get IFormatterConfiglet utility

>>> from zope.component import getUtility
>>> from z3ext.formatter.interfaces import IFormatterConfiglet

>>> configlet = getUtility(IFormatterConfiglet)

Setup request

>>> from zope import interface
>>> from zope.publisher.browser import TestRequest
>>> from zope.annotation.interfaces import IAttributeAnnotatable

>>> request = TestRequest(environ={'HTTP_ACCEPT_LANGUAGE': 'en'})
>>> interface.directlyProvides(request, IAttributeAnnotatable)

>>> from pytz import UTC
>>> from datetime import date, datetime, timedelta


DateTime formatter
------------------

>>> from z3ext.formatter.tests import ZPTPage
>>> page = ZPTPage()
>>> page.pt_edit(u'''
... 
...   
...     
...     
...     
...     
...     
...   
... ''', 'text/html')

>>> dt = datetime(2007, 1, 1, 0, 0, 0, tzinfo=UTC)
>>> dt
datetime.datetime(2007, 1, 1, 0, 0, tzinfo=)

By default we use UTC timezone for output:

>>> print page.render(request, now=dt)


01/01/07 12:00 AM
Jan 01, 2007 12:00:00 AM
January 01, 2007 12:00:00 AM +0000
Monday, January 01, 2007 12:00:00 AM UTC
Jan 01, 2007 12:00:00 AM




If datetime object doesn't contain timezone information, UTC is used

>>> print page.render(request, now=datetime(2007, 1, 1, 0, 0))


01/01/07 12:00 AM
Jan 01, 2007 12:00:00 AM
January 01, 2007 12:00:00 AM +0000
Monday, January 01, 2007 12:00:00 AM UTC
Jan 01, 2007 12:00:00 AM




Now let's chane timezone to US/Pacific, we change only time zone
not datetime value

>>> configlet.timezone = 'US/Pacific'

>>> print page.render(request, now=dt)


12/31/06 04:00 PM
Dec 31, 2006 04:00:00 PM
December 31, 2006 04:00:00 PM -0800
Sunday, December 31, 2006 04:00:00 PM PST
Dec 31, 2006 04:00:00 PM




fancyDatetime formatter
-----------------------

>>> now = datetime.now(UTC)

>>> fpage = ZPTPage()
>>> fpage.pt_edit(u'''
... 
...   
...     
...     
...     
...     
...   
... ''', 'text/html')

Today's datetime

>>> today = now - timedelta(hours=1)

>>> print fpage.render(request, now=today)


...



Yesterday's datetime

>>> yesterday = now - timedelta(hours=25)

>>> print fpage.render(request, now=yesterday)


...



Default timezone is UTC

>>> now = datetime.now(UTC)
>>> print fpage.render(request, now=now)


...



Date formatter
--------------

>>> datepage = ZPTPage()
>>> datepage.pt_edit(u'''
... 
...   
...     
...     
...   
... ''', 'text/html')

>>> d = date(2007, 1, 1)
>>> d
datetime.date(2007, 1, 1)

>>> print datepage.render(request, today=d)


Jan 01, 2007
01/01/07




Also you can get formatter from python code

>>> from z3ext.formatter.utils import getFormatter
>>> formatter = getFormatter(request, 'dateTime', 'full')
>>> formatter.format(dt)
u'Sunday, December 31, 2006 04:00:00 PM PST'

We will get FormatterNotDefined if formatter is unknown

>>> getFormatter(request, 'unknown')
Traceback (most recent call last):
...
FormatterNotDefined: ...

Wrong format, we should add path expression

>>> errpage = ZPTPage()
>>> errpage.pt_edit(u'''
...     ''', 'text/html')
>>> print errpage.render(request)
Traceback (most recent call last):
...
PTRuntimeError: ...

Unknown formatter

>>> errpage = ZPTPage()
>>> errpage.pt_edit(u'''
...     ''', 'text/html')
>>> print errpage.render(request)
Traceback (most recent call last):
...
FormatterNotDefined: unknown


Time formatter
--------------

>>> datepage = ZPTPage()
>>> datepage.pt_edit(u'''
... 
...   
...     
...     
...   
... ''', 'text/html')

>>> t = datetime(2007, 1, 1, 10, 34, 03)
>>> t
datetime.datetime(2007, 1, 1, 10, 34, 3)

>>> print datepage.render(request, time=t)


10:34:03 AM
10:34 AM




Custom formatter
================

We should define formatter factory and formatter itself
Let's implement formatter that accept string and currency name and
format as currency. Format of TALES expression whould be as
'formatter:,,,...:'
 is name of adapter that adapts IHTTPRequest to IFormatterFactory
also expression will pass  as args to factory.

>>> from z3ext.formatter.interfaces import IFormatter, IFormatterFactory

Here code of formatter:

>>> class MyFormatter(object):
...    interface.implements(IFormatter)
...
...    currencies = {'usd': '$', 'euro': 'Eur'}
...
...    def __init__(self, request, *args):
...       self.request = request
...       self.currency = self.currencies[args[0]]
...
...    def format(self, value):
...       return '%s %s'%(value, self.currency)

Now we need formatter factory:

>>> class MyFormatterFactory(object):
...    interface.implements(IFormatterFactory)
...
...    def __init__(self, request):
...        self.request = request
...
...    def __call__(self, *args, **kw):
...        return MyFormatter(self.request, *args)

Now we need register factory as named adapter for IHTTPRequest

>>> from zope.component import provideAdapter
>>> from zope.publisher.interfaces.http import IHTTPRequest

>>> provideAdapter(MyFormatterFactory, \
...   (IHTTPRequest,), IFormatterFactory, name='currency')

Now we can use formatter

>>> page = ZPTPage()
>>> page.pt_edit(u'''
... 
... 
... ''', 'text/html')

>>> print page.render(request)
121.04 $
121.04 Eur


humanDatetime formatter
-----------------------

>>> now = datetime.now(UTC)

>>> fpage = ZPTPage()
>>> fpage.pt_edit(u'''
... 
...   
...     
...     
...     
...     
...   
... ''', 'text/html')

Now datetime

>>> print fpage.render(request, now=now)


0 second(s) ago
0 second(s) ago
0 second(s) ago
0 second(s) ago



>>> today = now - timedelta(seconds=1)

>>> print fpage.render(request, now=today)


1 second(s) ago
1 second(s) ago
1 second(s) ago
1 second(s) ago



>>> today = now - timedelta(minutes=1)

>>> print fpage.render(request, now=today)


1 minute(s) ago
1 minute(s) ago
1 minute(s) ago
1 minute(s) ago



>>> today = now - timedelta(hours=1)

>>> print fpage.render(request, now=today)


1 hour(s) ago
1 hour(s) ago
1 hour(s) ago
1 hour(s) ago



>>> today = now - timedelta(days=1)

>>> print fpage.render(request, now=today)


1 day(s) ago
1 day(s) ago
1 day(s) ago
1 day(s) ago



>>> today = now - timedelta(days=7)

>>> print fpage.render(request, now=today)


1 week(s) ago
1 week(s) ago
1 week(s) ago
1 week(s) ago



>>> today = now - timedelta(days=30)

>>> print fpage.render(request, now=today)


1 month(s) ago
1 month(s) ago
1 month(s) ago
1 month(s) ago



>>> today = now - timedelta(days=367)

>>> print fpage.render(request, now=today)


1 year(s) ago
1 year(s) ago
1 year(s) ago
1 year(s) ago



Tomorrow's datetime

>>> today = now + timedelta(seconds=1)

>>> print fpage.render(request, now=today)


in 1 second(s)
in 1 second(s)
in 1 second(s)
in 1 second(s)



>>> today = now + timedelta(minutes=1)

>>> print fpage.render(request, now=today)


in 1 minute(s)
in 1 minute(s)
in 1 minute(s)
in 1 minute(s)



>>> today = now + timedelta(hours=1)

>>> print fpage.render(request, now=today)


in 1 hour(s)
in 1 hour(s)
in 1 hour(s)
in 1 hour(s)



>>> today = now + timedelta(days=1)

>>> print fpage.render(request, now=today)


in 1 day(s)
in 1 day(s)
in 1 day(s)
in 1 day(s)



>>> today = now + timedelta(days=7)

>>> print fpage.render(request, now=today)


in 1 week(s)
in 1 week(s)
in 1 week(s)
in 1 week(s)



>>> today = now + timedelta(days=30)

>>> print fpage.render(request, now=today)


in 1 month(s)
in 1 month(s)
in 1 month(s)
in 1 month(s)



>>> today = now + timedelta(days=365)

>>> print fpage.render(request, now=today)


in 1 year(s)
in 1 year(s)
in 1 year(s)
in 1 year(s)



=======
CHANGES
=======

1.4.2 (2009-11-09)
------------------

- Better 'fanctDatetime' js formatter


1.4.1 (2009-10-30)
------------------

- Added 'fancyDatetime' formatter js implementation

- Added `humandatetime` formatter js implementation


1.4.0 (2009-08-11)
------------------

- Predefine date,time,datetime formats, do not use locale formats

- Copyright holder changed


1.3.0 (2009-07-05)
------------------

- Added chameleon support

- Added 'formatter' chameleon expression


1.2.7 (2009-04-??)
------------------

- Do not use z3c.autoinclude


1.2.6 (2009-03-11)
------------------

- Added 'human' datetime formatter (XX minute(s) ago)

- Do not show seconds for fancyDatetime fomratter

- Fixed multple usage of one fancyDatetime formatter


1.2.5 (2008-11-23)
------------------

- z3ext.controlpanel is optional

- Added buildout for testing against zope3.4

1.2.4 (2008-10-21)
------------------

- Fixed russian translation

- nl translation updated


1.2.3 (2008-10-20)
------------------

- Added translations: nl, ru


1.2.2 (2008-10-10)
------------------

- Use new i18n domain z3ext.formatter


1.2.1 (2008-05-16)
------------------

- Replace 'autoinclude' with 'includeDependendcies'


1.2.0 (2008-03-25)
------------------

- Use z3c.autoinclude

- Code moved to svn.zope.org


1.1.2 (2008-03-06)
------------------

- Fixed bug in fancyDatetime formatter


1.1.1 (2008-02-05)
------------------

- Added 'Timezones' vocabulary

- Cleanup code


1.1.0 (2007-12-21)
------------------

- Added controlpanel configlet


1.0.0 (2007-12-07)
------------------

- Initial release.