Advanced Dynamo Node Customisation

With a foundation knowledge of ZeroTouch already established. this section delves into the advantages of customising Dynamo nodes to enhance both functionality and user experience. By adding features such as warning messages, informational messages, and custom icons, you can create nodes that are more intuitive, informative, and visually engaging. These customisations not only help users understand potential issues or optimise their workflows but also make your nodes stand out as professional and user-friendly tools.

Customising nodes is an excellent way to ensure your solutions are clear, reliable, and tailored to meet specific project needs.

Generating Custom Warning Messages Using OnLogWarningMessage

In Dynamo, the OnLogWarningMessage method provides a way to log warning messages directly to Dynamo's console. This is a powerful feature, especially for Zero Touch nodes, as it allows developers to alert users when there are issues with inputs or parameters that could lead to unexpected behavior. This guide will teach you how to implement OnLogWarningMessage in any Zero Touch node.

Implementation Steps for `OnLogWarningMessage`

Step 1: Import the Required Namespace

OnLogWarningMessage is part of the DynamoServices namespace, so begin by adding this to your project file.

using DynamoServices;

Step 2: Identify When to Log Warnings

Before adding a warning message, consider the logic in your method:

What conditions might cause incorrect or unexpected results?
Are there specific input values or parameters that the method requires to function correctly?

Examples of conditions to check:

Out-of-range values (e.g., if (inputValue < 0)).
Null or empty collections (e.g., if (list == null || list.Count == 0)).
Data type mismatches (e.g., if a file type is unsupported).

Step 3: Use `OnLogWarningMessage` to Log the Warning

Place OnLogWarningMessage calls where you detect conditions that could cause issues. When the condition is met, log a warning message that provides clear guidance to the user.

Syntax for `OnLogWarningMessage`

LogWarningMessageEvents.OnLogWarningMessage("Your warning message here.");

Example Implementations of `OnLogWarningMessage`

To demonstrate OnLogWarningMessage in action, here are different scenarios you might encounter when building a Zero Touch node.

Example 1: Validating Numeric Inputs

In this example, we'll build upon the custom node created in the previous "Zero-Touch Case Study - Grid Node"; A Method named RectangularGrid that generates a grid of rectangles based on xCount and yCount inputs. We will walk through testing If an input is invalid, and then using OnLogWarningMessage to log a warning and stop processing.

Using OnLogWarningMessage for Input Validation

When generating a grid based on xCount and yCount. You want to ensure both values are positive integers before proceeding.

public static List<Rectangle> CreateGrid(int xCount, int yCount)
{
    // Check if xCount and yCount are positive
    if (xCount <= 0 || yCount <= 0)
    {
        LogWarningMessageEvents.OnLogWarningMessage("Grid count values must be positive integers.");
        return new List<Rectangle>();  // Return an empty list if inputs are invalid
    }
    // Proceed with grid creation...
}

In this example:

Condition: If either xCount or yCount is less than or equal to zero.
Message: "Grid count values must be positive integers."

This will show the warning in Dynamo if a user enters zero or negative values, helping them understand the expected input.

Now we know what this looks like, we can implement it into the Grids example node:

using Autodesk.DesignScript.Geometry;
using DynamoServices;

namespace CustomNodes
{
    public class Grids
    {
        // The empty private constructor.
        // This will not be imported into Dynamo.
        private Grids() { }

        /// <summary>
        /// This method creates a rectangular grid from an X and Y count.
        /// </summary>
        /// <param name="xCount">Number of grid cells in the X direction</param>
        /// <param name="yCount">Number of grid cells in the Y direction</param>
        /// <returns>A list of rectangles</returns>
        /// <search>grid, rectangle</search>
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10)
        {
            // Check for valid input values
            if (xCount <= 0 || yCount <= 0)
            {
                // Log a warning message if the input values are invalid
                LogWarningMessageEvents.OnLogWarningMessage("Grid count values must be positive integers.");
                return new List<Rectangle>(); // Return an empty list if inputs are invalid
            }

            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                    Point cPt = rect.Center();
                }
            }

            return pList;
        }
    }
}

Example 2: Checking for Null or Empty Collections

If your method requires a list of points but a user passes an empty or null list, you can use OnLogWarningMessage to inform them about the issue.

public static Polygon CreatePolygonFromPoints(List<Point> points)
{
    if (points == null || points.Count < 3)
    {
        LogWarningMessageEvents.OnLogWarningMessage("Point list cannot be null or have fewer than three points.");
        return null;  // Return null if the input list is invalid
    }
    // Proceed with polygon creation...
}

In this example:

Condition: If the points list is null or contains fewer than three points.
Message: "Point list cannot be null or have fewer than three points."

This warns users that they need to pass a valid list with at least three points to form a polygon.

Example 3: Verifying File Type Compatibility

For a node that processes file paths, you may want to ensure that only certain file types are allowed. If an unsupported file type is detected, log a warning.

public static void ProcessFile(string filePath)
{
    if (!filePath.EndsWith(".csv"))
    {
        LogWarningMessageEvents.OnLogWarningMessage("Only CSV files are supported.");
        return;
    }
    // Proceed with file processing...
}

In this example:

Condition: If the file path doesn't end with ".csv".
Message: "Only CSV files are supported."

This warns users to ensure they are passing a CSV file, helping prevent issues related to incompatible file formats.

Adding Informational Messages with `OnLogInfoMessage`

In Dynamo, OnLogInfoMessage from the DynamoServices namespace lets developers log informational messages directly to Dynamo's console. This is helpful for confirming successful operations, communicating progress, or providing additional insights about node actions. This guide will teach you how to add OnLogInfoMessage in any Zero Touch node to enhance feedback and improve user experience.

Implementation Steps for `OnLogInfoMessage`

Step 1: Import the Required Namespace

OnLogInfoMessage is part of the DynamoServices namespace, so begin by adding this to your project file.

Step 2: Identify When to Log Information

Before adding an info message, think about the purpose of your method:

What information would be useful to confirm after an action is completed?
Are there key steps or milestones within the method that users might want to know about?

Examples of useful confirmations:

Completion messages (e.g., when a grid or model is fully created).
Details of processed data (e.g., "10 items processed successfully").
Execution summaries (e.g., parameters used in the process).

Step 3: Use `OnLogInfoMessage` to Log Informational Messages

Place OnLogInfoMessage calls at meaningful points in your method. When a key step or completion occurs, log an informational message to update the user on what happened.

Syntax for `OnLogInfoMessage`

LogWarningMessageEvents.OnLogInfoMessage("Your info message here.");

Example Implementations of `OnLogInfoMessage`

Here are different scenarios to demonstrate using OnLogInfoMessage in your Zero Touch nodes.

Example 1: Validating Numeric Inputs

In this example, we'll build upon the custom node created in the previous "Zero-Touch Case Study - Grid Node"; A Method named RectangularGrid that generates a grid of rectangles based on xCount and yCount inputs. We will walk through testing If an input is invalid, and then using OnLogInfoMessage to provide info after the node has completed its run.

Using OnLogInfoMessage for Input Validation

When generating a grid based on xCount and yCount. After generating the grid, you want to confirm its creation by logging an informational message with the grid's dimensions.

public static List<Rectangle> CreateGrid(int xCount, int yCount)
{
    var pList = new List<Rectangle>();
    // Grid creation code here...

    // Confirm successful grid creation
    LogWarningMessageEvents.OnLogInfoMessage($"Successfully created a grid with dimensions {xCount}x{yCount}.");

    return pList;
}

In this example:

Condition: The grid creation process has completed.
Message: "Successfully created a grid with dimensions {xCount}x{yCount}."

This message will inform users that the grid was created as specified, helping them confirm that the node worked as expected.

Now we know what this looks like, we can implement it into the Grids example node:

using Autodesk.DesignScript.Geometry;
using DynamoServices;

namespace CustomNodes
{
    public class Grids
    {
        // The empty private constructor.
        // This will not be imported into Dynamo.
        private Grids() { }

        /// <summary>
        /// This method creates a rectangular grid from an X and Y count.
        /// </summary>
        /// <param name="xCount">Number of grid cells in the X direction</param>
        /// <param name="yCount">Number of grid cells in the Y direction</param>
        /// <returns>A list of rectangles</returns>
        /// <search>grid, rectangle</search>
        public static List<Rectangle> RectangularGrid(int xCount = 10, int yCount = 10)
        {
            double x = 0;
            double y = 0;

            var pList = new List<Rectangle>();

            for (int i = 0; i < xCount; i++)
            {
                y++;
                x = 0;
                for (int j = 0; j < yCount; j++)
                {
                    x++;
                    Point pt = Point.ByCoordinates(x, y);
                    Vector vec = Vector.ZAxis();
                    Plane bP = Plane.ByOriginNormal(pt, vec);
                    Rectangle rect = Rectangle.ByWidthLength(bP, 1, 1);
                    pList.Add(rect);
                    Point cPt = rect.Center();
                }
            }

            // Log an info message indicating the grid was successfully created
            LogWarningMessageEvents.OnLogInfoMessage($"Successfully created a grid with dimensions {xCount}x{yCount}.");

            return pList;
        }
    }
}

Example 2: Providing Data Count Information

If you're creating a node that processes a list of points, you might want to log how many points were processed successfully. This can be useful for large datasets.

public static List<Point> ProcessPoints(List<Point> points)
{
    var processedPoints = new List<Point>();
    foreach (var point in points)
    {
        // Process each point...
        processedPoints.Add(point);
    }

    // Log info about the count of processed points
    LogWarningMessageEvents.OnLogInfoMessage($"{processedPoints.Count} points were processed successfully.");

    return processedPoints;
}

In this example:

Condition: After the loop completes, showing the count of processed items.
Message: "6 points were processed successfully."

This message will help users understand the result of the processing and confirm that all points were processed.

Example 3: Summarizing Parameters Used

In some cases, it's useful to confirm the input parameters a node used to complete an action. For example, if your node exports data to a file, logging the file name and path can reassure users that the correct file was used.

public static void ExportData(string filePath, List<string> data)
{
    // Code to write data to the specified file path...

    // Log the file path used for export
    LogWarningMessageEvents.OnLogInfoMessage($"Data exported successfully to {filePath}.");

}