Search Widget

Installation

  1. Download the zip file mentioned in the WPSL receipt.
  2. Log into your WordPress Admin area and go to Plugins > Add New.
  3. Click Upload Plugin on the top of the page.
  4. Select the zip file you downloaded in step 1.
  5. Click Install Now.
  6. Once the installation is complete, activate the plugin.

You can enable the widget under Appearance > Widgets by dragging it to one of the widgetized areas in your theme.

Search Widget

Activate License

You can find your license key in your purchase receipt, and in the ‘License Keys’ section on the account page.

Activate your license on the WPSL settings page under the ‘Licenses’ tab.

A valid license key is required in order to get automatic upgrades and support.

Configuration Options

Search widget options

Used widget template
This option is only visible when a custom template is available, and it allows you to select the used search widget template.

Title
The main title of the search widget.

Search label
This is shown directly above the search input field. If this field is left empty, then it will default to “Enter your location”.

Search field placeholder
This is the default text shown inside the search input field. You can for example set it to “city or zipcode”.

Enable autocomplete?
This activates the Google Maps autocomplete function for the search field.

Attempt to auto-locate the user?
This will try to automatically determine the users location with help from the HTML 5 Geolocation API.

Users can manually trigger geolocation requests?
This renders an icon next to the submit button that users can use to automatically set the value of the input field to their current location.

Show store category filter
If this option is enabled, a dropdown holding the store category names is shown under the search input field.

Category label
This is shown directly above the store category dropdown.

Select the page where you added the [wpsl] shortcode
After the user submitted the search form, the search results are shown on this page.

Shortcode

The code below shows the wpsl_widget shortcode with all the supported attributes.

[wpsl_widget title="Find Nearby Dealers" search_label="Your location" search_placeholder="zipcode" category_filter="true" category_label="Select Category" auto_locate="false" manually_locate="true" autocomplete="true" page_id="xxx" template="default"]

The page ID
The only required attribute is the page_id. The value for the page_id is the ID of the page where the wpsl shortcode is used. Without this value the widget will not be able to pass the widget input to the store locator.

You can find the page ID by opening the store locator page in the admin area and look for post=xxx in the URL bar. The xxx is the ID you need to include in the shortcode.

Post ID

So based on the above image you would do [wpsl_widget page_id="100583"].

Selecting A Template
The template attribute expects the ID value that’s used to load a custom template.

So if you loaded a custom template with this code, then you can use it in the shortcode like this [wpsl_widget template="custom"].

If the template attribute isn’t set, or contains an invalid value, then it will always load the default template.

Use A Custom Template

In case you like to modify the HTML structure of the search widget, then you can do so by using a custom template.

  1. If it doesn’t exist yet, create a wpsl-templates folder inside your active theme folder.
  2. Inside the wpsl-templates folder create a new file called custom-widget.php.
  3. Copy the code below and place it in the custom-widget.php that you just created. Modify this code to your needs.

    <?php
    $search_widget = new WPSL_Search_Widget();
    
    if ( $template_data['category_filter'] ) {
        $category = $search_widget->create_category_filter( $template_data );
    }
    ?>
    <form action="<?php echo get_permalink( $template_data['page_id'] ); ?>" method="post" id="wpsl-widget-form">
        <?php do_action( 'wpsl_before_widget_input' ); ?>
        <p>
            <label for="wpsl-widget-search"><?php echo esc_html( $template_data['search_label'] ); ?></label>
            <input type="text" name="wpsl-widget-search" placeholder="<?php echo esc_attr( $template_data['search_placeholder'] ); ?>" id="wpsl-widget-search" value="" >
        </p>
        <?php
        do_action( 'wpsl_after_widget_input' );
    
        if ( isset( $category ) ) {
            echo $category;
    
            do_action( 'wpsl_after_widget_category' );
        }
        ?>
        <p>
            <input id="wpsl-widget-submit" type="submit" value="<?php _e( 'Search', 'wpsl-widget' ); ?>">
            <?php if ( $template_data['manually_locate'] ) { ?>
                <span class="wpsl-icon-direction" title="<?php _e( 'Use your current location', 'wpsl-widget' ); ?>">&#xe800;</span>
            <?php } ?>
        </p>
    </form>
  4. Place the following code in the functions.php in your active theme folder. This will load the custom-widget.php template from the wpsl-templates folder in your theme folder.

    add_filter( 'wpsl_widget_templates', 'custom_widget_templates' );
    
    function custom_widget_templates( $templates ) {
    
        /**
         * The 'id' is used in the shortcode and accessible with [wpsl_widget template="the-used-id"]
         * The 'name' is shown in the widget configuration screen.
         * The 'path' points in this example to a 'wpsl-templates' folder inside your theme folder.
         * The 'file_name' is the name of the file that contains the custom template code.
         */
        $templates[] = array (
            'id'        => 'custom',
            'name'      => 'Custom template',
            'path'      => get_stylesheet_directory() . '/' . 'wpsl-templates/',
            'file_name' => 'custom-widget.php'
        );
    
        return $templates;
    }
  5. Call the custom template through the shortcode [wpsl_widget template="custom"], or select it on the widget configuration screen.

Notes

If you’re using the wpsl_templates filter to load a custom template, then make sure to include the following two things to make it compatible with the search widget.

  • Use the wpsl_search_input filter in the value field . This is required to pass the search value from the search widget to the input field in the store locator.

    The search input field with support for the search widget looks like this:

    <input autocomplete="off" id="wpsl-search-input" type="text" value="' . apply_filters( 'wpsl_search_input', '' ) . '" name="wpsl-search-input" />
  • Make sure there’s a way for the widget to add the wpsl-widget class to the outer template div. This class is used in the JS script to determine if it needs to automatically trigger the store search on page load.

    The required classes are added by including the $this->get_css_classes(); code on the outer template div.