📘 RAG Training Document: TSQL.APP Navigation & Validation

🏷️ Title: Validated Navigation in TSQL.APP

Version: 1.1
Author: UX1 Internal Training Team
Last Updated: 2025-02-02

📖 Introduction

This document provides a structured explanation of Navigation with Parameter Validation in the TSQL.APP framework. It describes best practices, key stored procedures, and step-by-step execution of navigation logic within the application.

🚀 Objectives

• Understand sp_api_goto for controlled navigation.

• Learn how to validate filter parameters before navigating.

• Implement toasts for user feedback.

• Follow best practices in TSQL.APP for variable declaration and error handling.

🔑 Key Stored Procedures Used

Stored Procedure	Purpose
sp_api_goto	Handles navigation between different sections.
sp_api_toast	Displays a UI message to users (success/warning/error).
ReducerExists	Custom function to check if a filter exists for a card.

🏗 Implementation Walkthrough

1️⃣ Basic Navigation

EXEC sp_api_goto @path = N'company';

✅ What It Does:

• Redirects the user to the Company section.

• No additional logic or validation is performed.

❌ Limitation:

• If further code exists after this, it will not execute since navigation occurs immediately.

2️⃣ Navigation with Parameters

EXEC sp_api_goto @path = N'planning', @search = N'filter=code.swhas(cool)'; --filters records where the field [code] starts with the text 'cool'

-- or 
EXEC sp_api_goto @path = N'planning', @search = N'filter=code.swhas(+cool)'; --filters records where the field [code] contains the text 'cool'

✅ What It Does:

• Navigates to the planning section.

• Appends the filter parameter to refine the view.

3️⃣ Checking for Filter Existence Before Navigating

-- 1. Declare all variables first

DECLARE @CardName NVARCHAR(128) = N'planning';

DECLARE @FilterName NVARCHAR(128) = N'nada';

DECLARE @FilterExists BIT;

DECLARE @ToastText NVARCHAR(MAX);

DECLARE @ToastClass NVARCHAR(100);

DECLARE @SearchParam NVARCHAR(MAX);

-- 2. Check if filter exists

SELECT @FilterExists = dbo.ReducerExists(@CardName, @FilterName);

-- 3. Prepare variables before stored procedure calls

IF @FilterExists = 1

BEGIN

SET @SearchParam = CONCAT(N'?red=', @FilterName);

EXEC sp_api_goto @path = @CardName, @search = @SearchParam;

END

ELSE

BEGIN

SET @ToastText = CONCAT(N'Filter "', @FilterName, N'" not found on
card "', @CardName, N'"');

SET @ToastClass = N'btn-warning';

EXEC sp_api_toast @text = @ToastText, @class = @ToastClass;

END;

✅ Best Practices Followed

1️⃣ Variable Declaration at the Start

✅ Ensures all variables are properly declared before execution.
✅ Enhances code maintainability and debugging.

2️⃣ Validation Before Action

✅ Prevents invalid navigation by checking if the filter exists first.

3️⃣ Providing User Feedback

✅ Instead of silent failures, users are notified using sp_api_toast.

4️⃣ Avoiding Hardcoded Parameters

✅ Uses dynamic @SearchParam to ensure flexibility.

🎯 Key Takeaways

1. Direct Navigation is simple but may not account for missing filters.

2. Validated Navigation ensures users are guided correctly.

3. Error Handling with Toasts improves user experience.

📌 Further Learning

• 📖 Read more on sp_api_goto in TSQL.APP Documentation.

• 🎓 Practice using sp_api_modal_input to dynamically select filters.

• 🛠 Try integrating sp_api_modal_table to preview available filters before navigating.

📌 Appendix

🛠 Alternative: Querying Available Filters (Commented Out in Code)

SELECT a.*

INTO #Filter

FROM api_card_actions a

JOIN api_card c ON c.id = a.card_id

WHERE c.name = 'planning' --@CardName

AND a.action = N'reducer';

EXEC sp_api_modal_table @tmptable=N'#filter';

✅ What It Does:

• Retrieves existing filters from the api_card_actions table.

• Displays them in a modal using sp_api_modal_table.

📌 Why Use This?

• Helpful for debugging missing filters in UI.

🎯 Conclusion

By applying these best practices, developers can create a robust navigation system in TSQL.APP that prevents users from encountering invalid states. 🚀