Add LilSnippets-AddBatchSupportForImporter

LilSnippets-AddBatchSupportForImporter.-.md

@@ -0,0 +1,43 @@
+# Add Batch Support for Importer
+
+This assumes you already have a working importer, and wish to add "dynamic batch" support to it.
+
+As usual, the word "import" is used generically; in some cases "export" might make more sense.
+
+Here are the specifics behind the example shown in these instructions:
+
+ * import command is: `rattail import-sample`
+ * import handler is at: `rattail.importing.sample:FromSampleToRattail`
+ * importer is identified by `'Product'` and is at: `rattail.importing.sample:ProductImporter`
+ * importer does not yet support dynamic batches
+
+## Declare Batch Support
+
+The first step is simple enough.  You just need to declare support within the importer's class.  (This is the 3rd bullet from above.)
+
+In our example we would edit the `ProductImporter` class within `~/src/rattail/rattail/importing/sample.py`:
+
+```python
+class ProductImporter(FromSample, importing.model.ProductImporter):
+
+    # must add this
+    batches_supported = True
+```
+
+## Make Things Pretty
+
+Each row within an import batch will have an "object description" which is displayed in the Tailbone UI for instance.  By default this description is basically `str(obj)` where `obj` is the source "object" being imported.  Many times that default object description is not very helpful or pretty, in which case you can override.  To do so you must add the `'_object_str'` field to the normalized data returned by your importer (3rd bullet from above).
+
+In our example we would edit the `normalize_host_object()` method of the `ProductImporter` class within `~/src/rattail/rattail/importing/sample.py`:
+
+```python
+class ProductImporter(FromSample, importing.model.ProductImporter):
+
+    def normalize_host_object(self, csvrow):
+        data = super(ProductImporter, self).normalize_host_object(csvrow)
+
+        # must add this
+        data['_object_str'] = "custom description for object: {}".format(csvrow)
+
+        return data
+```