TSQL.APP Modal Restart Guide

Overview

sp_api_modal_restart is a critical stored procedure in TSQL.APP that manages modal state and flow control. It allows developers to restart the current modal action or initiate a new one while preserving state data.

Syntax

EXEC sp_api_modal_restart 
    [@action_name = N'action_name',]  -- Optional: Name of new action to start (by default the current modal page will restart)
    [@values = @json,]                -- Optional: State data as JSON
    [@modal_clear = 0|1]              -- Optional: Clear modal before restart

Parameters

@action_name

• Type: NVARCHAR(128)
• Optional: Yes
• Purpose: Specifies a different action to start
• Default: Current action if omitted

@values

• Type: NVARCHAR(MAX)
• Optional: Yes
• Purpose: JSON string containing state values
• Format: Must use JSON PATH WITHOUT_ARRAY_WRAPPER

@modal_clear

• Type: BIT
• Optional: Yes
• Purpose: Clears modal before restart if set to 1
• Default: 0

Common Use Cases

1. Simple Restart

Use when you need to refresh the current modal without changing state:

EXEC sp_api_modal_restart;

2. Multi-Step Forms

Ideal for wizard-style interfaces where state must be preserved:

DECLARE @Step INT = 1;
DECLARE @Name NVARCHAR(100);
DECLARE @JsonValues NVARCHAR(MAX);

-- Get current values
EXEC sp_api_modal_get_value @name='@Name', @value=@Name OUT;

-- Prepare state for next step
SET @JsonValues = (
    SELECT [@Step] = @Step + 1,
           [@Name] = @Name
    FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
);

-- Restart with new state
EXEC sp_api_modal_restart @values=@JsonValues;

3. Changing Actions

When you need to start a different action while preserving context:

DECLARE @JsonValues NVARCHAR(MAX) = (
    SELECT [@SelectedID] = @ID,
           [@ViewType] = N'detail'
    FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
);

EXEC sp_api_modal_restart 
    @action_name = N'view_details',
    @values = @JsonValues;

Best Practices

1. State Management

• Always declare variables at the start of your script
• Use consistent naming conventions for state variables
• Validate state before passing to restart

-- Good Practice
DECLARE @Step INT;
DECLARE @Name NVARCHAR(100);
DECLARE @Email NVARCHAR(100);
DECLARE @JsonValues NVARCHAR(MAX);

-- Get current state
EXEC sp_api_modal_get_value @name='@Step', @value=@Step OUT;
EXEC sp_api_modal_get_value @name='@Name', @value=@Name OUT;
EXEC sp_api_modal_get_value @name='@Email', @value=@Email OUT;

-- Validate state
IF @Step IS NULL SET @Step = 1;
IF LEN(TRIM(ISNULL(@Name, N''))) < 2
BEGIN
    EXEC sp_api_toast @text=N'Please enter a valid name', @class=N'btn-warning';
    RETURN;
END

-- Prepare next state
SET @JsonValues = (
    SELECT [@Step] = @Step + 1,
           [@Name] = @Name,
           [@Email] = @Email
    FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
);

-- Restart with validated state
EXEC sp_api_modal_restart @values=@JsonValues;

2. Error Handling

Always implement proper error handling:

BEGIN TRY
    DECLARE @JsonValues NVARCHAR(MAX);
    SET @JsonValues = (
        SELECT [@Step] = 2,
               [@Data] = @SomeData
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    );
    
    EXEC sp_api_modal_restart @values=@JsonValues;
END TRY
BEGIN CATCH
    DECLARE @ErrorMsg NVARCHAR(MAX) = ERROR_MESSAGE();
    EXEC sp_api_toast @text=@ErrorMsg, @class=N'btn-danger';
END CATCH

3. JSON Construction

Always use the correct JSON format:

-- ✅ Correct
SET @JsonValues = (
    SELECT [@VariableName] = @Value
    FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
);

-- ❌ Incorrect - Don't construct JSON manually
SET @JsonValues = N'{"@VariableName": "' + @Value + N'"}';

Common Patterns

Progress Through Steps

DECLARE @Step INT;
DECLARE @JsonValues NVARCHAR(MAX);
DECLARE @NextButton NVARCHAR(MAX);

-- Get current state
EXEC sp_api_modal_get_value @name='@Step', @value=@Step OUT;
EXEC sp_api_modal_get_value @name='@NextButton', @value=@NextButton OUT;

IF @NextButton IS NOT NULL
BEGIN
    SET @JsonValues = (
        SELECT [@Step] = ISNULL(@Step, 1) + 1
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    );
    
    EXEC sp_api_modal_restart @values=@JsonValues;
END

Handling Back Navigation

DECLARE @Step INT;
DECLARE @JsonValues NVARCHAR(MAX);
DECLARE @BackButton NVARCHAR(MAX);

-- Get current state
EXEC sp_api_modal_get_value @name='@Step', @value=@Step OUT;
EXEC sp_api_modal_get_value @name='@BackButton', @value=@BackButton OUT;

IF @BackButton IS NOT NULL
BEGIN
    SET @JsonValues = (
        SELECT [@Step] = @Step - 1
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    );
    
    EXEC sp_api_modal_restart @values=@JsonValues;
END

Troubleshooting

Common Issues

1. State Not Persisting

   • Verify JSON format is correct
   • Check variable names start with @
   • Confirm JSON is using PATH WITHOUT_ARRAY_WRAPPER

2. Invalid JSON Format

   • Always use FOR JSON PATH
   • Include WITHOUT_ARRAY_WRAPPER
   • Don't manually construct JSON strings

3. Action Not Changing

   • Verify @action_name is correct
   • Check action exists
   • Confirm permissions

Security Considerations

1. Input Validation

   • Validate all state before restart
   • Sanitize any user input
   • Check permissions for new actions

2. State Management

   • Don't store sensitive data in state
   • Clear sensitive data when appropriate
   • Use appropriate data types

Performance Tips

1. Minimize State Size

   • Only pass necessary variables
   • Use appropriate data types
   • Clean up unnecessary state

2. Optimize JSON Creation

   • Use FOR JSON PATH
   • Avoid string concatenation
   • Keep JSON structure flat when possible