TextParameter

Class for creating text input parameter widgets that allow users to enter free-form text. This class can be imported from the squirrels.parameters or the squirrels module.

Factory methods

Factory methods are class methods that create and configure parameter instances. These methods are typically used in the pyconfigs/parameters.py file to create the parameter configurations (which describes the “shape” of the parameter but does not include the realtime user selections).

create_simple()

Decorator for creating a simple text parameter that doesn’t involve user attributes or parent parameters. The body of the decorated function does not need to return anything (i.e., it can simply be pass).

@classmethod
def create_simple(
    cls, name: str, label: str, 
    *, description: str = "", default_text: str = "", input_type: str = "text"
) -> Callable:

Hide arguments

str

required

The unique identifier for this parameter. Used to reference the parameter at query time (such as in context.py or when specifying parameter selections in the APIs).

str

required

The display label shown to users in the UI.

str

default:""

An optional description explaining the purpose of this parameter.

str

default:""

Default input text for this parameter. Defaults to empty string.

str

default:"text"

Communicates to the API client for the type of input field to use. Must be one of “text”, “textarea”, “number”, “color”, “date”, “datetime-local”, “month”, “time”, and “password”.

More information on “textarea” can be found at W3Schools textarea tag.
More information on other input types can be found at W3Schools HTML Input Types.

create_with_options()

Decorator for creating a parameter with options that can vary based on user attributes or parent parameter selections. The decorated function must return a list of TextParameterOption objects.

@classmethod
def create_with_options(
    cls, name: str, label: str, 
    *, description: str = "", input_type: str = "text",
    user_attribute: str | None = None, parent_name: str | None = None
) -> Callable:

Hide arguments

str

required

The unique identifier for this parameter. Used to reference the parameter at query time (such as in context.py or when specifying parameter selections in the APIs).

str

required

The display label shown to users in the UI.

str

default:""

An optional description explaining the purpose of this parameter.

str

default:"text"

More information on “textarea” can be found at W3Schools textarea tag.
More information on other input types can be found at W3Schools HTML Input Types.

str | None

default:"None"

A user attribute (like “access_level”) that determines which options are visible to different users. The decorated function should return options with matching user_groups values.To use custom user fields defined in pyconfigs/user.py, prefix with custom_fields. (e.g., "custom_fields.department").

str | None

default:"None"

The name of a parent parameter that controls which options are visible. The decorated function should return options with parent_option_ids matching the parent’s selected value.

create_from_source()

Decorator for creating a parameter populated from a database table or query using a TextDataSource. The decorated function must return a TextDataSource object.

@classmethod
def create_from_source(
    cls, name: str, label: str, 
    *, description: str = "", input_type: str = "text",
    user_attribute: str | None = None, parent_name: str | None = None
) -> Callable:

Hide arguments

str

required

The unique identifier for this parameter. Used to reference the parameter at query time (such as in context.py or when specifying parameter selections in the APIs).

str

required

The display label shown to users in the UI.

str

default:""

An optional description explaining the purpose of this parameter.

str

default:"text"

The type of input field to use. Must be one of “text”, “textarea”, “number”, “color”, “date”, “datetime-local”, “month”, “time”, and “password”.

str | None

default:"None"

A user attribute that determines which options from the data source are visible to different users.To use custom user fields defined in pyconfigs/user.py, prefix with custom_fields..

str | None

default:"None"

The name of a parent parameter that controls which options from the data source are visible.

Instance methods

Instance methods are available on parameter instances at query time (in context.py or data models) to retrieve selected values.

get_entered_text()

Gets the entered text. Returns a TextValue object that cannot be converted to string except through placeholders (to avoid SQL injection).

def get_entered_text(self) -> TextValue:

TextValue

A TextValue object containing the user’s entered text. This object has transformation methods like apply(), apply_percent_wrap(), apply_as_bool(), apply_as_number(), and apply_as_datetime() for safe usage in queries via placeholders.

is_enabled()

Returns True if the parameter has a valid option after applying user attribute and parent parameter selections, False otherwise.

def is_enabled(self) -> bool:

bool

True if the parameter has a valid option, False otherwise.

Examples for factory methods

All examples below are defined in the pyconfigs/parameters.py file.

Using create_simple for basic text input

For parameters that only need a single default value, use create_simple. The default text is passed directly to the decorator.

from squirrels import parameters as p

@p.TextParameter.create_simple(
    name="search_term", 
    label="Search Term",
    default_text="laptop",
    description="Enter search keywords"
)
def search_term_default():
    pass

Using textarea input type

This example creates a multi-line text input using the textarea type.

from squirrels import parameters as p

@p.TextParameter.create_simple(
    name="comments", 
    label="Comments",
    default_text="",
    input_type="textarea",
    description="Enter your comments"
)
def comments_default():
    pass

Cascading text parameter with varying defaults

This example shows how default text values change based on a parent parameter selection.

from squirrels import parameters as p, parameter_options as po

# Parent parameter
@p.SingleSelectParameter.create_with_options(
    name="report_type", 
    label="Report Type",
    description="Type of report to generate"
)
def report_type_options():
    return [
        po.SelectParameterOption(id="sales", label="Sales Report"),
        po.SelectParameterOption(id="inventory", label="Inventory Report"),
    ]

# Child text parameter with defaults varying by report type
@p.TextParameter.create_with_options(
    name="filter_text", 
    label="Filter Text",
    description="Text filter based on report type",
    parent_name="report_type"
)
def filter_text_options():
    return [
        po.TextParameterOption(
            default_text="revenue",
            parent_option_ids="sales"
        ),
        po.TextParameterOption(
            default_text="in stock",
            parent_option_ids="inventory"
        )
    ]

Text parameter with user-specific defaults

This example provides different default values based on user access levels.

from squirrels import parameters as p, parameter_options as po

@p.TextParameter.create_with_options(
    name="filter_keyword", 
    label="Filter Keyword",
    description="Default keyword for filtering",
    user_attribute="access_level"
)
def filter_keyword_options():
    return [
        po.TextParameterOption(
            default_text="public",
            user_groups=["guest"]
        ),
        po.TextParameterOption(
            default_text="",
            user_groups=["admin", "member"]
        )
    ]

Text parameter from database source

This example populates default text from a database table.

from squirrels import parameters as p, data_sources as ds

@p.TextParameter.create_from_source(
    name="default_category", 
    label="Default Category",
    description="Most popular search category"
)
def default_category_source() -> ds.TextDataSource:
    return ds.TextDataSource(
        table_or_query="""
            SELECT default_search_text
            FROM user_preferences
            WHERE is_active = 1
            LIMIT 1
        """,
        default_text_col="default_search_text"
    )

Cascading text from database source

This example shows a text parameter whose default comes from a database and depends on a parent parameter.

from squirrels import parameters as p, data_sources as ds

# Parent parameter for departments
@p.SingleSelectParameter.create_from_source(
    name="department_id", 
    label="Department",
    description="Select a department"
)
def department_source():
    return ds.SelectDataSource(
        table_or_query="departments",
        id_col="department_id",
        options_col="department_name"
    )

@p.TextParameter.create_from_source(
    name="department_search", 
    label="Department Search",
    description="Common search term for this department",
    parent_name="department_id"
)
def department_search_source():
    return ds.TextDataSource(
        table_or_query="""
            SELECT department_id, default_search_term
            FROM department_settings
        """,
        default_text_col="default_search_term",
        parent_id_col="department_id"
    )

Examples for instance methods

Once parameters are configured, you can use instance methods in your models to access the entered text. The parameter instances are available through the context object (e.g., sqrl.prms).

Basic usage in context.py

The TextValue object returned by get_entered_text() cannot be directly converted to string. It must be used through placeholders for SQL injection safety.

from squirrels import ContextArgs, TextValue

def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
    if sqrl.param_exists("search_term"):
        search_param = sqrl.prms["search_term"]
        assert isinstance(search_param, p.TextParameter)
        search_text: TextValue = search_param.get_entered_text()
        sqrl.set_placeholder("search_text", search_text.apply_percent_wrap())

Then, in the SQL model, use the placeholder as such:

-- models/federates/search_results.sql
SELECT *
FROM products
WHERE product_name LIKE $search_text 
  -- or :search_text for dbviews that use a sqlalchemy connection

This is the recommended way to use text parameters in SQL to prevent SQL injection.

Transforming text values

The TextValue object provides transformation methods for different use cases.

# In context.py
def main(ctx: dict[str, Any], sqrl: ContextArgs) -> None:
    if sqrl.param_exists("search_term"):
        search_param = sqrl.prms["search_term"]
        assert isinstance(search_param, p.TextParameter)
        
        search_text = search_param.get_entered_text()
        ctx["search_with_wildcards"] = search_text.apply_percent_wrap()  # Adds % before and after
        ctx["search_uppercase"] = search_text.apply(lambda x: x.upper())  # Custom transformation
        ctx["is_empty"] = search_text.apply_as_bool(lambda x: len(x) == 0)  # Convert to boolean
        ctx["search_length"] = search_text.apply_as_number(len)  # Convert to number

arguments

auth

connections

parameters

parameter_options

data_sources

dashboards

types

Factory methods

create_simple()

create_with_options()

create_from_source()

Instance methods

get_entered_text()

is_enabled()

Examples for factory methods

Using create_simple for basic text input

Using textarea input type

Cascading text parameter with varying defaults

Text parameter with user-specific defaults

Text parameter from database source

Cascading text from database source

Examples for instance methods

Basic usage in context.py

Transforming text values

​Factory methods

​create_simple()

​create_with_options()

​create_from_source()

​Instance methods

​get_entered_text()

​is_enabled()

​Examples for factory methods

​Using create_simple for basic text input

​Using textarea input type

​Cascading text parameter with varying defaults

​Text parameter with user-specific defaults

​Text parameter from database source

​Cascading text from database source

​Examples for instance methods

​Basic usage in context.py

​Transforming text values

Factory methods

create_simple()

create_with_options()

create_from_source()

Instance methods

get_entered_text()

is_enabled()

Examples for factory methods

Using create_simple for basic text input

Using textarea input type

Cascading text parameter with varying defaults

Text parameter with user-specific defaults

Text parameter from database source

Cascading text from database source

Examples for instance methods

Basic usage in context.py

Transforming text values