rspade_system/app/RSpade/man/rsxapp.txt

RSXAPP(3)                   RSX Framework Manual                   RSXAPP(3)

NAME
    rsxapp - Global JavaScript object containing runtime configuration and data

SYNOPSIS
    JavaScript:
        window.rsxapp.build_key                  // Manifest build hash
        window.rsxapp.user                       // Current user model data
        window.rsxapp.user.resolved_permissions  // Pre-computed user permissions
        window.rsxapp.site                       // Current site model data
        window.rsxapp.page_data                  // Custom page-specific data
        window.rsxapp.is_spa                     // Whether current page is SPA
        window.rsxapp.csrf                       // CSRF token for forms

DESCRIPTION
    window.rsxapp is a global JavaScript object rendered with every page bundle.
    It contains session data, configuration, and runtime state needed by
    client-side JavaScript. The object is built during bundle rendering in
    Rsx_Bundle_Abstract::__generate_html() and output as an inline <script> tag
    before bundle assets load.

    The rsxapp object provides:
    - Session context (user, site, authentication state)
    - Build information for cache management
    - Server time for client-server synchronization
    - Custom page data passed via PageData::add()
    - Debug configuration in development mode

HOW IT WORKS
    When a bundle renders (e.g., Frontend_Bundle::render()), the framework:
    1. Collects runtime data from various sources
    2. Merges custom page_data from PageData::add() calls
    3. JSON-encodes the data
    4. Outputs: <script>window.rsxapp = {...};</script>
    5. Bundle script tags follow, using rsxapp for initialization

    Framework core classes (Rsx_Time, Rsx_Storage, Ajax) read from rsxapp
    during their initialization, before application code runs.

OBJECT STRUCTURE
    Core Properties (always present):

        build_key           String. Manifest hash for cache-busting.
                            Changes when any source file changes.

        session_hash        String. Hashed session token for storage scoping.
                            Non-reversible hash of rsx cookie value.

        debug               Boolean. True in non-production environments.

        current_controller  String. PHP controller handling this request.

        current_action      String. Controller method name.

        is_auth             Boolean. True if user is logged in.

        is_spa              Boolean. True if page is SPA bootstrap.

        params              Object. URL parameters from route (e.g., {id: "4"}).

        csrf                String. CSRF token for form submissions.

    Session Data (when authenticated):

        user                Object. Current user model with all fields.
                            Includes enum properties (role_id__label, etc.),
                            resolved_permissions array, and __MODEL marker.

        user.resolved_permissions
                            Array. Pre-computed permission IDs for current user.
                            Includes role defaults plus supplementary grants,
                            minus supplementary denies. Use Permission class
                            for checking: Permission.has_permission(perm_id).

        site                Object. Current site model.

    Time Synchronization:

        server_time         String. ISO 8601 UTC timestamp from server.
                            Used by Rsx_Time to correct client clock skew.

        user_timezone       String. IANA timezone (e.g., "America/Chicago").
                            Resolved: user preference > site > config > default.

    Custom Data:

        page_data           Object. Data added via PageData::add().
                            Only present if data was added.

    Debug Mode Only:

        console_debug       Object. Console debug configuration.
                            Controls console_debug() output filtering.

    Mode-Dependent:

        ajax_batching       Boolean. When true, Ajax calls are batched.
                            Set automatically: true in debug/production,
                            false in development for easier debugging.

    Optional:

        flash_alerts        Array. Pending flash messages to display.
                            Consumed by Server_Side_Flash component.

        log_browser_errors  Boolean. When true, JS errors logged to server.

EXAMPLE OUTPUT
    Typical rsxapp object for authenticated SPA page:

        window.rsxapp = {
            "build_key": "72d8554b3a6a4382d9130707caff4009",
            "session_hash": "9b8cdc5ebf5a3db1e88d400bafe1af06...",
            "debug": true,
            "current_controller": "Frontend_Spa_Controller",
            "current_action": "index",
            "is_auth": true,
            "is_spa": true,
            "params": {"id": "4"},
            "user": {
                "id": 1,
                "first_name": "Test",
                "last_name": "User",
                "email": "test@example.com",
                "role_id": 300,
                "role_id__label": "Site Owner",
                "resolved_permissions": [2, 3, 4, 5, 6, 7],
                "__MODEL": "User_Model"
            },
            "site": {
                "id": 1,
                "name": "Test Site",
                "timezone": "America/Chicago",
                "__MODEL": "Site_Model"
            },
            "csrf": "f290180b609f8f353c3226accdc798961...",
            "page_data": {
                "contact_internal_id": 17
            },
            "server_time": "2026-01-13T07:48:11.482Z",
            "user_timezone": "America/Chicago"
        };

COMMON USAGE PATTERNS
    Check authentication:
        if (window.rsxapp.is_auth) {
            // User is logged in
        }

    Access current user:
        const user_name = window.rsxapp.user.first_name;
        const is_admin = window.rsxapp.user.role_id === User_Model.ROLE_SITE_OWNER;

    Check permissions (use Permission class):
        if (Permission.has_permission(User_Model.PERM_EDIT_DATA)) {
            // User can edit data
        }
        if (Permission.has_any_permission([User_Model.PERM_EDIT_DATA, User_Model.PERM_VIEW_DATA])) {
            // User can edit or view data
        }

    Read page data:
        const contact_id = window.rsxapp.page_data?.contact_internal_id;

    Get CSRF token for forms:
        $('form').append(`<input type="hidden" name="_token" value="${window.rsxapp.csrf}">`);

    Check if SPA mode:
        if (window.rsxapp.is_spa) {
            // Use client-side navigation
            Spa.dispatch('/new-route');
        }

ADDING CUSTOM DATA
    Use PageData::add() in PHP to add custom data to page_data:

        PageData::add([
            'feature_flags' => ['new_ui', 'beta_feature'],
            'config' => $site_config,
        ]);

    Access in JavaScript:
        if (window.rsxapp.page_data.feature_flags.includes('new_ui')) {
            // Enable new UI
        }

    See pagedata(3) for detailed usage.

UNDERSCORE KEY FILTERING
    Keys starting with single underscore (e.g., _internal) are automatically
    filtered out before JSON encoding. Keys with double underscore (e.g., __MODEL)
    are preserved. This allows models to have internal properties that don't
    leak to JavaScript.

FRAMEWORK CONSUMERS
    These framework classes read from rsxapp during initialization:

    Rsx_Time        Reads server_time and user_timezone for clock sync
    Rsx_Storage     Reads session_hash, user.id, site.id, build_key for scoping
    Ajax            Reads csrf for request headers
    Spa             Reads is_spa, params for routing
    Permission      Reads user.resolved_permissions for access control checks
    Debugger        Reads console_debug for output filtering

SEE ALSO
    pagedata(3), bundle_api(3), time(3), storage(3), spa(3), acls(3)

AUTHOR
    RSpade Framework

RSpade                         January 2026                       RSXAPP(3)