BLADE_TO_SPA_CONVERSION(3)      RSX Framework Manual      BLADE_TO_SPA_CONVERSION(3)

TEMPORARY DOCUMENT NOTICE
    This man page was created on 2025-11-23 to assist with porting RSpade
    projects from Blade templates to SPA actions.

    This document will be removed when all consumers of the framework report
    that their conversion is complete.

NAME
    blade_to_spa_conversion - Converting legacy Blade pages to SPA actions

DESCRIPTION
    This document preserves the process for converting legacy Blade pages to
    SPA actions, for reference when dealing with old code or third-party
    integrations.

CONVERSION PROCESS

    1. CREATE ACTION FILES

        In the feature directory, create the JavaScript action and template:

            touch Feature_Index_Action.js Feature_Index_Action.jqhtml

    2. CREATE ACTION CLASS

        Add the necessary decorators to define the SPA action:

            @route('/path')
            @layout('Frontend_Layout')
            @spa('Frontend_Spa_Controller::index')
            class Feature_Index_Action extends Spa_Action {
                full_width = true;  // For DataGrid pages
                async on_load() {
                    this.data.items = await Feature_Controller.fetch_items();
                }
            }

    3. CONVERT TEMPLATE SYNTAX

        Variable Interpolation:
            {{ $var }}      ->  <%= this.args.var %> or <%= this.data.var %>
            {!! $html !!}   ->  <%!= this.data.html %>

        Control Structures:
            @if($cond) / @endif             ->  <% if (cond) { %> / <% } %>
            @foreach($items as $item)       ->  <% for (let item of items) { %>
            @endforeach                     ->  <% } %>
            @for / @endfor                  ->  Standard JavaScript for loop
            @while / @endwhile              ->  Standard JavaScript while loop

        Comments:
            {{-- comment --}}               ->  <%-- comment --%>

        Includes:
            @include('partial')             ->  Create a jqhtml component instead

        Blade Directives:
            @auth / @endauth                ->  Handle in action's on_load() method
            @guest / @endguest              ->  Handle in action's on_load() method
            @can / @endcan                  ->  Check permissions in controller

    4. UPDATE CONTROLLER

        Remove the server-side route method and replace with Ajax endpoints:

            // Remove this:
            #[Route('/feature')]
            public static function index(Request $request, array $params = []) {
                return view('feature.index', ['items' => Feature_Model::all()]);
            }

            // Add this instead:
            #[Ajax_Endpoint]
            public static function fetch_items(Request $request, array $params = []) {
                return ['items' => Feature_Model::all()];
            }

    5. UPDATE ROUTE REFERENCES

        Search for all references to the old controller method:

            grep -r "Feature_Controller::method_name" rsx/app/

        Update route generation:
            Rsx::Route('Feature_Controller::method')  ->  Rsx::Route('Feature_Action')

        Check these common locations:
            - DataGrid templates (action buttons, row links)
            - Navigation menus
            - Redirect responses in controllers
            - Breadcrumb configurations

    6. ARCHIVE BLADE FILES

        Move old Blade files to the archive directory:

            mkdir -p /rsx/resource/archive/feature/
            mv rsx/app/feature/*.blade.php /rsx/resource/archive/feature/

    7. TEST THE CONVERSION

        Verify the SPA action works correctly:

            php artisan rsx:debug /path --console
            php artisan rsx:debug /path --screenshot-path=screenshot.png

COMMON CONVERSION PATTERNS

    FORMS
        Blade forms using @csrf and method="POST" should be converted to
        <Rsx_Form> components that handle Ajax submission automatically.

    AUTHENTICATION CHECKS
        Blade's @auth directive should be handled by the SPA controller's
        pre_dispatch() method or in the action's on_load() method.

    ASSET URLS
        {{ asset('path/to/file') }}  ->  Use bundle system or public directory
        {{ mix('app.js') }}          ->  Handled automatically by RSX bundle

    LARAVEL HELPERS
        {{ route('name') }}          ->  Rsx.Route('Action_Name')
        {{ url('/path') }}           ->  Rsx.Route('Action_Name')
        {{ config('key') }}          ->  Pass from controller or Ajax endpoint

NOTES
    - This conversion process is complete for the RSX starter template
    - New features should be built directly as SPA actions, not Blade views
    - Blade knowledge is only needed for understanding legacy code

SEE ALSO
    spa(3), jqhtml(3), routing(3)

RSX Framework                     2025-11-23            BLADE_TO_SPA_CONVERSION(3)