From b140f63a9121df0a80372642a564d10d099b176c Mon Sep 17 00:00:00 2001 From: Jason Bahl Date: Wed, 30 Jun 2021 08:05:07 -0600 Subject: [PATCH] Move docs for each field type out of the main README.md and into their own files. No changes to the content of the docs, just organization of the docs. --- README.md | 1661 +------------------------------ docs/fields/accordion.md | 10 + docs/fields/button-group.md | 41 + docs/fields/checkbox.md | 43 + docs/fields/clone.md | 9 + docs/fields/color-picker.md | 40 + docs/fields/date-picker.md | 40 + docs/fields/date-time-picker.md | 40 + docs/fields/email.md | 40 + docs/fields/file.md | 48 + docs/fields/flexible-content.md | 144 +++ docs/fields/gallery.md | 55 + docs/fields/google-map.md | 71 ++ docs/fields/group.md | 44 + docs/fields/image.md | 48 + docs/fields/link.md | 55 + docs/fields/message.md | 8 + docs/fields/number.md | 40 + docs/fields/oembed.md | 41 + docs/fields/page-link.md | 87 ++ docs/fields/password.md | 40 + docs/fields/post-object.md | 125 +++ docs/fields/radio.md | 40 + docs/fields/range.md | 40 + docs/fields/relationship.md | 72 ++ docs/fields/repeater.md | 68 ++ docs/fields/select.md | 40 + docs/fields/tab.md | 8 + docs/fields/taxonomy.md | 53 + docs/fields/text-area.md | 41 + docs/fields/text.md | 41 + docs/fields/time-picker.md | 41 + docs/fields/true-false.md | 41 + docs/fields/url.md | 41 + docs/fields/user.md | 81 ++ docs/fields/wysiwyg.md | 39 + 36 files changed, 1766 insertions(+), 1610 deletions(-) create mode 100644 docs/fields/accordion.md create mode 100644 docs/fields/button-group.md create mode 100644 docs/fields/checkbox.md create mode 100644 docs/fields/clone.md create mode 100644 docs/fields/color-picker.md create mode 100644 docs/fields/date-picker.md create mode 100644 docs/fields/date-time-picker.md create mode 100644 docs/fields/email.md create mode 100644 docs/fields/file.md create mode 100644 docs/fields/flexible-content.md create mode 100644 docs/fields/gallery.md create mode 100644 docs/fields/google-map.md create mode 100644 docs/fields/group.md create mode 100644 docs/fields/image.md create mode 100644 docs/fields/link.md create mode 100644 docs/fields/message.md create mode 100644 docs/fields/number.md create mode 100644 docs/fields/oembed.md create mode 100644 docs/fields/page-link.md create mode 100644 docs/fields/password.md create mode 100644 docs/fields/post-object.md create mode 100644 docs/fields/radio.md create mode 100644 docs/fields/range.md create mode 100644 docs/fields/relationship.md create mode 100644 docs/fields/repeater.md create mode 100644 docs/fields/select.md create mode 100644 docs/fields/tab.md create mode 100644 docs/fields/taxonomy.md create mode 100644 docs/fields/text-area.md create mode 100644 docs/fields/text.md create mode 100644 docs/fields/time-picker.md create mode 100644 docs/fields/true-false.md create mode 100644 docs/fields/url.md create mode 100644 docs/fields/user.md create mode 100644 docs/fields/wysiwyg.md diff --git a/README.md b/README.md index f231b0f..1ad8cba 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # WPGraphQL for Advanced Custom Fields -WPGraphQL for Advanced Custom Fields automatically exposes your ACF fields to the WPGraphQL Schema. +WPGraphQL for Advanced Custom Fields automatically exposes your ACF fields to the WPGraphQL Schema. - [Install and Activate](#install-and-activate) - [Installing from Github](#install-from-github) @@ -8,51 +8,51 @@ WPGraphQL for Advanced Custom Fields automatically exposes your ACF fields to th - [Dependencies](#dependencies) - [Adding Fields to the WPGraphQL Schema](#adding-fields-to-wpgraphql) - [Supported Fields](#supported-fields) - - [Text](#text-field) - - [Text Area](#text-area-field) - - [Number](#number-field) - - [Range](#range-field) - - [Email](#email-field) - - [URL](#url-field) - - [Password](#password-field) - - [Image](#image-field) - - [File](#file-field) - - [WYSIWYG Editor](#wysiwyg-field) - - [oEmbed](#oembed-field) - - [Gallery](#gallery-field) - - [Select](#select-field) - - [Checkbox](#checkbox-field) - - [Radio Button](#radio-button-field) - - [Button Group](#button-group-field) - - [True/False](#true-false-field) - - [Link](#link-field) - - [Post Object](#post-object-field) - - [Page Link](#page-link-field) - - [Relationship](#relationship-field) - - [Taxonomy](#taxonomy-field) - - [User](#user-field) - - [Google Map](#google-map-field) - - [Date Picker](#date-picker-field) - - [Date/Time Picker](#date-time-picker-field) - - [Time Picker](#time-picker-field) - - [Color Picker](#color-picker-field) - - [Message](#message-field) - - [Accordion](#accordion-field) - - [Tab](#tab-field) - - [Group](#group-field) - - [Repeater](#repeater-field) - - [Flexible Content](#flexible-content-field) - - [Clone](#clone-field) + - [Accordion](./docs/fields/accordion.md) + - [Button Group](./docs/fields/button-group.md) + - [Checkbox](./docs/fields/checkbox.md) + - [Clone](./docs/fields/clone.md) + - [Color Picker](./docs/fields/color-picker.md) + - [Date Picker](./docs/fields/date-picker.md) + - [Date/Time Picker](./docs/fields/date-time-picker.md) + - [Email](./docs/fields/email.md) + - [File](./docs/fields/file.md) + - [Flexible Content](./docs/fields/flexible-content.md) + - [Gallery](./docs/fields/gallery.md) + - [Google Map](./docs/fields/google-map.md) + - [Group](./docs/fields/group.md) + - [Image](./docs/fields/image.md) + - [Link](./docs/fields/link.md) + - [Message](./docs/fields/message.md) + - [Number](./docs/fields/number.md) + - [Oembed](./docs/fields/oembed.md) + - [Page Link](./docs/fields/page-link.md) + - [Password](./docs/fields/password.md) + - [Post Object](./docs/fields/post-object.md) + - [Radio](./docs/fields/radio.md) + - [Range](./docs/fields/range.md) + - [Relationship](./docs/fields/relationship.md) + - [Repeater](./docs/fields/repeater.md) + - [Select](./docs/fields/select.md) + - [Tab](./docs/fields/tab.md) + - [Taxonomy](./docs/fields/taxonomy.md) + - [Text](./docs/fields/text.md) + - [Text Area](./docs/fields/text-area.md) + - [Time Picker](./docs/fields/time-picker.md) + - [True/False](./docs/fields/true-false.md) + - [Url](./docs/fields/url.md) + - [User](./docs/fields/user.md) + - [WYSIWYG](./docs/fields/wysiwyg.md) - [Options Pages](#options-pages) - [Location Rules](#location-rules) ## Install and Activate -WPGraphQL for Advanced Custom Fields is not currently available on the WordPress.org repository, so you must download it from Github, or Composer. +WPGraphQL for Advanced Custom Fields is not currently available on the WordPress.org repository, so you must download it from Github, or Composer. ### Installing From Github -To install the plugin from Github, you can [download the latest release zip file](https://github.com/wp-graphql/wp-graphql-acf/archive/master.zip), upload the Zip file to your WordPress install, and activate the plugin. +To install the plugin from Github, you can [download the latest release zip file](https://github.com/wp-graphql/wp-graphql-acf/archive/master.zip), upload the Zip file to your WordPress install, and activate the plugin. [Click here](https://wordpress.org/support/article/managing-plugins/) to learn more about installing WordPress plugins from a Zip file. @@ -62,19 +62,19 @@ To install the plugin from Github, you can [download the latest release zip file ## Dependencies -In order to use WPGraphQL for Advanced Custom Fields, you must have [WPGraphQL](https://github.com/wp-graphql/wp-graphql) and [Advanced Custom Fields](https://advancedcustomfields.com) (free or pro) installed and activated. +In order to use WPGraphQL for Advanced Custom Fields, you must have [WPGraphQL](https://github.com/wp-graphql/wp-graphql) and [Advanced Custom Fields](https://advancedcustomfields.com) (free or pro) installed and activated. ## Adding Fields to the WPGraphQL Schema **TL;DR:** [Here's a video](https://www.youtube.com/watch?v=rIg4MHc8elg) showing an overview of usage. -Advanced Custom Fields, or ACF for short, enables users to add Field Groups, either using a [Graphical User Interface](https://www.advancedcustomfields.com/resources/creating-a-field-group/), [PHP code](https://www.advancedcustomfields.com/resources/register-fields-via-php/), or [local JSON](https://www.advancedcustomfields.com/resources/local-json/) to various screens in the WordPress dashboard, such as (but not limited to) the Edit Post, Edit User and Edit Term screens. +Advanced Custom Fields, or ACF for short, enables users to add Field Groups, either using a [Graphical User Interface](https://www.advancedcustomfields.com/resources/creating-a-field-group/), [PHP code](https://www.advancedcustomfields.com/resources/register-fields-via-php/), or [local JSON](https://www.advancedcustomfields.com/resources/local-json/) to various screens in the WordPress dashboard, such as (but not limited to) the Edit Post, Edit User and Edit Term screens. -Whatever method you use to register ACF fields to your WordPress site should work with WPGraphQL for Advanced Custom Fields. For the sake of simplicity, the documentation below will _primarily_ use the Graphic User Interface for examples. +Whatever method you use to register ACF fields to your WordPress site should work with WPGraphQL for Advanced Custom Fields. For the sake of simplicity, the documentation below will _primarily_ use the Graphic User Interface for examples. ### Add ACF Fields to the WPGraphQL Schema -The first step in using Advanced Custom Fields with WPGraphQL is to [create an ACF Field Group](https://www.advancedcustomfields.com/resources/creating-a-field-group/). +The first step in using Advanced Custom Fields with WPGraphQL is to [create an ACF Field Group](https://www.advancedcustomfields.com/resources/creating-a-field-group/). By default, field groups are _not_ exposed to WPGraphQL. You must opt-in to expose your ACF Field Groups and fields to the WPGraphQL Schema as some information managed by your ACF fields may not be intended for exposure in a queryable API like WPGraphQL. @@ -96,7 +96,7 @@ When registering ACF Fields in PHP, you need to add `show_in_graphql` and `graph ``` function my_acf_add_local_field_groups() { - + acf_add_local_field_group(array( 'key' => 'group_1', 'title' => 'My Group', @@ -120,7 +120,7 @@ function my_acf_add_local_field_groups() { ), ), )); - + } add_action('acf/init', 'my_acf_add_local_field_groups'); @@ -130,7 +130,7 @@ Each individual field will inherit its GraphQL name from the supplied `name` tag ## Supported Fields -In order to document interacting with the fields in GraphQL, an example field group has been created with one field of each type. +In order to document interacting with the fields in GraphQL, an example field group has been created with one field of each type. To replicate the same field group documented here you can download the [example field group](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/field-group-examples-export.json) and [import it](https://support.advancedcustomfields.com/forums/topic/importing-exporting-acf-settings/) into your environment. @@ -138,1565 +138,6 @@ For the sake of documentation, this example field group has the [location rule]( ![Location rule set to Post Type is equal to Post](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/location-rule-post-type-post.png?raw=true) -### Text Field - -Text fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Text fields can be queried and a String will be returned. - -Here, we have a Text field named `text` on the Post Edit screen within the "ACF Docs" Field Group. - -![Text field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/text-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - text - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "text": "Text Value" - } - } - } -} -``` - -### Text Area Field - -Text Area fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Text Area fields can be queried and a String will be returned. - -Here, we have a Text Area field named `text_area` on the Post Edit screen within the "ACF Docs" Field Group. - -![Text Area field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/text-area-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - textArea - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "textArea": "Text value" - } - } - } -} -``` - -### Number Field - -Number fields are added to the WPGraphQL Schema as a field with the Type `Float`. - -Number fields can be queried and a Float will be returned. - -Here, we have a Number field named `number` on the Post Edit screen within the "ACF Docs" Field Group. - -![Number field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/number-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - number - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "number": 5 - } - } - } -} -``` - -### Range Field - -Range fields are added to the WPGraphQL Schema as a field with the Type `Float`. - -Range fields can be queried and a Float will be returned. - -Here, we have a Range field named `range` on the Post Edit screen within the "ACF Docs" Field Group. - -![Range field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/range-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - range - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "range": 5 - } - } - } -} -``` - -### Email Field - -Email fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Email fields can be queried and a String will be returned. - -Here, we have an Email field named `email` on the Post Edit screen within the "ACF Docs" Field Group. - -![Email field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/email-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - email - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "email": "test@example.com" - } - } - } -} -``` - -### URL Field - -Url fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Url fields can be queried and a String will be returned. - -Here, we have a URL field named `url` on the Post Edit screen within the "ACF Docs" Field Group. - -![Url field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/url-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - url - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "url": "https://wpgraphql.com" - } - } - } -} -``` - -### Password Field - -Password fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Password fields can be queried and a String will be returned. - -Here, we have a Password field named `password` on the Post Edit screen within the "ACF Docs" Field Group. - -![Password field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/password-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - password - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "password": "123456" - } - } - } -} -``` - -### Image Field - -Image fields are added to the WPGraphQL Schema as a field with the Type `MediaItem`. - -Image fields can be queried and a MediaItem will be returned. - -The `MediaItem` type is an Object type that has it's own fields that can be selected. So, instead of _just_ getting the Image ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the `id` and `sourceUrl`. - -Here, we have an Image field named `image` on the Post Edit screen within the "ACF Docs" Field Group. - -![Image field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/image-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - image { - id - sourceUrl(size: MEDIUM) - } - } - } -} -``` - -And the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "image": { - "id": "YXR0YWNobWVudDozMjM=", - "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/03/babe-ruth-300x169.jpg" - } - } - } - } -} -``` - -### File Field - -File fields are added to the WPGraphQL Schema as a field with the Type `MediaItem`. - -File fields can be queried and a MediaItem will be returned. - -The `MediaItem` type is an Object type that has it's own fields that can be selected. So, instead of _just_ getting the File ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the `id` and `mediaItemUrl`. - -Here, we have a File field named `file` on the Post Edit screen within the "ACF Docs" Field Group. - -![File field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/file-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - file { - id - mediaItemUrl - } - } - } -} -``` - -And the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "file": { - "id": "YXR0YWNobWVudDozMjQ=", - "mediaItemUrl": "http://acf2.local/wp-content/uploads/2020/03/little-ceasars-receipt-01282020.pdf" - } - } - } - } -} -``` - -### WYSIWYG Editor Field - -WYSIWYG fields are added to the WPGraphQL Schema as a field with the Type `String`. - -WYSIWYG fields can be queried and a String will be returned. - -Here, we have a WYSIWYG field named `wysiwyg` on the Post Edit screen within the "ACF Docs" Field Group. - -![WYSIWYG field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/wysiwyg-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post( id: "acf-example-test" idType: URI ) { - acfDocs { - wysiwyg - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "wysiwyg": "

Some content in a WYSIWYG field

\n" - } - } - } -} -``` - -### oEmbed Field - -oEmbed fields are added to the WPGraphQL Schema as a field with the Type `String`. - -oEmbed fields can be queried and a String will be returned. - -Here, we have a oEmbed field named `oembed` on the Post Edit screen within the "ACF Docs" Field Group. - -![oEmbed field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/oEmbed-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - oembed - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "oembed": "https://www.youtube.com/watch?v=ZEytXfaWwcc" - } - } - } -} -``` - -### Gallery Field - -Gallery fields are added to the WPGraphQL Schema as a field with the Type of `['list_of' => 'MediaItem']`. - -Gallery fields can be queried and a list of MediaItem types will be returned. - -Since the type is a list, we can expect an array to be returned. And since the Type within the list is `MediaItem`, we can ask for fields we want returned for each `MediaItem` in the list. In this case, let's say we want to ask for the `id` of each image and the `sourceUrl`, (size large). - -Here, we have a Gallery field named `gallery` on the Post Edit screen within the "ACF Docs" Field Group. - -![Gallery field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/gallery-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - gallery { - id - sourceUrl(size: LARGE) - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "gallery": [ - { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth.jpg" - }, - { - "id": "YXR0YWNobWVudDoyNTU=", - "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth-baseball-986x1024.jpg" - } - ] - } - } - } -} -``` - -### Select Field - -Select fields (when configured to _not_ allow mutliple selections) are added to the WPGraphQL Schema as a field with the Type `String`. - -Select fields, without multiple selections allowed, can be queried and a String will be returned. - -Here, we have a Select field named `select` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected. - -![Select field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/select-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - select - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "select": "choice_1" - } - } - } -} -``` - -### Checkbox Field - -Checkbox fields are added to the WPGraphQL Schema as a field with the Type `[ 'list_of' => 'String' ]`. - -Checkbox fields can be queried and a list (array) of Strings (the selected values) will be returned. - -Here, we have a Checkbox field named `checkbox` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected. - -![Checkbox field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/checkbox-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - checkbox - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "checkbox": [ - "choice_1" - ] - } - } - } -} -``` - -### Radio Button Field - -Radio Button fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Radio Button fields can be queried and a String will be returned. - -Here, we have a Radio Button field named `radio_button` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected. - -![Radio Button field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/radio-button-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - radioButton - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "radioButton": "choice_2" - } - } - } -} -``` - -### Button Group Field - -Button Group fields are added to the WPGraphQL Schema as a field with the Type `String`. - -Button Group fields can be queried and a String will be returned. - -Here, we have a Button Group field named `button_group` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected. - -![Button Group field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/button-group-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - buttonGroup - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "buttonGroup": "choice_2" - } - } - } -} -``` - -### True/False Field - -True/False fields are added to the WPGraphQL Schema as a field with the Type `Boolean`. - -True/False fields can be queried and a Boolean will be returned. - -Here, we have a True/False field named `true_false` on the Post Edit screen within the "ACF Docs" Field Group, and "true" is selected. - -![True/False field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/true-false-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - trueFalse - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "trueFalse": true - } - } - } -} -``` - -### Link Field - -Link fields are added to the WPGraphQL Schema as a field with the Type `ACF_Link`. - -Link fields can be queried and a `ACF_Link` will be returned. The ACF Link is an object with fields that can be selected. - -The available fields on the `ACF_Link` Type are: - -- **target** (String): The target of the link -- **title** (String): The target of the link -- **url** (String): The url of the link - -Here, we have a Link field named `link` on the Post Edit screen within the "ACF Docs" Field Group. - -![Link field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/link-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - link { - target - title - url - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "link": { - "target": "", - "title": "Hello world!", - "url": "http://acf2.local/hello-world/" - } - } - } - } -} -``` - -### Post Object Field - -Post Object fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. - -If the field is configured to allow multiple selections, it will be added to the Schema as a List Of the Union Type. - -Since Post Object fields can be configured to be limited to certain Post Types, the Union will represent those Types. - -For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: - -![Post Object field Post Type Config](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/post-object-field-post-type-config.png?raw=true) - -Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: - -![Post Object field Union Possible Types](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/post-object-field-possible-types.png?raw=true) - -Here, we have a Post Object field named `post_object` on the Post Edit screen within the "ACF Docs" Field Group, configured with the Post "Hello World!". - -![Post Object field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/post-object-field-input-post.png?raw=true) - -As a GraphQL consumer, we don't know in advance if the value is going to be a Page or a Post. - -So we can specify, via GraphQL fragment, what fields we want if the object is a Post, or if it is a Page. - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - postObject { - __typename - ... on Post { - id - title - date - } - ... on Page { - id - title - } - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "postObject": { - "__typename": "Post", - "id": "cG9zdDox", - "title": "Hello world!", - "date": "2020-02-20T23:12:21" - } - } - } - } -} -``` - -If the input of the field was saved as a Page, instead of a Post, like so: - -![Post Object field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/post-object-field-input-page.png?raw=true) - -Then the same query above, would return the following results: - -```json -{ - "data": { - "post": { - "acfDocs": { - "postObject": { - "__typename": "Page", - "id": "cGFnZToy", - "title": "Sample Page" - } - } - } - } -} -``` - -Now, if the field were configured to allow multiple values, the field would be added to the Schema as a `listOf`, returning an Array of the Union. - -If the field were set with a value of one Page, and one Post, like so: - -![Post Object field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/post-object-field-input-multi.png?raw=true) - -Then the results of the same query as above would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "postObject": [ - { - "__typename": "Page", - "id": "cGFnZToy", - "title": "Sample Page" - }, - { - "__typename": "Post", - "id": "cG9zdDox", - "title": "Hello world!", - "date": "2020-02-20T23:12:21" - } - ] - } - } - } -} -``` - -### Page Link Field - -Page Link fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. - -Since Page Link fields can be configured to be limited to certain Post Types, the Union will represent those Types. - -For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: - -![Page Link field Post Type Config](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/page-link-field-post-type-config.png?raw=true) - -Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: - -![Page Link field Union Possible Types](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/page-link-field-possible-types.png?raw=true) - -Here, we have a Page Link field named `page_link` on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to the "Sample Page" page. - -![Page Link field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/page-link-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - pageLink { - __typename - ... on Post { - id - title - date - } - ... on Page { - id - title - } - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "pageLink": { - "__typename": "Page", - "id": "cGFnZToy", - "title": "Sample Page" - } - } - } - } -} -``` - -Here, we set the value to the "Hello World" Post: - -![Page Link field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/page-link-field-input-2.png?raw=true) - -And the results of the same query are now: - -```json -{ - "data": { - "post": { - "acfDocs": { - "pageLink": { - "__typename": "Post", - "id": "cG9zdDox", - "title": "Hello world!", - "date": "2020-02-20T23:12:21" - } - } - } - } -} -``` - -### Relationship Field - -Relationship fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. - -Since Relationship fields can be configured to be limited to certain Post Types, the Union will represent those Types. - -For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: - -![Relationship field Post Type Config](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/relationship-field-post-type-config.png?raw=true) - -Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: - -![Relationship field Union Possible Types](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/relationship-field-possible-types.png?raw=true) - -Here, we have a Relationship field named `relationship` on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to "Hello World!" post, and the "Sample Page" page. - -![Relationship field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/relationship-field-input.png?raw=true) - -This field can be Queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - relationship { - __typename - ... on Post { - id - title - date - } - ... on Page { - id - title - } - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "relationship": [ - { - "__typename": "Post", - "id": "cG9zdDox", - "title": "Hello world!", - "date": "2020-02-20T23:12:21" - }, - { - "__typename": "Page", - "id": "cGFnZToy", - "title": "Sample Page" - } - ] - } - } - } -} -``` - -### Taxonomy Field - -The Taxonomy field is added to the GraphQL Schema as a List Of the Taxonomy Type. - -For example, if the field is configured to the "Category" taxonomy, then the field in the Schema will be a List of the Category type. - -![Taxonomy field Taxonomy Config](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/taxonomy-field-taxonomy-config.png?raw=true) - -Here, we have a Taxonomy field named `taxonomy` on the Post Edit screen within the "ACF Docs" Field Group, configured with the Category "Test Category". - -![Taxonomy field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/taxonomy-field-input.png?raw=true) - -This field can be queried like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - taxonomy { - __typename - id - name - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "taxonomy": [ - { - "__typename": "Category", - "id": "Y2F0ZWdvcnk6Mg==", - "name": "Test Category" - } - ] - } - } - } -} -``` - -### User Field - -User fields are added to the WPGraphQL Schema as a field with a User type. - -Here, we have a User field named `user` on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" as the value. - -![User field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/user-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - user { - id - username - firstName - lastName - } - } - } -} -``` - -and the response would look like: - -```json -{ - "data": { - "post": { - "acfDocs": { - "user": { - "id": "dXNlcjox", - "username": "jasonbahl", - "firstName": "Jason", - "lastName": "Bahl" - } - } - } - } -} -``` - -If the field is configured to allow multiple selections, it's added to the Schema as a List Of the User type. - -Here, we have a User field named `user` on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" and "WPGraphQL" as the value. - -![User field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/user-field-input-multiple.png?raw=true) - -and the response to the same query would look like: - -```json -{ - "data": { - "post": { - "acfDocs": { - "user": [ - { - "id": "dXNlcjox", - "username": "jasonbahl", - "firstName": "Jason", - "lastName": "Bahl" - }, - { - "id": "dXNlcjoy", - "username": "WPGraphQL", - "firstName": "WP", - "lastName": "GraphQL" - } - ] - } - } - } -} -``` - -### Google Map Field - -Google Map fields are added to the WPGraphQL Schema as the `ACF_GoogleMap` Type. - -The `ACF_GoogleMap` Type has fields that expose location data. The available fields are: - -- **city** (String): The city associated with the location -- **country** (String): The country associated with the location -- **countryShort** (String): The country abbreviation associated with the location -- **latitude** (String): The latitude associated with the location -- **longitude** (String): The longitude associated with the location -- **placeId** (String): Place IDs uniquely identify a place in the Google Places database and on Google Maps. -- **postCode** (String): The post code associated with the location -- **state** (String): The state associated with the location -- **stateShort** (String): The state abbreviation associated with the location -- **streetAddress** (String): The street address associated with the location -- **streetName** (String): The street name associated with the location -- **streetNumber** (String): The street number associated with the location -- **zoom** (String): The zoom defined with the location - -Here, we have a Google Map field named `google_map` on the Post Edit screen within the "ACF Docs" Field Group, set with the Address "1 Infinite Loop, Cupertino, CA 95014, USA" as the value. - -![Google Map field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/map-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - googleMap { - streetAddress - streetNumber - streetName - city - state - postCode - countryShort - } - } - } -} -``` - -and the response would look like: - -```json -{ - "data": { - "post": { - "acfDocs": { - "googleMap": { - "streetAddress": "1 Infinite Loop, Cupertino, CA 95014, USA", - "streetNumber": "1", - "streetName": "Infinite Loop", - "city": "Cupertino", - "state": "California", - "postCode": "95014", - "placeId": "ChIJHTRqF7e1j4ARzZ_Fv8VA4Eo", - "countryShort": "US" - } - } - } - } -} -``` - -### Date Picker Field - -The Date Picker field is added to the WPGraphQL Schema as field with the Type `String`. - -Date Picker fields can be queried and a String will be returned. - -Here, we have a Date Picker field named `date_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "13/03/2020" is the date set. - -![Date Picker field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/date-picker-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - datePicker - } - } -} -``` - -and the result of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "datePicker": "13/03/2020" - } - } - } -} -``` - -### Date/Time Picker Field - -The Date/Time Picker field is added to the WPGraphQL Schema as field with the Type `String`. - -Date/Time Picker fields can be queried and a String will be returned. - -Here, we have a Date/Time Picker field named `date_time_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "20/03/2020 8:15 am" is the value. - -![Date Picker field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/date-time-picker-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - dateTimePicker - } - } -} -``` - -and the result of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "dateTimePicker": "20/03/2020 8:15 am" - } - } - } -} -``` - -### Time Picker Field - -The Time Picker field is added to the WPGraphQL Schema as field with the Type `String`. - -Time Picker fields can be queried and a String will be returned. - -Here, we have a Time Picker field named `time_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "12:30 am" is the value. - -![Time Picker field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/time-picker-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - timePicker - } - } -} -``` - -and the result of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "timePicker": "12:30 am" - } - } - } -} -``` - -### Color Picker Field - -The Color Picker field is added to the WPGraphQL Schema as field with the Type `String`. - -Color Picker fields can be queried and a String will be returned. - -Here, we have a Color Picker field named `color_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "#dd3333" is the value. - -![Color Picker field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/color-picker-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - colorPicker - } - } -} -``` - -and the result of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "colorPicker": "12:30 am" - } - } - } -} -``` - -### Message Field - -Message fields are not currently supported. - -### Accordion Field - -Accordion Fields are not currently supported. - -### Tab Field - -Tab fields are not currently supported. - -### Group Field - -Group Fields are added to the WPGraphQL Schema as fields resolving to an Object Type named after the Group. - -Here, we have a Group field named `group` on the Post Edit screen within the "ACF Docs" Field Group. Within the "group" field, we have a Text Field named `text_field_in_group` and a Text Area field named `text_area_field_in_group` - -![Group field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/group-field-input.png?raw=true) - -We can query the fields within the group like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - group { - textFieldInGroup - textAreaFieldInGroup - } - } - } -} -``` - -And the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "group": { - "textFieldInGroup": "Text value, in group", - "textAreaFieldInGroup": "Text are value, in group" - } - } - } - } -} -``` - -### Repeater Field - -Repeater Fields are added to the Schema as a List Of the Type of group that makes up the fields. - -For example, we've created a Repeater Field that has a Text Field named `text_field_in_repeater` and an Image Field named `image_field_in_repeater`. - -Here, the Repeater Field is populated with 2 rows: -- Row 1: - - Text Field: Text Value 1 - - Image: 256 -- Row 2: - - Text Field: Text Value 2 - - Image: 255 - -![Repeater field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/repeater-field-input.png?raw=true) - -This field can be queried in GraphQL like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - repeater { - textFieldInRepeater - imageFieldInRepeater { - databaseId - id - sourceUrl - } - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "repeater": [ - { - "textFieldInRepeater": "Text Value 1", - "imageFieldInRepeater": { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth.jpg" - } - }, - { - "textFieldInRepeater": "Text Value 2", - "imageFieldInRepeater": { - "id": "YXR0YWNobWVudDoyNTU=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-scaled.jpg" - } - } - ] - } - } - } -} -``` - -### Flexible Content Field - -The Flexible Content is a powerful ACF field that allows for groups of fields to be organized into "Layouts". - -These Layouts can be made up of other types of fields, and can be added and arranged in any order. - -Flexible Content Fields are added to the WPGraphQL Schema as a List Of [Unions](https://graphql.org/learn/schema/#union-types). - -The Union for a Flex Field is made up of each Layout in the Flex Field as the possible Types. - -In our example, we've created a Flex Field with 3 layouts named "Layout One", "Layout Two" and "Layout Three". In the Schema, we can see the Flex Field Union's Possible Types are these 3 layouts. - -![Flex Fields Schema Union Possible Types](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/flex-field-union-possible-types.png?raw=true) - -Each of these Layout types will contain the fields defined for the layout and can be queried like fields in any other Group. - -Here's an example of a Flex Field named `flexible_content`, with 3 layouts: - -- Layout One - - Text field named "text" - - Text field named "another_text_field" -- Layout Two - - Image field named "image" -- Layout Three - - Gallery field named "gallery" - -Above are the possible layouts and their fields. These layouts can be added and arranged in any order. While we, as a GraphQL consumer, don't know ahead of time what order they will be in, we _do_ know what the possibilities are. - -Here's an example of a Flex Field named `flexible_content` with the values saved as "Layout One", "Layout Two" and "Layout Three", in that order, all populated with their respective fields. - -![Flex field in the Edit Post screen](https://github.com/wp-graphql/wp-graphql-acf/blob/master/docs/img/flex-field-input.png?raw=true) - -We can query this field like so: - -```graphql -{ - post(id: "acf-example-test", idType: URI) { - acfDocs { - flexibleContent { - __typename - ... on Post_Acfdocs_FlexibleContent_LayoutOne { - text - anotherTextField - } - ... on Post_Acfdocs_FlexibleContent_LayoutTwo { - image { - id - sourceUrl(size: MEDIUM) - } - } - ... on Post_Acfdocs_FlexibleContent_LayoutThree { - gallery { - id - sourceUrl(size: MEDIUM) - } - } - } - } - } -} -``` - -and the results of the query would be: - -```json -{ - "data": { - "post": { - "acfDocs": { - "flexibleContent": [ - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne", - "text": "Text Value One", - "anotherTextField": "Another Text Value" - }, - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo", - "image": { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" - } - }, - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree", - "gallery": [ - { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" - }, - { - "id": "YXR0YWNobWVudDoyNTU=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg" - } - ] - } - ] - } - } - } -} -``` - -If we were to re-arrange the layouts, so that the order was "Layout Three", "Layout One", "Layout Two", the results of the query would be: - -```json -"data": { - "post": { - "acfDocs": { - "flexibleContent": [ - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree", - "gallery": [ - { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" - }, - { - "id": "YXR0YWNobWVudDoyNTU=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg" - } - ] - } - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne", - "text": "Text Value One", - "anotherTextField": "Another Text Value" - }, - { - "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo", - "image": { - "id": "YXR0YWNobWVudDoyNTY=", - "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" - } - }, - ] - } - } - } -``` - -### Clone Field - -The clone field is not fully supported (yet). We plan to support it in the future. - ## Options Pages **Reference**: https://www.advancedcustomfields.com/add-ons/options-page/ @@ -1738,11 +179,11 @@ Alternatively, it's you can check the Fields API Reference to learn about exposi ## Location Rules -Advanced Custom Fields field groups are added to the WordPress dashboard by being assigned "Location Rules". +Advanced Custom Fields field groups are added to the WordPress dashboard by being assigned "Location Rules". -WPGraphQL for Advanced Custom Fields uses the Location Rules to determine where in the GraphQL Schema the field groups/fields should be added to the Schema. +WPGraphQL for Advanced Custom Fields uses the Location Rules to determine where in the GraphQL Schema the field groups/fields should be added to the Schema. -For example, if a Field Group were assigned to "Post Type is equal to Post", then the field group would show in the WPGraphQL Schema on the `Post` type, allowing you to query for ACF fields of the Post, anywhere you can interact with the `Post` type in the Schema. +For example, if a Field Group were assigned to "Post Type is equal to Post", then the field group would show in the WPGraphQL Schema on the `Post` type, allowing you to query for ACF fields of the Post, anywhere you can interact with the `Post` type in the Schema. ### Supported Locations @@ -1750,10 +191,10 @@ For example, if a Field Group were assigned to "Post Type is equal to Post", the ### Why aren't all location rules supported? -You might notice that some location rules don't add fields to the Schema. This is because some location rules are based on context that doesn't exist when the GraphQL Schema is generated. +You might notice that some location rules don't add fields to the Schema. This is because some location rules are based on context that doesn't exist when the GraphQL Schema is generated. -For example, if you have a location rule to show a field group only on a specific page, how would that be exposed the the Schema? There's no Type in the Schema for just one specific page. +For example, if you have a location rule to show a field group only on a specific page, how would that be exposed the the Schema? There's no Type in the Schema for just one specific page. -If you're not seeing a field group in the Schema, look at the location rules, and think about _how_ the field group would be added to a Schema that isn't aware of context like which admin page you're on, what category a Post is assigned to, etc. +If you're not seeing a field group in the Schema, look at the location rules, and think about _how_ the field group would be added to a Schema that isn't aware of context like which admin page you're on, what category a Post is assigned to, etc. If you have ideas on how these specific contextual rules should be handled in WPGraphQL, submit an issue so we can consider how to best support it! diff --git a/docs/fields/accordion.md b/docs/fields/accordion.md new file mode 100644 index 0000000..d5aa667 --- /dev/null +++ b/docs/fields/accordion.md @@ -0,0 +1,10 @@ +# Accordion + +The Accordion Field in Advanced Custom Fields that lets users separate other fields in collapsible +sections. + +This field is for administrative display purposes and is not exposed in WPGraphQL. + +---- + +- **Next Field:** [Button Group](./button-group.md) diff --git a/docs/fields/button-group.md b/docs/fields/button-group.md new file mode 100644 index 0000000..142b774 --- /dev/null +++ b/docs/fields/button-group.md @@ -0,0 +1,41 @@ +# Button Group Field + +Button Group fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Button Group fields can be queried and a String will be returned. + +Here, we have a Button Group field named `button_group` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected. + +![Button Group field in the Edit Post screen](../img/button-group-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + buttonGroup + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "buttonGroup": "choice_2" + } + } + } +} +``` + +---- + +- **Previous Field:** [Accordion](./accordion.md) +- **Next Field:** [Checkbox](./checkbox.md) + diff --git a/docs/fields/checkbox.md b/docs/fields/checkbox.md new file mode 100644 index 0000000..c95c0c9 --- /dev/null +++ b/docs/fields/checkbox.md @@ -0,0 +1,43 @@ +# Checkbox Field + +Checkbox fields are added to the WPGraphQL Schema as a field with the Type `[ 'list_of' => 'String' ]`. + +Checkbox fields can be queried and a list (array) of Strings (the selected values) will be returned. + +Here, we have a Checkbox field named `checkbox` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected. + +![Checkbox field in the Edit Post screen](../img/checkbox-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + checkbox + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "checkbox": [ + "choice_1" + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Button Group](./button-group.md) +- **Next Field:** [Clone](./clone.md) + diff --git a/docs/fields/clone.md b/docs/fields/clone.md new file mode 100644 index 0000000..93ff021 --- /dev/null +++ b/docs/fields/clone.md @@ -0,0 +1,9 @@ +# Clone Field + +The clone field is not fully supported (yet). We plan to support it in the future. + +---- + +- **Previous Field:** [Checkbox](./checkbox.md) +- **Next Field:** [Color Picker](./color-picker.md) + diff --git a/docs/fields/color-picker.md b/docs/fields/color-picker.md new file mode 100644 index 0000000..73fee41 --- /dev/null +++ b/docs/fields/color-picker.md @@ -0,0 +1,40 @@ +# Color Picker Field + +The Color Picker field is added to the WPGraphQL Schema as field with the Type `String`. + +Color Picker fields can be queried and a String will be returned. + +Here, we have a Color Picker field named `color_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "#dd3333" is the value. + +![Color Picker field in the Edit Post screen](../img/color-picker-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + colorPicker + } + } +} +``` + +and the result of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "colorPicker": "12:30 am" + } + } + } +} +``` + +---- + +- **Previous Field:** [Clone](./clone.md) +- **Next Field:** [Date Picker](./date-picker.md) diff --git a/docs/fields/date-picker.md b/docs/fields/date-picker.md new file mode 100644 index 0000000..4ac098c --- /dev/null +++ b/docs/fields/date-picker.md @@ -0,0 +1,40 @@ +# Date Picker Field + +The Date Picker field is added to the WPGraphQL Schema as field with the Type `String`. + +Date Picker fields can be queried and a String will be returned. + +Here, we have a Date Picker field named `date_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "13/03/2020" is the date set. + +![Date Picker field in the Edit Post screen](../img/date-picker-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + datePicker + } + } +} +``` + +and the result of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "datePicker": "13/03/2020" + } + } + } +} +``` + +---- + +- **Previous Field:** [Color Picker](./color-picker.md) +- **Next Field:** [Date/Time Picker](./date-time-picker.md) diff --git a/docs/fields/date-time-picker.md b/docs/fields/date-time-picker.md new file mode 100644 index 0000000..5188ff4 --- /dev/null +++ b/docs/fields/date-time-picker.md @@ -0,0 +1,40 @@ +# Date/Time Picker Field + +The Date/Time Picker field is added to the WPGraphQL Schema as field with the Type `String`. + +Date/Time Picker fields can be queried, and a String will be returned. + +Here, we have a Date/Time Picker field named `date_time_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "20/03/2020 8:15 am" is the value. + +![Date Picker field in the Edit Post screen](../img/date-time-picker-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + dateTimePicker + } + } +} +``` + +and the result of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "dateTimePicker": "20/03/2020 8:15 am" + } + } + } +} +``` + +---- + +- **Previous Field:** [Date Picker](./date-picker.md) +- **Next Field:** [Email](./email.md) diff --git a/docs/fields/email.md b/docs/fields/email.md new file mode 100644 index 0000000..112b167 --- /dev/null +++ b/docs/fields/email.md @@ -0,0 +1,40 @@ +# Email Field + +Email fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Email fields can be queried and a String will be returned. + +Here, we have an Email field named `email` on the Post Edit screen within the "ACF Docs" Field Group. + +![Email field in the Edit Post screen](../img/email-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + email + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "email": "test@example.com" + } + } + } +} +``` + +---- + +- **Previous Field:** [Date/Time Picker](./date-time-picker.md) +- **Next Field:** [File](./file.md) diff --git a/docs/fields/file.md b/docs/fields/file.md new file mode 100644 index 0000000..4010a14 --- /dev/null +++ b/docs/fields/file.md @@ -0,0 +1,48 @@ +# File Field + +File fields are added to the WPGraphQL Schema as a field with the Type `MediaItem`. + +File fields can be queried and a MediaItem will be returned. + +The `MediaItem` type is an Object type that has it's own fields that can be selected. So, instead of _just_ getting the File ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the `id` and `mediaItemUrl`. + +Here, we have a File field named `file` on the Post Edit screen within the "ACF Docs" Field Group. + +![File field in the Edit Post screen](../img/file-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + file { + id + mediaItemUrl + } + } + } +} +``` + +And the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "file": { + "id": "YXR0YWNobWVudDozMjQ=", + "mediaItemUrl": "http://acf2.local/wp-content/uploads/2020/03/little-ceasars-receipt-01282020.pdf" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Email](./email.md) +- **Next Field:** [Flexible Content](./flexible-content.md) diff --git a/docs/fields/flexible-content.md b/docs/fields/flexible-content.md new file mode 100644 index 0000000..8c90d07 --- /dev/null +++ b/docs/fields/flexible-content.md @@ -0,0 +1,144 @@ +# Flexible Content Field + +The Flexible Content is a powerful ACF field that allows for groups of fields to be organized into "Layouts". + +These Layouts can be made up of other types of fields, and can be added and arranged in any order. + +Flexible Content Fields are added to the WPGraphQL Schema as a List Of [Unions](https://graphql.org/learn/schema/#union-types). + +The Union for a Flex Field is made up of each Layout in the Flex Field as the possible Types. + +In our example, we've created a Flex Field with 3 layouts named "Layout One", "Layout Two" and "Layout Three". In the Schema, we can see the Flex Field Union's Possible Types are these 3 layouts. + +![Flex Fields Schema Union Possible Types](../img/flex-field-union-possible-types.png?raw=true) + +Each of these Layout types will contain the fields defined for the layout and can be queried like fields in any other Group. + +Here's an example of a Flex Field named `flexible_content`, with 3 layouts: + +- Layout One + - Text field named "text" + - Text field named "another_text_field" +- Layout Two + - Image field named "image" +- Layout Three + - Gallery field named "gallery" + +Above are the possible layouts and their fields. These layouts can be added and arranged in any order. While we, as a GraphQL consumer, don't know ahead of time what order they will be in, we _do_ know what the possibilities are. + +Here's an example of a Flex Field named `flexible_content` with the values saved as "Layout One", "Layout Two" and "Layout Three", in that order, all populated with their respective fields. + +![Flex field in the Edit Post screen](../img/flex-field-input.png?raw=true) + +We can query this field like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + flexibleContent { + __typename + ... on Post_Acfdocs_FlexibleContent_LayoutOne { + text + anotherTextField + } + ... on Post_Acfdocs_FlexibleContent_LayoutTwo { + image { + id + sourceUrl(size: MEDIUM) + } + } + ... on Post_Acfdocs_FlexibleContent_LayoutThree { + gallery { + id + sourceUrl(size: MEDIUM) + } + } + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "flexibleContent": [ + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne", + "text": "Text Value One", + "anotherTextField": "Another Text Value" + }, + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo", + "image": { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" + } + }, + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree", + "gallery": [ + { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" + }, + { + "id": "YXR0YWNobWVudDoyNTU=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg" + } + ] + } + ] + } + } + } +} +``` + +If we were to re-arrange the layouts, so that the order was "Layout Three", "Layout One", "Layout Two", the results of the query would be: + +```json +"data": { + "post": { + "acfDocs": { + "flexibleContent": [ + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutThree", + "gallery": [ + { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" + }, + { + "id": "YXR0YWNobWVudDoyNTU=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-289x300.jpg" + } + ] + } + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutOne", + "text": "Text Value One", + "anotherTextField": "Another Text Value" + }, + { + "__typename": "Post_Acfdocs_FlexibleContent_LayoutTwo", + "image": { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-300x169.jpg" + } + }, + ] + } + } + } +``` + +---- + +- **Previous Field:** [File](./file.md) +- **Next Field:** [Gallery](./gallery.md) diff --git a/docs/fields/gallery.md b/docs/fields/gallery.md new file mode 100644 index 0000000..2eb3cd7 --- /dev/null +++ b/docs/fields/gallery.md @@ -0,0 +1,55 @@ +# Gallery Field + +Gallery fields are added to the WPGraphQL Schema as a field with the Type of `['list_of' => 'MediaItem']`. + +Gallery fields can be queried and a list of MediaItem types will be returned. + +Since the type is a list, we can expect an array to be returned. And since the Type within the list is `MediaItem`, we can ask for fields we want returned for each `MediaItem` in the list. In this case, let's say we want to ask for the `id` of each image and the `sourceUrl`, (size large). + +Here, we have a Gallery field named `gallery` on the Post Edit screen within the "ACF Docs" Field Group. + +![Gallery field in the Edit Post screen](../img/gallery-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + gallery { + id + sourceUrl(size: LARGE) + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "gallery": [ + { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth.jpg" + }, + { + "id": "YXR0YWNobWVudDoyNTU=", + "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/02/babe-ruth-baseball-986x1024.jpg" + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Flexible Content](./flexible-content.md) +- **Next Field:** [Google Map](./google-map.md) + diff --git a/docs/fields/google-map.md b/docs/fields/google-map.md new file mode 100644 index 0000000..f99b8fc --- /dev/null +++ b/docs/fields/google-map.md @@ -0,0 +1,71 @@ +# Google Map Field + +Google Map fields are added to the WPGraphQL Schema as the `ACF_GoogleMap` Type. + +The `ACF_GoogleMap` Type has fields that expose location data. The available fields are: + +- **city** (String): The city associated with the location +- **country** (String): The country associated with the location +- **countryShort** (String): The country abbreviation associated with the location +- **latitude** (String): The latitude associated with the location +- **longitude** (String): The longitude associated with the location +- **placeId** (String): Place IDs uniquely identify a place in the Google Places database and on Google Maps. +- **postCode** (String): The post code associated with the location +- **state** (String): The state associated with the location +- **stateShort** (String): The state abbreviation associated with the location +- **streetAddress** (String): The street address associated with the location +- **streetName** (String): The street name associated with the location +- **streetNumber** (String): The street number associated with the location +- **zoom** (String): The zoom defined with the location + +Here, we have a Google Map field named `google_map` on the Post Edit screen within the "ACF Docs" Field Group, set with the Address "1 Infinite Loop, Cupertino, CA 95014, USA" as the value. + +![Google Map field in the Edit Post screen](../img/map-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + googleMap { + streetAddress + streetNumber + streetName + city + state + postCode + countryShort + } + } + } +} +``` + +and the response would look like: + +```json +{ + "data": { + "post": { + "acfDocs": { + "googleMap": { + "streetAddress": "1 Infinite Loop, Cupertino, CA 95014, USA", + "streetNumber": "1", + "streetName": "Infinite Loop", + "city": "Cupertino", + "state": "California", + "postCode": "95014", + "placeId": "ChIJHTRqF7e1j4ARzZ_Fv8VA4Eo", + "countryShort": "US" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Gallery](./gallery.md) +- **Next Field:** [Group](./group.md) diff --git a/docs/fields/group.md b/docs/fields/group.md new file mode 100644 index 0000000..8e38227 --- /dev/null +++ b/docs/fields/group.md @@ -0,0 +1,44 @@ +# Group Field + +Group Fields are added to the WPGraphQL Schema as fields resolving to an Object Type named after the Group. + +Here, we have a Group field named `group` on the Post Edit screen within the "ACF Docs" Field Group. Within the "group" field, we have a Text Field named `text_field_in_group` and a Text Area field named `text_area_field_in_group` + +![Group field in the Edit Post screen](../img/group-field-input.png?raw=true) + +We can query the fields within the group like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + group { + textFieldInGroup + textAreaFieldInGroup + } + } + } +} +``` + +And the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "group": { + "textFieldInGroup": "Text value, in group", + "textAreaFieldInGroup": "Text are value, in group" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Google Map](./google-map.md) +- **Next Field:** [image](./image.md) diff --git a/docs/fields/image.md b/docs/fields/image.md new file mode 100644 index 0000000..4f34999 --- /dev/null +++ b/docs/fields/image.md @@ -0,0 +1,48 @@ +# Image Field + +Image fields are added to the WPGraphQL Schema as a field with the Type `MediaItem`. + +Image fields can be queried and a MediaItem will be returned. + +The `MediaItem` type is an Object type that has it's own fields that can be selected. So, instead of _just_ getting the Image ID returned and having to ask for the MediaItem object in a follow-up request, we can ask for fields available on the MediaItem Type. For this example, we ask for the `id` and `sourceUrl`. + +Here, we have an Image field named `image` on the Post Edit screen within the "ACF Docs" Field Group. + +![Image field in the Edit Post screen](../img/image-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + image { + id + sourceUrl(size: MEDIUM) + } + } + } +} +``` + +And the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "image": { + "id": "YXR0YWNobWVudDozMjM=", + "sourceUrl": "http://wpgraphql.local/wp-content/uploads/2020/03/babe-ruth-300x169.jpg" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Group](./group.md) +- **Next Field:** [Link](./link.md) diff --git a/docs/fields/link.md b/docs/fields/link.md new file mode 100644 index 0000000..fa6ab5e --- /dev/null +++ b/docs/fields/link.md @@ -0,0 +1,55 @@ +# Link Field + +Link fields are added to the WPGraphQL Schema as a field with the Type `ACF_Link`. + +Link fields can be queried and a `ACF_Link` will be returned. The ACF Link is an object with fields that can be selected. + +The available fields on the `ACF_Link` Type are: + +- **target** (String): The target of the link +- **title** (String): The target of the link +- **url** (String): The url of the link + +Here, we have a Link field named `link` on the Post Edit screen within the "ACF Docs" Field Group. + +![Link field in the Edit Post screen](../img/link-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + link { + target + title + url + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "link": { + "target": "", + "title": "Hello world!", + "url": "http://acf2.local/hello-world/" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Image](./image.md) +- **Next Field:** [Message](./message.md) + diff --git a/docs/fields/message.md b/docs/fields/message.md new file mode 100644 index 0000000..bbefeab --- /dev/null +++ b/docs/fields/message.md @@ -0,0 +1,8 @@ +# Message Field + +Message fields are not currently supported. + +---- + +- **Previous Field:** [Link](./link.md) +- **Next Field:** [Number](./number.md) diff --git a/docs/fields/number.md b/docs/fields/number.md new file mode 100644 index 0000000..71e4d99 --- /dev/null +++ b/docs/fields/number.md @@ -0,0 +1,40 @@ +# Number Field + +Number fields are added to the WPGraphQL Schema as a field with the Type `Float`. + +Number fields can be queried, and a Float will be returned. + +Here, we have a Number field named `number` on the Post Edit screen within the "ACF Docs" Field Group. + +![Number field in the Edit Post screen](../img/number-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + number + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "number": 5 + } + } + } +} +``` + +---- + +- **Previous Field:** [Message](./message.md) +- **Next Field:** [Oembed](./oembed.md) diff --git a/docs/fields/oembed.md b/docs/fields/oembed.md new file mode 100644 index 0000000..07604c2 --- /dev/null +++ b/docs/fields/oembed.md @@ -0,0 +1,41 @@ +# oEmbed Field + +oEmbed fields are added to the WPGraphQL Schema as a field with the Type `String`. + +oEmbed fields can be queried, and a String will be returned. + +Here, we have a oEmbed field named `oembed` on the Post Edit screen within the "ACF Docs" Field Group. + +![oEmbed field in the Edit Post screen](../img/oEmbed-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + oembed + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "oembed": "https://www.youtube.com/watch?v=ZEytXfaWwcc" + } + } + } +} +``` + +---- + +- **Previous Field:** [Number](./number.md) +- **Next Field:** [Page Link](./page-link.md) + diff --git a/docs/fields/page-link.md b/docs/fields/page-link.md new file mode 100644 index 0000000..49a3747 --- /dev/null +++ b/docs/fields/page-link.md @@ -0,0 +1,87 @@ +# Page Link Field + +Page Link fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. + +Since Page Link fields can be configured to be limited to certain Post Types, the Union will represent those Types. + +For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: + +![Page Link field Post Type Config](../img/page-link-field-post-type-config.png?raw=true) + +Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: + +![Page Link field Union Possible Types](../img/page-link-field-possible-types.png?raw=true) + +Here, we have a Page Link field named `page_link` on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to the "Sample Page" page. + +![Page Link field in the Edit Post screen](../img/page-link-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + pageLink { + __typename + ... on Post { + id + title + date + } + ... on Page { + id + title + } + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "pageLink": { + "__typename": "Page", + "id": "cGFnZToy", + "title": "Sample Page" + } + } + } + } +} +``` + +Here, we set the value to the "Hello World" Post: + +![Page Link field in the Edit Post screen](../img/page-link-field-input-2.png?raw=true) + +And the results of the same query are now: + +```json +{ + "data": { + "post": { + "acfDocs": { + "pageLink": { + "__typename": "Post", + "id": "cG9zdDox", + "title": "Hello world!", + "date": "2020-02-20T23:12:21" + } + } + } + } +} +``` + +---- + +- **Previous Field:** [Oembed](./oembed.md) +- **Next Field:** [Checkbox](./password.md) + diff --git a/docs/fields/password.md b/docs/fields/password.md new file mode 100644 index 0000000..8b89f7b --- /dev/null +++ b/docs/fields/password.md @@ -0,0 +1,40 @@ +# Password Field + +Password fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Password fields can be queried, and a String will be returned. + +Here, we have a Password field named `password` on the Post Edit screen within the "ACF Docs" Field Group. + +![Password field in the Edit Post screen](../img/password-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + password + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "password": "123456" + } + } + } +} +``` + +---- + +- **Previous Field:** [Page Link](./page-link.md) +- **Next Field:** [Post Object](./post-object.md) diff --git a/docs/fields/post-object.md b/docs/fields/post-object.md new file mode 100644 index 0000000..deed218 --- /dev/null +++ b/docs/fields/post-object.md @@ -0,0 +1,125 @@ +# Post Object Field + +Post Object fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. + +If the field is configured to allow multiple selections, it will be added to the Schema as a List Of the Union Type. + +Since Post Object fields can be configured to be limited to certain Post Types, the Union will represent those Types. + +For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: + +![Post Object field Post Type Config](../img/post-object-field-post-type-config.png?raw=true) + +Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: + +![Post Object field Union Possible Types](../img/post-object-field-possible-types.png?raw=true) + +Here, we have a Post Object field named `post_object` on the Post Edit screen within the "ACF Docs" Field Group, configured with the Post "Hello World!". + +![Post Object field in the Edit Post screen](../img/post-object-field-input-post.png?raw=true) + +As a GraphQL consumer, we don't know in advance if the value is going to be a Page or a Post. + +So we can specify, via GraphQL fragment, what fields we want if the object is a Post, or if it is a Page. + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + postObject { + __typename + ... on Post { + id + title + date + } + ... on Page { + id + title + } + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "postObject": { + "__typename": "Post", + "id": "cG9zdDox", + "title": "Hello world!", + "date": "2020-02-20T23:12:21" + } + } + } + } +} +``` + +If the input of the field was saved as a Page, instead of a Post, like so: + +![Post Object field in the Edit Post screen](../img/post-object-field-input-page.png?raw=true) + +Then the same query above, would return the following results: + +```json +{ + "data": { + "post": { + "acfDocs": { + "postObject": { + "__typename": "Page", + "id": "cGFnZToy", + "title": "Sample Page" + } + } + } + } +} +``` + +Now, if the field were configured to allow multiple values, the field would be added to the Schema as a `listOf`, returning an Array of the Union. + +If the field were set with a value of one Page, and one Post, like so: + +![Post Object field in the Edit Post screen](../img/post-object-field-input-multi.png?raw=true) + +Then the results of the same query as above would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "postObject": [ + { + "__typename": "Page", + "id": "cGFnZToy", + "title": "Sample Page" + }, + { + "__typename": "Post", + "id": "cG9zdDox", + "title": "Hello world!", + "date": "2020-02-20T23:12:21" + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Password](./password.md) +- **Next Field:** [Radio](./radio.md) + diff --git a/docs/fields/radio.md b/docs/fields/radio.md new file mode 100644 index 0000000..a11d9b5 --- /dev/null +++ b/docs/fields/radio.md @@ -0,0 +1,40 @@ +# Radio Button Field + +Radio Button fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Radio Button fields can be queried and a String will be returned. + +Here, we have a Radio Button field named `radio_button` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 2" is selected. + +![Radio Button field in the Edit Post screen](../img/radio-button-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + radioButton + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "radioButton": "choice_2" + } + } + } +} +``` + +---- + +- **Previous Field:** [Post Object](./post-object.md) +- **Next Field:** [Range](./range.md) diff --git a/docs/fields/range.md b/docs/fields/range.md new file mode 100644 index 0000000..2768acd --- /dev/null +++ b/docs/fields/range.md @@ -0,0 +1,40 @@ +# Range Field + +Range fields are added to the WPGraphQL Schema as a field with the Type `Float`. + +Range fields can be queried, and a Float will be returned. + +Here, we have a Range field named `range` on the Post Edit screen within the "ACF Docs" Field Group. + +![Range field in the Edit Post screen](../img/range-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + range + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "range": 5 + } + } + } +} +``` + +---- + +- **Previous Field:** [Radio](./radio.md) +- **Next Field:** [Relationship](./relationship.md) diff --git a/docs/fields/relationship.md b/docs/fields/relationship.md new file mode 100644 index 0000000..5c0fb30 --- /dev/null +++ b/docs/fields/relationship.md @@ -0,0 +1,72 @@ +# Relationship Field + +Relationship fields are added to the WPGraphQL Schema as a field with a [Union](https://graphql.org/learn/schema/#union-types) of Possible Types the field is configured to allow. + +Since Relationship fields can be configured to be limited to certain Post Types, the Union will represent those Types. + +For example, if the Post Object field is configured to allow Posts of the `post` and `page` types to be selected: + +![Relationship field Post Type Config](../img/relationship-field-post-type-config.png?raw=true) + +Then the Union type for the field will allow `Post` and `Page` types to be returned, as seen in the Schema via GraphiQL: + +![Relationship field Union Possible Types](../img/relationship-field-possible-types.png?raw=true) + +Here, we have a Relationship field named `relationship` on the Post Edit screen within the "ACF Docs" Field Group, and the value is set to "Hello World!" post, and the "Sample Page" page. + +![Relationship field in the Edit Post screen](../img/relationship-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + relationship { + __typename + ... on Post { + id + title + date + } + ... on Page { + id + title + } + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "relationship": [ + { + "__typename": "Post", + "id": "cG9zdDox", + "title": "Hello world!", + "date": "2020-02-20T23:12:21" + }, + { + "__typename": "Page", + "id": "cGFnZToy", + "title": "Sample Page" + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Range](./range.md) +- **Next Field:** [Repeater](./repeater.md) + diff --git a/docs/fields/repeater.md b/docs/fields/repeater.md new file mode 100644 index 0000000..f57d5bb --- /dev/null +++ b/docs/fields/repeater.md @@ -0,0 +1,68 @@ +# Repeater Field + +Repeater Fields are added to the Schema as a List Of the Type of group that makes up the fields. + +For example, we've created a Repeater Field that has a Text Field named `text_field_in_repeater` and an Image Field named `image_field_in_repeater`. + +Here, the Repeater Field is populated with 2 rows: +- Row 1: + - Text Field: Text Value 1 + - Image: 256 +- Row 2: + - Text Field: Text Value 2 + - Image: 255 + +![Repeater field in the Edit Post screen](../img/repeater-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + repeater { + textFieldInRepeater + imageFieldInRepeater { + databaseId + id + sourceUrl + } + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "repeater": [ + { + "textFieldInRepeater": "Text Value 1", + "imageFieldInRepeater": { + "id": "YXR0YWNobWVudDoyNTY=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth.jpg" + } + }, + { + "textFieldInRepeater": "Text Value 2", + "imageFieldInRepeater": { + "id": "YXR0YWNobWVudDoyNTU=", + "sourceUrl": "http://acf2.local/wp-content/uploads/2020/02/babe-ruth-baseball-scaled.jpg" + } + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Relationship](./relationship.md) +- **Next Field:** [Select](./select.md) diff --git a/docs/fields/select.md b/docs/fields/select.md new file mode 100644 index 0000000..cf3b566 --- /dev/null +++ b/docs/fields/select.md @@ -0,0 +1,40 @@ +# Select Field + +Select fields (when configured to _not_ allow mutliple selections) are added to the WPGraphQL Schema as a field with the Type `String`. + +Select fields, without multiple selections allowed, can be queried and a String will be returned. + +Here, we have a Select field named `select` on the Post Edit screen within the "ACF Docs" Field Group, and "Choice 1" is selected. + +![Select field in the Edit Post screen](../img/select-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + select + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "select": "choice_1" + } + } + } +} +``` + +---- + +- **Previous Field:** [Repeater](./repeater.md) +- **Next Field:** [Tab](./tab.md) diff --git a/docs/fields/tab.md b/docs/fields/tab.md new file mode 100644 index 0000000..481486b --- /dev/null +++ b/docs/fields/tab.md @@ -0,0 +1,8 @@ +# Tab Field + +Tab fields are not currently supported. + +---- + +- **Previous Field:** [Select](./select.md) +- **Next Field:** [Taxonomy](./taxonomy.md) diff --git a/docs/fields/taxonomy.md b/docs/fields/taxonomy.md new file mode 100644 index 0000000..69593c1 --- /dev/null +++ b/docs/fields/taxonomy.md @@ -0,0 +1,53 @@ +# Taxonomy Field + +The Taxonomy field is added to the GraphQL Schema as a List Of the Taxonomy Type. + +For example, if the field is configured to the "Category" taxonomy, then the field in the Schema will be a List of the Category type. + +![Taxonomy field Taxonomy Config](../img/taxonomy-field-taxonomy-config.png?raw=true) + +Here, we have a Taxonomy field named `taxonomy` on the Post Edit screen within the "ACF Docs" Field Group, configured with the Category "Test Category". + +![Taxonomy field in the Edit Post screen](../img/taxonomy-field-input.png?raw=true) + +This field can be queried like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + taxonomy { + __typename + id + name + } + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "taxonomy": [ + { + "__typename": "Category", + "id": "Y2F0ZWdvcnk6Mg==", + "name": "Test Category" + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Tab](./tab.md) +- **Next Field:** [Text](./text.md) + diff --git a/docs/fields/text-area.md b/docs/fields/text-area.md new file mode 100644 index 0000000..c3b20a5 --- /dev/null +++ b/docs/fields/text-area.md @@ -0,0 +1,41 @@ +# Text Area Field + +Text Area fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Text Area fields can be queried and a String will be returned. + +Here, we have a Text Area field named `text_area` on the Post Edit screen within the "ACF Docs" Field Group. + +![Text Area field in the Edit Post screen](../img/text-area-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + textArea + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "textArea": "Text value" + } + } + } +} +``` + +---- + +- **Previous Field:** [Text](./text.md) +- **Next Field:** [Time Picker](./time-picker.md) + diff --git a/docs/fields/text.md b/docs/fields/text.md new file mode 100644 index 0000000..5c437ec --- /dev/null +++ b/docs/fields/text.md @@ -0,0 +1,41 @@ +# Text Field + +Text fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Text fields can be queried and a String will be returned. + +Here, we have a Text field named `text` on the Post Edit screen within the "ACF Docs" Field Group. + +![Text field in the Edit Post screen](../img/text-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + text + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "text": "Text Value" + } + } + } +} +``` + +---- + +- **Previous Field:** [Taxonomy](./taxonomy.md) +- **Next Field:** [Text Area](./text-area.md) + diff --git a/docs/fields/time-picker.md b/docs/fields/time-picker.md new file mode 100644 index 0000000..4f9ada3 --- /dev/null +++ b/docs/fields/time-picker.md @@ -0,0 +1,41 @@ +# Time Picker Field + +The Time Picker field is added to the WPGraphQL Schema as field with the Type `String`. + +Time Picker fields can be queried and a String will be returned. + +Here, we have a Time Picker field named `time_picker` on the Post Edit screen within the "ACF Docs" Field Group, and "12:30 am" is the value. + +![Time Picker field in the Edit Post screen](../img/time-picker-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + timePicker + } + } +} +``` + +and the result of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "timePicker": "12:30 am" + } + } + } +} +``` + +---- + +- **Previous Field:** [Text Area](text-area.md) +- **Next Field:** [True/False](true-false.md) + diff --git a/docs/fields/true-false.md b/docs/fields/true-false.md new file mode 100644 index 0000000..887f556 --- /dev/null +++ b/docs/fields/true-false.md @@ -0,0 +1,41 @@ +# True/False Field + +True/False fields are added to the WPGraphQL Schema as a field with the Type `Boolean`. + +True/False fields can be queried and a Boolean will be returned. + +Here, we have a True/False field named `true_false` on the Post Edit screen within the "ACF Docs" Field Group, and "true" is selected. + +![True/False field in the Edit Post screen](../img/true-false-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + trueFalse + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "trueFalse": true + } + } + } +} +``` + +---- + +- **Previous Field:** [Time Picker](./time-picker.md) +- **Next Field:** [url](./url.md) + diff --git a/docs/fields/url.md b/docs/fields/url.md new file mode 100644 index 0000000..1290924 --- /dev/null +++ b/docs/fields/url.md @@ -0,0 +1,41 @@ +# URL Field + +Url fields are added to the WPGraphQL Schema as a field with the Type `String`. + +Url fields can be queried and a String will be returned. + +Here, we have a URL field named `url` on the Post Edit screen within the "ACF Docs" Field Group. + +![Url field in the Edit Post screen](../img/url-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + url + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "url": "https://wpgraphql.com" + } + } + } +} +``` + +---- + +- **Previous Field:** [True/False](./true-false.md) +- **Next Field:** [User](./user.md) + diff --git a/docs/fields/user.md b/docs/fields/user.md new file mode 100644 index 0000000..3fa00fe --- /dev/null +++ b/docs/fields/user.md @@ -0,0 +1,81 @@ +# User Field + +User fields are added to the WPGraphQL Schema as a field with a User type. + +Here, we have a User field named `user` on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" as the value. + +![User field in the Edit Post screen](../img/user-field-input.png?raw=true) + +This field can be queried in GraphQL like so: + +```graphql +{ + post(id: "acf-example-test", idType: URI) { + acfDocs { + user { + id + username + firstName + lastName + } + } + } +} +``` + +and the response would look like: + +```json +{ + "data": { + "post": { + "acfDocs": { + "user": { + "id": "dXNlcjox", + "username": "jasonbahl", + "firstName": "Jason", + "lastName": "Bahl" + } + } + } + } +} +``` + +If the field is configured to allow multiple selections, it's added to the Schema as a List Of the User type. + +Here, we have a User field named `user` on the Post Edit screen within the "ACF Docs" Field Group, set with the User "jasonbahl" and "WPGraphQL" as the value. + +![User field in the Edit Post screen](../img/user-field-input-multiple.png?raw=true) + +and the response to the same query would look like: + +```json +{ + "data": { + "post": { + "acfDocs": { + "user": [ + { + "id": "dXNlcjox", + "username": "jasonbahl", + "firstName": "Jason", + "lastName": "Bahl" + }, + { + "id": "dXNlcjoy", + "username": "WPGraphQL", + "firstName": "WP", + "lastName": "GraphQL" + } + ] + } + } + } +} +``` + +---- + +- **Previous Field:** [Url](./url.md) +- **Next Field:** [WYSIWYG](./wysiwyg.md) diff --git a/docs/fields/wysiwyg.md b/docs/fields/wysiwyg.md new file mode 100644 index 0000000..d9742fb --- /dev/null +++ b/docs/fields/wysiwyg.md @@ -0,0 +1,39 @@ +# WYSIWYG Editor Field + +WYSIWYG fields are added to the WPGraphQL Schema as a field with the Type `String`. + +WYSIWYG fields can be queried and a String will be returned. + +Here, we have a WYSIWYG field named `wysiwyg` on the Post Edit screen within the "ACF Docs" Field Group. + +![WYSIWYG field in the Edit Post screen](../img/wysiwyg-field-input.png?raw=true) + +This field can be Queried in GraphQL like so: + +```graphql +{ + post( id: "acf-example-test" idType: URI ) { + acfDocs { + wysiwyg + } + } +} +``` + +and the results of the query would be: + +```json +{ + "data": { + "post": { + "acfDocs": { + "wysiwyg": "

Some content in a WYSIWYG field

\n" + } + } + } +} +``` + +---- + +- **Previous Field:** [User](./user.md)