1. Home
  2. WordPress Plugins
  3. OOW PJAX
  4. Documentation

OOW PJAX

OOW PJAX DOCUMENTATION

Plugin Overview

OOW PJAX, developed by OOWCODE and OOWPRESS, transforms your WordPress site into a fast, seamless navigation experience using PJAX (PushState + AJAX). By replacing full page reloads with dynamic content updates, it delivers an app-like feel while maintaining compatibility with any WordPress theme. Built with pure JavaScript (no jQuery), version 1.1 introduces advanced features like script priority control, page-specific style injection, and fine-grained script execution, making it ideal for portfolios, blogs with persistent media players, or dynamic content sites.

How It Works

OOW PJAX intercepts internal link clicks and form submissions, loading content via AJAX and updating the browser’s URL using the History API. Key steps include:

  • Link Interception: Captures clicks on internal links, skipping external links, target="_blank", or excluded selectors (e.g., .no-pjax).
  • AJAX Loading: Fetches new page content and scripts without reloading the entire page.
  • Content Update: Replaces specified containers (e.g., #main, .content) with new content.
  • URL Synchronization: Updates the browser’s URL for natural forward/back navigation.
  • Persistent Elements: Preserves fixed elements (e.g., media players, sticky headers) during transitions.
  • Style Injection: Optionally injects page-specific stylesheets and inline styles for consistent rendering.
  • Script Management: Re-executes scripts in updated containers, footer, or inline scripts with strict validation.
  • Caching: Stores pages locally for instant repeat visits (disabled for logged-in users).
  • Loading Indicator: Displays a customizable overlay during transitions.

Why Use OOW PJAX?

  • Lightning-Fast Navigation: Reduces load times by avoiding full page reloads.
  • Seamless User Experience: Delivers smooth, app-like transitions for better engagement.
  • Persistent Elements: Keeps media players, menus, or widgets active during navigation.
  • Lightweight & Modern: Uses vanilla JavaScript, no jQuery, for optimal performance.
  • Developer-Friendly: Offers custom events, script priority control, and debug tools.
  • Secure Implementation: Employs nonces, sanitization, and script validation.
  • Theme-Agnostic: Works with any WordPress theme via customizable containers.
  • SEO-Friendly: Maintains proper URLs and history for search engine compatibility.

Configuration and Settings

Configure OOW PJAX in the Settings tab (OOWCODE > OOW PJAX > Settings). Below is a detailed breakdown of each setting:

SettingDescriptionValueUsageExample
Enable PJAX (oow_pjax_enabled)Activates or deactivates PJAX functionality.Checkbox (enabled by default)Check to enable PJAX; uncheck for standard WordPress navigation.Enable to start using PJAX.
Target Containers (oow_pjax_targets)HTML containers to update with AJAX content.Space-separated CSS selectors (default: #main)Specify IDs or classes for your theme’s content area. Inspect source code to find the correct container (e.g., <div id="main">).#main .content updates multiple containers.
Exclude Selectors (oow_pjax_exclude_selectors)Links or elements to exclude from PJAX.Space-separated CSS selectors (empty by default)Bypass PJAX for specific links (e.g., popups, .no-pjax) or elements like #wpadminbar..no-pjax #player-controls excludes media player controls.
Exclude External Links (oow_pjax_exclude_external)Excludes links to external domains.Checkbox (enabled by default)Prevent PJAX from loading external content (e.g., https://example.com).Uncheck only if external content loading is desired (rare).
Exclude Links with target=”_blank” (oow_pjax_exclude_target_blank)Excludes links opening in new tabs.Checkbox (enabled by default)Respects standard behavior of target="_blank" links.<a target="_blank"> opens in a new tab without PJAX.
Enable Cache (oow_pjax_enable_cache)Caches pages for faster repeat visits.Checkbox (disabled by default)Enable for sites with frequent internal navigation. Disabled for logged-in users.Enable for a blog with heavy article browsing.
Cache Lifetime (oow_pjax_cache_lifetime)Duration (in seconds) pages remain cached.Integer (default: 300 seconds)Adjust based on content update frequency. Set to 0 for no expiration.3600 (1 hour) for static sites; 300 for dynamic sites.
Custom Events (oow_pjax_custom_events)Triggers custom JavaScript events during PJAX.Space-separated event names (empty by default)Add events (e.g., pjax:before, pjax:after) for custom scripts like analytics or media players.pjax:before pjax:after for event listeners.
Enable Debug Mode (oow_pjax_debug_mode)Logs detailed information in the browser console.Checkbox (disabled by default)Enable temporarily to diagnose issues (e.g., AJAX errors, selector issues).View logs in browser console (F12).
Enable Loader (oow_pjax_enable_loader)Shows a loading overlay during transitions.Checkbox (enabled by default)Inform users of loading. Disable for no visual indicator.Spinner appears during content loading.
Loader CSS (oow_pjax_loader_css)Customizes the loading overlay’s appearance.CSS code (default: circular spinner)Modify CSS for brand alignment. Use Reset to Default to revert.border: 5px solid #0073aa for a blue spinner.
Minimum Loader Duration (oow_pjax_min_loader_duration)Minimum loader display time (in milliseconds).Integer (default: 200 ms)Prevent loader from disappearing too quickly on fast connections.500 ms ensures visibility for half a second.
Enable Form Handling (oow_pjax_enable_forms)Submits forms via AJAX.Checkbox (disabled by default)Enable for seamless form submissions (e.g., comments, login). Test compatibility.Comment form submits without reloading.
Script Priority (oow_pjax_script_priority)Sets the loading order of oow-pjax.js in the footer.Integer (default: 9999)Use a high value to load PJAX after other scripts for compatibility.9999 ensures late loading.
Enable Page-Specific Styles (oow_pjax_enable_page_styles)Injects page-specific stylesheets and inline styles.Checkbox (disabled by default)Enable to maintain consistent styling during transitions.Enable for themes with unique page styles.
Enable Script Re-execution (oow_pjax_enable_reexecute_scripts)Re-runs scripts in updated containers.Checkbox (disabled by default)Enable for dynamic content requiring script reinitialization (e.g., sliders).Enable for a gallery in #main.
Enable Footer Scripts Execution (oow_pjax_enable_footer_scripts)Executes footer scripts from AJAX responses.Checkbox (disabled by default)Enable for plugins relying on footer scripts.Enable for analytics or chat widgets.
Enable Inline Scripts Execution (oow_pjax_enable_inline_scripts)Executes inline scripts with strict validation.Checkbox (disabled by default)Enable for inline scripts in AJAX content, ensuring security.Enable for custom inline JavaScript.

Tips for Optimal Configuration

Identify Theme Containers

  • Inspect source code (right-click > Inspect) to find the main content container (e.g., #main, .content).
  • Test with one selector before adding multiple to avoid conflicts.

Test Exclusions

  • Add .no-pjax to links bypassing PJAX (e.g., PDFs, popups).
  • Exclude persistent elements like media player controls (e.g., #player-controls).

Customize the Loader

  • Modify Loader CSS to match your brand (e.g., use theme colors).
  • Ensure visibility on all devices, including mobile.

Optimize Script Loading

  • Set Script Priority to a high value (e.g., 9999) if other scripts conflict with PJAX.
  • Test Enable Script Re-execution for dynamic content like sliders or galleries.

Style Injection

  • Enable Enable Page-Specific Styles for themes with unique page styles.
  • Verify styles load correctly in the browser’s developer tools.

Use Debug Mode

  • Enable Debug Mode to log AJAX requests, script execution, and errors.
  • Check the console (F12) for detailed logs.

Test Caching

  • Enable Enable Cache and set Cache Lifetime for frequently visited pages.
  • Ensure dynamic content (e.g., comments) updates correctly with caching plugins.

Form Compatibility

  • Test all forms (e.g., Contact Form 7, login) with Enable Form Handling enabled.
  • Disable if compatibility issues arise and contact support.

Example Configuration

For a WordPress site using a theme like Astra:

  • Enable PJAX: Enabled
  • Target Containers: #main .content
  • Exclude Selectors: .no-pjax #player-controls .wp-block-button
  • Exclude External Links: Enabled
  • Exclude Links with target=”_blank”: Enabled
  • Enable Cache: Enabled
  • Cache Lifetime: 3600 (1 hour)
  • Custom Events: pjax:before pjax:after
  • Enable Debug Mode: Disabled (enable for troubleshooting)
  • Enable Loader: Enabled
  • Loader CSS: border: 5px solid #0073aa (theme color)
  • Minimum Loader Duration: 300 ms
  • Enable Form Handling: Enabled
  • Script Priority: 9999
  • Enable Page-Specific Styles: Enabled
  • Enable Script Re-execution: Enabled
  • Enable Footer Scripts Execution: Enabled
  • Enable Inline Scripts Execution: Disabled (enable if needed)

Troubleshooting

Content Not Loading

  • Verify Target Containers selectors are correct (e.g., #main exists).
  • Enable Debug Mode to check console for AJAX errors.

Loader Not Displaying

  • Ensure Enable Loader is checked and Loader CSS isn’t overridden.
  • Check for conflicting CSS in the browser’s developer tools.

Scripts Not Executing

  • Enable Enable Script Re-execution or Enable Footer Scripts Execution for dynamic content.
  • Verify Script Priority is high enough (e.g., 9999) to avoid conflicts.

Styles Not Applying

  • Enable Enable Page-Specific Styles and check for stylesheet conflicts.
  • Use browser tools to inspect loaded styles.

Forms Not Working

  • Test without Enable Form Handling to isolate issues.
  • Ensure form plugins (e.g., Contact Form 7) are compatible.

Plugin Conflicts

  • Add conflicting plugin selectors to Exclude Selectors.
  • Temporarily disable other plugins to identify conflicts.

Support