Merge pull request #5 from do3cc/master

paster scripts and updated documentation

docs/index.txt

@@ -10,34 +10,78 @@ Welcome to pyramid_formalchemy's documentation!
 About
 =====
 
-``pyramid_formalchemy`` provide a CRUD interface for ``pyramid`` based on ``FormAlchemy``
+``pyramid_formalchemy`` provides a CRUD interface for ``pyramid`` based on ``FormAlchemy``
 
-It also allow to use ``FormAlchemy`` to render forms in your application.
+It also allows to use ``FormAlchemy`` to render forms in your application.
 
 Installation
 ============
 
-With easy_install::
+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 paster template. 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
+
+or with easy_install::
 
   $ easy_install pyramid_formalchemy
 
-It's also highly recommended to install fa.jquery to get a nicer interface::
+Only after that, the paster template 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 paster template. The provided
+template works well with pyramid_alchemy, pyramid_routesalchemy and
+akhet. To bootstrap an application, call paster like that::
 
-  $ easy_install fa.jquery
+  $ paster create -t akhet -t 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 fareadme.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::
+
+  $ paster create -t 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 line of configuration in the ``__init__.main()`` function 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 stuff like this:
+It's better to enable the jquery features like this:
 
 .. literalinclude:: ../pyramidapp/pyramidapp/jquery.py
    :pyobject: main
@@ -101,9 +145,9 @@ and per Model::
 Setting permissions
 ===================
 
-pyramid_formalchemy take care of some ``__acl__`` attributes.
+pyramid_formalchemy takes care of some ``__acl__`` attributes.
 
-Setting permissions for the globale interface
+Setting permissions for the global interface
 ---------------------------------------------
 
 You just need to subclass the default factory in your application:

pyramid_formalchemy/paster.py

@@ -0,0 +1,8 @@
+from tempita import paste_script_template_renderer
+from pyramid.paster import PyramidTemplate
+
+class PyramidFormAlchemyTemplate(PyramidTemplate):
+    _template_dir = ('pyramid_formalchemy', 'paster_templates/pyramid_fa')
+    summary = "Pyramid application template to extend other templates with "
+    "formalchemy"
+    template_renderer = staticmethod(paste_script_template_renderer)

pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faforms.py_tmpl

@@ -0,0 +1,8 @@
+from formalchemy import forms
+from formalchemy import tables
+
+class FieldSet(forms.FieldSet):
+    pass
+
+class Grid(tables.Grid):
+    pass

pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fainit.py_tmpl

@@ -0,0 +1,21 @@
+from {{package}} import models, faforms
+
+def includeme(config):
+    config.include('pyramid_formalchemy')
+    # Adding the jquery libraries
+    config.include('fa.jquery')
+    # Adding the package specific routes
+    config.include('{{package}}.faroutes')
+
+    try:
+        # pyramid_alchemy
+        session_factory = models.DBSession
+    except AttributeError:
+        # akhet
+        session_factory = models.Session
+
+    config.formalchemy_admin("/admin",
+                             models=models,
+                             forms=faforms,
+                             session_factory=session_factory,
+                             view="fa.jquery.pyramid.ModelView")

pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fareadme.txt

@@ -0,0 +1,23 @@
+This script does not want to tell you how your app should be set up.
+As such, it does not set an app up for you.
+
+Please use this template together with other templates, like akhet, 
+pyramid_routesalchemy or pyramid_alchemy.
+
+To finally include FormAlchemy, modify your main method were you
+create the wsgi application, and include {{package}}.fainit to the
+configuration, like that:
+
+    >>> config.include("{{package}}.fainit")
+
+If you are using pyramid_routesalchemy or pyramid_alchemy,
+you must modify the models.py. For FormAlchemy to be able to use the
+Model, the Model must have a constructer that can be called without
+any argument.
+So open up models.py and either remove the constructor of MyModel,
+or add default values.
+
+If you are using akhet, nothing special needs to be done.
+
+After this modifications, you should find the FormAlchemy Admin
+Interface under /admin

pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faroutes.py_tmpl

@@ -0,0 +1,19 @@
+from {{package}} import models
+def includeme(config):
+    try:
+        # pyramid_alchemy
+        session_factory = models.DBSession
+    except AttributeError:
+        # akhet
+        session_factory = models.Session
+
+    try:
+        # Example for pyramid_routesalchemy and akhet
+        from {{package}}.models import MyModel
+        config.formalchemy_model("/my_model", package='{{package}}',
+                                 model='{{package}}.models.MyModel',
+                                 session_factory=session_factory,
+                                 view='fa.jquery.pyramid.ModelView')
+    except ImportError:
+        pass
+    

setup.py

@@ -26,5 +26,9 @@ setup(name='pyramid_formalchemy',
       include_package_data=True,
       zip_safe=False,
       install_requires=requires,
+      entry_points = """
+[paste.paster_create_template]
+pyramid_fa = pyramid_formalchemy.paster:PyramidFormAlchemyTemplate
+"""
       )