Products: Utilizing the "Reference" Field to Combine two References into one Click Charge

Introduction to the "Reference" Field in shopVOX Products

The latest update to shopVOX introduces a powerful new feature for managing products: the "Reference" field. This field allows users to enter a specific value that can be accessed from various areas within the Product module, streamlining calculations and enhancing functionality.

Key Attributes: Width and Height

Materials in shopVOX are defined by two essential attributes: Width and Height. These attributes are stored in the variables svItem_sheet_width and svItem_sheet_height, respectively. When a material is selected from a dropdown menu, these variables are readily available for use in custom code blocks.

Accessing Width and Height in Custom Code Blocks

When constructing a product and creating a dropdown menu with material options, referencing the values of svItem_sheet_width and svItem_sheet_height in your custom code blocks is a straightforward process. For instance, if a user selects a material with a Width of 54 inches and a Height of 100 inches, the variables svItem_sheet_width and svItem_sheet_height will automatically reflect these chosen values. It's that simple and convenient!

Accessing Referenced Width and Height in Custom Code Blocks

The new "Reference" field allows for dynamic and flexible use of material dimensions when constructing a product and creating a dropdown menu with material options. Instead of directly referencing svItem_sheet_width and svItem_sheet_height, you can now use any name you choose for the reference field.

For example, if you set a reference named customRef, you can access the Width and Height values using customRef_sheet_width and customRef_sheet_height in your custom code blocks. If a user selects a material with a Width of 54 inches and a Height of 120 inches, the variables customRef_sheet_width and customRef_sheet_height will automatically reflect these chosen values.

This approach enables greater flexibility and customization in your product configurations, making it simple and convenient to perform calculations based on user selections. By utilizing the "Reference" field, you ensure that your custom code is both powerful and adaptable to various scenarios.

Initializing and Using Referenced Width and Height in Custom Code Blocks

When a user enters a reference name, the referenced variables are immediately initialized to have a value of zero. For example, customRef_sheet_width and customRef_sheet_height would start with an initial value of zero. This mechanism ensures that users do not need to make a selection from a dropdown menu to initialize the reference.

When a user does make a selection, the values of customRef_sheet_width and customRef_sheet_height are updated to reflect the dimensions of the selected material. This process replaces the initial zero values with the actual width and height values of the chosen material, allowing for accurate calculations and enhanced functionality within custom code blocks.

Best Practices for Using References in Custom Code Blocks

When using a reference, it is first essential to check if the reference has a zero value before performing any calculations. While there are instances where this may not be necessary, if your calculations involve dividing by the reference value and it is zero, you could encounter an infinity error in JavaScript.

To avoid this issue, it is best practice to test the reference values before proceeding with your calculations. 

For example, you can use the following condition: 

(customRef_sheet_width > 0 && customRef_sheet_height > 0) ? yourCustomCode : alternativeCode;. 

Replace yourCustomCode with your specific calculations and alternativeCode with what should happen if the reference values are zero.

This approach ensures that your code handles zero values properly, preventing errors and maintaining the integrity of your calculations.

Practical Application

This feature is incredibly convenient as it enables users to perform many calculations based on their selections. Whether you need to calculate the total material needed, optimize usage, or determine pricing, having direct access to these variables simplifies the process and ensures accuracy.

By leveraging the new "Reference" field and the predefined attributes of materials, shopVOX users can enhance their workflow and improve efficiency in product management.

Example Use Case: Calculating the Sum of Two Materials for a Printer Click Charge

Scenario:

You have a product that involves printing on two different materials, and you need to calculate the combined sheet count to calculate the click charge for a printer. This is where the "Reference" field in shopVOX comes in handy.

1. Go to Settings > Products > "+ Add New Product"

   

2. Fill in the details, I am using sample information, feel free to use your own
   1. Product Name: Product with Reference - Example
   2. Interface: Custom
   3. Choose a Type, Category, Income and Cost of Goods Account
   4. "Save Product"

   

3. Click "+Add Product Template"

   

4. Add Modifiers Width and Height

   

5. Add Drop Down Menu for Material 1, and fill in the details
   1. Menu Name: Material 1
   2. Item: Material
   3. Item Type: Digital Printing
   4. Item Category: Paper - Text
   5. Item Kind: Company Items
   6. System Formula: None
   7. Multiplier: 1
   8. Reference: material1Ref
   9. Custom Code Block:

      Math.ceil(svLineItem_qty/(Math.floor(svItem_sheet_width/Width)*Math.floor(svItem_sheet_height/Height)))

   

6. Add Drop Down Menu for Material 2, and fill in the details
   1. Menu Name: Material 2
   2. Item: Material
   3. Item Type: Digital Printing
   4. Item Category: Paper - Text
   5. Item Kind: Company Items
   6. System Formula: None
   7. Multiplier: 1
   8. Reference: material2Ref
   9. Custom Code Block:

      Math.ceil(svLineItem_qty/(Math.floor(svItem_sheet_width/Width)*Math.floor(svItem_sheet_height/Height)))

      

7. The Product Template should look like this so far

   

8. Add in a Default Item for the Click Charge
   1. Item Type: machine Rate
   2. Machine Rate: Click charge
   3. Formula: None
   4. Multiplier:1
   5. Custom Code Block:

      (material1Ref_sheet_width >0 && material1Ref_sheet_height >0 && material2Ref_sheet_width >0 && material2Ref_sheet_height >0)
      ?
      (Math.ceil(svLineItem_qty/(Math.floor(material1Ref_sheet_width/Width)*Math.floor(material1Ref_sheet_height/Height))))  +  (Math.ceil(svLineItem_qty/(Math.floor(material2Ref_sheet_width/Width)*Math.floor(material2Ref_sheet_height/Height))))
      :
      (material1Ref_sheet_width >0 && material1Ref_sheet_height >0)
      ?
      Math.ceil(svLineItem_qty/(Math.floor(material1Ref_sheet_width/Width)*Math.floor(material1Ref_sheet_height/Height)))
      :
      (material2Ref_sheet_width >0 && material2Ref_sheet_height >0)
      ?
      Math.ceil(svLineItem_qty/(Math.floor(material2Ref_sheet_width/Width)*Math.floor(material2Ref_sheet_height/Height)))
      :
      0
      ;

      

      1. This JavaScript code block is a nested conditional (ternary) operator that calculates a value based on the dimensions of two referenced materials and a specified quantity (svLineItem_qty). The purpose of the code is to determine the total number of items that can be produced from the given materials, considering their dimensions.
         
         First Condition Check: This checks if both materials (material1Ref and material2Ref) have valid dimensions and calculates if true
         Second Condition Check: If the first material has valid dimensions but the second does not, and calculates if true
         Third Condition True: If only the second material has valid dimensions, the code calculates the number of items that can be produced
         Else (Default) Case: If neither material has valid dimensions, the result is 0.
         
         This logic ensures that calculations are performed only with valid dimensions, avoiding potential errors or infinity results in JavaScript.
         
9. The Product Template should look like this

   

10. Time to test! Go to Check Pricing
    1. Quantity: 100
    2. Width: 5, Height :5
    3. Choose from Material 1 drop down
    4. Choose Material 2 drop down

       

    5. Click "Pricing Breakdown"

       

Example Scenario: Calculating Click Charges Using Material Drop Downs

With a quantity of 100 and a width and height of 5 inches each, the click charge is dynamically updated based on the selections made from Material Dropdown 1 and Material Dropdown 2. The calculations add the values from both dropdowns together if both are selected, or use the value from a single dropdown if only one is selected. If no selections are made, the result will be zero.

How it Works:

1. Both Materials Selected:
   • The click charge calculation includes the combined area of both selected materials.
2. One Material Selected:
   • The click charge calculation uses the area of the single selected material.
3. No Materials Selected:
   • The click charge defaults to zero.

This approach ensures accurate pricing based on the materials chosen, providing flexibility and precision in managing product configurations.

Reminder of Best Practices for Using References

Before performing calculations, it is crucial to check if the reference values are zero to avoid errors. Using conditional checks ensures that calculations are only performed with valid values, preventing infinity errors in JavaScript

Conclusion

The "Reference" field in shopVOX Products is a powerful tool that enhances product management by allowing dynamic and flexible use of material dimensions. By following best practices and utilizing this feature effectively, users can improve their workflow, accuracy, and efficiency in managing complex product configurations. The examples provided illustrate practical applications, highlighting the benefits and versatility of this new feature in shopVOX.