Merge pull request #140 from Guusggg/patch-1

Added a lot of information about context variables in reports

docs/report/build.md

@@ -17,8 +17,10 @@ In addition to the default report context variables, the following context varia
 
 | Variable | Description |
 | --- | --- |
-| build | The build object the report is being generated against |
+| build | The [Build](./context_variables.md#build) object the report is being generated against |
-| part | The part object that the build references |
+| part | The [Part](./context_variables.md#part) object that the build references |
 | reference | The build order reference string |
 | quantity | Build order quantity |
 
+
+

docs/report/context_variables.md

@@ -0,0 +1,226 @@
+---
+title: Context Variables
+---
+
+## Context Variables 
+
+### Report
+
+!!! info "Specific Report Context"
+    Specific report types may have additional context variables, see below.
+
+Each report has access to a number of context variables by default. The following context variables are provided to every report template:
+
+| Variable | Description |
+| --- | --- |
+| date | Current date, represented as a Python datetime.date object |
+| datetime | Current datetime, represented as a Python datetime object |
+| default_page_size | InvenTree default page size variable |
+| report_name | Name of the report template |
+| report_description | Description of the report template |
+| report_revision | Revision of the report template |
+| request | Django request object |
+| user | User who made the request to render the template |
+
+#### Build
+
+In addition to the default report context variables, the following context variables are made available to the build order report template for rendering:
+
+| Variable | Description |
+| --- | --- |
+| build | The [Build](./context_variables.md#build) object the report is being generated against |
+| part | The [Part](./context_variables.md#part) object that the build references |
+| reference | The build order reference string |
+| quantity | Build order quantity |
+
+#### Label
+
+Certain types of labels have different context variables then other labels.
+
+##### Stock Item Label
+
+The following variables are made available to the StockItem label template:
+
+| Variable | Description |
+| -------- | ----------- |
+| item | The [StockItem](./context_variables.md#stockitem) object itself |
+| part | The [Part](./context_variables.md#part) object which is referenced by the [StockItem](./context_variables.md#stockitem) object |
+| name | The `name` field of the associated Part object | 
+| ipn | The `IPN` field of the associated Part object |
+| revision | The `revision` field of the associated Part object |
+| quantity | The `quantity` field of the StockItem object |
+| serial | The `serial` field of the StockItem object |
+| uid | The `uid` field of the StockItem object |
+| tests | Dict object of TestResult data associated with the StockItem |
+| parameters | Dict object containing the parameters associated with the base Part |
+
+
+##### Stock Location Label
+
+The following variables are made available to the StockLocation label template:
+
+| Variable | Description |
+| -------- | ----------- |
+| location | The [StockLocation](./context_variables.md#stocklocation) object itself |
+
+### Parts
+
+!!! incomplete "TODO"
+    This section requires further work
+
+#### Part
+Each part object has access to a lot of context variables about the part. The following context variables are provided when accessing a `Part` object:
+
+| Variable | Description |
+|----------|-------------|
+| name | Brief name for this part |
+| full_name | Full name for this part (including IPN, if not null and including variant, if not null) |
+| variant | Optional variant number for this part - Must be unique for the part name
+| category | The [PartCategory](./context_variables.md#part-category) object to which this part belongs
+| description | Longer form description of the part
+| keywords | Optional keywords for improving part search results
+| IPN | Internal part number (optional)
+| revision | Part revision
+| is_template | If True, this part is a 'template' part
+| link | Link to an external page with more information about this part (e.g. internal Wiki)
+| image | Image of this part
+| default_location | The default [StockLocation](./context_variables.md#stocklocation) object where the item is normally stored (may be null)
+| default_supplier | The default [SupplierPart](./context_variables.md#supplierpart) which should be used to procure and stock this part
+| default_expiry | The default expiry duration for any StockItem instances of this part
+| minimum_stock | Minimum preferred quantity to keep in stock
+| units | Units of measure for this part (default='pcs')
+| salable | Can this part be sold to customers?
+| assembly | Can this part be build from other parts?
+| component | Can this part be used to make other parts?
+| purchaseable | Can this part be purchased from suppliers?
+| trackable | Trackable parts can have unique serial numbers assigned, etc, etc
+| active | Is this part active? Parts are deactivated instead of being deleted
+| virtual | Is this part "virtual"? e.g. a software product or similar
+| notes | Additional notes field for this part
+| creation_date | Date that this part was added to the database
+| creation_user | User who added this part to the database
+| responsible | User who is responsible for this part (optional)
+| starred | Wether the part is starred or not |
+| disabled | Wether the part is disabled or not |
+| total_stock | The total amount in stock |
+| quantity_being_built | The amount being built |
+| required_build_order_quantity | The amount required for build orders |
+| allocated_build_order_quantity | The amount allocated for build orders |
+| required_sales_order_quantity | The amount required for sales orders |
+| allocated_sales_order_quantity | The amount allocated for sales orders |
+| available | Wether the part is available or not | 
+| on_order | The amount that are on order |
+| required | The total amount required for build orders and sales orders |
+| allocated | The total amount allocated for build orders and sales orders |
+
+#### Part Category
+
+| Variable | Description |
+|----------|-------------|
+| name | Name of this category |
+| parent | Parent category |
+| default_location | Default [StockLocation](./context_variables.md#stocklocation) object for parts in this category or child categories |
+| default_keywords | Default keywords for parts created in this category |
+
+### Stock
+
+!!! incomplete "TODO"
+    This section requires further work
+
+#### StockItem
+
+| Variable | Description |
+|----------|-------------|
+| parent | Link to another [StockItem](./context_variables.md#stockitem) from which this StockItem was created |
+| uid | Field containing a unique-id which is mapped to a third-party identifier (e.g. a barcode) |
+| part | Link to the master abstract [Part](./context_variables.md#part) that this [StockItem](./context_variables.md#stockitem) is an instance of |
+| supplier_part | Link to a specific [SupplierPart](./context_variables.md#supplierpart) (optional) |
+| location | The [StockLocation](./context_variables.md#stocklocation) Where this [StockItem](./context_variables.md#stockitem) is located |
+| quantity | Number of stocked units |
+| batch | Batch number for this [StockItem](./context_variables.md#stockitem) |
+| serial | Unique serial number for this [StockItem](./context_variables.md#stockitem) |
+| link | Optional URL to link to external resource |
+| updated | Date that this stock item was last updated (auto) |
+| expiry_date | Expiry date of the [StockItem](./context_variables.md#stockitem) (optional) |
+| stocktake_date | Date of last stocktake for this item |
+| stocktake_user | User that performed the most recent stocktake |
+| review_needed | Flag if [StockItem](./context_variables.md#stockitem) needs review |
+| delete_on_deplete | If True, [StockItem](./context_variables.md#stockitem) will be deleted when the stock level gets to zero |
+| status | Status of this [StockItem](./context_variables.md#stockitem) (ref: InvenTree.status_codes.StockStatus) |
+| notes | Extra notes field |
+| build | Link to a Build (if this stock item was created from a build) |
+| is_building | Boolean field indicating if this stock item is currently being built (or is "in production") |
+| purchase_order | Link to a [PurchaseOrder](./context_variables.md#purchaseorder) (if this stock item was created from a PurchaseOrder) |
+| infinite | If True this [StockItem](./context_variables.md#stockitem) can never be exhausted |
+| sales_order | Link to a [SalesOrder](./context_variables.md#salesorder) object (if the StockItem has been assigned to a SalesOrder) |
+| purchase_price | The unit purchase price for this [StockItem](./context_variables.md#stockitem) - this is the unit price at time of purchase (if this item was purchased from an external supplier) |
+| packaging | Description of how the StockItem is packaged (e.g. "reel", "loose", "tape" etc) |
+
+#### StockLocation
+
+| Variable | Description |
+|----------|-------------|
+| barcode | Brief payload data (e.g. for labels) |
+| item_count | Simply returns the number of stock items in this location. | 
+
+### Suppliers
+
+!!! incomplete "TODO"
+    This section requires further work
+
+#### Supplier
+
+| Variable | Description |
+|----------|-------------|
+
+#### SupplierPart
+
+| Variable | Description |
+|----------|-------------|
+| part | Link to the master Part (Obsolete) |
+| source_item | The sourcing [StockItem](./context_variables.md#stockitem) linked to this [SupplierPart](./context_variables.md#supplierpart) instance |
+| supplier | [Supplier](./context_variables.md#supplier) that supplies this part | 
+| SKU | Stock keeping unit (supplier part number) | 
+| link | Link to external website for this supplier part | 
+| description | Descriptive notes field | 
+| note | Longer form note field | 
+| base_cost | Base charge added to order independent of quantity e.g. "Reeling Fee" |
+| multiple | Multiple that the part is provided in |
+| lead_time | Supplier lead time |
+| packaging | packaging that the part is supplied in, e.g. "Reel" |
+| pretty_name | The IPN, supplier name, supplier SKU and (if not null) manufacturer string joined by `|`. Ex. `P00037 | Company | 000021` |
+| unit_pricing | The price for one unit. |
+| price_breaks | Return the associated price breaks in the correct order |
+| has_price_breaks | Wether this [SupplierPart](./context_variables.md#supplierpart) has price breaks |
+| manufacturer_string | Format a MPN string for this [SupplierPart](./context_variables.md#supplierpart). Concatenates manufacture name and part number. |
+
+### Manufacturers
+
+!!! incomplete "TODO"
+    This section requires further work
+
+#### Manufacturer
+
+| Variable | Description |
+|----------|-------------|
+
+#### ManufacturerPart 
+
+| Variable | Description |
+|----------|-------------|
+
+
+### Orders
+
+!!! incomplete "TODO"
+    This section requires further work
+
+#### PurchaseOrder
+| Variable | Description |
+|----------|-------------|
+
+#### SalesOrder
+
+| Variable | Description |
+|----------|-------------|
+

docs/report/labels.md

@@ -98,6 +98,8 @@ Location Name: {{ location.name }}
 {% endraw %}
 ```
 
+Refer to the [context variables documentation](./context_variables.md).
+
 ### Barcodes
 
 Refer to the [barcode documentation](./barcodes.md).
@@ -214,8 +216,8 @@ The following variables are made available to the StockItem label template:
 
 | Variable | Description |
 | -------- | ----------- |
-| item | The StockItem object itself |
+| item | The [StockItem](./context_variables.md#stockitem) object itself |
-| part | The Part object which is referenced by the StockItem object |
+| part | The [Part](./context_variables.md#part) object which is referenced by the [StockItem](./context_variables.md#stockitem) object |
 | name | The `name` field of the associated Part object | 
 | ipn | The `IPN` field of the associated Part object |
 | revision | The `revision` field of the associated Part object |
@@ -259,7 +261,7 @@ The following variables are made available to the StockLocation label template:
 
 | Variable | Description |
 | -------- | ----------- |
-| location | The StockLocation object itself |
+| location | The [StockLocation](./context_variables.md#stocklocation) object itself |
 
 ## Part Labels
 
@@ -283,8 +285,8 @@ The following context variables are made available to the Part label template:
 
 | Variable | Description |
 | -------- | ----------- |
-| part | The part object |
+| part | The [Part](./context_variables.md#part) object |
-| category | The PartCategory which contains the Part |
+| category | The [Part Category](./context_variables.md#part-category) which contains the Part |
 | name | The name of the part |
 | description | The description text for the part |
 | IPN | Internal part number (IPN) for the part |
@@ -303,4 +305,4 @@ Part: {{ part.name }}
 Length: {{ parameters.length }}
 
 {% endraw %}
-```
+```

docs/report/report.md

@@ -50,21 +50,7 @@ For example, rendering the name of a part (which is available in the particular
 
 ### Context Data
 
-Each report has access to a number of context variables by default. The following context variables are provided to every report template:
+Please refer to the [Context variables](./context_variables.md) page.
-
-| Variable | Description |
-| --- | --- |
-| date | Current date, represented as a Python datetime.date object |
-| datetime | Current datetime, represented as a Python datetime object |
-| default_page_size | InvenTree default page size variable |
-| report_name | Name of the report template |
-| report_description | Description of the report template |
-| report_revision | Revision of the report template |
-| request | Django request object |
-| user | User who made the request to render the template |
-
-!!! info "Specific Report Context"
-    Specific report types may have additional context variables
 
 ### Conditional Rendering
 

docs/report/test.md

@@ -31,11 +31,11 @@ In addition to the default report context variables, the following context varia
 
 | Variable | Description |
 | --- | --- |
-| stock_item | The individual stock item for which this test report is being generated |
+| stock_item | The individual [StockItem](./context_variables.md#stockitem) object for which this test report is being generated |
-| part | The Part of which the stock_item is an instance |
+| part | The [Part](./context_variables.md#part) object of which the stock_item is an instance |
 | results | A dict of test result objects, where the 'key' for each test result is a shortened version of the test name (see below) |
 | result_list | A list of each test result object |
-| installed_items | A flattened list representing all `StockItem` objects which are *installed inside* the referenced `StockItem` object |
+| installed_items | A flattened list representing all [StockItem](./context_variables.md#stockitem) objects which are *installed inside* the referenced [StockItem](./context_variables.md#stockitem) object |
 
 #### Results
 
@@ -57,7 +57,7 @@ Uploaded by {{ results.firmwarechecksum.user }}{% endraw %}
 
 #### Installed Items
 
-The *installed_items* context variable is a list of all `StockItem` instances which are installed inside the `StockItem` referenced by the report template. Each `StockItem` can be dereferenced as follows:
+The *installed_items* context variable is a list of all [StockItem](./context_variables.md#stockitem) instances which are installed inside the [StockItem](./context_variables.md#stockitem) referenced by the report template. Each [StockItem](./context_variables.md#stockitem) can be dereferenced as follows:
 
 ```html
 {% raw %}
@@ -71,4 +71,4 @@ The *installed_items* context variable is a list of all `StockItem` instances wh
     {% endfor %}
 </table>
 {% endraw %}
-```
+```

mkdocs.yml

@@ -85,6 +85,7 @@ nav:
       - Build Order: report/build.md
       - Order: report/order.md
     - Barcodes: report/barcodes.md
+    - Context Variables: report/context_variables.md
   - Admin:
     - Admin Interface: admin/admin.md
     - User Permissions: admin/permissions.md
@@ -142,4 +143,4 @@ extra:
     property: UA-143467500-1
 
 use_directory_urls: true
-strict: true
+strict: true