Ajax Search Pro for Wordpress

Ajax Search Pro for Wordpress by WPDreams


Ajax Search Pro is a professional ajax search engine for WordPress. (ver 2.3)

Very important section for those who are updating from previous versions!

Before installing over an older version of the search please:

 

The package from codecanyon contains this documentation and a file named ajax-search-pro.zip. 

Installing a plugin in WordPress is the easiest thing in the world!
In this steb-by-step instruction guide you will learn this procedure and you can use it with any other plugin out there!

  1. Login to administrator area
    To login to your wordpress administrator area you must go to http://yoursitename.com/wp-admin page.
  2. Opening the plugins tab
    Open up the plugins tab from the right menu bar. After the plugins page loads click on add new!

     
  3. Upload and Install!
    Select the Upload option from the list and upload the polaroid-slider.zip file and hit install! After the successful installation click on activate plugin!



     
  4. That's it!
    This is the way of installing plugins in WordPress from the envato marketplaces.
    You should now be able to see the plugin in the activated plugins list.

Creating a search form is a piece of cake after you have installed the plugin. A menu called "Ajax Search Pro" should appear on the administrator area (on the right) usually right above the Settings menu.

By clicking on this item brings up the Ajax Search Pro settings page. Here you can add, remove and modify the search forms. Normally it would not require to add a search form, but since it is possible to add more search forms onto your page it is neccesary to configure each search form one by one.

Click on the "Ajax Search Pro" menu item, and you should see the following screen:

 

Okay, let's add a new search form. Name it whatever you like, I will name it Main page

 

As you can see the page refreshes and the new search item is there, ready to use.

This new item has some interesting icons and input fields available. The settings icon will open the search settings, the red x is for removing the search form and the two imput fields are the shortcodes. One is for the posts and the other one is for templates. This means, that you can place the search inside a post or page, by copy/pasting the contents of the "Search Shortcode" input field. If you want to place the search in your template, then all you need to do is to grab the content of the other input field, paste it into your template file and you are ready to go!

There is also a possibility to add the search as widget. You ha two options:

  1. Go to the widgets page, place the Ajax Search Pro widget onto the page, select the search and save it.
  2. ...or grabbing the search shortcode and placing it in a text widget.

It's you to choose. Usually the second option is useful if you want something else to put into the text widget box, not only the search plugin.

Easy as 1-2-3. In the next sections I will explain the search options step by step.

Lets open up the settings, by clicking on the small gear icon next to the red x icon on one of the search items.

A huge menu should slide down, and you should see the options categorised.

The general Options

As you can see, the general options contain the most essential information about the search form. These otpiojns determine the overall behaviour of the search form. 

Let's see the explanation of these options one by one. I will skip to the keyword suggestion part, since the options above it are straigthforward, I can add nothing to them.

I recommend setting this height and the image height to the same.

Image Settings

This part requires a little more explanation. You can turn on/off the images in general. The images will be parsed and cached in the search cache folder for future use. This enhances the speed of the search engine. You can then set the sources of the image. Each source can have it's own priority: Low, Medium, High and Don't use.
The default settings are working as following:
The plugin searches for images in the featured image content. If there is no image, then tries to parse the post content and grabs the first image. If the post content does not have any image, then the plugin tries to fetch the post excerpt and grab the first image. If an image was found, then it will be resized and cached by it's name.
Possible sources:

All you need to do is to assign the priorities. If you would like to show images only from post content, then set the post content to Hight Priority and the other items to Dont't use. I think it is all cleared with images.

If you set no to Search in posts, Search in pages and Search in products, then there will be no results whatsoever. The same thing applies to Search in content, Search in title, Search in excerpt.

After setting up the general behaviour of the search, there are two more settings groups besides themes.

You can set up the frontend settings and the search layout.

Frontend Search Settings options

 

As you may have already noticed, there is a settings icon on the search plugin on the frontend. With these options you can manage which checkboxes do you want to show for the user. If you set all to No, then no settings icon will appear.

The default value of the checkboxes on the frontend are the values set in the general options section.

These selectors highly increase the user experience, I dont recommend to turn all of the off.
You can also set the highlight text for each option. It's good for translations.

Show search in custom post types selector - Drag and drop the custom post type selectors as you like. You can add the text you want to show on the frontend for each selector!

Layout options

 

You can remove some of the ascpects from the results list like author, date, description.

Note, that removing the title is not possible, since it is essential for the user to navigate to the correct url.

The No results text and the Did you meand text options are letting you set the text to show when there are no results, and when the keyword suggestions are shown.

Text Highlighting is for highlighting the search term in the result box. You can change the font color and the font background color of the hightlighted text. The Highlight only whole words option determines, wheter only exact matched words should be hihglighted, or all the words should be highlighted in the results separately.

By setting up the layout you are ready to modify the template of the search plugin.

Every result gets a relevance value based on the weight numbers. You can set these numbers in the relevance options panel. The weight is the measure of importance. When two results have the same relevance value, then the default ordering will be used to determine their position. You can change this ordering on the general options tab. (Result ordering option)

Exact matches weight - when the whole search term exatly matches the text. 

For example, the search term "lorem ipsum" has an exact match in the following text:

"Lorem ipsum sit dolor amet creetum indos piratom."

Random matches weight - when parts of search term matches the text. 

For example, the search term "lorem dolor test" has an exact match in the following text:

"Lorem ipsum sit dolor amet creetum indos piratom."

 

In other words, put the highest number to the field that is the most relevant to your search, and put the lowest number to the field that is the least relevant.

The theme options page is a little more wider, then the other option groups. With these options you can define the whole layout of the search. By customising it to the right color/font scheme will improve the user experience.

I have created two images for better understanding the parts of the search plugin on the frontend. You will find each these options on the theme settings group.

Every single option on the theme settings group refers to ethier one of these areas. I will not explain them one by one, it is unneccessary, rather I will explain the usage of each option type.

The preview

You can preview each one of your search forms before saving. After opening up the search settings you can click on the show button on the bottom left corner of the page. This will bring up the search preview. After making some changes in the theme options click on the refresh button and the preview will refresh with the new options.

Theme chooser

This option contains all the pre-defined themes. After selection the preview area will refresh and the values of the settings will change accordingly.

Gradient Selector

Gradient selector is for selecting two colors fading at each other at the selected axis. You can set the axis, angle and the colors. By selecting two identical colors the angle and the axis have no effect. 

 

Border Options

This option was designed directly for border settings. You can set the border width, border style and border radius as well.

 

Box shadow

The box shadow is a css3 option, this means, that it has no effect in older browser such as internet exploder 7 or 8 and some mobile browsers.
Still, it is no reason to not to use this option for modern designing.

 

The offsets determine the shadow position and the blur, spread it's size. The offset is always calculated from the left top corner of the affected element. Feel free to experiment, if you havent worked with box shadows yet!

Font options

The essentials of the layout lays in fonts. A good font choice can change everything. This font chooser has more than 50 built in fonts, some of them are from the google web fonts directory.

 

By using many different google fonts can slow down your site! Stick to 1-2 font types if possible.


These are the main option types for the theme editing. I recommend to use the built in themes and then edit them for your own needs. After editing one option you can always hit the refresh button on preview to see the changes.

Advanced options lets you customize the search on a higher level.

Custom title & Description

If you want to show extra fields in title or in description - like price fron Woocommerce or other custom field, then you need to edit the following fields:

Explanation:

You can add any text to this fields and use custom pseudo-code in {custom_field_name} format. There are two pre-defined pseudo-codes:

  1. {titlefield} - this will display the actual title, that had been parsed from the database
  2. {descriptionfield} - this will display the actual description, that had been parsed from the database

For example, if you want to show the price separated by "-" in the title on a WooCommerce product, then your configuration should look like this:

The "_price" is the custom field name in WooCommerce for the current product price, and we want the currency as well, so we put the "$" sign after. The results will look like this:

As you can see, the price is now added before the title, followed by the "$" sign and  the "-" character. 

You can add as many custom fields as you want,  there is no limit!

 

This part of the documentation is for advanced users and developers only!

API is for accessing the search from another client based application.

You can access one search method from outside the application, this method is triggering an input change and forces the search to actually "search".

Getting the search node

Look up the id of the search you want to access, it's in the end of the shortcode. ex.: if the ['wpdreams_ajaxsearchpro id=1'] is the shortcode, then the id is 1.

The search node has the following id: #ajaxsearchpro+id, in this case #ajaxsearchpro1

This is the id of the node which contains the function you want to call.

Triggering a search

The api syntax is the following:

jQuery(#ajaxsearchpro1).ajaxsearchpro(method, params);

To trigger a search, you need to call the searchfor method with the keyword you want:

jQuery(#ajaxsearchpro1).ajaxsearchpro('searchfor', 'keyword');

As you can see, in the previous section we got the node id, and there is the syntax to trigger the search. It actually calls the searchfor method with the keyword parameter. You can replace the keyword with whatever you want.

This section is for advanced users/developers only!

As from version 2.0 actions and filters were added to the search plugin. You can read more about the general use of actions/filters in the wordpress codex.

The naming convention of the actions and filters is very straightforward, I don't think they need more explanation. In case of trouble open a support  ticket and I will help you out with these.

The actions list

Functional actions
Layout actions
 

The Filters list

Only if cache is not activated!
  • $allpageposts = apply_filters( 'asp_pagepost_results', $allpageposts );
  • $allcommentsresults = apply_filters( 'asp_comment_results', $allcommentsresults );
  • $buddypresults = apply_filters( 'asp_buddyp_results', $buddypresults );
  • $blogresults = apply_filters( 'asp_blog_results', $blogresults ); 
  • $results = apply_filters( 'asp_only_keyword_results', $results );
  • $results = apply_filters( 'asp_only_non_keyword_results', $results );
  • $results = apply_filters( 'asp_results', $results );
  • $s = apply_filters( 'asp_search_phrase_before_cleaning', $s );
  • $s = apply_filters( 'asp_search_phrase_after_cleaning', $s );
 
  • $r->title = apply_filters( 'asp_result_title_before_prostproc' , $r->title);
  • $r->content = apply_filters( 'asp_result_content_before_prostproc' , $r->content);
  • $r->image = apply_filters( 'asp_result_image_before_prostproc' , $r->image);
  • $r->author = apply_filters( 'asp_result_author_before_prostproc' , $r->author);
  • $r->date = apply_filters( 'asp_result_date_before_prostproc' , $r->date);
 
  • $r->title = apply_filters( 'asp_result_title_after_prostproc' , $r->title);
  • $r->content = apply_filters( 'asp_result_content_after_prostproc' , $r->content);
  • $r->image = apply_filters( 'asp_result_image_after_prostproc' , $r->image);
  • $r->author = apply_filters( 'asp_result_author_after_prostproc' , $r->author);
  • $r->date = apply_filters( 'asp_result_date_after_prostproc' , $r->date);
 
With cacheing activated 
  • $cache_content = apply_filters( 'asp_cached_content_json', $cache_content);
 

Examples

Adding an extra word to the search phrase before searching
  add_filter ( 'asp_search_phrase_after_cleaning', 'add_phrase', 1, 1 );

  function add_phrase($phrase) {
    return $phrase." test";
  }
Printing something before the first search object
  add_action ( 'asp_layout_before_shortcode', 'print_this', 1, 1 );

  function print_this($id) {
    if ($id==1)
      print "Hello world!";
  }