Skip to content

Commit

Permalink
DOC Revert doc changes. These are now done in another module.
Browse files Browse the repository at this point in the history
  • Loading branch information
@GuySartorelli
GuySartorelli committed Jul 7, 2022
1 parent 6129530 commit 1cf2fcb
Show file tree
Hide file tree
Showing 4 changed files with 23 additions and 147 deletions.
139 changes: 18 additions & 121 deletions docs/en/02_Developer_Guides/00_Model/11_Scaffolding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,9 @@ An example is `DataObject`, Silverstripe CMS will automatically create your CMS
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{

private static $db = [
'IsActive' => 'Boolean',
'Title' => 'Varchar',
Expand Down Expand Up @@ -77,7 +78,7 @@ your `$summary_fields` config specifies fields that are not stored in the databa
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{

private static $searchable_fields = [
Expand All @@ -87,138 +88,34 @@ class MyDataObject extends DataObject
}
```

### Primary search field

Tabular views such as `GridField` or `ModalAdmin` include a search bar. As of Silverstripe CMS 4.12, the search bar will search across all of your searchable fields by default. It will return a match if the search terms appear in any of the searchable fields.

#### Exclude fields from the primary search

If you have fields which you do _not_ want to be searched with this primary search (e.g. date fields which need special consideration), you can mark them as being explicitly excluded by setting `primary` to false in the searchable fields configuration for that field:

```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
{
private static $searchable_fields = [
'Name',
'BirthDate' => [
'primary' => false
],
];
}
```

#### Customise the primary search field name

By default the primary search field uses the name "q". If you already use that field name or search query in your [SearchContext](/developer_guides/search/searchcontext), you can change this to whatever name you prefer either globally or per class:

[hint]
If you set `primary_search_field_name` to any empty string, primary search will be disabled entirely. Instead, the first field in your searchable fields configuration will be used, which was the default behaviour prior to Silverstripe CMS 4.12.
[/hint]

**Globally change the primary search field name via yaml config**
```yml
SilverStripe\ORM\DataObject:
primary_search_field_name: 'my_primary_field_name'
```
**Customise the primary search field name via yaml _or_ php config**
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
{
private static string $primary_search_field_name = 'my_primary_field_name';
}
```

#### Specify a search filter for primary search

By default, the primary search will search across your fields using a [PartialMatchFilter](api:SilverStripe\ORM\Filters\PartialMatchFilter) regardless of what filters you have [specified for those fields](#specify-a-form-field-or-search-filter).

You can configure this to be a specific filter class, or else disable the primary search filter. Disabling the filter will result in the filters you have specified for each field being used when searching against that field in the primary search.

Like the primary search field name, you can set this either globally or per class:

**Globally change the primary search filter via yaml config**
```yml
# use a specific filter
SilverStripe\ORM\DataObject:
primary_search_field_filter: 'SilverStripe\ORM\Filters\EndsWithFilter'

# or disable the filter to fall back on individual fields' filters
SilverStripe\ORM\DataObject:
primary_search_field_filter: ''
```
**Customise the primary search filter via yaml _or_ php config**
```php
use SilverStripe\ORM\DataObject;
use SilverStripe\ORM\Filters\EndsWithFilter;

class MyDataObject extends DataObject
{
private static string $primary_search_field_name = EndsWithFilter::class;
}
```

[warning]
You may get unexpected results using some filters if you don't disable splitting the query into terms - for example if you use an [ExactMatchFilter](api:SilverStripe\ORM\Filters\ExactMatchFilter), each term in the query _must_ exactly match the value in at least one field to get a match. If you disable splitting terms, the whole query must exactly match a field value instead.
[/warning]

#### Splitting search queries into individual terms

By default the primary search field qill split your search query into individual terms, and search across your searchable field for each term. At least one field must match each term to get a match.

For example: with the search query "farm house" at least one field must have a match for the word "farm", and at least one field must have a match for the word "house". There does _not_ need to be a field which matches the full phrase "farm house".

You can disable this behaviour by setting `DataObject.primary_search_split_terms` to false. This would mean that for the example above a `DataObject` would need a field that matches "farm house" to be included in the results. Simply amtching "farm" or "house" alone would not be sufficient.

Like the primary search field name, you can set this either globally or per class:

**Globally disable splitting terms via yaml config**
```yml
SilverStripe\ORM\DataObject:
primary_search_split_terms: false
```
**Disable splitting terms via yaml _or_ php config**
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
{
private static bool $primary_search_split_terms = false;
}
```

### Specify a form field or search filter

Searchable fields will appear in the search interface with a default form field (usually a [TextField](api:SilverStripe\Forms\TextField)) and a
default search filter assigned (usually a [PartialMatchFilter](api:SilverStripe\ORM\Filters\PartialMatchFilter)). To override these defaults, you can specify
default search filter assigned (usually an [ExactMatchFilter](api:SilverStripe\ORM\Filters\ExactMatchFilter)). To override these defaults, you can specify
additional information on `$searchable_fields`:

```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{

private static $searchable_fields = [
'Name' => 'PartialMatchFilter',
'ProductCode' => NumericField::class
];
}
```

If you assign a single string value, you can set it to be either a [FormField](api:SilverStripe\Forms\FormField) or [SearchFilter](api:SilverStripe\ORM\Filters\SearchFilter). To specify
both or to combine this with other configuration, you can assign an array:
If you assign a single string value, you can set it to be either a [FormField](api:SilverStripe\Forms\FormField) or [SearchFilter](api:SilverStripe\ORM\Filters\SearchFilter). To specify
both, you can assign an array:

```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{

private static $searchable_fields = [
'Name' => [
'field' => TextField::class,
Expand Down Expand Up @@ -274,10 +171,6 @@ class Player extends DataObject

Use a single search field that matches on multiple database fields with `'match_any'`. This also supports specifying a field and a filter, though it is not necessary to do so.

[alert]
If you don't specify a field, you must use the name of a real database field instead of a custom name so that a default field can be determined.
[/alert]

```php
class Order extends DataObject
{
Expand Down Expand Up @@ -305,6 +198,10 @@ class Order extends DataObject
}
```

[alert]
If you don't specify a field, you must use the name of a real database field instead of a custom name so that a default field can be determined.
[/alert]

## Summary Fields

Summary fields can be used to show a quick overview of the data for a specific [DataObject](api:SilverStripe\ORM\DataObject) record. The most common use
Expand All @@ -313,7 +210,7 @@ is their display as table columns, e.g. in the search results of a [ModelAdmin](
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{
private static $db = [
'Name' => 'Text',
Expand Down Expand Up @@ -342,7 +239,7 @@ class OtherObject extends DataObject
];
}

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{
private static $db = [
'Name' => 'Text',
Expand All @@ -369,7 +266,7 @@ Non-textual elements (such as images and their manipulations) can also be used i
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{
private static $db = [
'Name' => 'Text',
Expand All @@ -394,7 +291,7 @@ In order to re-label any summary fields, you can use the `$field_labels` static.
```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
class MyDataObject extends DataObject
{
private static $db = [
'Name' => 'Text',
Expand Down
5 changes: 4 additions & 1 deletion docs/en/02_Developer_Guides/12_Search/01_Searchcontext.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ The default output of a [SearchContext](api:SilverStripe\ORM\Search\SearchContex
[DataObject](api:SilverStripe\ORM\DataObject) instance.

[notice]
[SearchContext](api:SilverStripe\ORM\Search\SearchContext) is mainly used by [ModelAdmin](/developer_guides/customising_the_admin_interface/modeladmin), as it powers the [`DataObject::$searchable_fields` configuration](/developer_guides/model/scaffolding#searchable-fields).
[SearchContext](api:SilverStripe\ORM\Search\SearchContext) is mainly used by [ModelAdmin](/developer_guides/customising_the_admin_interface/modeladmin).
[/notice]

## Usage
Expand Down Expand Up @@ -89,6 +89,7 @@ the `$fields` constructor parameter.

### Generating a search form from the context


```php
use SilverStripe\Forms\Form;
use SilverStripe\Forms\FieldList;
Expand Down Expand Up @@ -177,6 +178,7 @@ The change is in **$results = $this->getResults($data);**, because you are using
Another thing you cant forget is to check the name of the singleton you are using in your project. the example uses
**MyDataObject**, you need to change it for the one you are using


### The Pagination Template

to show the results of your custom search you need at least this content in your template, notice that
Expand Down Expand Up @@ -228,6 +230,7 @@ Results.PaginationSummary(4) defines how many pages the search will show in the

See [SearchFilter](api:SilverStripe\ORM\Filters\SearchFilter) API Documentation


## Related Documentation

* [ModelAdmin](/developer_guides/customising_the_admin_interface/modeladmin)
Expand Down
3 changes: 1 addition & 2 deletions docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ class makes a guess at how those fields should be searched, e.g. showing a check
`$db` definition.

To remove, add or modify searchable fields, define a new [DataObject::$searchable_fields](api:SilverStripe\ORM\DataObject::$searchable_fields) static on your model
class (see [Searchable Fields](/developer_guides/model/scaffolding#searchable-fields) and [SearchContext](../search/searchcontext) docs for details).
class (see [SearchContext](../search/searchcontext) docs for details).

**app/src/Product.php**

Expand All @@ -233,7 +233,6 @@ class Product extends DataObject
The results are shown in a tabular listing, powered by the [GridField](../forms/field_types/gridfield), more specifically
the [GridFieldDataColumns](api:SilverStripe\Forms\GridField\GridFieldDataColumns) component. This component looks for a [DataObject::$summary_fields](api:SilverStripe\ORM\DataObject::$summary_fields) static on your
model class, where you can add or remove columns. To change the title, use [DataObject::$field_labels](api:SilverStripe\ORM\DataObject::$field_labels).
See [Summary Fields](/developer_guides/model/scaffolding#summary-fields) and [Field labels](/developer_guides/model/scaffolding#field-labels) for details.

**app/src/Product.php**

Expand Down
23 changes: 0 additions & 23 deletions docs/en/04_Changelogs/4.12.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ title: 4.12.0 (unreleased)

- [Regression test and Security audit](#audit)
- [Features and enhancements](#features-and-enhancements)
- [Search multiple `searchable_fields` by default](#primary-search-field)
- [Samesite attribute on cookies](#cookies-samesite)
- [Other features](#other-features)
- [Bugfixes](#bugfixes)
Expand All @@ -21,28 +20,6 @@ While it is still advised that you perform your own due diligence when upgrading

## Features and enhancements {#features-and-enhancements}

### Search multiple `searchable_fields` by default {#primary-search-field}

The initial search text field which appears in the search interface now searches across all of your searchable fields by default. It will return a match if the search terms appear in any of the searchable fields.

If you have fields which you do _not_ want to be searched with this primary search (e.g. date fields which need special consideration), you can mark them as being explicitly excluded by setting `primary` to false in the searchable fields configuration for that field:

```php
use SilverStripe\ORM\DataObject;

class MyDataObject extends DataObject
{
private static $searchable_fields = [
'Name',
'BirthDate' => [
'primary' => false
],
];
}
```

There is also additional configuration, such as which `SearchFilter` it uses ([PartialMatchFilter](api:SilverStripe\ORM\Filters\PartialMatchFilter) by default), and whether it should split the search query into individual search terms or search as a phrase. Check out [Primary search field](/developer_guides/model/scaffolding#primary-search-field) for more information.

### Samesite attribute on cookies {#cookies-samesite}

The `samesite` attribute is now set on all cookies. To avoid backward compatability issues, the `Lax` value has been set by default, but we recommend reviewing the requirements of your project and setting an appropriate value.
Expand Down

0 comments on commit 1cf2fcb

Please sign in to comment.