tablrr docs

Appearance

WordPress Plugin Guide ​

The tablrr WordPress plugin lets you embed your tablrr listings on any WordPress page or post using simple shortcodes. This guide walks you through installation, configuration, and using the plugin to display your affiliate marketing comparison tables.

Table of Contents ​

  1. Getting Started
  2. Domain Verification
  3. Configuration
  4. Using Shortcodes
  5. Cache Management
  6. Troubleshooting
  7. Plugin Updates
  8. Uninstalling the Plugin

Getting Started ​

The tablrr WordPress plugin connects your WordPress site to your tablrr account, allowing you to display beautifully formatted operator comparison tables and grids anywhere on your site. Once configured, you can embed listings using simple shortcodes that automatically update with your latest content.

System Requirements ​

Before installing the plugin, ensure your site meets these requirements:

  • WordPress: Version 6.0 or higher
  • PHP: Version 8.4 or higher
  • HTTPS: Your site must use a secure connection

Note: Check your WordPress and PHP versions in your hosting control panel or contact your hosting provider if you're unsure.

Installation ​

To install the tablrr WordPress plugin:

  1. Download the plugin ZIP file from your tablrr account or the tablrr website
  2. Log in to your WordPress admin dashboard
  3. Navigate to Plugins > Add New
  4. Click Upload Plugin at the top of the page
  5. Click Choose File and select the downloaded tablrr plugin ZIP file
  6. Click Install Now
  7. After installation completes, click Activate Plugin

Once activated, you'll see tablrr in your WordPress admin menu on the left sidebar. Click it to access the plugin settings page.

Note: If you don't have a tablrr account yet, you'll need to create one at tablrr.app before you can use the plugin.

Domain Verification ​

Domain verification ensures your WordPress site is correctly linked to your tablrr account. You must complete domain verification before you can configure your API token and start using the plugin.

What is Domain Verification? ​

Domain verification confirms that you own or control the WordPress site where you're installing the plugin. This security step ensures that only authorized sites can access your tablrr listings.

How to Verify Your Domain ​

To verify your domain:

  1. Go to your tablrr dashboard at app.tablrr.app
  2. Navigate to your site settings or domain settings
  3. Find the verification code for your domain
  4. Copy the verification code
  5. In your WordPress admin, go to tablrr in the menu
  6. Find the Domain Verification section
  7. Paste the verification code into the Verification Code field
  8. Click Verify Domain

After clicking Verify Domain, you'll see a status message indicating whether verification was successful. If verification succeeds, you'll see a green checkmark with the date and time your domain was verified.

Understanding Verification Status ​

  • Verified: Your domain is successfully verified. You can proceed to API token configuration.
  • Not Verified: The verification code is incorrect or expired. Check that you copied the code correctly and try again.

Note: If you change your domain or need to re-verify, you can update the verification code at any time. The plugin will show your current verification status in the settings page.

After your domain is verified, proceed to Configuration to set up your API token.

Configuration ​

After verifying your domain, configure your API connection by adding your API token. This allows the plugin to fetch your listings from your tablrr account.

Prerequisites: Complete Domain Verification before configuring your API token.

Getting Your API Token ​

To get your API token:

  1. Log in to your tablrr dashboard at app.tablrr.app
  2. Navigate to Settings > API Tokens
  3. Click Generate New Token or copy an existing token
  4. Copy the token immediately - you won't be able to see it again after closing the page

Note: Keep your API token secure. Don't share it publicly or commit it to version control.

Entering Your API Token ​

To configure your API token in WordPress:

  1. In your WordPress admin, go to tablrr in the menu
  2. Find the API Configuration section
  3. Paste your API token into the API Token field
  4. Click Save API Settings

You'll see a confirmation message when your settings are saved successfully.

Testing Your Connection ​

After saving your API token, test the connection to ensure everything is working:

  1. In the API Configuration section, find the Connection Test area
  2. Click Test Connection
  3. Wait for the test to complete

Connection Test Results:

  • Success: "Successfully connected to tablrr API" - Your connection is working correctly. You can start using shortcodes.
  • Failure: An error message appears - Check the troubleshooting section below for solutions.

Note: If the connection test fails, verify that your API token is correct and that your domain is verified. Connection issues are usually caused by incorrect tokens or unverified domains.

Using Shortcodes ​

Once your domain is verified and your API token is configured, you can embed tablrr listings anywhere on your WordPress site using shortcodes.

Basic Shortcode Format ​

The basic shortcode format is:

[tablrr id="your_listing_public_id"]

Replace your_listing_public_id with the actual public ID of the listing you want to display.

Finding Your Listing Public ID ​

To find your listing's public ID:

  1. Log in to your tablrr dashboard
  2. Go to Listings
  3. Find the listing you want to embed
  4. Copy the Public ID or look for the WP Shortcode field
  5. Use this ID in your shortcode

Example: If your listing's public ID is abc123def456, your shortcode would be:

[tablrr id="abc123def456"]

Where to Use Shortcodes ​

You can use the [tablrr] shortcode in:

  • Posts: Add the shortcode directly in the post editor
  • Pages: Insert the shortcode anywhere in page content
  • Widgets: Use shortcodes in text widgets (if your theme supports it)
  • Page builders: Most page builders support shortcodes in their content blocks

Note: The shortcode renders the complete listing with all formatting, styles, and interactivity configured in your tablrr dashboard.

Using Multiple Listings ​

You can use multiple shortcodes on the same page to display different listings:

[tablrr id="abc123def456"]

[tablrr id="xyz789ghi012"]

Each listing displays independently with its own styling and content.

Custom Styling with Class Attribute ​

You can add a custom CSS class to your shortcode for additional styling:

[tablrr id="abc123def456" class="my-custom-class"]

This adds the class my-custom-class to the listing wrapper, allowing you to apply custom CSS from your theme.

Note: The listing will still use its tablrr-configured styles. The custom class is added as an additional wrapper class for your theme's CSS to target.

Cache Management ​

The plugin automatically caches listing content to ensure fast page loads. Understanding how caching works helps you know when content updates and when to manually clear the cache.

What is Caching? ​

Caching stores a copy of your listing content locally on your WordPress site. Instead of fetching content from the tablrr API every time someone visits your page, the plugin uses the cached version, which loads much faster.

How Long Content is Cached ​

Listing content is cached for 1 hour (3600 seconds). After one hour, the cache automatically expires and fresh content is fetched from the tablrr API the next time someone views the page.

Note: This means changes you make in your tablrr dashboard may take up to 1 hour to appear on your WordPress site, unless you manually clear the cache.

When Content Updates Automatically ​

Content updates automatically when:

  • The cache expires after 1 hour
  • Someone visits the page after the cache has expired
  • The plugin is updated or reactivated

When to Manually Clear Cache ​

Clear the cache manually when:

  • You've made changes in your tablrr dashboard and want them to appear immediately
  • You're testing changes and need to see updates right away
  • You suspect cached content is outdated or incorrect

How to Clear Cache ​

To clear all cached listings:

  1. In your WordPress admin, go to tablrr in the menu
  2. Find the Cache Management section
  3. Click Clear Cache
  4. Wait for the confirmation message

After clearing the cache, the next time someone visits a page with a tablrr shortcode, fresh content will be fetched from the tablrr API.

Note: Clearing the cache affects all listings on your site. Individual listings cannot be cleared separately.

Troubleshooting ​

This section helps you resolve common issues you might encounter while using the tablrr WordPress plugin.

Connection Issues ​

Unable to Connect to tablrr API ​

Issue: Connection test fails or you see "Unable to connect to tablrr API" errors.

Solution:

  1. Verify your API token is correct in the API Configuration section
  2. Ensure your domain is verified (check the Domain Verification section)
  3. Check that your site has an active internet connection
  4. Try saving your API token again
  5. Run the connection test again

If the issue persists, your API token may have been revoked. Generate a new token in your tablrr dashboard and update it in WordPress.

Connection Test Failing ​

Issue: The connection test button shows an error.

Solution:

  1. Make sure you've saved your API token before testing
  2. Verify your domain is verified
  3. Check that your WordPress site can make outbound HTTP requests
  4. Try deactivating and reactivating the plugin
  5. Contact support if the problem continues

Invalid API Credentials ​

Issue: Error message indicates invalid API credentials.

Solution:

  1. Go to your tablrr dashboard and verify your API token is still active
  2. Generate a new API token if needed
  3. Copy the new token carefully, ensuring no extra spaces
  4. Paste it into the API Token field in WordPress
  5. Click Save API Settings
  6. Test the connection again

Display Issues ​

Listing Not Showing on Page ​

Issue: Shortcode is in your content but nothing appears on the frontend.

Solution:

  1. Verify the shortcode syntax is correct: [tablrr id="your_id"]
  2. Check that the listing public ID is correct
  3. Ensure your API token is configured and connection test passes
  4. Check that the listing exists and is published in your tablrr dashboard
  5. View the page as an administrator - error messages are only visible to admins
  6. Clear your browser cache and refresh the page

Note: If you're logged in as an administrator, you'll see error messages if something is wrong. Regular visitors won't see these messages.

Listing Not Found Error ​

Issue: You see "[tablrr] error: Listing not found" (visible to admins only).

Solution:

  1. Verify the listing public ID in your shortcode matches the ID in your tablrr dashboard
  2. Check that the listing is published and active in tablrr
  3. Ensure your API token has access to this listing
  4. Try the connection test to verify your API credentials are working
  5. Clear the cache and refresh the page

Shortcode Not Working ​

Issue: Shortcode appears as text instead of rendering the listing.

Solution:

  1. Ensure the shortcode is formatted correctly with square brackets: [tablrr id="your_id"]
  2. Check that the plugin is activated
  3. Verify you're using the correct shortcode name: tablrr (not tablrr_listing or similar)
  4. Try removing and re-adding the shortcode
  5. Check if your theme or another plugin is interfering with shortcodes

Styling Looks Wrong ​

Issue: Listing displays but styling appears broken or incorrect.

Solution:

  1. Clear the plugin cache (see Cache Management)
  2. Check your theme's CSS isn't overriding tablrr styles
  3. Verify the listing's styling in your tablrr dashboard
  4. Clear your browser cache
  5. Check for JavaScript errors in your browser's developer console

Content Issues ​

Content Not Updating ​

Issue: Changes made in tablrr dashboard don't appear on your WordPress site.

Solution:

  1. Clear the plugin cache (content is cached for 1 hour)
  2. Wait for the cache to expire naturally (1 hour)
  3. Verify changes are saved in your tablrr dashboard
  4. Check that you're viewing the correct listing
  5. Refresh the page after clearing cache

Note: Due to caching, changes may take up to 1 hour to appear automatically. Clear the cache to see changes immediately.

Changes Not Appearing ​

Issue: You've made updates but they're not showing on your site.

Solution:

  1. Clear the plugin cache from the Cache Management section
  2. Verify the changes are saved in your tablrr dashboard
  3. Check you're using the correct listing public ID in your shortcode
  4. View the page in an incognito/private browser window to bypass browser cache
  5. Wait a few minutes and refresh - sometimes CDN or server caching delays updates

Old Content Showing ​

Issue: Outdated content is still displaying even after making changes.

Solution:

  1. Clear the plugin cache immediately
  2. Clear your browser cache
  3. Check your hosting provider's caching (if using a caching plugin or CDN, clear those caches too)
  4. Verify the correct listing ID is in your shortcode
  5. Check that changes are actually saved in your tablrr dashboard

Error Messages ​

Understanding Error Messages ​

Error messages in the plugin use plain language to describe what went wrong. Here are common error messages and what they mean:

  • "Listing not found" - The listing ID in your shortcode doesn't exist or you don't have access to it
  • "Invalid API credentials" - Your API token is incorrect or has been revoked
  • "Unable to connect to tablrr API" - The plugin can't reach the tablrr servers (network issue or API problem)
  • "Rate limit exceeded" - Too many requests in a short time (usually resolves automatically)
  • "Content temporarily unavailable" - A temporary server issue (try again later)

Note: Error messages are only visible to WordPress administrators. Regular site visitors won't see error messages - they'll simply see nothing where the listing should appear.

What Users See vs. What Admins See ​

  • Administrators: See detailed error messages with error codes to help diagnose issues
  • Regular visitors: See nothing (blank space) where the listing should appear if there's an error

This prevents confusing error messages from appearing to your site visitors while giving you the information needed to fix issues.

When to Contact Support ​

Contact support if:

  • Connection test fails after verifying your API token and domain
  • Error messages persist after following troubleshooting steps
  • Listings work in tablrr dashboard but not on your WordPress site
  • You're unable to verify your domain
  • Plugin updates fail or cause errors

When contacting support, include:

  • The exact error message you're seeing
  • Steps you've already tried
  • Your WordPress and PHP versions
  • Whether the connection test passes or fails

Plugin Updates ​

The tablrr WordPress plugin checks for updates automatically and notifies you when new versions are available. Keeping your plugin updated ensures you have the latest features and security improvements.

How Updates Work ​

The plugin checks for updates by connecting to the tablrr update server. This happens automatically in the background, similar to how WordPress checks for core and other plugin updates.

Note: The plugin uses a custom update mechanism, not the WordPress.org plugin directory. Updates come directly from tablrr.

When Updates Are Available ​

You'll see update notifications in your WordPress admin when:

  • A new version of the plugin is released
  • You visit the Plugins page in WordPress admin
  • WordPress checks for updates (happens automatically)

Update notifications appear as a banner or notice on the Plugins page, similar to other WordPress plugin updates.

How to Update the Plugin ​

To update the plugin when a new version is available:

  1. Go to Plugins in your WordPress admin menu
  2. Find tablrr in the list of plugins
  3. If an update is available, you'll see an Update Now link
  4. Click Update Now
  5. Wait for the update to complete
  6. The plugin will automatically reactivate after updating

Note: You can also update multiple plugins at once using the bulk update feature on the Plugins page.

What Happens During Updates ​

During the update process:

  1. WordPress downloads the new plugin version
  2. The old version is replaced with the new version
  3. Plugin cache is automatically cleared
  4. The plugin reactivates automatically
  5. Your settings and configuration are preserved

Note: Your API token, domain verification, and other settings remain intact after updates. You don't need to reconfigure the plugin.

Automatic vs. Manual Updates ​

  • Automatic updates: The plugin can be set to update automatically (if enabled in WordPress settings)
  • Manual updates: You control when to update by clicking Update Now on the Plugins page

Note: It's recommended to update plugins during low-traffic periods and to test your site after updating to ensure everything works correctly.

Uninstalling the Plugin ​

If you need to remove the tablrr WordPress plugin from your site, follow these steps to uninstall it cleanly.

When You Might Want to Uninstall ​

You might want to uninstall the plugin if:

  • You're no longer using tablrr listings on your site
  • You're switching to a different solution
  • You're troubleshooting issues and want a fresh start
  • You're decommissioning the site

Note: Uninstalling the plugin removes all plugin data. If you might use the plugin again, consider deactivating it instead of uninstalling.

How to Deactivate the Plugin ​

To temporarily disable the plugin without removing it:

  1. Go to Plugins in your WordPress admin menu
  2. Find tablrr in the plugin list
  3. Click Deactivate

Deactivating preserves all your settings and data. You can reactivate it later without reconfiguration.

How to Uninstall the Plugin ​

To completely remove the plugin:

  1. Go to Plugins in your WordPress admin menu
  2. Find tablrr in the plugin list
  3. Click Deactivate (if currently active)
  4. Click Delete
  5. Confirm deletion when prompted

Warning: Uninstalling permanently removes the plugin and all its data. This cannot be undone.

What Data is Removed ​

When you uninstall the plugin, the following data is removed:

  • Plugin files and code
  • All cached listing content
  • API token and configuration settings
  • Domain verification data
  • All plugin options stored in the database

What Data is Preserved ​

The following data is not removed and remains on your site:

  • WordPress posts and pages (shortcodes remain as text but won't render)
  • Your WordPress site content and settings
  • Other plugins and their data
  • Your theme and theme settings

Note: After uninstalling, any [tablrr] shortcodes in your content will appear as plain text and won't render listings. You may want to remove or replace these shortcodes manually.

Re-installation Considerations ​

If you reinstall the plugin later:

  • You'll need to complete domain verification again
  • You'll need to configure your API token again
  • All cached content will be regenerated
  • Shortcodes in your content will start working again once configured

Your tablrr account and listings remain unchanged - only the WordPress plugin connection is removed.

Next Steps ​

Now that you've set up the tablrr WordPress plugin, here's what to do next:

  1. Create or select listings in your tablrr dashboard that you want to display
  2. Add shortcodes to your pages using the format [tablrr id="your_id"]
  3. Test your listings by viewing pages on the frontend
  4. Monitor performance and clear cache when needed
  5. Keep the plugin updated to ensure you have the latest features

For more information about creating and managing listings, visit the listings guide.