diff --git a/docs/index.txt b/docs/index.txt index 97b03c8..8e28687 100644 --- a/docs/index.txt +++ b/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: diff --git a/pyramid_formalchemy/paster.py b/pyramid_formalchemy/paster.py new file mode 100644 index 0000000..40e9546 --- /dev/null +++ b/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) diff --git a/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faforms.py_tmpl b/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faforms.py_tmpl new file mode 100644 index 0000000..428e4b5 --- /dev/null +++ b/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 diff --git a/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fainit.py_tmpl b/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fainit.py_tmpl new file mode 100644 index 0000000..7388c96 --- /dev/null +++ b/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") diff --git a/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fareadme.txt b/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/fareadme.txt new file mode 100644 index 0000000..906ff90 --- /dev/null +++ b/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 diff --git a/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faroutes.py_tmpl b/pyramid_formalchemy/paster_templates/pyramid_fa/+package+/faroutes.py_tmpl new file mode 100644 index 0000000..46bc43c --- /dev/null +++ b/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 + diff --git a/setup.py b/setup.py index 5ca1adb..8e0c31f 100644 --- a/setup.py +++ b/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 +""" )