diff --git a/CHANGELOG.md b/CHANGELOG.md index c807974..44a9577 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # CHANGELOG +## 14.2.0 + +- Added icon picker field + ## 14.1.0 - Added `select` method to tab field diff --git a/README.md b/README.md index 335a0f4..193cbd9 100644 --- a/README.md +++ b/README.md @@ -14,12 +14,12 @@ Extended ACF provides an object-oriented API to register groups and fields with - [Usage](#usage) - [Settings](#settings) - [Fields](#fields) - - [Basic Fields](#basic-fields) - - [Choice Fields](#choice-fields) - - [Content Fields](#content-fields) - - [jQuery Fields](#jquery-fields) - - [Layout Fields](#layout-fields) - - [Relational Fields](#relational-fields) + - [Basic](#basic) + - [Content](#content) + - [Choice](#choice) + - [Relational](#relational) + - [Advanced](#advanced) + - [Layout](#layout) - [Location](#location) - [Conditional Logic](#conditional-logic) - [Non-standards](#non-standards) @@ -91,9 +91,9 @@ Text::make('Title', 'heading') ->required() ``` -Most fields have the methods `default`, `required`, and `wrapper`. The [basic fields](#basic-fields) also have the methods `prepend`, `append`, `placeholder`, `readOnly`, and `disabled`. Please also check the non-standard methods mentioned in the [non-standards](#non-standards) section. +Most fields have the methods `default`, `required`, and `wrapper`. The [basic fields](#basic) also have the methods `prepend`, `append`, `placeholder`, `readOnly`, and `disabled`. Please also check the non-standard methods mentioned in the [non-standards](#non-standards) section. -### Basic Fields +### Basic **Email** - The [email field](https://www.advancedcustomfields.com/resources/text) creates a simple email input. @@ -174,7 +174,90 @@ URL::make('Website') ->required() ``` -### Choice Fields +### Content + +**File** - The [file field](https://www.advancedcustomfields.com/resources/file) allows a file to be uploaded and selected. + +```php +use Extended\ACF\Fields\File; + +File::make('Resturant Menu', 'menu') + ->helperText('Add the menu **pdf** file.') + ->acceptedFileTypes(['pdf']) + ->library('all') // all, uploadedTo + ->minSize('400 KB') + ->maxSize(5) // MB if entered as int + ->format('array') // id, url, array (default) + ->required() +``` + +**Gallery** - The [gallery field](https://www.advancedcustomfields.com/resources/gallery) provides a simple and intuitive interface for managing a collection of images. + +```php +use Extended\ACF\Fields\Gallery; + +Gallery::make('Images') + ->helperText('Add the gallery images.') + ->acceptedFileTypes(['jpg', 'jpeg', 'png']) + ->minHeight(500) + ->maxHeight(1400) + ->minWidth(1000) + ->maxWidth(2000) + ->minFiles(1) + ->maxFiles(6) + ->minSize('400 KB') + ->maxSize(5) // MB if entered as int + ->library('all') // all, uploadedTo + ->format('array') // id, url, array (default) + ->previewSize('medium') // thumbnail, medium, large + ->prependFiles() + ->required() +``` + +**Image** - The [image field](https://www.advancedcustomfields.com/resources/image) allows an image to be uploaded and selected. + +```php +use Extended\ACF\Fields\Image; + +Image::make('Background Image') + ->helperText('Add an image in at least 12000x100px and only in the formats **jpg**, **jpeg** or **png**.') + ->acceptedFileTypes(['jpg', 'jpeg', 'png']) + ->minHeight(500) + ->maxHeight(1400) + ->minWidth(1000) + ->maxWidth(2000) + ->minSize('400 KB') + ->maxSize(5) // MB if entered as int + ->library('all') // all, uploadedTo + ->format('array') // id, url, array (default) + ->previewSize('medium') // thumbnail, medium, large + ->required() +``` + +**Oembed** - The [oEmbed field](https://www.advancedcustomfields.com/resources/oembed) allows an easy way to embed videos, images, tweets, audio, and other content. + +```php +use Extended\ACF\Fields\Oembed; + +Oembed::make('Tweet') + ->helperText('Add a tweet from Twitter.') + ->required() +``` + +**WYSIWYG** - The [WYSIWYG field](https://www.advancedcustomfields.com/resources/wysiwyg-editor) creates a full WordPress tinyMCE content editor. + +```php +use Extended\ACF\Fields\WYSIWYGEditor; + +WYSIWYGEditor::make('Content') + ->helperText('Add the text content.') + ->tabs('visual') // all, text, visual (default) + ->toolbar(['bold', 'italic', 'link']) // aligncenter, alignleft, alignright, blockquote, bold, bullist, charmap, forecolor, formatselect, fullscreen, hr, indent, italic, link, numlist, outdent, pastetext, redo, removeformat, spellchecker, strikethrough, underline, undo, wp_adv, wp_help, wp_more + ->disableMediaUpload() + ->lazyLoad() + ->required() +``` +### Choice **Button Group** - The [button group](https://www.advancedcustomfields.com/resources/button-group) field creates a list of radio buttons. @@ -203,7 +286,7 @@ Checkbox::make('Color') ->required() ``` -**Radio** - The [radio button field](https://www.advancedcustomfields.com/resources/radio-button) creates a list of select-able inputs. +**Radio Button** - The [radio button field](https://www.advancedcustomfields.com/resources/radio-button) creates a list of select-able inputs. ```php use Extended\ACF\Fields\RadioButton; @@ -245,91 +328,95 @@ TrueFalse::make('Social Media', 'display_social_media') ->required() ``` -### Content Fields +### Relational -**File** - The [file field](https://www.advancedcustomfields.com/resources/file) allows a file to be uploaded and selected. +**Link** - The [link field](https://www.advancedcustomfields.com/resources/link) provides a simple way to select or define a link (url, title, target). ```php -use Extended\ACF\Fields\File; +use Extended\ACF\Fields\Link; -File::make('Resturant Menu', 'menu') - ->helperText('Add the menu **pdf** file.') - ->acceptedFileTypes(['pdf']) - ->library('all') // all, uploadedTo - ->minSize('400 KB') - ->maxSize(5) // MB if entered as int - ->format('array') // id, url, array (default) +Link::make('Read More Link') + ->format('array') // url, array (default) ->required() ``` -**Gallery** - The [gallery field](https://www.advancedcustomfields.com/resources/gallery) provides a simple and intuitive interface for managing a collection of images. +**Page Link** - The [page link field](https://www.advancedcustomfields.com/resources/page-link) allows the selection of 1 or more posts, pages or custom post types. ```php -use Extended\ACF\Fields\Gallery; +use Extended\ACF\Fields\PageLink; -Gallery::make('Images') - ->helperText('Add the gallery images.') - ->acceptedFileTypes(['jpg', 'jpeg', 'png']) - ->minHeight(500) - ->maxHeight(1400) - ->minWidth(1000) - ->maxWidth(2000) - ->minFiles(1) - ->maxFiles(6) - ->minSize('400 KB') - ->maxSize(5) // MB if entered as int - ->library('all') // all, uploadedTo - ->format('array') // id, url, array (default) - ->previewSize('medium') // thumbnail, medium, large - ->prependFiles() +PageLink::make('Contact Link') + ->postTypes(['contact']) + ->postStatus(['publish']) // draft, future, pending, private, publish + ->taxonomies(['category:city']) + ->disableArchives() + ->nullabel() + ->multiple() ->required() ``` -**Image** - The [image field](https://www.advancedcustomfields.com/resources/image) allows an image to be uploaded and selected. +**Post Object** - The [post object field](https://www.advancedcustomfields.com/resources/post-object) creates a select field where the choices are your pages + posts + custom post types. ```php -use Extended\ACF\Fields\Image; +use Extended\ACF\Fields\PostObject; -Image::make('Background Image') - ->helperText('Add an image in at least 12000x100px and only in the formats **jpg**, **jpeg** or **png**.') - ->acceptedFileTypes(['jpg', 'jpeg', 'png']) - ->minHeight(500) - ->maxHeight(1400) - ->minWidth(1000) - ->maxWidth(2000) - ->minSize('400 KB') - ->maxSize(5) // MB if entered as int - ->library('all') // all, uploadedTo - ->format('array') // id, url, array (default) - ->previewSize('medium') // thumbnail, medium, large +PostObject::make('Animal') + ->helperText('Select an animal') + ->postTypes(['animal']) + ->postStatus(['publish']) // draft, future, pending, private, publish + ->nullabel() + ->multiple() + ->format('object') // id, object (default) ->required() ``` -**Oembed** - The [oEmbed field](https://www.advancedcustomfields.com/resources/oembed) allows an easy way to embed videos, images, tweets, audio, and other content. +**Relationship** - The [relationship field](https://www.advancedcustomfields.com/resources/relationship) creates a very attractive version of the post object field. ```php -use Extended\ACF\Fields\Oembed; +use Extended\ACF\Fields\Relationship; -Oembed::make('Tweet') - ->helperText('Add a tweet from Twitter.') +Relationship::make('Contacts') + ->helperText('Add the contacts.') + ->postTypes(['contact']) + ->postStatus(['publish']) // draft, future, pending, private, publish + ->filters([ + 'search', + 'post_type', + 'taxonomy' + ]) + ->elements(['featured_image']) + ->minPosts(3) + ->maxPosts(6) + ->format('object') // id, object (default) ->required() ``` -**WYSIWYG** - The [WYSIWYG field](https://www.advancedcustomfields.com/resources/wysiwyg-editor) creates a full WordPress tinyMCE content editor. +**Taxonomy** - The [taxonomy field](https://www.advancedcustomfields.com/resources/taxonomy) allows the selection of 1 or more taxonomy terms. ```php -use Extended\ACF\Fields\WYSIWYGEditor; +use Extended\ACF\Fields\Taxonomy; -WYSIWYGEditor::make('Content') - ->helperText('Add the text content.') - ->tabs('visual') // all, text, visual (default) - ->toolbar(['bold', 'italic', 'link']) // aligncenter, alignleft, alignright, blockquote, bold, bullist, charmap, forecolor, formatselect, fullscreen, hr, indent, italic, link, numlist, outdent, pastetext, redo, removeformat, spellchecker, strikethrough, underline, undo, wp_adv, wp_help, wp_more - ->disableMediaUpload() - ->lazyLoad() - ->required() +Taxonomy::make('Cinemas') + ->helperText('Select one or more cinema terms.') + ->taxonomy('cinema') + ->appearance('checkbox') // checkbox, multi_select, radio, select + ->create(false) // false or true (default) + ->load(true) // true or false (default) + ->save(true) // true or false (default)x + ->format('id'), // object or id (default) +``` + +**User** - The user field creates a select field for all your users. + +```php +use Extended\ACF\Fields\User; + +User::make('User') + ->roles(['administrator', 'editor']) // administrator, author, contributor, editor, subscriber + ->format('array'), // id, object, array (default) ``` -### jQuery Fields +### Advanced **Color Picker** - The [color picker field](https://www.advancedcustomfields.com/resources/color-picker) allows a color to be selected via a JavaScript popup. @@ -340,6 +427,7 @@ ColorPicker::make('Text Color') ->helperText('Add the text color.') ->default('#4a9cff') ->opacity() + ->format('string') // array, string (default) ->required() ``` @@ -355,6 +443,18 @@ DatePicker::make('Birthday') ->required() ``` +**Icon Picker** - The [icon picker field](https://www.advancedcustomfields.com/resources/icon-picker) allows you to easily select a Dashicon, a Media Library image, or a URL for an image or SVG. + +```php +use Extended\ACF\Fields\IconPicker; + +IconPicker::make('Icon') + ->helperText('Add the icon.') + ->format('string') // array, string (default) + ->tabs(['dashicons']) // [dashicons, media_library, url] (default) + ->required() +``` + **Time Picker** - The [time picker field](https://www.advancedcustomfields.com/resources/time-picker) creates a jQuery time selection popup. ```php @@ -392,7 +492,7 @@ GoogleMap::make('Address', 'address') ->required() ``` -### Layout Fields +### Layout **Accordion** - The [accordion field](https://www.advancedcustomfields.com/resources/accordion) is used to organize fields into collapsible panels. @@ -514,94 +614,6 @@ Tab::make('Tab 3') ->endpoint(), // This will make a break in the tabs and create a new group of tabs ``` -### Relational Fields - -**Link** - The [link field](https://www.advancedcustomfields.com/resources/link) provides a simple way to select or define a link (url, title, target). - -```php -use Extended\ACF\Fields\Link; - -Link::make('Read More Link') - ->format('array') // url, array (default) - ->required() -``` - -**Page Link** - The [page link field](https://www.advancedcustomfields.com/resources/page-link) allows the selection of 1 or more posts, pages or custom post types. - -```php -use Extended\ACF\Fields\PageLink; - -PageLink::make('Contact Link') - ->postTypes(['contact']) - ->postStatus(['publish']) // draft, future, pending, private, publish - ->taxonomies(['category:city']) - ->disableArchives() - ->nullabel() - ->multiple() - ->required() -``` - -**Post Object** - The [post object field](https://www.advancedcustomfields.com/resources/post-object) creates a select field where the choices are your pages + posts + custom post types. - -```php -use Extended\ACF\Fields\PostObject; - -PostObject::make('Animal') - ->helperText('Select an animal') - ->postTypes(['animal']) - ->postStatus(['publish']) // draft, future, pending, private, publish - ->nullabel() - ->multiple() - ->format('object') // id, object (default) - ->required() -``` - -**Relationship** - The [relationship field](https://www.advancedcustomfields.com/resources/relationship) creates a very attractive version of the post object field. - -```php -use Extended\ACF\Fields\Relationship; - -Relationship::make('Contacts') - ->helperText('Add the contacts.') - ->postTypes(['contact']) - ->postStatus(['publish']) // draft, future, pending, private, publish - ->filters([ - 'search', - 'post_type', - 'taxonomy' - ]) - ->elements(['featured_image']) - ->minPosts(3) - ->maxPosts(6) - ->format('object') // id, object (default) - ->required() -``` - -**Taxonomy** - The [taxonomy field](https://www.advancedcustomfields.com/resources/taxonomy) allows the selection of 1 or more taxonomy terms. - -```php -use Extended\ACF\Fields\Taxonomy; - -Taxonomy::make('Cinemas') - ->helperText('Select one or more cinema terms.') - ->taxonomy('cinema') - ->appearance('checkbox') // checkbox, multi_select, radio, select - ->create(false) // false or true (default) - ->load(true) // true or false (default) - ->save(true) // true or false (default)x - ->format('id'), // object or id (default) -``` - -**User** - The user field creates a select field for all your users. - -```php -use Extended\ACF\Fields\User; - -User::make('User') - ->roles(['administrator', 'editor']) // administrator, author, contributor, editor, subscriber - ->format('array'), // id, object, array (default) -``` - ## Location The `Location` class allows you to write custom location rules without specifying the `name`, `operator`, and `value` keys. If no `operator` is provided, it will use the `operator` as the `value`. For additional details on custom location rules, please visit [this link](https://www.advancedcustomfields.com/resources/custom-location-rules). diff --git a/composer.json b/composer.json index f11e4ea..4aad3b6 100644 --- a/composer.json +++ b/composer.json @@ -46,7 +46,7 @@ }, "extra": { "branch-alias": { - "dev-master": "14.1-dev" + "dev-master": "14.2-dev" } } } diff --git a/src/Fields/IconPicker.php b/src/Fields/IconPicker.php new file mode 100644 index 0000000..8fa3fe0 --- /dev/null +++ b/src/Fields/IconPicker.php @@ -0,0 +1,64 @@ +settings['return_format'] = $format; + + return $this; + } + + /** + * @param array $tabs dashicons, media_library, url + * @throws \InvalidArgumentException + */ + public function tabs(array $tabs): static + { + foreach ($tabs as $tab) { + if (!in_array($tab, ['dashicons', 'media_library', 'url'])) { + throw new InvalidArgumentException("Invalid argument tab [$tab]."); + } + } + + $this->settings['tabs'] = $tabs; + + return $this; + } +} diff --git a/tests/Fields/IconPickerTest.php b/tests/Fields/IconPickerTest.php new file mode 100644 index 0000000..9a4b8bb --- /dev/null +++ b/tests/Fields/IconPickerTest.php @@ -0,0 +1,56 @@ +format('array')->get(); + $this->assertSame('array', $field['return_format']); + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Invalid argument format [test].'); + + IconPicker::make('Invalid Format')->format('test')->get(); + } + + public function testTabs() + { + $field = IconPicker::make('Icon Picker Tabs')->tabs(['dashicons'])->get(); + $this->assertSame(['dashicons'], $field['tabs']); + + $this->expectException(InvalidArgumentException::class); + $this->expectExceptionMessage('Invalid argument tab [test].'); + + $field = IconPicker::make('Invalid Tab')->tabs(['test'])->get(); + } +}