Common Objects
==============

You may import all common objects under the ``web2py_utils.utils`` namespace::

    from web2py_utils import utils
    # or
    from web2py_utils.utils import *

STRFTIME
--------

This is a dictionary object that includes commonly used strftime formats in 
a human readable format.

Usage::

    {{= request.now.strftime(web2py_utils.STRFTIME['time_date']) }}

Available formatters:

============    ===================     =======
Key             Format                  Example
============    ===================     =======
time_date       %I:%M %p %d-%m-%Y       01:03 AM 28-04-2010
============    ===================     =======

gURL
----

A replacement for the web2py global URL helper. This will remove the request
object so that you do not have to keep passing it everytime you call URL.

Place the following code in a model file.

Usage::

    URL = web2py_utils.utils.gURL(request)

    >>> print URL(f='hello')
    /welcome/default/hello

LayoutManager
-------------

A class to manage layouts. This will allow for hot-swappable layouts in any app.

It provides methods for getting static files, and templates from a layout, as well
as overriding default views if they exist.

Usage::

    layout = LayoutManager(request, response, URL, '<layout_name>',
                     base='layout.html',
                     autooverride=True)


    >>> layout = LayoutManager(request, response, URL, 'admin')
    >>> layout.template('index.html')
    layouts/admin/index.html
    >>> layout.template('hello/world.html')
    layouts/admin/hello/world.html
    >>> layout.static('img/logo.png')
    welcome/static/layouts/admin/img/logo.png
    >>> layout()
    layouts/admin/layout.html

    >>> layout = LayoutManager(request, response, URL)
    >>> layout.template('index.html')
    index.html
    >>> layout.template('hello/world.html')
    hello/world.html
    >>> layout.static('img/logo.png')
    welcome/static/img/logo.png
    >>> layout()
    layout.html

    

If autooverride is set, it will replace response.view if you have a view that matches
in the layout.

In your views, replace ``{{extend "layout.html"}}`` with::

    {{extend layout()}}

AdminManager
------------

TODO

BUTTON
------

A button helper. Use like you would use any other web2py helper

CONFIRM_BOX
-----------

A simple interface for a form confirmation, if yes is pressed it will execute the
``func_yes``, or if no, ``func_no``.

w
-

SQL Like wrapper. Converts text to lower and wraps with wildcards.

Usage::

    >>> web2py_utils.utils.w("Hello World")
    "%hello world%"

ws
--

SQL Like wrapper, however this takes a string with spaces, and replaces it with
wildcards

Usage::

    >>> web2py_utils.utils.ws("Hello World")
    "%hello%world%

decode_phone
------------

Takes a string, and converts it to only numbers 0-9.

Usage::

    >>> web2py_utils.utils.decode_phone('(512) 587-1234')
    5125871234

encode_phone
------------

Usage::

    >>> web2py_utils.utils.encode_phone('5125871234')
    (512) 587-1234

generate_uuid
-------------

Generates a unique identifer for the record.
This is used so that the record can be identified
without the record id being exposed.

Usage::

    >>> me = db.person[myid]
    >>> web2py_utils.utils.generate_uuid(me, digest_alg='sha512')
    <insert hashed value here>

only
----

Make sure that the exposed action always returns the ``what`` data

This is a function decorator.

Usage::

    # This will set request.extension to .json
    # and set the response.view to
    # generic.json
    >>> @web2py_utils.utils.only('json', request, response)
    >>> def get_dogs():
    >>>    return dict(dogs=db().select(db.dogs.ALL))

    # This will set the request.extension to .xml
    # and set the response.view to
    # custom.xml
    >>> @web2py_utils.utils.only('xml', request, response, template='custom')
    >>> def get_dogs():
    >>>    return dict(dogs=db().select(db.dogs.ALL))

As a convenience, a wrapper function is provided so that you do not have
to pass request and response objects every time you decorate a function.

In a model, place the following code.

    >>> only = web2py_utils.utils.only_wrapper(request, response)

Now we can use this object much simpler.

    # This will set the request.extension to .json
    # and set the response.view to
    # jsontemplates/default.json
    >>> @only('json', template='jsontemplates/default')
    >>> def get_dogs():
    >>>    return dict(dogs=db().select(db.dogs.ALL))