Niagara PRO TIPS: PX Includes - Part 1

Niagara PRO TIPS: PX Includes - Part 1

Video Tutorial: Niagara PRO TIPS: PX Includes - Part 1

Overview

This guide covers the basics of PX includes in Niagara 4, including how to create reusable PX components and how to use variables in PX includes for powerful, efficient graphics development. Part 1 focuses on fundamentals and variable substitution techniques.

What are PX Includes?

PX Includes are reusable PX files that can be embedded into other PX files as single widgets. They allow you to:

• Create common UI components once and reuse them across multiple graphics

• Maintain consistency across all PX views

• Reduce engineering time and effort

• Minimize errors from repetitive manual configuration

• Update content in one place and have it apply everywhere

Basic PX Include Concepts

File Organization

Best Practice: Create an includes folder in your PX directory to organize PX include files.

Station Structure:
└── px/
    ├── includes/
    │   ├── header.px
    │   ├── zone_detail.px
    │   ├── table_header.px
    │   └── odd_row.px
    ├── equipment_schedule.px
    └── floor_plan.px

Designing PX Include Files

When creating a PX file intended for use as an include, consider these design principles:

1. Use Canvas Pane as Root Element

Important: The root element should be a canvas pane, not a scroll pane.

Why?

• PX includes are embedded as widgets in other files

• Canvas panes provide fixed sizing and positioning

• Scroll panes add unnecessary complexity when embedded

2. Configure Scaling Settings

Recommended Setting: Set scaling to None

How to Configure:

1. Select the canvas pane

2. Look at canvas pane settings

3. Set scaling to None

Why?

• The parent PX file will handle scaling

• Prevents double-scaling issues

• Maintains predictable sizing

3. Size Appropriately

Set your canvas pane size to exactly what's needed for the content:

• Not too large (wasted space)

• Not too small (content won't fit)

• Just right for the widgets you're including

Method 1: Simple PX Includes (No Variables)

Use Case: Common Headers and Navigation

Common elements you might include on all PX views:

• Weather information

• Hyperlinks to alarm console

• Hyperlinks to history views

• Web chart views

• Company logos

• Theme and general design elements

Creating a Simple PX Include

Step 1: Create the Include File

1. Navigate to px/includes/ folder

2. Create new PX file (e.g., header.px)

3. Design your content with labels, widgets, etc.

Step 2: Configure the Canvas

1. Ensure root element is a canvas pane

2. Set scaling to None

3. Size canvas to fit content

Step 3: Add Your Content

Add whatever widgets you want:

• Labels with static text

• Hyperlinks

• Images/logos

• Weather widgets

• Navigation elements

Using a Simple PX Include

Step 1: Open Target PX File

Open the PX file where you want to embed the include (e.g., equipment_schedule.px)

Typical Structure:

Scroll Pane
└── Canvas Pane
    └── (Your content here)

Step 2: Drag and Drop

1. From the station tree, locate your include file (e.g., px/includes/header.px)

2. Drag and drop it onto your target PX file

3. This creates a PX Include Widget

Step 3: Position the Widget

• The entire include appears as one item in the target PX file

• Everything moves together as a unit

• Easy to position consistently

Benefits of Simple PX Includes

✅ Consistency - All individual labels/widgets from source appear as one unit
✅ Easy Positioning - Move entire include as single item
✅ No Wiggling - Components stay together, don't shift around
✅ Single Source - Edit include file, changes appear on all pages using it
✅ Time Savings - Reduces engineering time significantly
✅ Consistent Graphics - Same look and feel across entire site

Method 2: PX Includes with Variables

Understanding the Challenge

Consider a floor plan graphic with multiple zones. Each zone label might have:

• Bound Label Binding - Absolute ORD to equipment (e.g., air handler)

• Hyperlink Property - Relative ORD to equipment graphic

• Spectrum Binding - ORD to point for background color animation

• Spectrum Set Point Binding - ORD for set point animation

Problem:

• Zone 1 Label: 4 bindings = 4 ORDs to configure

• Zone 1 Equipment Label: 2 bindings = 2 ORDs to configure

• Total: 6 ORDs per zone

• 10 Zones: 60 ORDs to manually configure!

Solution: PX Includes with Variables

Example: Floor Plan Zone Details

The Problem Scenario

Two Labels per Zone:

Equipment Label (e.g., "AHU-01"):

• Bound Label Binding: Absolute slot path to air handler

• Hyperlink: Relative hyperlink to graphic detail

Room Temp Label:

• Label Binding: ORD to room temperature point

• Hyperlink: ORD to area

• Spectrum Binding: ORD to room temp (animates background color)

• Spectrum Set Point Binding: ORD (animates set point of spectrum)

Total ORDs to Configure:

• Equipment Label: 2 ORDs

• Room Temp Label: 4 ORDs

• Total per Zone: 6 ORDs

Creating a PX Include with Variables

Step 1: Create New PX File

1. Navigate to px/includes/ folder

2. Create new PX file (e.g., zone_detail.px)

Step 2: Configure Canvas Pane

1. Replace scroll pane with canvas pane:

   • Cut canvas pane

   • Delete scroll pane

   • Paste canvas pane back as root

2. Set scaling to None

3. Set canvas size to fit content:

   • Example: Width = 90, Height = 60

   • Just large enough to hold your widgets

Step 3: Copy Widgets from Original

1. Open your floor plan graphic

2. Select and copy the zone labels you want to template

3. Return to your zone_detail.px include file

4. Paste the widgets

Result: Widgets with existing ORDs (mixture of relative and absolute)

Converting ORDs to Variables

Understanding Variable Syntax

Variable Format:

$(VariableName)/remaining/path

Components:

• $ - Dollar sign (indicates variable)

• (VariableName) - Variable name in parentheses (arbitrary name you choose)

• /remaining/path - Additional ORD path beyond the base component (if needed)

Conversion Rules

Rule 1: Base Component Replacement

Original ORD:

station:|slot:/Drivers/BacnetNetwork/AH_01

Variable ORD:

$(zone)

Explanation: The entire absolute slot path to the base component is replaced with the variable.

Rule 2: Base Component + Additional Path

Original ORD:

station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTemp

Variable ORD:

$(zone)/points/RoomTemp

Explanation: Base component replaced by variable, additional path remains.

Rule 3: Relative ORD Conversion

Original Relative ORD:

slot:AH_01/graphic/detail

Variable ORD:

$(device)/graphic/detail

Explanation: The slot reference that resolves to the parameter device is replaced with the variable.

Important: Forward Slash Handling

⚠️ Critical Detail:

When appending additional path to a variable, keep the leading forward slash:

Correct:

$(room_temp)/points/RoomTemp
                ↑
         Keep the slash!

Why?
Because you're appending to the substituted ORD, the leading slash is necessary.

Contrast with Relative ORDs:

slot:points/RoomTemp
     ↑
No leading slash (relative syntax)

Step-by-Step Variable Conversion Example

Equipment Label Bindings

Binding 1: Bound Label Binding

Original:

station:|slot:/Drivers/BacnetNetwork/AH_01

Variable Conversion:

$(zone)

Binding 2: Hyperlink Property

Original:

slot:AH_01/graphic/detail

Variable Conversion:

$(equip)/graphic/detail

Room Temp Label Bindings

Binding 1: Label Binding

Original:

station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTemp

Variable Conversion:

$(room_temp)/points/RoomTemp

Binding 2: Hyperlink

Original:

slot:AH_01/area

Variable Conversion:

$(peanut_butter)/area

(Yes, you can use arbitrary names like "peanut_butter"!)

Binding 3: Spectrum Binding

Original:

station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTemp

Variable Conversion:

$(jelly)/points/RoomTemp

(Variable names are completely arbitrary)

Binding 4: Spectrum Set Point Binding

Original:

station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTempSP

Variable Conversion:

$(zone)/points/RoomTempSP

Variable Naming Best Practices

Arbitrary But Meaningful

You Can Use:

• $(zone)

• $(device)

• $(equipment)

• $(room_temp)

• $(peanut_butter) ← Valid but not recommended!

• $(jelly) ← Valid but not recommended!

Recommended Practice

Use the same variable name for all bindings that share the same base component:

All bindings using same base equipment:
- $(zone)
- $(zone)
- $(zone)
- $(zone)

Result: Only ONE variable to bind when using the include!

In the tutorial example, different variable names are used to emphasize the concept, but in practice, use consistent naming.

Using PX Includes with Variables

Step 1: Select Base Components

Instead of dragging the PX include file directly:

1. Navigate to the component tree

2. Select the base component(s) you want to bind to

   • Example: Select multiple air handlers

   • Can select single or multiple components

Step 2: Drag and Drop onto PX Editor

1. Drag the selected component(s) onto your PX editor

2. The Make Widget Wizard appears

Step 3: Choose "Include PX File"

1. In the Make Widget Wizard, select "Include px file"

2. Browse to your include file (e.g., zone_detail.px)

3. Click to select it

Step 4: Bind Variables (The Magic!)

PX File Variables Section:

• The wizard displays "Select px file variables define"

• Shows all variables defined in your source PX file

• Each variable from your include appears in the list

Example Variables Shown:

- $(zone)
- $(equip)
- $(room_temp)
- $(peanut_butter)
- $(jelly)

If You Used Consistent Naming:

- $(zone)  ← Only one variable!

Step 5: Select Variables to Bind

Option A: Bind All (Typical)

• Multi-select all variables

• All will map to the same base component you dragged

Option B: Selective Binding

• Choose only specific variables

• Useful for advanced scenarios

Step 6: Click OK

Result:

• PX include widgets are created

• All widgets move together as one unit

• Variables automatically bound to your selected component(s)

Viewing Variable Bindings

After creating PX includes with variables:

1. Select a PX include widget

2. Look at Properties

3. Find the Variables property

What You'll See:

Variables Property Explanation:

• Left Side: Variable names from source file

• Right Side: What they resolved to (absolute ORDs)

Example:

Variable Mapping:
$(zone) → station:|slot:/Drivers/BacnetNetwork/AH_01
$(zone)/points/RoomTemp → station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTemp
$(zone)/points/RoomTempSP → station:|slot:/Drivers/BacnetNetwork/AH_01/points/RoomTempSP

When No Additional Path:

• Just the base component

• Variable = Base ORD

When Additional Path Specified:

• Base component + remaining path

• Variable gets substituted, remainder appended

Benefits of PX Includes with Variables

Time Savings

Without Variables:

• Zone 1: Manually configure 6 ORDs

• Zone 2: Manually configure 6 ORDs

• Zone 10: Manually configure 6 ORDs

• Total: 60 ORDs to configure manually

With Variables:

• Drag 10 components at once

• Select PX include file

• Bind variables (one click)

• Done!

Error Reduction

✅ Eliminates "fat finger" errors - No manual ORD typing
✅ Consistency - All zones use same template
✅ No typos - Automatic substitution
✅ No missing bindings - Template includes everything

Efficiency

✅ Faster deployment - Drag and drop vs. manual configuration
✅ Rapid changes - Update include file, affects all instances
✅ Scalability - Works for 10 zones or 100 zones

Use Case 2: Equipment Schedule Tables

The Challenge

Building equipment schedule tables with traditional approaches:

• Component Grids: Good, but limited design flexibility

• VE Grids: Good, but limited design flexibility

• Manual Labels: Maximum flexibility, but tedious to configure

Solution: PX Includes with variables for table rows!

Equipment Schedule Design

Component Structure

Table Header (Include #1):

• File: table_header.px

• Canvas pane sized to fit column headers

• Contains labels with static text

• Column headers for: Equipment Name, Status, Temperature, Setpoint, etc.

Odd Row (Include #2):

• File: odd_row.px

• Canvas pane sized to fit one row

• Contains bound labels with variable ORDs

• All labels use $(zone) variable

• Light background color

Even Row (Include #3):

• File: even_row.px

• Identical to odd row (labels, bindings, size)

• Only difference: Slightly different background color

• Provides alternating row appearance

Creating Equipment Schedule Table

Step 1: Add Table Header

1. Open equipment schedule PX file

2. Drag table_header.px include

3. Drop at top of page

4. Position as column headers

Result: Static header row with column titles

Step 2: Add Equipment Rows

1. From component tree, select all air handlers

2. Drag onto PX editor

3. Make Widget Wizard → Include px file

4. Select odd_row.px

5. Bind variable: $(zone) → Selected air handlers

6. Click OK

Result: Multiple PX include widgets, one per air handler

Step 3: Alternate Row Colors (Optional)

For better visual appearance:

1. Select even-numbered PX includes (2nd, 4th, 6th, etc.)

2. Look at properties

3. Find Include property (points to actual PX file)

4. Change from odd_row.px to even_row.px

Result: Alternating row colors in your table!

Equipment Schedule Configuration

Each Row's Bound Labels

All labels in odd_row.px use variable ORDs:

$(zone) → Base air handler
$(zone)/points/Status → Equipment status
$(zone)/points/RoomTemp → Current temperature
$(zone)/points/RoomTempSP → Temperature setpoint
$(zone)/points/FanStatus → Fan status
... etc.

Key Point: One variable ($(zone)) used throughout = one binding operation!

Benefits for Equipment Schedules

✅ Design Flexibility - Full control over layout, colors, fonts
✅ Quick Deployment - Drag all equipment at once
✅ Easy Updates - Modify include files, affects all rows
✅ No Manual ORD Editing - Automatic variable substitution
✅ Alternating Colors - Easy to implement with two include files
✅ Scalable - Works for 5 pieces of equipment or 500

PX Include Variables: Complete Workflow

Planning Phase

Step 1: Identify Reusable Components

• What elements repeat across multiple graphics?

• Floor plan zone details?

• Equipment schedule rows?

• Navigation headers?

Step 2: Design Your Include

• What widgets are needed?

• What ORDs need to be configured?

• What base component will be the variable?

Creation Phase

Step 1: Create Include File

1. Create PX file in px/includes/ folder

2. Use canvas pane as root

3. Set scaling to None

4. Size appropriately

Step 2: Add Widgets

• Copy from existing graphics, or

• Create from scratch

Step 3: Convert ORDs to Variables

• Replace base component paths with $(variableName)

• Keep additional paths after variable

• Remember leading slash on appended paths

Implementation Phase

Step 1: Select Base Components

• From component tree

• Single or multiple selection

Step 2: Drag and Drop

• Drag onto PX editor

• Make Widget Wizard appears

Step 3: Choose Include and Bind Variables

• Select your include file

• Bind displayed variables

• Click OK

Step 4: Verify

• Check variable property

• Confirm ORD substitution worked correctly

• Test functionality

Best Practices

Variable Naming

Do:
✅ Use descriptive names: $(zone), $(equipment), $(device)
✅ Use consistent names when possible (fewer variables = easier binding)
✅ Use lowercase with underscores: $(room_temp)

Don't:
❌ Use random names like $(peanut_butter) in production
❌ Use different variables for same base component (unless necessary)
❌ Use spaces in variable names

File Organization

Do:
✅ Create px/includes/ folder for organization
✅ Use descriptive filenames: zone_detail.px, table_header.px
✅ Group related includes together
✅ Document what each include is for

Don't:
❌ Scatter include files throughout station
❌ Use vague names like include1.px, include2.px

Canvas Sizing

Do:
✅ Size canvas exactly to content
✅ Test include in target files to verify sizing
✅ Set scaling to None

Don't:
❌ Make canvas too large (wastes space)
❌ Make canvas too small (content cut off)
❌ Leave scaling on (causes issues when embedded)

Variable Design

Do:
✅ Use same variable for all bindings with same base
✅ Only create additional variables when base differs
✅ Document which variable maps to what

Don't:
❌ Create unnecessary variables
❌ Use different variables for same base (makes binding tedious)

Troubleshooting

Variables Not Showing in Wizard

Problem: Variables section is empty in Make Widget Wizard

Possible Causes:

• Variable syntax incorrect (missing $, parentheses)

• PX include file not saved

• Wrong file selected

Solution:

• Verify variable syntax: $(variableName)

• Save include file

• Select correct include file

ORDs Not Resolving Correctly

Problem: Bindings don't work after using include

Possible Causes:

• Missing forward slash in appended path

• Incorrect variable substitution

• Base component doesn't match expected structure

Solution:

• Check for leading slash: $(var)/points/Temp

• Verify ORD structure in include file

• Confirm dragged component has expected points/paths

Include Appears But Content Wrong

Problem: PX include widget appears but shows wrong data

Possible Causes:

• Variables bound to wrong components

• Variable names mismatched

• Include file updated but not refreshed

Solution:

• Check Variables property - verify mappings

• Ensure variable names match between definition and binding

• Refresh/reload PX view

Key Takeaways

✅ PX Includes enable reusable UI components across multiple graphics
✅ Simple includes (no variables) work great for static content like headers
✅ Variable includes dramatically reduce configuration time for repeated elements
✅ Variable syntax: $(variableName) with optional /additional/path
✅ One variable per base component is the most efficient approach
✅ Use includes folder for organization
✅ Canvas pane root with scaling set to None
✅ Drag components (not include file) to use variables
✅ Make Widget Wizard handles variable binding automatically
✅ Massive time savings on large projects with many similar components

Coming in Part 2

The next video will cover:

• More complex examples with PX includes

• Using value bindings on PX include widgets

• Dynamic substitutions based on station information

• Advanced techniques and use cases

Quick Reference

Simple PX Include (No Variables)

1. Create include file with canvas pane root
2. Add content (labels, widgets, etc.)
3. Drag include file onto target PX
4. Position as needed

PX Include with Variables

1. Create include file with canvas pane root
2. Add widgets with variable ORDs: $(varName)/path
3. Select base component(s) from tree
4. Drag onto PX editor
5. Make Widget Wizard → Include px file
6. Select include file
7. Bind variables
8. Click OK

Variable ORD Syntax

$(variableName)                    → Base component only
$(variableName)/points/Temp        → Base + additional path
$(var1)/path/to/point              → Keep leading slash!

Presenter: James Johnson
Series:Niagara PRO TIPS
Topic:PX Includes - Part 1
Part:1 of 2
Key Concept:Using PX includes with variables to dramatically reduce configuration time and errors

YouTube: http://www.youtube.com/@TridiumInc