Pro search additional mods

docs/add-ons/pro-search/filters.md

@@ -10,19 +10,23 @@
 
 [TOC]
 
+Different type of Filters are automatically used by the `pro_search:results` tag when the query form uses specific field names, or the results tag includes specific parameters. 
+
+For instance, if a search form contains a `keywords` field, the [Keywords filter](#keywords-filter) will be invoked. If the results tag has a `distance:to="cf_entry_lat|cf_entry_long"` parameter, the [Distance filter](#distance-filter) will be used. If the `search:field_name` parameter or field is used, Pro Search will use the [Field Search filter](#field-search) on the results
 
 ## Keywords Filter
 
-The Keywords filter lets you filter entries by search terms (ie. keywords). You need to create at least one Collection to use the Keywords filter. (You don't need a collection for other types of filters.)
+The Keywords filter lets you filter entries by search terms (ie. keywords) and calculates a relevance score for each item in the search results.
 
-Using the Keywords filter also adds a relevance score to the search results. To further fine-tune a keyword search, the following parameters are available.
+NOTE: **Note:** You need to create at least one [Collection](add-ons/pro-search/collections.md) to use with the Keywords filter. (You don't need to create a collection to use the other types of filters, just when using Keywords.)
 
+To further fine-tune a keyword search, the following parameters are available.
 
 ### Parameters
 
 #### collection
 
-Limit search results to given collection names or IDs. If this is not specified and keywords are given, results will use all collections
+Limit search results to specified [collections](add-ons/pro-search/collections.md) (names or IDs). If this parameter is not used and keywords are being searched, EE will search in all collections, so it's best to use this rather than `channel=` in the results. 
 
     collection="news|staff"
 
@@ -173,7 +177,7 @@ NOTE: **Note:** When enabled, inflections and stems are only applied to keyword
 
 ## Categories
 
-You can use the native `category` parameter to filter by category. For more advanced filtering by category, you can also divide categories into groups. The group syntax lets you combine AND and OR filtering (category 1 or 2 and category 3 or 4), as parameters are always combined with AND.
+Use the native `category` parameter to filter by category. For more advanced filtering by category, you can also divide categories into groups. The group syntax lets you combine AND and OR filtering (category 1 or 2 and category 3 or 4), as parameters are always combined with AND.
 
 ### `category`
 
@@ -187,27 +191,28 @@ NOTE: **Note:** Use category IDs instead of URL titles for better performance.
 
 ## Distance
 
-You can use the Distance filter to limit results by a given maximum distance. This filter prefers for you to use two channel fields where latitude and longitude values are stored. Alternatively, you can use a single field where the two values are separated by a comma. Using the Distance filter will limit results to entries that actually have latitude and longitude values entered.
+Use the Distance filter to limit results by a given maximum distance. This filter prefers for you to use two channel fields where latitude and longitude values are stored. Alternatively, you can use a single field where the two values are separated by a comma. Using the Distance filter will limit results to entries that actually have latitude and longitude values entered.
 
 ### Parameters
 
 #### `distance:from`
 
-Latitude and longitude values separated by a vertical bar, used to calculate the distance.
+The spot you're using to calculate the distance from. Must be latitude and longitude values separated by a vertical bar.
 
     distance:from="52.163298|4.505547"
 
 #### `distance:to`
 
-The one or two channel field names that contain the latitude and longitude values separated by a vertical bar, used to calculate the distance.
+The one or two channel field names that contain the latitude and longitude values you're comparing distance to, separated by a vertical bar if two fields.
 
+    distance:to="store_geocode"
     distance:to="cf_entry_lat|cf_entry_long"
 
 NOTE: **Note:** Use two separate fields instead of a single one for better performance.
 
 #### `distance:radius`
 
-The maximum distance between the from and to values. Leave blank for no maximum.
+The maximum distance allowable between the from and to values. Leave blank for no maximum.
 
     distance:radius="50"
 
@@ -219,17 +224,15 @@ The unit for the distances, either km, mi, m or yd. Defaults to km.
 
 ### Variables
 
-The Distance filter makes this variable available in the [Results tag](/add-ons/pro-search/tags.md#exppro_searchresults):
-
 #### `{pro_search_distance}`
 
-The calculated distance in the given unit for this entry.
+The calculated distance in the given unit for this entry. The Distance filter makes this variable available in the [Results tag](/add-ons/pro-search/tags.md#exppro_searchresults).
 
-NOTE: **Note:** Using the Distance filter will return the search results ordered by distance, ignoring keyword relevance if applicable. Override by explicitly setting the orderby parameter.
+NOTE: **Note:** Using the Distance filter will return the search results ordered by distance instead of keyword relevance (if applicable). You can override this by explicitly setting the orderby parameter to `relevance`.
 
 ## Field Search
 
-You can use the native `search:field_name` parameter to target specific fields. Additionally, Pro Search can target the entry’s ***title***, ***url_title***, ***status***, target [Grid](/fieldtypes/grid.md) columns, use multiple values for [numeric matching](/channels/entries.md#numeric-matching) (in combination with the `gt`, `gte`, `lt` and `lte` params), and use ***starts / ends with*** matching.
+Use the native `search:field_name` parameter to target specific fields, just like `channel:entry` does already. Additionally, Pro Search's `pro_search:results` can target the entry’s ***title***, ***url_title***, ***status***, and target [Grid](/fieldtypes/grid.md) columns. It can also use multiple values for [numeric matching](/channels/entries.md#numeric-matching) (in combination with the `gt`, `gte`, `lt` and `lte` params), and use ***starts / ends with*** matching.
 
 ### Parameters
 
@@ -295,26 +298,34 @@ NOTE: **Note:** using `smart_field_search="yes"` can affect performance, dependi
 
 ## Ranges
 
-You can use the Ranges filter to limit results by a given range, targeting a numeric or date field. If Pro Search detects that the given channel field for the range is a date field, it will try and convert the given range values to timestamps. This will allow custom date ranges as well.
+Use the Ranges filter to target a numeric or date field and limit results by a given range. If Pro Search detects that the given channel field for the range is a date field, it will try and convert the given range values to timestamps. This will allow custom date ranges as well.
 
 ### Parameters
 
 #### `range:field_name`
 
-Takes a from and to value, separated by a vertical bar: |. Use `field_name:column_name` to target Grid/Matrix columns (v4.2.0+).
+Takes both a from and to value, separated by a vertical bar: |. Use `field_name:column_name` to target Grid/Matrix columns (v4.2.0+).
+
+    range:ticket_price="20|80"
 
 #### `range-from:field_name`
 
 Takes a single from value. Use `field_name:column_name` to target Grid/Matrix columns (v4.2.0+).
 
+    range-from:hire_date="2020-01-01"
+
 #### `range-to:field_name`
 
 Takes a single to value. Use field_name:column_name to target Grid/Matrix columns (v4.2.0+).
 
+    range-to:age="65"
+
 #### `range:min_field:max_field`
 
 Where min and max are two separate (non-Grid/Matrix) fields. If a single value is given, entries will be returned where the value is between the min and max fields. If a from and to value is given, entries will be returned where the min and max fields overlap the given range.
 
+    range:min-deposit:max-deposit="1000"
+
 #### `range-from:min_field:max_field`
 
 Where min and max are two separate fields. Takes a single from value.
@@ -325,7 +336,7 @@ Where min and max are two separate fields. Takes a single to value.
 
 #### `exclude`
 
-Accepts parameter names. Excludes a given parameter value from the range itself. For example, `range:field_name="0|10" exclude="range:field_name"` will result in values `> 0` and `< 10` rather than `>= 0` and `<= 10`.
+Accepts parameter names. Excludes a given parameter value from the range itself. For example, `range:field_name="0|10" exclude="range:field_name"` will result in search values `> 0` and `< 10` rather than `>= 0` and `<= 10`.
 
 NOTE: **Note:** For numeric fields, make sure the Field Content option in the field’s settings is set to Number, Integer or Decimal.
 
@@ -346,7 +357,7 @@ Apart from any custom numeric or date field, the following standard channel fiel
 
 ## Relationships
 
-You can use the Relationships filter to limit results by given parent or child entry IDs. The filter works for [Relationships fieldtypes](/fieldtypes/relationships.md).
+Use the Relationships filter to limit results by given parent or child entry IDs. The filter works for [Relationships fieldtypes](/fieldtypes/relationships.md).
 
 ### Parameters
 
@@ -370,7 +381,7 @@ NOTE: **Note:** Use entry IDs instead of URL titles for better performance.
 
 ## Tags
 
-You can use the Tags filter to limit results by given tag names or IDs. For more advanced filtering by tags, you can also divide tags into groups. The group syntax lets you combine AND and OR filtering (tag 1 or 2 and tag 3 or 4), as parameters are always combined with AND.
+Use the Tags filter to limit results by given tag names or IDs. For more advanced filtering by tags, you can also divide tags into groups. The group syntax lets you combine AND and OR filtering (tag 1 or 2 and tag 3 or 4), as parameters are always combined with AND.
 
 ### Parameters
 

docs/add-ons/pro-search/overview.md

@@ -9,20 +9,20 @@
 
 # Pro Search
 
-ExpressionEngine’s native `channel:entries` tag allows you to fetch and filter entries in many ways by setting its parameters. The native Search module allows for filtering by keyword, but is limited in its capabilities. Pro Search combines the two into one module and then throw in extra features, filters, and a performance boost.
+ExpressionEngine’s native `channel:entries` tag allows you to fetch and filter entries in many ways by using its parameters. The native Search module, `search:search_results`,  allows for searching by keyword, and returning results from many channels, but is very limited in its overall capabilities. Pro Search combines the two into one module and then throws in many extra features, powerful filters, and a performance boost.
 
+Pro Search uses a custom [full-text](http://dev.mysql.com/doc/refman/5.5/en/fulltext-search.html) index instead of the raw entry data, which makes searching by keywords **Very Fast**. It also adds **relevance** to search results, which can be custom tuned by assigning **different weights** to any searchable field.
 
-Searching by **keywords** uses a custom [full-text](http://dev.mysql.com/doc/refman/5.5/en/fulltext-search.html) index instead of the raw entry data, which makes Pro Search fast. **Very fast**. It also adds **relevance** to search results which can be influenced by applying **weight** to any searchable field.
+Apart from the powerful [keywords filter](/add-ons/pro-search/filters.md#keywords), and the ability to **use any native parameter as a search filter**, Pro Search adds several other filters to further enhance and refine your entries loop or your search results:
 
-Apart from the powerful [keywords filter](/add-ons/pro-search/filters.md#keywords), and the ability to **use any native parameter as a search filter**, Pro Search adds several other filters to further enhance and refine your search results:
-
-- Select any combination of [categories](/add-ons/pro-search/filters.md#categories);
-- Limit entries by a given [distance](/add-ons/pro-search/filters.md#distance) based on latitude/longitude values;
-- Target [specific fields](/add-ons/pro-search/filters.md#field-search), including Titles and Grid columns;
-- Define numeric or date [ranges](/add-ons/pro-search/filters.md#ranges);
-- Filter based on an entry’s [relationship](/add-ons/pro-search/filters.md#relationships) with other entries;
-- Filter by [Grid calculations](https://github.com/low/low_search_table) like min/max values or averages;
-- Filter by [Author fields](https://github.com/low/low_search_members) like screen name or email;
+- Category: Select any combination of [categories](/add-ons/pro-search/filters.md#categories);
+- Distance: Limit entries by a given [distance](/add-ons/pro-search/filters.md#distance) based on latitude/longitude values;
+- Fields: Target [specific fields](/add-ons/pro-search/filters.md#field-search), including Titles and Grid columns;
+- Number Ranges: Define numeric or date [ranges](/add-ons/pro-search/filters.md#ranges);
+- Relationships: Filter based on an entry’s [relationship](/add-ons/pro-search/filters.md#relationships) with other entries;
+- Math: Filter by [Grid calculations](https://github.com/low/low_search_table) like min/max values or averages;
+- Author: Filter by [Author fields](https://github.com/low/low_search_members) like screen name or email;
+- SQL: Filter a field based on a [SQL query](/add-ons/pro-search/parameters.html#sql-parameters)
 
 Other features include:
 

docs/add-ons/pro-search/tags.md

@@ -185,15 +185,23 @@ Use this parameter to pass through a previously executed encoded search query. N
 
 [TOC=4 hide]
 
-The Results tag supports all parameters from the native channel:entries tag and any parameters made available by the Filters. In addition to those, the following parameters are available. Any parameters set in the tag will override the ones in the given query.
+The Results tag supports:
+* all parameters from the native `channel:entries` tag, and
+* the parameters listed below, and
+* any additional parameters made available by the Filters referenced by your query.
 
-    {exp:pro_search:results query="{segment_3}" default:limit="10"}
+Any parameters set in the `pro_search:results` tag will override the ones in the provided query.
+
+    {exp:pro_search:results query="{segment_3}" default:limit="10" }
+     <p>You searched for "{pro_search_keywords}".</p>
      {if count ==  1}<ol>{/if}
-      <li><a href="{comment_url_title_auto_path}">{title}</a></li>
+      <li><a href="{auto_path}">{title}</a></li>
      {if count == total_results}</ol>{/if}
      {if no_results}No search results{/if}
     {/exp:pro_search:results}
 
+NOTE: **Note:** The Keywords filter has a unique parameter: `collection`. If the `collection` parameter is not set, the keywords Filter will search ALL collections. The `channel` parameter is available to limit any results set, including a result set that used the keywords Filter. But for keywords searches, it is much more efficient to define the specific collection(s) you want to search via the `collection` parameter, rather than limit the results by `channel` after searching EVERY collection.
+
 #### `alias:parameter=`
 
 Point a given parameter to any other, so parameter x gets treated like parameter y. For example, to use the param `q` as an alias for `keywords`, use `alias:keywords="q"`. Useful if you have previous or multiple search forms with different names for the same parameters, and you want to have one result page.