.. pyramid_formalchemy documentation master file, created by
   sphinx-quickstart on Sat Jan 15 20:18:53 2011.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

===============================================
Welcome to pyramid_formalchemy's documentation!
===============================================

About
=====

``pyramid_formalchemy`` provides a CRUD interface for ``pyramid`` based on ``FormAlchemy``

It also allows to use ``FormAlchemy`` to render forms in your application.

Installation
============

pyramid_formalchemy must be a dependency of you application, so you
must add "pyramid_formalchemy" as a dependency in your setup.py under
install_requires. You must now update your environment, in case of
buildout, by running a new buildout. If you want nicer jquery
functionality also add a dependency for ``fa.jquery``.

pyramid_formalchemy also provides a pyramid scaffold. It can be used to
add a skeleton to an existing project or to create a new project. If you
create a new project, you must first install pyramid_formalchemy in
your python environment, either with pip::

  $ pip install pyramid_formalchemy pyramid_fanstatic fa.jquery

or with easy_install::

  $ easy_install pyramid_formalchemy pyramid_fanstatic fa.jquery

Only after that, the pyramid scaffold becomes available.
The template was made with the idea that it can be used to extend
existing applications. It does not create an app for you. For
bootstrapping your app, you need another pyramid scaffold. The provided
template works well with ``alchemy``, ``Akhet``. To bootstrap an application,
call paster like that::

  $ pcreate -s alchemy -s pyramid_fa myapp

Or for ``Akhet``::

  $ pcreate -s akhet -s pyramid_fa myapp

The application is created by akhet, akhet does not know about
pyramid_formalchemy, and pyramid_formalchemy cannot modify the app
configuration. So you have to do this by hand. First, you must add the
install dependency like explained earlier. Second, you must add the
following line in the main method
that returns the wsgi app, directly after Configurator has been
created (The example assumes that the Configurator instance is stored
under the name "config")::

  ...
  config.include('myapp.fainit')
  ...

More details are explained in ``myapp/README_FORMALCHEMY.txt``.
The process is the same for other templates. For the pyramid ones
there are additional changes necessary that are also explained in fareadme.txt

To add the minimum configuration to an existing application, you
should be able to run::

  $ pcreate -s pyramid_fa myapp

All files that paster creates are prefixed with fa, and should not
interfere with existing code. The other customizations described for
fresh applications are also valid for existing apps.

Basic usage
============

Add an empty ``forms.py`` module at the root of your project.

Now you just need to include two lines of configuration in the ``__init__.main()`` function of your project.
Here is the one used for testing:

.. literalinclude:: ../pyramidapp/pyramidapp/__init__.py

This will render the **basic** formalchemy interface.

It's better to enable the jquery features like this:

.. literalinclude:: ../pyramidapp/pyramidapp/jquery.py
   :pyobject: main


That's it. Now launch your app, browse ``/admin/`` and enjoy it !


About Models
=============

Here is a typical model to use full features of pyramid_formalchemy. Notice
that the fields are defined using :py:func:`formalchemy.Column`:

.. literalinclude:: ../../formalchemy_project/models.py
   :pyobject: User

See also :mod:`pyramid_formalchemy.actions` to customize form buttons per model.

Advanced usage
===============

Custom view, factory, forms
----------------------------

In the toward examples we just pass a ``package`` parameter to
:func:`~pyramid_formalchemy.configure`.  By default the function will try to
load ``package.models``, ``package.models.DBSession`` and ``package.forms`` but
you can override this. In this case you don't need to specify a package::


    config.formalchemy_admin(config,
                             forms='formalchemy_project.forms',
                             models='formalchemy_project.mymodels',
                             session_factory='formalchemy_project.session.Session',
                             )

You can also change the path ``prefix`` used. pyramid_formalchemy will use
``/admin/`` by default. See :func:`~pyramid_formalchemy.configure`.

Having fun with the query_factory parameter
-------------------------------------------

.. literalinclude:: ../../formalchemy_project/__init__.py
   :pyobject: main

Custom views per model
----------------------

You can also register custom CRUD views per ModelListing::


    config.formalchemy_model_view('admin',
                                  model='pyramidapp.models.Foo',
                                  context='pyramid_formalchemy.resources.ModelListing',
                                  renderer='templates/foolisting.pt',
                                  attr='listing',
                                  request_method='GET',
                                  permission='view')

and per Model::


    config.formalchemy_model_view('admin',
                                  model='pyramidapp.models.Foo',
                                  context='pyramid_formalchemy.resources.Model',
                                  name='',
                                  renderer='templates/fooshow.pt',
                                  attr='show',
                                  request_method='GET',
                                  permission='view')

Events
=======

pyramid_formalchemy got some hooks to help you to customize things. See :mod:`pyramid_formalchemy.events`.

Actions
=======

pyramid_formalchemy allow you to customize links and actions of your views. See :mod:`pyramid_formalchemy.actions`.

Setting permissions
===================

pyramid_formalchemy takes care of some ``__acl__`` attributes.

Setting permissions for the global interface
---------------------------------------------

You just need to subclass the default factory in your application:

.. literalinclude:: ../pyramidapp/pyramidapp/security.py

Setting permissions per model
-----------------------------

You can also add an ``__acl__`` attribute to your model class:

.. literalinclude:: ../pyramidapp/pyramidapp/models.py
   :pyobject: Bar

Api
===

.. toctree::
   :maxdepth: 2

   modules/index.txt

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`