Getting Started

Welcome

Advanced Custom Search PRO is a WordPress plugin for anyone who needs an advanced search for posts (or custom posts), and users in WordPress admin or in frontend.

Benefits

• Advanced search for posts and users in WordPress Admin.
• Visual builder for frontend search forms with Drag & Drop.
• Works with Advanced Custom Fields, WooCommerce and WPML.
• Uses your posts archive and does not need a custom template.

Features

• Perform complex queries directly from the posts and users list.
• Use specific filters for each field.
• Search in WordPress built-in posts, custom post types, and WordPress users.
• Search posts by any post attribute (i.e. title, content, publish, excerpt, slug, ...).
• Specify which comparison operator you want to use (each field has its own comparison operators, according to the field type).

Quick Start

How to use

Step 1: create a new search form
From WordPress Menu » Advanced Custom Search » Search Forms, click the Add New button.

Step 2: create form fields with visual builder
Simply drag & drop fields from the list on the right to the form container on the left. You can configure each field filling in its details (see section: Customizing a form field).

Step 3: set form options
From the right sidebar, fill in the form settings: Post Types you want to search for, destination archive page slug, jQuery UI theme for supported fields. See details in Configuring a search form section. The HTML code box is auto-generated. Don't forget to assign a title to the form!

Step 4: customize form styles (optional)
Insert your custom CSS, if you need. It will be applied to the form. See Writing form styles (CSS) for details.

Step 5: include search form in your website
Choose one of the following inclusion methods:

• Shortcode method
  From the forms list (WordPress Menu » Advanced Custom Search » Search Forms) copy the shortcode for the form you have just created. Paste the form shortcode anywhere you need, in a post (or page) content editor.
• Advanced Custom Search PRO widget method
  From WordPress Menu » Appearance » Widgets insert the ACS - Search Form widget just like any other widget, by clicking or dragging it in the sidebar you want.

Backend

Introduction

Advanced Custom Search PRO lets you easily perform advanced searches for posts; in every posts list of your WordPress backend (WordPress built-in or custom post types) there is an Advanced Search button by which you can open the search form.

Searching posts

In the top-right corner of each posts list screen there is an Advanced Search button; it opens the search form with all fields that you can use to filter posts.

Every filter has a field, in which you can enter the content you are searching for, and a button by which you can choose the operator for the comparison. For example you can search for posts with a specific title, but also for those that have a title containing your search terms.

Below you can find a summary of the available field types:

• text — text fields are the most common fields you can use for searching posts; they allow you to enter search terms of your choice.
• select — used in fields that have a specific set of values (i.e. post status, taxonomies, etc.).
• date range — composed of two linked fields, one for the minimum and one for the maximum values; you can fill both fields for a closed range search or use only one for an open range.
• number — similar to text fields, but they perform a numeric comparison and have more comparison operators.
• picker — (only for some ACF fields: posts relationship, image field, etc.) allow you to pick a value from a dialog window specific for the field type (i.e. posts, images, files, etc.).

The comparison operators depend on the field type.

• = matches posts with exactly identical content only. If you search for apple, it will not find posts containing apples content.
• LIKE matches posts containing the text you searched for. If you search for apple, it will find posts containing apples content or I like apples!.
• != matches posts not equal to the content you searched for. You can search for post with status different from publish, category different from uncategorized, and so on.
• > and >= matches posts with content greater than (or equal to) the value you searched for.
• < and <= matches posts with content less than (or equal to) the value you searched for.

Admin options

In Advanced Custom Search » Admin Views you can customize what fields are shown in the Advanced Search forms for each WordPress list screen.

The Post Types Views section of the screen allows you to choose what fields you want to show in the Advanced Search forms; each column represents a built-in or custom post type, each row represents a form field.

Checking a field will show it in the corresponding search form. The fields list is grouped by Field Groups (WordPress built-in fields, WooCommerce fields, custom fields you created in ACF): you can select all fields in a group by checking the corrisponding Field Group checkbox.

The Post Types Options section of the screen allows you to group fields by their own field group; it is useful when you want to simplify and make more sense of the interface when you have a lot of fields (maybe with repeated names).

The Users Views section of the screen allows you to choose what fields you want to show in the Advanced Search forms; each column represents a built-in or custom user role, each row represents a form field.

Checking a field will show it in the corresponding search form. The fields list is grouped by Field Groups (WordPress built-in fields, custom fields you created in ACF): you can select all fields in a group by checking the corrisponding Field Group checkbox.

The Users Options section of the screen allows you to group fields by their own field group; it is useful when you want to simplify and make more sense of the interface when you have a lot of fields (maybe with repeated names).

Frontend

Introduction

Advanced Custom Search PRO lets you create search forms for your website visitors. A Search Form allows the users to search and filter a post archive (i.e. blog posts, site news, eCommerce products, etc.).

Building a search form

Building a search form is a very simple process; thanks to the powerful Visual Builder you can simply build the form by dragging and dropping the fields you need in the form container: Advanced Custom Search will do the magic.

To create a new form go to Advanced Custom Search » Search Forms and click the Add New button: the Visual Builder will show up.

Enter the form name (useful to recognize it) and start building your form; in the right column you'll find all available fields for your WordPress site, arranged in groups. Simply drag a field and drop it on the main Visual Builder area.

When you drop the field, its settings will appear; you can customize the appearance of the field, set the field label and an optional placeholder; each field type has its own settings (see Customizing a form field).

Every change you make affects the HTML Code the plugin generates in real-time: it will be the actual HTML that will be used in your website. You can customize your form appearance by using the CSS Styles editor (see Writing form styles (CSS)).

Customizing a form field

Each form field can be customized directly in the editor: there are some settings common to all fields: label, placeholder and CSS classes. See the following table for further details:

setting	description
label	it contains the field label, usually placed before the field itself; tells the users the meaning of the field
placeholder	it contains a field brief description, usually used to tells the user how to format the field content
CSS classes	additional CSS classes you can use to customize the field (see Writing form styles (CSS))

Other settings are field specific and they depend on the field type; in a select field, for example, you can choose if you want to show it as a dropdown or with a checkable list; you can also hide some values for the field.

Below you can find a brief summary of fields and their own settings:

• button — there are two types of buttons: submit and reset. The submit button is used to start the search, while the reset button clears the form. A button is a special field and it doesn't have a label or a placeholder setting.

  setting	description
  button text	the text displayed inside the button

• text — the most common field type you can use for searching posts; it allows you to enter search terms. It doesn't have additional settings other than the common ones.
• select — used in fields that have a specific set of values (i.e. post status, taxonomies, etc.).

  setting	description
  field type	choose between single value and multiple values: the first one allows the user to choose only one value from a dropdown while the second shows a list of checkable items allowing the user to mark more than one choice
  exclude options	a list of options that you don't want to show; the autocomplete will help you enter the values in the exclusion list

• date range — one of the most powerful fields with a lot of options, it is used for date fields like published, last modified, etc. This type of field doesn't have the default placeholder setting.

  setting	description
  field type	choose between four options: date range, that is the most complete search composed of two different fields, one for each range limit; only dates after and only dates before, respectively for dates greater than and lower than the inserted value; specific date, used to search a single value
  "from" placeholder	same as the default placeholder setting, but specific for the "from" field (available only in date range and only dates after modes)
  "to" placeholder	same as the default placeholder setting, but specific for the "to" field (available only in date range and only dates before modes)
  date picker	option that enhances the text version of the date fields with a more intuitive date picker using jQuery UI (see jQuery UI datepicker)
  date format	the dateFormat option for the jQuery UI datepicker

• number — similar to text fields, but they perform a numeric comparison and have more settings for UI customization.

  setting	description
  field type	choose between single, that shows one single field to search an exact value, and range that allows searches for values between a minimum and a maximum
  "single" placeholder	same as the default placeholder setting, but specific for the single field (available only in single mode)
  "from" placeholder	same as the default placeholder setting, but specific for the "from" field (available only in range mode)
  "to" placeholder	same as the default placeholder setting, but specific for the "to" field (available only in range mode)
  min	minimum value that the user can choose
  max	maximum value that the user can choose
  slider	option that enhances the text version of number fields with a more intuitive slider using jQuery UI (see jQuery UI slider)
  slider values	choose between append to "label" tag and don't show; the first option appends the selected values to the label tag linked to the field itself while the second one doesn't show anything

• boolean — similar to select, but with two options only: true and false.

  setting	description
  "true" text	text displayed on the "true" option of the select
  "false" text	text displayed on the "false" option of the select

• user — dropdown with the users list of your WordPress installation as options.

  setting	description
  filter users by role	choose which roles you want to filter users by; if not specified all users will be shown

Configuring a search form

When creating a Search Form or editing an existing one, you can configure some additional options related to search results. There are three options that you can customize:

• Post types — used to filter the results for specific post types; if not specified, the plugin will search in all public and searchable post types.
• Archive slug — this will be the permalink of your search results page; it must be unique and it will not work if another page with the same slug exists. By default it will be auto-generated using the form name; in this field you can also use the / character in order to create custom URLs like http://www.example.com/posts/results.
• jQuery UI theme — some fields can be enhanced by using jQuery UI: this option allows you to choose which theme you want to use in your frontend. The dropdown contains all supported jQuery UI themes; for more information please take a look at jQuery UI ThemeRoller.
• jQuery UI Theme URL — the URL of a custom CSS for a jQuery UI theme. This field is available only if you choose Custom Theme from the jQuery UI Theme dropdown.

The HTML editor

The HTML editor is read-only and auto-generated according to your actions in Visual Builder. It's useful to have a preview of the generated code and to get the exact ids and classes of the generated tags, if you need to edit the form styles with CSS (see Writing form styles (CSS)).

Writing form styles (CSS)

After the Visual Builder you will find an editor that can be used to customize the appearance of the form in your website. The HTML editor shows the generated code and you can write stylesheets based on its content.

Each field has a <label> tag (if a label was specified during the configuration) and an [acsformfield ...] shortcode where you can find an auto-generated id attribute that you can use to refer to the field itself in your stylesheets.

In the CSS Styles editor you can write whatever CSS you want to make your form amazing.

Including a form in a page

The two main options to include a form in a page are shortcode and widget:

• shortcode — this method is useful to insert a Search Form in a content editor.

  From the forms list (Advanced Custom Search » Search Forms) copy the shortcode for the form you have just created. Paste the form shortcode anywhere you need, in a post (or page) content editor.

• widget — this method is useful to insert a Search Form in a sidebar.

  From Appearance » Widgets insert the ACS - Search Form widget just like any other widget, by clicking or dragging it in the sidebar you want. While the Widget is in your sidebar, pick a form from the dropdown and optionally insert a title for the widget.

Advanced Usage

Use forms in themes (PHP)

If you need to insert a form directly in your theme files, you have to use the WordPress native function do_shortcode.

From Advanced Custom Search » Search Forms you can grab the shortcode of each form you have created.

Simply copy the desired shortcode and make WordPress process it using do_shortcode.

<?php echo do_shortcode('[acsform id="1090" title="Sample Form"]'); ?>

Using javascript

Each field has an auto-generated id attribute that you can use to refer to the field itself in your javascripts and it can be obtained from the HTML Code section.

For example, making a field required by using jQuery can be done with the following code:

jQuery('#acs_sf_012ce077708697e030b0d92a8c30705f').attr('required', true);

General

F.A.Q.

How do I use the plugin?
The main search form is in the posts list (also available for pages or custom posts) and can be accessed by the Advanced Search dropdown on the top right of the screen.

How do I make a search?
In the Advanced Search form you can fill one or more fields with the desired search terms, then press the Search button to perform the search.

How do I change comparison operator?
Every search field has different comparison types depending on the field type: in a date field you can search values after or before a date or between two specific dates.

How do I manage what fields are showed in the search form?
In the Views page you have a table showing registered post types; for each post type you can choose what fields you want to show in the search form by checking the corresponding checkbox.

Updates

Advanced Custom Search PRO is available for purchase in the Envato Marketplace. To unlock updates, you need an Envato account and an Envato API key. If you don't know how to do it, follow the instructios below.

Step 1:
Go to http://codecanyon.net/sign_in and sign in with your account.

Step 2:
In your account menu, choose Settings.

Step 3:
In "Your Details" menu, choose API Keys.

Step 4:
In Generate another API Key box enter a label for your key, then press Generate API Key.

Step 5:
Copy the generated API key from Your API Keys list and use it to unlock plugin updates.

Step 6:
Go to Advanced Custom Search > Settings on your WordPress installation.

Step 7:
Enter your Envato Username and the generated Envato API key in the form.

License

Advanced Custom Search PRO is a commercial WordPress plugin released under Apache License 2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You can read the full License at http://www.apache.org/licenses/LICENSE-2.0