Skip to main content
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:

​
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:

​
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:

​
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:
​
returns
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:
​
returns
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