rattail-manual/docs/data/batch/custom.rst

=====================
Adding a Custom Batch
=====================

If none of the native batch types fit your needs, you can always add a new one.
See :doc:`native` for the list of what's available.

Adding a new batch type involves 3 steps:

* add the batch table schema
* add the batch handler
* add web views for user interaction

For sake of example here, we'll define a "Please Come Back" batch.  The purpose
of this batch is to identify members who've not shopped in the store within the
last 6 months, and generate custom coupons for each, to encourage them to come
back.

Adding the batch table schema is not much different than adding any other table
to the DB; see also :doc:`/data/db/extend`.  Note that you should always prefix
table names with something unique to your app, and generally speaking the word
"batch" should go in there somewhere too.  For instance we might call them:

* ``poser_batch_plzcomeback``
* ``poser_batch_plzcomeback_row``

To add the batch tables, create a new Python module.  This would go in
``~/src/poser/poser/db/model/batch/plzcomeback.py`` for instance.  Within that
module you then define the batch table classes.  Be sure to also define the
``batch_key`` for the main table, which should also get the app-specific
prefix, e.g.::

   from rattail.db.model import Base, BatchMixin, BatchRowMixin

   class PleaseComeBack(BatchMixin, Base):
       __tablename__ = 'poser_batch_plzcomeback'
       __batchrow_class__ = 'PleaseComeBackRow'
       batch_key = 'poser_plzcomeback'
       model_title = "Please Come Back Batch"
       model_title_plural = "Please Come Back Batches"

   class PleaseComeBackRow(BatchRowMixin, Base):
       __tablename__ = 'poser_batch_plzcomeback_row'
       __batch_class__ = PleaseComeBack
       model_title = "Please Come Back Batch Row"

To add the batch handler, create a new Python module.  This would go in
``~/src/poser/poser/batch/plzcomeback.py`` for instance.  Within that module
you then define the batch handler class.  Be sure to tie this back to the main
batch table, e.g.::

   from rattail.batch import BatchHandler
   from poser.db import model

   class PleaseComeBackHandler(BatchHandler):
       batch_model_class = model.PleaseComeBack

To add the web views, also create a new Python module.  This one would go in
``~/src/poser/poser/web/views/batch/plzcomeback.py`` for instance.  Within that
module you then define the batch master view class.  Be sure to tie this back
to both the batch and row tables, as well as the handler, e.g.::

   from tailbone.views.batch import BatchMasterView
   from poser.db import model

   class PleaseComeBackView(BatchMasterView):
       model_class = model.PleaseComeBack
       model_row_class = model.PleaseComeBackRow
       default_handler_spec = 'poser.batch.plzcomeback:PleaseComeBackHandler'
       route_prefix = 'batch.poser_plzcomeback'
       url_prefix = '/batches/please-come-back'

   def includeme(config):
       PleaseComeBackView.defaults(config)