From f6356dccc5db1658b93a77c752b8c4aded907348 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Tue, 28 Nov 2023 20:52:54 +1300 Subject: [PATCH] NEW SearchableDropdownField --- lang/en.yml | 5 + src/Forms/SearchableDropdownField.php | 18 + src/Forms/SearchableDropdownTrait.php | 593 ++++++++++++++++++ src/Forms/SearchableMultiDropdownField.php | 20 + .../php/Forms/SearchableDropdownTraitTest.php | 219 +++++++ .../php/Forms/SearchableDropdownTraitTest.yml | 7 + 6 files changed, 862 insertions(+) create mode 100644 src/Forms/SearchableDropdownField.php create mode 100644 src/Forms/SearchableDropdownTrait.php create mode 100644 src/Forms/SearchableMultiDropdownField.php create mode 100644 tests/php/Forms/SearchableDropdownTraitTest.php create mode 100644 tests/php/Forms/SearchableDropdownTraitTest.yml diff --git a/lang/en.yml b/lang/en.yml index 0fd9893a967..7b065af4376 100644 --- a/lang/en.yml +++ b/lang/en.yml @@ -141,6 +141,11 @@ en: IsNullLabel: 'Is Null' SilverStripe\Forms\NumericField: VALIDATION: "'{value}' is not a number, only numbers can be accepted for this field" + SilverStripe\Forms\SearchableDropdownTrait: + SELECT: 'select' + TYPE_TO_SEARCH: 'type to search' + CONJUNCTIVE: ' or ' + DOTS: '...' SilverStripe\Forms\TextField: VALIDATEMAXLENGTH: 'The value for {name} must not exceed {maxLength} characters in length' SilverStripe\Forms\TimeField: diff --git a/src/Forms/SearchableDropdownField.php b/src/Forms/SearchableDropdownField.php new file mode 100644 index 00000000000..a172e667de2 --- /dev/null +++ b/src/Forms/SearchableDropdownField.php @@ -0,0 +1,18 @@ +setLabelField($labelField); + $this->addExtraClass('ss-searchable-dropdown-field'); + $this->init(); + } + + /** + * Returns a JSON string of options for lazy loading. + */ + public function search(HTTPRequest $request): HTTPResponse + { + $response = HTTPResponse::create(); + $response->addHeader('Content-Type', 'application/json'); + if (!SecurityToken::singleton()->checkRequest($request)) { + $response->setStatusCode(400); + $response->setBody(json_encode(['message' => 'Invalid CSRF token'])); + return $response; + } + $term = $request->getVar('term') ?? ''; + $options = $this->getOptionsForSearchRequest($term); + $response->setBody(json_encode($options)); + return $response; + } + + /** + * Get whether the currently selected value(s) can be cleared + */ + public function getIsClearable(): bool + { + return $this->isClearable; + } + + /** + * Set whether the currently selected value(s) can be cleared + */ + public function setIsClearable(bool $isClearable): static + { + $this->isClearable = $isClearable; + return $this; + } + + /** + * Get whether values are lazy loading via AJAX + */ + public function getIsLazyLoaded(): bool + { + return $this->isLazyLoaded; + } + + /** + * Set whehter values are lazy loaded via AJAX + */ + public function setIsLazyLoaded(bool $isLazyLoaded): static + { + $this->isLazyLoaded = $isLazyLoaded; + if ($isLazyLoaded) { + $this->setIsSearchable(true); + } + return $this; + } + + /** + * Get the limit of items to lazy load + */ + public function getLazyLoadLimit(): int + { + return $this->lazyLoadLimit; + } + + /** + * Set the limit of items to lazy load + */ + public function setLazyLoadLimit(int $lazyLoadLimit): static + { + $this->lazyLoadLimit = $lazyLoadLimit; + return $this; + } + + /** + * Get the placeholder text + */ + public function getPlaceholder(): string + { + $placeholder = $this->placeholder; + if ($placeholder) { + return $placeholder; + } + // SearchableDropdownField will have the getEmptyString() method from SingleSelectField + if (method_exists($this, 'getEmptyString')) { + $emptyString = $this->getEmptyString(); + if ($emptyString) { + return $emptyString; + } + } + if ($this->getUseDynamicPlaceholder()) { + $parts = []; + if (!$this->getIsLazyLoaded()) { + $parts[] = _t(__TRAIT__ . '.SELECT', 'select'); + } + if ($this->getIsSearchable()) { + $parts[] = _t(__TRAIT__ . '.TYPE_TO_SEARCH', 'type to search'); + } + $conjunctive = _t(__TRAIT__ . '.CONJUNCTIVE', ' or '); + $dots = _t(__TRAIT__ . '.DOTS', '...'); + return ucfirst(implode($conjunctive, $parts)) . $dots; + } + return ''; + } + + /** + * Set the placeholder text + * + * Calling this will also call setHasEmptyDefault(true), if the method exists on the class, + * which is required for the placeholder functionality to work on SearchableDropdownField + * + * In the case of SearchableDropField this method should be used instead of setEmptyString() which + * will be remvoved in a future version + */ + public function setPlaceholder(string $placeholder): static + { + $this->placeholder = $placeholder; + // SearchableDropdownField will have the setHasEmptyDefault() method from SingleSelectField + if (method_exists($this, 'setHasEmptyDefault')) { + $this->setHasEmptyDefault(true); + } + return $this; + } + + /** + * Get the search context to use + * If a search context has been set via setSearchContext() that will be used + * Will fallback to using the dataobjects default search context if a sourceList has been set + * Otherwise will return null + */ + public function getSearchContext(): ?SearchContext + { + if ($this->searchContext) { + return $this->searchContext; + } + if ($this->sourceList) { + $dataClass = $this->sourceList->dataClass(); + /** @var DataObject $obj */ + $obj = $dataClass::create(); + return $obj->getDefaultSearchContext(); + } + return null; + } + + /** + * Set the search context to use instead of the dataobjects default search context + * + * Calling this will also call setUseSearchContext(true) + */ + public function setSearchContext(?SearchContext $searchContext): static + { + $this->searchContext = $searchContext; + $this->setUseSearchContext(true); + return $this; + } + + /** + * Get whether to use a dynamic placeholder if a normal placeholder is not set + */ + public function getUseDynamicPlaceholder(): bool + { + return $this->useDynamicPlaceholder; + } + + /** + * Set whether to use a dynamic placeholder if a normal placeholder is not set + */ + public function setUseDynamicPlaceholder(bool $useDynamicPlaceholder): static + { + $this->useDynamicPlaceholder = $useDynamicPlaceholder; + return $this; + } + + /** + * Get whether to use a search context instead searching on labelField + */ + public function getUseSearchContext(): bool + { + return $this->useSearchContext; + } + + /** + * Set whether to use a search context instead searching on labelField + */ + public function setUseSearchContext(bool $useSearchContext): static + { + $this->useSearchContext = $useSearchContext; + return $this; + } + + /** + * Get whether the field allows searching by typing characters into field + */ + public function getIsSearchable(): bool + { + return $this->isSearchable; + } + + /** + * Set whether the field allows searching by typing characters into field + */ + public function setIsSearchable(bool $isSearchable): static + { + $this->isSearchable = $isSearchable; + return $this; + } + + /** + * This returns an array rather than a DataList purely to retain compatibility with ancestor getSource() + */ + public function getSource(): array + { + return $this->getListMap($this->sourceList); + } + + /* + * @param mixed $source + */ + public function setSource($source): static + { + if (!is_a($source, DataList::class)) { + throw new InvalidArgumentException('Source must be a DataList'); + } + // Setting to $this->sourceList instead of $this->source because SelectField.source + // docblock type is array|ArrayAccess i.e. does not allow DataList + $this->sourceList = $source; + return $this; + } + + /** + * Get the field to use for the label of the option + * + * The default value of 'Title' will map to DataObject::getTitle() if a Title DB field does not exist + */ + public function getLabelField(): string + { + return $this->labelField; + } + + /** + * Set the field to use for the label of the option + */ + public function setLabelField(string $labelField): static + { + $this->labelField = $labelField; + return $this; + } + + public function getAttributes(): array + { + $name = $this->getName(); + if ($this->getIsMultiple() && strpos($name, '[') === false) { + $name .= '[]'; + } + return array_merge( + parent::getAttributes(), + [ + 'name' => $name, + 'data-schema' => json_encode($this->getSchemaData()), + ] + ); + } + + /** + * Get a list of selected ID's + */ + public function getValueArray(): array + { + $value = $this->Value(); + if (empty($value)) { + return []; + } + if (is_array($value)) { + $arr = $value; + // Normalise FormBuilder values to be like Page EditForm values + // + // Page EditForm $values for non-multi field will be + // [ + // 0 => '10', + // ]; + // FormBuilder $values for non-multi field will be + // [ + // 'label' => 'MyTitle15', 'value' => '10' + // ] + if (array_key_exists('value', $arr)) { + $arr = [$arr['value']]; + } + // Page EditForm $values for multi will be + // [ + // 0 => '10', + // 1 => '15' + // ]; + // FormBuilder $values for multi will be + // [ + // 0 => ['label' => '10', 'value' => 'MyTitle10', 'selected' => false], + // 1 => ['label' => '15', 'value' => 'MyTitle15', 'selected' => false] + // ]; + if (array_key_exists(0, $arr) && is_array($arr[0]) && array_key_exists('value', $arr[0])) { + $arr = array_map(fn ($a) => $a['value'], $arr); + } + $arr = array_filter($arr); + return array_map(fn ($a) => (int) $a, $arr); + } + try { + // things stdClass cannot be cast to string + (string) $value; + } catch (Error $e) { + $value = 0; + } + if (ctype_digit((string) $value) && $value != 0) { + return [(int) $value]; + } + if ($value instanceof SS_List) { + return array_filter($value->column('ID')); + } + if ($value instanceof DataObject && $value->exists()) { + return [$value->ID]; + } + // Don't know what value is, handle gracefully + return []; + } + + public function Field($properties = []): DBHTMLText + { + // The entwine class needs to be added so that it is rendered in an entwine context + $this->addExtraClass('entwine'); + return $this->customise($properties)->renderWith(self::class); + } + + public function saveInto(DataObjectInterface $record): void + { + if (empty($record)) { + return; + } + $name = $this->getName(); + $ids = $this->getValueArray(); + if (substr($name, -2) === 'ID') { + // has_one field + $record->$name = $ids[0] ?? 0; + $record->write(); + } else { + // has_many / many_many field + if (!method_exists($record, 'hasMethod')) { + throw new LogicException('record does not have method hasMethod()'); + } + /** @var DataObject $record */ + if (!$record->hasMethod($name)) { + throw new LogicException("Relation $name does not exist"); + } + /** @var Relation $relation */ + $relation = $record->$name(); + if (!is_a($relation, Relation::class)) { + throw new LogicException("$name is not a Relation"); + } + $relation->setByIDList($ids); + } + } + + /** + * @param Validator $validator + */ + public function validate($validator): bool + { + return $this->extendValidationResult(true, $validator); + } + + public function Type(): string + { + return ''; + } + + public function getSchemaDataType(): string + { + if ($this->getIsMultiple()) { + return FormField::SCHEMA_DATA_TYPE_MULTISELECT; + } + return FormField::SCHEMA_DATA_TYPE_SINGLESELECT; + } + + /** + * Provide data to the JSON schema for the frontend component + */ + public function getSchemaDataDefaults(): array + { + $data = parent::getSchemaDataDefaults(); + $data = $this->updateDataForSchema($data); + $name = $this->getName(); + if ($this->getIsMultiple() && strpos($name, '[') === false) { + $name .= '[]'; + } + $data['name'] = $name; + $data['disabled'] = $this->isDisabled() || $this->isReadonly(); + if ($this->getIsLazyLoaded()) { + $data['optionUrl'] = Controller::join_links($this->Link(), 'search'); + } else { + $data['options'] = array_values($this->getOptionsForSchema()->toNestedArray()); + } + return $data; + } + + public function getSchemaStateDefaults(): array + { + $data = parent::getSchemaStateDefaults(); + $data = $this->updateDataForSchema($data); + return $data; + } + + abstract protected function init(): void; + + /** + * Get whether the field allows multiple values + */ + protected function getIsMultiple(): bool + { + return $this->isMultiple; + } + + /** + * Set whether the field allows multiple values + * This is only intended to be called from init() by implemented classes, and not called directly + * To instantiate a dropdown where only a single value is allowed, use SearchableDropdownField. + * To instantiate a dropdown where multiple values are allowed, use SearchableMultiDropdownField + */ + protected function setIsMultiple(bool $isMultiple): static + { + $this->isMultiple = $isMultiple; + return $this; + } + + private function getOptionsForSearchRequest(string $term): array + { + if (!$this->sourceList) { + return []; + } + $dataClass = $this->sourceList->dataClass(); + $labelField = $this->getLabelField(); + /** @var DataObject $obj */ + $obj = $dataClass::create(); + $key = $this->getUseSearchContext() ? $obj->getGeneralSearchFieldName() : $this->getLabelField(); + $searchParams = [$key => $term]; + $hasLabelField = (bool) $obj->getSchema()->fieldSpec($dataClass, $labelField); + $sort = $hasLabelField ? $labelField : null; + $limit = $this->getLazyLoadLimit(); + $newList = $this->getSearchContext()->getQuery($searchParams, $sort, $limit); + // Map into a distinct list + $options = []; + foreach ($newList->map('ID', $labelField) as $id => $label) { + $options[] = [ + 'value' => $id, + 'label' => $label, + ]; + } + return $options; + } + + private function getOptionsForSchema(bool $onlySelected = false): ArrayList + { + $options = ArrayList::create(); + if (!$this->sourceList) { + return $options; + } + $values = $this->getValueArray(); + if (empty($values)) { + $selectedValuesList = ArrayList::create(); + } else { + $selectedValuesList = $this->sourceList->filterAny(['ID' => $values]); + } + // SearchableDropdownField will have the getHasEmptyDefault() method from SingleSelectField + // Note that SingleSelectField::getSourceEmpty() will not be called for the react-select component + if (!$onlySelected && method_exists($this, 'getHasEmptyDefault') && $this->getHasEmptyDefault()) { + // Add an empty option to the start of the list of options + $options->push(ArrayData::create([ + 'value' => 0, + 'label' => $this->getPlaceholder(), + 'selected' => $selectedValuesList->count() === 0 + ])); + } + if ($onlySelected) { + $options = $this->updateOptions($options, $selectedValuesList, $selectedValuesList); + } else { + $options = $this->updateOptions($options, $this->sourceList, $selectedValuesList); + } + return $options; + } + + private function updateDataForSchema(array $data): array + { + $selectedOptions = $this->getOptionsForSchema(true); + $value = $selectedOptions->count() ? $selectedOptions->toNestedArray() : null; + if (is_null($value) + && method_exists($this, 'getHasEmptyDefault') + && !$this->getHasEmptyDefault() + ) { + $allOptions = $this->getOptionsForSchema(); + $value = $allOptions->first()?->toMap(); + } + $data['lazyLoad'] = $this->getIsLazyLoaded(); + $data['clearable'] = $this->getIsClearable(); + $data['multi'] = $this->getIsMultiple(); + $data['placeholder'] = $this->getPlaceholder(); + $data['searchable'] = $this->getIsSearchable(); + $data['value'] = $value; + return $data; + } + + /** + * @var ArrayList $options The options list being updated that will become + * @var DataList|ArrayList $items The items to be turned into options + * @var DataList|ArrayList $values The values that have been selected i.e. the value of the Field + */ + private function updateOptions( + ArrayList $options, + DataList|ArrayList $items, + DataList|ArrayList $selectedValuesList + ): ArrayList { + $labelField = $this->getLabelField(); + $selectedIDs = $selectedValuesList->column('ID'); + /** @var DataObject $item */ + foreach ($items as $item) { + $selected = in_array($item->ID, $selectedIDs); + $options->push(ArrayData::create([ + 'value' => $item->ID, + 'label' => $item->$labelField, + 'selected' => $selected, + ])); + } + return $options; + } +} diff --git a/src/Forms/SearchableMultiDropdownField.php b/src/Forms/SearchableMultiDropdownField.php new file mode 100644 index 00000000000..46fec276db6 --- /dev/null +++ b/src/Forms/SearchableMultiDropdownField.php @@ -0,0 +1,20 @@ +setIsMultiple(true); + $this->setIsClearable(true); + } +} diff --git a/tests/php/Forms/SearchableDropdownTraitTest.php b/tests/php/Forms/SearchableDropdownTraitTest.php new file mode 100644 index 00000000000..272c6c64862 --- /dev/null +++ b/tests/php/Forms/SearchableDropdownTraitTest.php @@ -0,0 +1,219 @@ +assertSame($singleField->getSchemaDataType(), FormField::SCHEMA_DATA_TYPE_SINGLESELECT); + $this->assertSame($multiField->getSchemaDataType(), FormField::SCHEMA_DATA_TYPE_MULTISELECT); + } + + public function testSearch(): void + { + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $request = new HTTPRequest('GET', 'someurl', ['term' => 'Team']); + $request->addHeader('X-SecurityID', SecurityToken::getSecurityID()); + $response = $field->search($request); + $this->assertSame(200, $response->getStatusCode()); + $actual = json_decode($response->getBody(), true); + $ids = Team::get()->column('ID'); + $names = Team::get()->column('Name'); + $expected = [ + ['value' => $ids[0], 'label' => $names[0]], + ['value' => $ids[1], 'label' => $names[1]], + ['value' => $ids[2], 'label' => $names[2]], + ]; + $this->assertSame($expected, $actual); + } + + public function testSearchNoCsrfToken(): void + { + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $request = new HTTPRequest('GET', 'someurl', ['term' => 'Team']); + $response = $field->search($request); + $this->assertSame(400, $response->getStatusCode()); + $actual = json_decode($response->getBody(), true); + $expected = ['message' => 'Invalid CSRF token']; + $this->assertSame($expected, $actual); + } + + public function testPlaceholder(): void + { + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $this->assertSame('Select or type to search...', $field->getPlaceholder()); + $field->setIsSearchable(false); + $this->assertSame('Select...', $field->getPlaceholder()); + $field->setIsLazyLoaded(true); + $this->assertSame('Type to search...', $field->getPlaceholder()); + $field->setEmptyString('My empty string'); + $this->assertSame('My empty string', $field->getPlaceholder()); + $field->setPlaceholder('My placeholder'); + $this->assertSame('My placeholder', $field->getPlaceholder()); + } + + public function testSeachContext(): void + { + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $team = Team::get()->first(); + // assert fallback is the default search context + $this->assertSame( + $team->getDefaultSearchContext()->getFields()->dataFieldNames(), + $field->getSearchContext()->getFields()->dataFieldNames() + ); + // assert setting a custom search context should override the default + $searchContext = new SearchContext(Team::class, new FieldList(new HiddenField('lorem'))); + $field->setSearchContext($searchContext); + $this->assertSame( + $searchContext->getFields()->dataFieldNames(), + $field->getSearchContext()->getFields()->dataFieldNames() + ); + } + + public function testLabelField(): void + { + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + // will use the default value of 'Title' for label field + $this->assertSame('Title', $field->getLabelField()); + // can override the default + $field->setLabelField('Something'); + $this->assertSame('Something', $field->getLabelField()); + } + + /** + * @dataProvider provideGetValueArray + */ + public function testGetValueArray(mixed $value, string|array $expected): void + { + if ($value === '') { + $value = Team::get(); + $ids = Team::get()->column('ID'); + $expected = [$ids[0], $ids[1], $ids[2]]; + } elseif ($value === '') { + $value = Team::get()->first(); + $expected = [$value->ID]; + } + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $field->setValue($value); + $this->assertSame($expected, $field->getValueArray()); + } + + public function provideGetValueArray(): array + { + return [ + 'empty' => [ + 'value' => '', + 'expected' => [], + ], + 'array single form builder' => [ + 'value' => ['Title' => 'MyTitle15', 'Value' => '10', 'Selected' => false], + 'expected' => [10], + ], + 'array multi form builder' => [ + 'value' => [ + ['MyTitle10' => '10', 'Value' => '10', 'Selected' => true], + ['MyTitle15' => '15', 'Value' => '15', 'Selected' => false], + ], + 'expected' => [10, 15], + ], + 'string int' => [ + 'value' => '3', + 'expected' => [3], + ], + 'zero string' => [ + 'value' => '0', + 'expected' => [], + ], + 'datalist' => [ + 'value' => '', + 'expected' => '', + ], + 'dataobject' => [ + 'value' => '', + 'expected' => '', + ], + 'something else' => [ + 'value' => new stdClass(), + 'expected' => [], + ], + 'negative int' => [ + 'value' => -1, + 'expected' => [], + ], + 'negative string int' => [ + 'value' => '-1', + 'expected' => [], + ], + ]; + } + + public function testGetSchemaDataDefaults(): void + { + // setting a form is required for Link() which is called for 'optionUrl' + $form = new Form(); + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $field->setForm($form); + $team = Team::get()->first(); + $schema = $field->getSchemaDataDefaults(); + $this->assertSame('MyField', $schema['name']); + $this->assertSame(['value' => $team->ID, 'label' => $team->Name, 'selected' => false], $schema['value']); + $this->assertFalse($schema['multi']); + $this->assertTrue(is_array($schema['options'])); + $this->assertFalse(array_key_exists('optionUrl', $schema)); + $this->assertFalse($schema['disabled']); + // lazyload changes options/optionUrl + $field->setIsLazyLoaded(true); + $schema = $field->getSchemaDataDefaults(); + $this->assertFalse(array_key_exists('options', $schema)); + $this->assertSame('field/MyField/search', $schema['optionUrl']); + // disabled + $field->setReadonly(true); + $schema = $field->getSchemaDataDefaults(); + $this->assertTrue($schema['disabled']); + // multi field name + $field = new SearchableMultiDropdownField('MyField', 'MyField', Team::get()); + $field->setForm($form); + $schema = $field->getSchemaDataDefaults(); + $this->assertSame('MyField[]', $schema['name']); + $this->assertTrue($schema['multi']); + // accessors + $field = new SearchableDropdownField('MyField', 'MyField', Team::get()); + $field->setForm($form); + $schema = $field->getSchemaDataDefaults(); + $this->assertFalse($schema['lazyLoad']); + $this->assertFalse($schema['clearable']); + $this->assertSame('Select or type to search...', $schema['placeholder']); + $this->assertTrue($schema['searchable']); + $field->setIsLazyLoaded(true); + $field->setIsClearable(true); + $field->setPlaceholder('My placeholder'); + $field->setIsSearchable(false); + $schema = $field->getSchemaDataDefaults(); + $this->assertTrue($schema['lazyLoad']); + $this->assertTrue($schema['clearable']); + $this->assertSame('My placeholder', $schema['placeholder']); + $this->assertFalse($schema['searchable']); + } +} diff --git a/tests/php/Forms/SearchableDropdownTraitTest.yml b/tests/php/Forms/SearchableDropdownTraitTest.yml new file mode 100644 index 00000000000..8ed8217342e --- /dev/null +++ b/tests/php/Forms/SearchableDropdownTraitTest.yml @@ -0,0 +1,7 @@ +SilverStripe\Forms\Tests\FormTest\Team: + team01: + Name: Team 01 + team02: + Name: Team 02 + team03: + Name: Team 03