.. _conf.calc.funcblocktemp:

==================================
Configure Function Block Templates
==================================

:term:`Function block templates<Function Block Template>` allow you to define reusable logic that can be applied across one or more flowsheets. This is especially useful when you anticipate that a particular function block will be used repeatedly.

When a function block template is updated, all flowsheets that reference it will automatically adopt the new logic.

.. note:: For templates already being used in flowsheets, the template changes are limited to equation updates. I/O pins cannot be added or removed.

To help organise your templates, you can group them into categories. These categories make it easier to locate and select the appropriate template within the Flowsheet Manager.

You can perform the following actions with function block templates:

- Create new templates
- Update existing templates
- Delete templates that are no longer needed
- Assign templates to categories

The steps for managing templates and categories are outlined below.


Create Function Block Templates
*******************************

1. Choose :menuselection:`Configuration --> Calculation --> Function Block Templates` from the menu.
2. On the **Function Block Templates** tab, click |add| **Add** on the toolbar.
3. In the **FB Template Configuration** dialog, enter data as follows:

   .. list-table:: 
      :widths: 1 5
      :header-rows: 1
      :class: tight-table

      * - Field
        - Description
      * - **Name**
        - Enter a name that uniquely identifies the function block template.
      * - **Description**
        - Provide additional information about the template's purpose.
      * - **Image**
        - You can add an image to the function block template, which will represent the function block in the flowsheet and will also appear next to the template in the Flowsheet Manager's Palette.
          
          First upload the image using the **Upload** button (if it hasn't been uploaded yet) and then select the image file from this field.
          
          For example, if you've uploaded a blue plus icon for the **AddTwo** function block template, it will appear in the Palette instead of the standard function block template icon:

          .. image:: images/conf.calc.fbtemplate.image.png
             :align: center
             :scale: 80%

      * - **Logic Type**
        - Select the logic engine that interprets the logic in the Expression field:
        
          - *mXparser*: for mathematical expressions using mXparser syntax.
          - *Python*: for logic written in Python.
          - *Thermo*: for thermodynamic-specific logic (if applicable).

          For more information about these logic engines, see :ref:`calculation.logics`.

      * - **Secure Equations**
        - Click this button to lock the expression and prevent unauthorised editing or viewing. Use this to protect sensitive or proprietary logic.
      * - **Expression**
        - Enter the logic for the function block using one or more equations. Each equation must be placed on a separate line. 
             
          If using mXparser logic, note the following:

          - Each equation must end with a semicolon (;).
          - You can include comment lines by prefixing them with //.
          - Any argument that matches a **pin name** or **parameter name** will use the corresponding pin I/O mapped value or parameter value.
          - Arguments that match a pin name with the suffix xQV will access or assign the quality of that pin.
          - Arguments that do not match any pin or parameter name will be treated as internal variables within the expression.
  
          For more information, see :ref:`calculation.logics.mxparser`.

      * - **Validate Equations**
        - Click this button to check the syntax and logic of the expression based on the selected Logic Type.

          - If the expression is valid, a green message confirms successful validation.
          - If there are errors, a red message appears with details to help correct the issue.

      * - **Equation Validated**
        - A system-controlled checkbox that is automatically checked when the expression passes validation. This provides a quick visual indicator of whether the logic has been successfully verified.

4. Save your entries.
5. Add pins to the function block template as required. If your expression contains variables, you have to create a pin for each:

   a. On the **Function Block Templates** tab, expand the details for the relevant template by clicking |add| at the start of the row. |one|
   b. On the **Pins** tab, at the top right side of the expanded view area, click |add| next to the *Search* box to add a new entry for input or output pins. |two|
   c. In the new row that is added, make the following entries:

      * **Type** field: Select IN or OUT to determine if the pin is an input or an output for the function block. |three|
      * **Pin Name**: Specify the variable that the pin represents in the expression. |four|
      * **Description**: Enter a description if required (optional).
  
   d. Click |saveblue| to save the new entry |five|.

   .. image:: images/conf.calc.fbtemplate.pins.png

6. Optionally, you can define parameters to use within the expression of a function block template. A parameter is a named variable with a constant value, such as a fixed number or unit. To create a parameter:
   
   a. On the **Function Block Templates** tab, expand the details of the relevant template by clicking |add| at the start of the row. |one|
   b. Go to the **Parameters** tab.
   c. At the top right side of the view area, click |add| next to the *Search* box to add a new entry. |two|
   d. In the new row, make the following entries |three|:

      * **Name** field: Enter a unique name for the parameter 
      * **Description**:  (Optional) Add a brief description of the parameter.
      * **Value**: Enter the constant value for the parameter. 
      * **Unit Type**: Select the appropriate unit type (for example, Area, Distance).
      * **Unit of Measure**: Choose the unit (for example, m², m, kg).
      * **Read Only**: Select this option if the parameter should not be modified during execution.
  
   e. Click |saveblue| to save the new entry |four|.

   Once defined, you can reference the parameter by name in the expression field. For example, if you define X1 as an area with a value of 5 m², you can use X1 in your logic, and it will be replaced with the defined value during calculation.

   .. image:: images/conf.calc.fbtemplate.parameter.png 

7. If required, you can validate the expression using the |tick| button in the **Action** column for the function block template.

   .. image:: images/conf.calc.fbtemplate.verify.png 

.. _conf.calc.funcblocktemp.update:

Update Function Block Templates
*******************************

To update the main attributes of a function block template:

1. On the **Function Block Templates** tab, click |edit| in the row of the relevant function block template.
2. In the **FB Template Configuration** dialog, update values as required.
3. Save your entries.

To update the pins or parameters of a function block template:

1. Ensure that the template is not in use in any flowsheets.
2. Expand the details of the relevant template by clicking the |add| icon at the start of the row.
3. Go to the **Pins** or **Parameters** tab as required.
4. Update the entries:

   - Click |edit| in the row of an item to update its values.
   - Click |delete| in the row of an item to delete it.



Delete Function Block Templates
*******************************

You can delete one or more function block templates as follows:

1. On the **Function Block Templates** tab, select one ore more rows using the selection icon at the start of the row. |one|
2. Click |delete| **Delete** on the toolbar of the tab. |two|
3. Confirm the deletion in the dialog that appears.

   .. image:: images/conf.calc.fbtemplate.delete.png 

Create Categories for Function Block Templates
**********************************************

You can group function block templates into categories to organise them more effectively and simplify selection in the Flowsheet Manager. To create a new category:

1. Choose :menuselection:`Configuration --> Calculation --> Function Block Templates` from the menu.
2. On the **Function Block Templates** pane, go to the **Categories** tab.
3. Click |add| **Add** on the toolbar.
4. Enter a name and a description in the **Category** dialog.
5. Save your entries.

   .. image:: images/conf.calc.fbtemplate.category.png 

Assign Function Block Templates to Categories
*********************************************

You can assign function block templates to categories in the Flowsheet Manager as follows:

1. Choose :menuselection:`Configuration --> Calculation --> Flowsheets` from the menu.
2. At the top of the pane, click **Configuration** to enter editing mode.
3. In the **Palettes** area on the left side of the **Flowsheet Manager**, right-click the function block template you want to assign.
   
   Templates that haven't been assigned to a category yet appear under the **UnAssigned** category.

4. From the context menu, select **Assign To** and choose the required category from the list of predefined options.
   
   For example, you want to assign the **MultiplyThree** function block template to the **Multiplication** category:


   .. image:: images/conf.calc.fbtemplate.category.assign.png 

|

..  admonition:: Result 

    The function block template gets added under the selected category:

    .. image:: images/conf.calc.fbtemplate.category.assign2.png 


.. |add| image:: images/icon.add.png

.. |edit| image:: images/icon.edit.png

.. |delete| image:: images/icon.delete.png

.. |one| image:: images/step_one.png
   :scale: 50%

.. |two| image:: images/step_two.png
   :scale: 50%

.. |three| image:: images/step_three.png
   :scale: 50%

.. |four| image:: images/step_four.png
   :scale: 50%

.. |five| image:: images/step_five.png
   :scale: 50%

.. |addblue| image:: images/icon.add.blue.png

.. |saveblue| image:: images/icon.save.blue.png

.. |tick| image:: images/icon.tick.png