add docs to BarcodeMixin

docs/docs/barcodes/internal.md

@@ -19,7 +19,7 @@ Some simple examples of this format are shown below:
 | Stock Location | `{% raw %}{"stocklocation": 1}{% endraw %}` |
 | Supplier Part | `{% raw %}{"supplierpart": 99}{% endraw %}` |
 
-The numerical ID value used is the _Primary Key_ (PK) of the particular object in the database.
+The numerical ID value used is the *Primary Key* (PK) of the particular object in the database.
 
 #### Downsides
 
@@ -27,7 +27,7 @@ The numerical ID value used is the _Primary Key_ (PK) of the particular object i
 2. The model name key has not a fixed length. Some model names are longer than others. E.g. a part QR code with the shortest possible id requires 11 chars, while a stock location QR code with the same id would already require 20 chars, which already requires QR code version 2 and quickly version 3.
 
 !!! info "QR code versions"
-    There are 40 different qr code versions from 1-40. They all can encode more data than the previous version, but require more "squares". E.g. a V1 QR codes has 21x21 "pixels" while a V2 already has 25x25. For more information see [QR code comparison](https://www.qrcode.com/en/about/version.html).
+    There are 40 different qr code versions from 1-40. They all can encode more data than the previous version, but require more "squares". E.g. a V1 QR codes has 21x21 "squares" while a V2 already has 25x25. For more information see [QR code comparison](https://www.qrcode.com/en/about/version.html).
 
 For a more detailed size analysis of the JSON-based QR codes refer to [this issue](https://github.com/inventree/InvenTree/issues/6612).
 
@@ -37,7 +37,9 @@ While JSON-based QR Codes encode all necessary information, they come with the d
 
 - `INV-` is a constant prefix. This is configurable in the InvenTree Barcode plugins settings per instance to support environments that use multiple instances.
 - `??` is a two character alphanumeric (`0-9A-Z  $%*+-./:` (45 chars)) code, individual to each model.
-- `x` the actual pk of the model. Now with an overhead of 6 chars for every model, this format supports the following amount of model instances using the described QR code modes:
+- `x` the actual pk of the model.
+
+Now with an overhead of 6 chars for every model, this format supports the following amount of model instances using the described QR code modes:
 
 | QR code mode | Alphanumeric mode | Mixed mode |
 | --- | --- | --- |

docs/docs/extend/plugins/barcode.md

@@ -4,7 +4,7 @@ title: Barcode Mixin
 
 ## Barcode Plugins
 
-InvenTree supports decoding of arbitrary barcode data via a **Barcode Plugin** interface. Barcode data POSTed to the `/api/barcode/` endpoint will be supplied to all loaded barcode plugins, and the first plugin to successfully interpret the barcode data will return a response to the client.
+InvenTree supports decoding of arbitrary barcode data and generation of internal barcode formats via a **Barcode Plugin** interface. Barcode data POSTed to the `/api/barcode/` endpoint will be supplied to all loaded barcode plugins, and the first plugin to successfully interpret the barcode data will return a response to the client.
 
 InvenTree can generate native QR codes to represent database objects (e.g. a single StockItem). This barcode can then be used to perform quick lookup of a stock item or location in the database. A client application (for example the InvenTree mobile app) scans a barcode, and sends the barcode data to the InvenTree server. The server then uses the **InvenTreeBarcodePlugin** (found at `src/backend/InvenTree/plugin/builtin/barcodes/inventree_barcode.py`) to decode the supplied barcode data.
 
@@ -26,7 +26,7 @@ POST {
 
 ### Builtin Plugin
 
-The InvenTree server includes a builtin barcode plugin which can decode QR codes generated by the server. This plugin is enabled by default.
+The InvenTree server includes a builtin barcode plugin which can generate and decode the QR codes. This plugin is enabled by default.
 
 ::: plugin.builtin.barcodes.inventree_barcode.InvenTreeInternalBarcodePlugin
     options:
@@ -39,14 +39,12 @@ The InvenTree server includes a builtin barcode plugin which can decode QR codes
 
 ### Example Plugin
 
-Please find below a very simple example that is executed each time a barcode is scanned.
+Please find below a very simple example that is used to return a part if the barcode starts with `PART-`
 
 ```python
-from django.utils.translation import gettext_lazy as _
-
-from InvenTree.models import InvenTreeBarcodeMixin
 from plugin import InvenTreePlugin
 from plugin.mixins import BarcodeMixin
+from part.models import Part
 
 class InvenTreeBarcodePlugin(BarcodeMixin, InvenTreePlugin):
 
@@ -56,16 +54,39 @@ class InvenTreeBarcodePlugin(BarcodeMixin, InvenTreePlugin):
     VERSION = "0.0.1"
     AUTHOR = "Michael"
 
-    status = 0
-
     def scan(self, barcode_data):
+        if barcode_data.startswith("PART-"):
+            try:
+                pk = int(barcode_data.split("PART-")[1])
+                instance = Part.objects.get(pk=pk)
+                label = Part.barcode_model_type()
 
-        self.status = self.status+1
-        print('Started barcode plugin', self.status)
-        print(barcode_data)
-        response = {}
-        return response
-
+                return {label: instance.format_matched_response()}
+            except Part.DoesNotExist:
+                pass
 ```
 
 To try it just copy the file to src/InvenTree/plugins and restart the server. Open the scan barcode window and start to scan codes or type in text manually. Each time the timeout is hit the plugin will execute and printout the result. The timeout can be changed in `Settings->Barcode Support->Barcode Input Delay`.
+
+### Custom Internal Format
+
+To implement a custom internal barcode format, the `generate(...)` method from the Barcode Mixin needs to be overridden. Then the plugin can be selected at `System Settings > Barcodes > Barcode Generation Plugin`.
+
+```python
+from InvenTree.models import InvenTreeBarcodeMixin
+from plugin import InvenTreePlugin
+from plugin.mixins import BarcodeMixin
+
+class InvenTreeBarcodePlugin(BarcodeMixin, InvenTreePlugin):
+    NAME = "MyInternalBarcode"
+    TITLE = "My Internal Barcodes"
+    DESCRIPTION = "support for custom internal barcodes"
+    VERSION = "0.0.1"
+    AUTHOR = "InvenTree contributors"
+
+    def generate(self, model_instance: InvenTreeBarcodeMixin):
+        return f'{model_instance.barcode_model_type()}: {model_instance.pk}'
+```
+
+!!! info "Scanning implementation required"
+    The parsing of the custom format needs to be implemented too, so that the scanning of the generated QR codes resolves to the correct part.