Store Locator Plus® Internal Docs

Goal: replace the legacy locations management table written in PHP and jQuery with a modern React component preferably MUI DataGridPro.

Legacy Locations Management Table

Rendering The UI

Rendering of the PHP page in WordPress is routed via this path:
– WordPress admin menu “Locations” (WordPress plugin) or “Location Details” (SaaS) for menu_items[‘slp_manage_locations’]
– Admin Menu calls \SLP_Admin_UI::renderLocationsPage to render the page.
– Calls \SLP_Admin_Locations::display

This renders the location manage page which has several tab panels.
Each tab panel is added or augmented with the slp_build_locations_panels custom WordPress hook.
The Locations Management Table is added with a hook priority of 10 that calls \SLP_Admin_Locations::addListLocationsSetting

When the page renders it goes inside an HTML div (tab panel) that is exposed when a user clicks on the List menu item in the horizontal tab menu that is currently rendered as a React component on the same page.

The List Locations Tab Panel Content

This page is comprised of HTML from the following methods:

• \SLP_Admin_Locations::create_string_location_table_start –
  starting HTML wrappers for the locations table
  
• \SLP_Notifications_Manager::get_html –
  renders a notification or “SnackBar” style notices manager if any notification messages are on the notifications array.
  
• The ‘manage_locations_table’ \SLP_Setting object rendered by \SLP_Settings_manage_locations_table –
  Draws the main locations data grid / table.
  
• \SLP_Admin_Locations::create_string_location_table_end –
  ending HTML wrappers for the locations table

\SLP_Admin_Locations::create_string_location_table_start calls the following methods:

• \SLP_Admin_Locations::set_location_query –
  Manages the SLP database queries.
  • Adds location query modifiers for the where clause via the custom hook slp_manage_location_where
    • Used by the Power plugin via \SLP_Power_Admin_Locations_Actions::process when action =
      • filter_by_category – to filter locations by category
      • show_uncoded – filter locations to those that are not geocoded (empty latitude or longitude fields)
      • filter_by_property – filter locations to match properties like name, zip code, country, state
  • Adds location query modifiers via \SLP_Admin_Locations::set_location_filter
  • Adds a sort order to the location results via \SLP_Admin_Locations::set_location_order
• Executes the location query via \SLP_Data::get_SQL
• Gets a total location count and stores it in \SLP_Admin_Locations::$total_locations_shown
• Adjust the pagination starting page number if necessary storing the value in \SLP_Admin_Locations::$start
  
  
  
• If no locations, adds a WordPress nonce with wp_nonce_field( ‘screen-options-nonce’, ‘screenoptionnonce’, false ) and shows the no locations message and returns.
  
• If there are locations:
  • Outputs a hidden input field name=’start’ with the starting offset for pagination
  • If the page is rendered after a form post (processing the apply to all button) outputs a hidden input name=”apply_to_all” with a value=”1″
  • Outputs a div for the simulated pagination navigation block via \SLP_Admin_Locations::createstring_PanelManageTablePagination

\SLP_Settings_manage_locations_table main locations data grid rendering calls the following methods:

• \SLP_Settings_manage_locations_table::display handles the main rendering which calls…
  • \SLP_Admin_Locations::display_manage_locations_table
    This is where the main HTML table is rendered that will be the primary object replaced by the MUI DataGridPro component.
    • Add the HTML input checkbox for each row, wired to a jQuery call to help managed checked/unchecked state.
    • Calls \SLP_Admin_Locations::display_column_headers to put field labels on top of the table columns.
    • Uses the custom filter slp_locations_manage_cssclass to apply custom CSS styling on rows for
      • invalid location entries via \SLP_Admin_Locations::filter_InvalidHighlight
      • locations with the private field set to true via \SLP_Admin_Locations::add_private_location_css
      • adds custom data specific styling via \SLP_Admin_Locations::customize_location_list_displayed_data
    • Managed the location data query, preparing the database layer for where clauses, sorting, etc.
    • Adds action buttons for edit, delete, etc to an Actions column which presents icons to modify data in each row
    • Loops through he list of returned locations records and displays rows of locations
      • Column data HTML output can be modified via the WordPress hook slp_column_data. This is used by these plugins:
        • Experience:
          • add_filter( ‘slp_column_data’, array( $this, ‘filter_FieldDataToManageLocations’ ), 90, 3 );
        • Power:
          • add_filter( ‘slp_column_data’, array( $this, ‘customize_location_list_displayed_data’ ), 20, 3 );
          • add_filter( ‘slp_column_data’, array( $this, ‘extend_location_columns’ ), 90, 3 );
        • Premier:
          • add_filter( ‘slp_column_data’, array( $this, ‘checkmark_territory_bounds’ ), 20, 3 );
        • Store-Locator-Plus:
          • add_filter( ‘slp_column_data’, array( $this, ‘customize_location_list_displayed_data’ ), 10, 3 );

Task : Replace The Manage Locations PHP and jQuery managed table with MUI DataGrid Pro

Licensing MUI DataGrid Pro

There is a license for MUI DataGrid Pro.
You can find an example in the HistoryTable React component in MySLP Dashboard (wp-content/plugins/myslp-dashboard/src/settings_history/HistoryTable.tsx).
The MySLP Dashboard plugin invokes the license in that component via import “@licensing/MuiLicense.js”;
This methodology can be copied for SLP.

Guidelines

• Use the built-in DataGrid features for sorting, filtering, checkboxes to select row, pagination, and other extended features of the MUI component.
• Extract the data manipulation elements from the legacy Store Locator Plus location management PHP code and integrate them into a location REST endpoint in the Store Locator Plus plugin.
  • The Store Locator Plus plugin already has REST endpoints for fetching location data
  • These existing endpoints may need to be augmented to accommodate all features of the manage locations table
  • Be sure to follow any custom WordPress hooks and filters employed to manipulate data
    • Pay special attention to hook and filters in the Experience, Power, and Premier plugins
• Connect the interactions of the React LocationsTable component that was started in wp-content/plugins/store-locator-plus/src/LocationsTable/LocationsTable.tsx to the data display of the new MUI DataGrid Pro table for locations.
  • The LocationsTableHeader React component has been designed to interact with this data display table.
    • This component currently interacts with the legacy PHP and backend data processing interfaces.
    • Update the interactions as appropriate to take advantage of the new MUI Data Grid Pro features.
• Locate the local AI knowledge and context files related to prior work on the location management interface, especially task summaries related to the LocationsTableHeader components.
  • Find $HOME/PhpstormProjects/workspace-sprocket/knowledge/ai-summaries/locations
• Ask clarification questions before starting.
• If unsure of any step in the process, pause and ask for guidance.
• If any step of the process is not resolving in several turns, pause to explain the issue and proposed path forward and ask for guidance or assistance if needed.

Feedback Turn 1 : Store Locator Plus plugin version 2607.22.02

Tasks

• ✅ Revert the action bar styling , see details below.
• The per-row checkbox does not work, clicking the checkbox does not change the state of the checkbox UI on the row.
• Pagination does not work. Reproduction:
  • Set page length to 10. Page 1-20 of 21 shown.
  • Click the > to move to the next page. Page redraws showing 1-10 again.
• ✅ Fix Bulk Actions Categorize Slide Out Styling , see details below. Style is not correct.
• ✅ The edit button on each row (in LocationsDataGrid) does not invoke an action.
• ✅ Fix the add tags modal styling, see details below.
• ✅ Drop the With These Properties option from the filter drop down (LocationsFilter)
  • Remove associated React code to show the slide out drawer and render the selectors.
• ✅ Remove the LocationsSearch component from the LocationsTableHeader action bar.
  • Remove associated React code for display as well as related processing that is not in use by the DataGrid Pro implementation.

Revert The Action Bar Styling

The Manage Locations action bar (LocationsTableHeader component) style was changed.
The image below was what it looked like before the Codex GPT-5.6-Sol agent created the React version of the manage locations table.
This styling should have not been changed.

The revised action bar is shown here:

• Color scheme of apply, apply to all, and search buttons have changed.

Bulk Actions Categorize Slide Out Styling

• The apply and apply to all are buttons not the top right as icons next to the close button.
• The categories are following the WordPress hierarchy display

Fix the add tags modal styling

For Review

With These Properties Filter Not Rendering

THIS IS NOT AN ACTIONABLE ITEM. This is a record of the changes made by the AI agent that produced a subpar result.

The “With These Properties” filter can be removed as MUI DataGrid Prod provides more advanced per-column filtering.

The drop down filter menu (rendered via the LocationsFilter component) no longer shows the slide out filter properties selector.

• Select “With These Properties”
• This should show a slide out drawer where a user can pick the properties to filter on (reference first image below), the drawer is not rendering on the visible UI surface (reference second image below).

Feedback Turn 2 : Store Locator Plus plugin version 2607.22.03

Tasks (Issues)

• Click the per-row checkbox does not check the box.
  • Cannot select single rows in the DataGrid.
• ✅ Pagination does not work.
  • Reproduction:
    • There are 25 locations
    • Set page length to 10. Page 1-20 of 21 shown.
    • Click the > to move to the next page. Page redraws showing 1-10 again.

Tasks (Improvements)

• ✅ Separate the latitude and longitude after the business name into two new separate columns on the data grid.
  • Keep the name column pure with only the name rendered.
  • Add the latitude and longitude as separate columns as they are in the database.
  • This may require a back end change depending on how the REST data is procured.
• ✅ Remember the state of the DataGrid columns.
  • The following properties of the DataGridPro should be remembered across page loads or table interactions:
    • Column Order
    • Hidden Columns
    • Filters
    • Sort Order
  • The state should be stored in the browser React state between page refreshes.
  • The state should make a REST call to store this state in the WordPress user meta as well.
    • This will likely require a new REST endpoint.
    • The meta key should start with the SLPLUS_PREFIX plus a name you deem appropriate (maybe csl-slplus-LocationsGridState)?
    • Use that user meta to remember the table state if the user moves off the page to another interface in WordPress and comes back.
    • This will also allow the table to remember the state if a user logs off and comes back the next day.
• ✅ With DataGridPro there is an option to lock the table header (column names) and footer (pagination) and vertically scroll rows in between.
  • The display mode also appears to be able to match the height and width of the DataGridPro to the bounding box.
  • See the demo under the “Pro Version” header at https://mui.com/x/react-data-grid/

Feedback Turn 3 : Store Locator Plus plugin version 2607.23.01

Tasks (Issues)

• ✅ Click the per-row checkbox does not check the box.
  • This issue has been a problem since Turn 1 and is going to need human intervention.
  • Cannot select single rows in the DataGrid.
  • The check/uncheck a single location does not work.

Tasks (Improvements)

• ✅ Remove the LocationsFilter component from the LocationsTableHeader component.
  • The last remaining filter “Show Uncoded” is no longer needed now that latitude and longitude are on the column list.
• Move the latitude and longitude column to be directly after the distance column on initial startup state.
• ✅ When the DataGridPro meta data about column order, hide/show, or filters are in place add notification box above the table to let the user know “Custom table settings are in place. Some columns may be hidden or reordered.”

Feedback Turn 4 : Store Locator Plus plugin version 2607.23.02

Tasks (Improvements)

• Move the notification box about custom columns to the top right.
• Introduce a “Reset” button in the “Custom table settings” notification.
  • When the reset button is clicked, reset the DataGrid state back to the original defaults updating the stored state and related user meta in the process.

Observations

Actions to not need to be taken here. These are findings while reviewing the AI agent work.

• To deal with styling issues with the React components, the AI Agent (Codex 5.6-Sol) added <div className=”react-wrapper”> to the LocationsTable component.
  • This would be more efficient by adding class=”react-wrapper” to the \SLP_Settings_manage_locations_table::display method that builds the div this React component attaches to.
    • Why? It creates one less HTML element the DOM processors need to navigate during processing.

The Settings Interface architecture drives most of the legacy Store Locator Plus admin interfaces. These are the interfaces customers interact with most often, especially on the SaaS platform. It is the main component of the SLP Dashboard for SaaS.

It was originally written to manage the UI surfaces that present the myriad of settings (options) available to customers. It presents the “dials the users turn” to change how their store locator maps and directory presentations are configured. It grew to cover other admin UI interfaces including the Locations Interface.

Research Notes

About SLP_Settings

Extends SLP_Base_ReactObject which extends SLPlus_BaseClass_Object

SLP_Settings::render_settings_page

Outputs the HTML for settings pages, including the location details page (it uses the “settings” page construct). The output all ends up in a HTML element: <div class=’dashboard-wrapper’>…</div>.

General layout:

• <div class=’dashboard-wrapper’>
  • <header id=”dashboard-header” class=”dashboard-header”> = React blue bar header
  • <div class=’dashboard-main store-locator-plus’>
    • <section class=’dashboard-content’>
      • <div id=’wpcsl_container’ …>
        • <form method=’post’ class=’slplus_settings_form’ …>
          • …
          • <div id=”main” class=”dashboard-content-inner panel-settings”>
          • <div id=”wpcsl-nav” class=”sub_navigation”> = from \SLP_Settings::sublevel_navbar
          • <div id=”content” class=”content js settings-content”>

The settings page header

The page header ends up in:

<header id="dashboard-header" class="dashboard-header"><!-- react slp_adminheader --></header>

Which is setup and managed with:

		// -- include the asset file to get the WordPress Scripts defined dependencies and version ID
		$asset = include SLPLUS_PLUGINDIR . 'build/slp_adminheader/script.asset.php';

		wp_enqueue_script( 'slp_adminheader', SLPLUS_PLUGINURL . '/build/slp_adminheader/script.js', $asset['dependencies'], $asset['version'], true );

		wp_add_inline_script( 'slp_adminheader', 'const slpReact = ' . wp_json_encode( $this->get_vars_for_react() ) . ';', 'before' );

Rendered via the React component at
wp-content/plugins/store-locator-plus/src/components/AdminHeader.js

That renders React Components:

• <CssBaseline/>
• <AdminHeader/>

Where <AdminHeader/> renders as:

• <AppBar position=”sticky”>
  • <Toolbar>
    • <Typography variant=”h6″ component=”div”
      sx={{flexGrow: 1}}>{slpReact.pageName}</Typography>
    • {mainButtonGroup}
    • <Tooltip title={__(‘Documentation’, ‘store-locator-le’)}>
      • <IconButton … documentation … />

The settings page sub navbar (menu)

In the current version the header element DOES NOT contain the sub navbar.

It is rendered via SLP_Settings::sublevel_navbar deep inside the <div class=’dashboard-wrapper’>…</div> element.

React Update To Render Subnavbar

The goal is to render the \SLP_Settings::sublevel_navbar HTML output using React instead of the current PHP and HTML implementation.

The AdminHeader at wp-content/plugins/store-locator-plus/src/components/AdminHeader.js renders the top-of-page header with the page name and some interactive icon buttons.

The task is to add a submenu below the Toolbar that is comprised of the sections currently residing in $this->sections in the \SLP_Settings::sublevel_navbar method.  Using the $titleText ($section->name) within.  The wp_kses_post function current used to set $titleText is not necessary as the $section->name is already considered "clean".

The best way to get the variables into React so they are accessible in JavaScript is to modify the \SLP_Base_ReactObject::get_vars_for_react method.  Instead of attempting to override or extend the base \SLP_Base_ReactObject::get_vars_for_react method, add a filter in \SLP_Settings for slp_react_vars.   That will extend the react variable array via this return method on the end of the get_vars_for_react method:
apply_filters( 'slp_react_vars', $defaultVars );

You will find a good reference implementation of the slp_react_vars filter via:
\Customer_Profile_Site_Info::initialize - adds the filter for that class
\Customer_Profile_Site_Info::extendReactVars - extends the available JavaScript variables for React

In our case we are not extending MySLP variables, so the SLP_Settings::extendReactVars method should be more like this:
$vars['SLP']['sections'][] = array( 
'name' => $section->name,
'div_id' => ! empty( $section->div_id ) ? $section->div_id : $section->slug,
'link_id' => "wpcsl-option-{$div_id}"
);
This should be set up by looping through $this->sections in a new extendReactVars method in SLP_Settings.

This should create a horizontal navbar that shows and reveals each section by the div id. This may require further refinement as the current system uses outdated JavaScript and jQuery to hide and reveal subsequent divs by using the div IDS as noted in the link_id property.   For now we will assume that if React renders the components correctly the pre-existing JavaScript will take over.

Initial Results

Works on locations page.
Does not work on Settings page.
Spacing is not well defined, needs more space between menu items.

The locations interface needs a major overhaul.

Let’s investigate the process and where we can start shimming some React components.

Research

Main Loader : Locations | Location Details (SaaS) Menu

• \SLP_Admin_UI::create_admin_menu
  • The main hook attached to \SLP_Admin_UI::$menu_items[‘slp_manage_locations‘]
  • When clicked, fires \SLP_Admin_UI::renderLocationsPage
    • Which calls \SLP_Admin_Locations::display

Locations Page Header (UI)

The locations page is a bastardized combination of the SLP_Settings class and WP_List_Table.

The top-of-page header appears to be handled by SLP_Settings.
SLP_Settings extends SLP_Base_ReactObject
To start rendering the page is calls \SLP_Base_ReactObject::render with these attributes:
– $scriptHandle = ‘slp_settings’
– $scriptFilebase = ‘slp_settings’
This methodology ends up render the SLPSettingsPanel React component (wp-content/plugins/store-locator-plus/src/slp_settings/slp_settings.tsx)

That means the page header is rendering using the Reactionary standard <AdminHeader> for the page.
Currently SLP_Settings is only leverage the pageName property, but it also supports sections as a property which is the submenu.

With the 2606.26.01 release the Settings system uses the React AdminHeader menu.

\SLP_Settings::render_settings_page

• $this->sections may have is_topmenu set, this indicates the top level menus in the app

Locations Card (Defunct?)

This may no longer be used: \SLP_Admin_Locations::create_location_details_box

SLP_Admin_Locations

extends WP_List_Table – this is already going to be a shit show. The WP_List_Table interface is from 1902. Maybe before that. It is awful.

Referenced by:

• \MySLP_Admin::do_admin_startup()
  • Setting the screen property , probably not needed:
    SLP_Admin_Locations::get_instance()->screen = ‘store-locator-plus_page_slp_manage_locations’;
• \SLP_Power_Pages_Admin::extend_location_edit()
  • Only if Store Pages is active, add an edit section to show an “edit Store Page” link
• \SLP_Power_Pages_Admin::set_page_actions()
  • Add the recreate store page action hyperlink under each location on the table
• \SLP_Actions::save_screen_options()
  • To save the screen options, which is currently only the page (table rows) length.
• \SLP_Admin_Locations_Add::
  • initialize
  • extended_data_block – for extended data fields
• \SLP_Admin_UI::renderLocationsPage
  • To render the UI
• \SLP_Location_LoadFromWP::import
  • To only report back any URL the person puts in is invalid.
  • This is called from \SLP_Admin_Locations_Actions::process_actions when the current_action is load_from_wp
  • This is setup from \SLP_Admin_Locations_Load
• \SLP_Settings_manage_locations_table::display
  • A shim for $this->settings->add_ItemToGroup( array(
    ‘group_params’ => $group_params,
    ‘type’ => ‘manage_locations_table’,
    ) );

SLP_Admin_Locations

Hooks & Filters Fired

• slp_locations_manage_bulkactions : creates the list of bulk action dropdown items
  • SLP_Power_Admin_Locations
  • SLP_Experience_Admin
  • SLP_Power_Pages_Admin
• slp_locations_manage_filters : The filter location drop down items
  • SLP_Power_Admin
• slp_locations_manage_cssclass : Adds extra CSS classes
  • SLP_Experience_Admin
• slp_column_data : Change the data rendered in a column
• slp_manage_locations_actionbar_ui : modify the action bar on top of the table
• slp_modify_admin_locations_script_data : modify the script data for the JavaScript on the page
• slp_manage_location_columns
• pls_manage_location_where
• slp_manage_locations_buttons
• slp_build_locations_panels

Not used:

• slp_invalid_highlight
• slp_edit_location_change_extended_data_info
• slp_manage_expanded_location_columns

Screen for WP_List_Table

This is messing up the UI.
Let’s see if we can drop this, start peeling away layers to simplify this interface as we work toward a React version.

locations_per_page

• Tracked via \SLPlus::$userMetaKeys
  • Stored in user meta via \SLP_AJAX::update_slp_user_meta
• \SLP_Actions::init sets a filter on set-screen-option … it calls…
  • \SLP_Actions::save_screen_options … which only runs if the current page is slp_manage_locations… if so it calls…
    • \SLP_Admin_Locations::save_screen_options
      • Which returns the value of locations_per_page

Best option is to make this a React interface for page length / pagination