Add LilSnippets-AddExecOptionsForBatch

LilSnippets-AddExecOptionsForBatch.-.md

@@ -0,0 +1,78 @@
+# Add Execution Options for a Batch
+
+This assumes you already have a batch (table, handler, master view), and population / execution works as expected, but you wish to provide user with some options at the execution step.
+
+## Batch Handler
+
+Ultimately the new execution options must be recognized and implemented by the batch handler, so that's our first step.
+
+Let's say we have a "pricing" batch handler and we want to let the user declare whether or not new labels should be deployed along with the new prices, and to which label printer if so.
+
+We might edit a class called `PricingBatchHandler` in a file like `~/src/poser/poser/batch/pricing.py`:
+
+```python
+from rattail.batch import pricing as base
+
+class PricingBatchHandler(base.PricingBatchHandler):
+
+    # must add new options to method signature
+    def execute(self, batch, deploy_labels=False, label_printer=None, progress=None, **kwargs):
+
+        # do whatever you normally do for execution here
+        self.deploy_prices(batch, progress=progress)
+
+        # check status of new option, and act accordingly
+        if deploy_labels:
+            self.deploy_labels(batch, label_printer, progress=progress)
+
+        return True
+
+    def deploy_labels(self, batch, label_printer, progress=None):
+
+        # must do something here
+        print("deploying labels to printer: %s" % label_printer)
+
+```
+
+## Batch Master View
+
+Now that the batch handler will honor the new execution options, we declare them for the UI, in the batch master view.
+
+Note that the important part, is that you define this "execution options schema" such that its nodes correspond to the options accepted by your batch handler's `execute()` method, i.e. per the above step.  They should match in both "name" and "data type".
+
+Here we might edit a class called `PricingBatchView` in a file like `~/src/poser/poser/web/views/batch/pricing.py`:
+
+```python
+import colander
+from tailbone import forms
+
+from tailbone.views.batch import pricing as base
+
+
+POSSIBLE_PRINTERS = {
+    'zebra001':         "Zebra #1",
+    'zebra002':         "Zebra #2",
+    'cognitive001':     "Cognitive #1",
+}
+
+
+# must add this; can call it whatever you like
+class ExecutionOptions(colander.Schema):
+
+    # NOTE: these schema nodes must correspond in both name and type,
+    # to the options accepted by handler's `execute()` method
+
+    deploy_labels = colander.SchemaNode(colander.Bool())
+
+    label_printer = colander.SchemaNode(
+        colander.String(),
+        validator=colander.OneOf(POSSIBLE_PRINTERS),
+        widget=forms.widgets.PlainSelectWidget(values=POSSIBLE_PRINTERS.items()))
+
+
+class PricingBatchView(base.PricingBatchView):
+
+    # must add this; should refer to schema defined above
+    execution_options_schema = ExecutionOptions
+
+```