Advanced Custom Fields (ACF)

메타 필드를 사용하고, PRO 확장 기능이 제공하는 기능과 결합하면 Advanced Custom Fields (ACF) 플러그인의 커스텀 필드를 조회하고 변경할 수 있습니다.

ACF가 지원하는 모든 필드 타입에 대해 커스텀 필드를 가져오고 변경하는 방법을 보여주는 쿼리를 소개합니다:

기본 필드 타입 쿼리

ACF의 기본 필드 타입은 metaValue 필드를 사용하여 직접 쿼리할 수 있습니다:

query GetPost {
  post(by: { id: 1 }) {
    text: metaValue(key: "text_field")
    textarea: metaValue(key: "textarea_field")
    number: metaValue(key: "number_field")
    range: metaValue(key: "range_field")
    email: metaValue(key: "email_field")
    url: metaValue(key: "url_field")
    password: metaValue(key: "password_field")
  }
}

콘텐츠 필드 타입 쿼리

커스텀 필드가 관계형(예: 이미지 또는 파일)인 경우, 메타 필드에서 ID를 내보내고 이후 쿼리에서 해당 엔티티(Media 타입)를 즉시 쿼리할 수 있습니다.

그 외에는 단순한 필드 타입이므로 metaValue를 사용하여 직접 쿼리할 수 있습니다:

query GetPostDataAndExportRelationships {
  post(by: { id: 1 }) {
    # Image field type
    imageId: metaValue(key: "image_field")
      @export(as: "imageId")
 
    # File field type
    fileId: metaValue(key: "file_field")
      @export(as: "fileId")
 
    # WYSIWYG editor field type
    wysiwyg_editor: metaValue(key: "wysiwyg_editor_field")
 
    # Oembed field type
    oembed: metaValue(key: "oembed_field")    
  }
}
 
query QueryPostRelationships
  @depends(on: "GetPostDataAndExportRelationships")
{  
  # Query the image
  relationshipImage: mediaItem(by: { id: $imageId }) {
    id
    src
  }
 
  # Query the file
  relationshipFile: mediaItem(by: { id: $fileId }) {
    id
    src
  }
}

선택 필드 타입 쿼리

선택 필드 타입은 metaValue를 사용하여 단순한 필드 타입으로 쿼리할 수 있습니다.

ACF는 값의 배열을 단일 항목에 JSON 문자열로 인코딩하여 저장하므로, 배열을 가져오려면 (metaValues 대신) metaValue 필드를 사용해야 합니다.

불리언 값의 경우 _equals 필드를 사용하여 String에서 Boolean으로 형변환합니다:

query GetPost {
  post(by: { id: 1 }) {
    # Select field type - Whether a single or multiple values, we always use `metaValue`
    select: metaValue(key: "select_field")
    multiSelect: metaValue(key: "multi_select_field")
 
    # Checkbox field type
    checkbox: metaValue(key: "checkbox_field")
 
    # Radio button field type
    radioButton: metaValue(key: "radio_button_field")
 
    # Button group field type
    buttonGroup: metaValue(key: "button_group_field")
 
    # True/False field type
    trueFalseAsString: metaValue(key: "true_false_field")
    trueFalse: _equals(value1: $__trueFalseAsString, value2: "1")
  }
}

관계형 필드 타입 쿼리

커스텀 필드가 관계형(예: 포스트, 사용자, 택소노미 등)인 경우, 메타 필드에서 ID를 내보내고 이후 쿼리에서 해당 엔티티(Post, User, Taxonomy 등의 타입)를 즉시 쿼리할 수 있습니다.

그 외에는 단순한 필드 타입이므로 metaValue를 사용하여 직접 쿼리할 수 있습니다:

query GetPostDataAndExportRelationships {
  post(by: { id: 1 }) {
    link: metaValue(key: "link_field")
    
    # Post Object field type
    post_object: metaValue(key: "post_object_field")
      @export(as: "post_object_id")
 
    # Multiple Post Object field type
    post_objects: metaValue(key: "post_objects_field")
      @export(as: "post_object_ids")
    
    # Page Link field type
    page_link: metaValue(key: "page_link_field")
      @export(as: "page_link_id")
 
    # Multiple Page Link field type
    page_links: metaValue(key: "page_links_field")
      @export(as: "page_link_ids")
    
    # Relationship field type
    relationships: metaValue(key: "relationship_field")
      @export(as: "relationship_ids")
    
    # Taxonomy field type
    categoryTaxonomy: metaValue(key: "category_taxonomy_field")
      @export(as: "category_taxonomy_ids")
 
    tagTaxonomy: metaValue(key: "tag_taxonomy_field")
      @export(as: "tag_taxonomy_ids")
 
    # User field type
    user: metaValue(key: "user_field")
      @export(as: "user_id")
 
    # Multiple User field type
    users: metaValue(key: "users_field")
      @export(as: "user_ids")
  }
}
 
query QueryPostRelationships
  @depends(on: "GetPostDataAndExportRelationships")
{  
  # Query the post
  postObject: customPost(by: { id: $post_object_id }, status: any) {
    id
    title
  }
 
  # Query the list of posts
  postObjects: customPosts(filter: { ids: $post_object_ids, status: any }, pagination: { limit: -1 }) {
    id
    title
  }
   
  # Query the page
  pageLink: page(by: { id: $page_link_id }, status: any) {
    id
    title
  }
 
  # Query the list of pages
  pageLinks: pages(filter: { ids: $page_link_ids, status: any }, pagination: { limit: -1 }) {
    id
    title
  }
 
  # Query the relationship post
  relationships: customPosts(filter: { ids: $relationship_ids, status: any }, pagination: { limit: -1 }) {
    id
    title
  }
 
  # Query the list of categories
  categoryTaxonomy: categories(filter: { ids: $category_taxonomy_ids }, taxonomy: "category") {
    id
    name
  }
 
  # Query the list of tags
  tagTaxonomy: tags(filter: { ids: $tag_taxonomy_ids }, taxonomy: "post_tag") {
    id
    name
  }
 
  # Query the user
  user: user(by: { id: $user_id }) {
    id
    name
  }
 
  # Query the list of users
  users: users(filter: { ids: $user_ids }, pagination: { limit: -1 }) {
    id
    name
  }
}

여러 포스트에 대한 모든 관계를 쿼리하면서, 포스트 간에 공유되더라도 각 관계를 한 번만 가져올 수도 있습니다:

query GetPostDataAndExportRelationships
  @configureWarningsOnExportingDuplicateVariable(enabled: false)
{
  # Multiple posts
  posts {
    # Post Object field type
    post_object: metaValue(key: "post_object_field")
      @export(
        as: "post_object_id_list",
        type: LIST
      )
 
    # Multiple Post Object field type
    post_objects: metaValue(key: "post_objects_field")
      @export(
        as: "post_object_ids_list"
        type: LIST
      )
  }
}
 
query TransformRelationships
  @depends(on: "GetPostDataAndExportRelationships")
{
  flattenedPostObjectIdsList: _arrayFlatten(array: $post_object_ids_list)
    @arrayUnique
    @export(as: "post_object_ids_list")
}
 
query QueryPostRelationships
  @depends(on: "TransformRelationships")
{  
  # Query the post
  postObjectList: customPosts(filter: { ids: $post_object_id_list, status: any }, pagination: { limit: -1 }) {
    id
    title
  }
 
  # Query the list of posts
  postObjectsList: customPosts(filter: { ids: $post_object_ids_list, status: any }, pagination: { limit: -1 }) {
    id
    title
  }
}

날짜 필드 타입 쿼리

날짜는 "YMD" 형식(예: "20240320")의 문자열로 저장되므로, 타임스탬프로 파싱한 후 _date 함수에 전달해야 합니다.

query GetPost {
  post(by: { id: 1 }) {
    # Date Picker field
    dateAsString: metaValue(key: "date_picker_field")
    dateYear: _strSubstr(string: $__dateAsString, offset: 0, length: 4)
    dateMonth: _strSubstr(string: $__dateAsString, offset: 4, length: 2)
    dateDay: _strSubstr(string: $__dateAsString, offset: 6, length: 2)
    dateAsTimestamp: _makeTime(year: $__dateYear, month: $__dateMonth, day: $__dateDay, hour: 0, minute: 0, second: 0)
    date: _date(format: "Y-m-d", timestamp: $__dateAsTimestamp)
 
    # Date Time Picker field
    dateTime: metaValue(key: "date_time_picker_field")
 
    # Time Picker field
    timeAsString: metaValue(key: "time_picker_field")
    timeHours: _strSubstr(string: $__timeAsString, offset: 0, length: 2)
    timeMinutes: _strSubstr(string: $__timeAsString, offset: 3, length: 2)
    timeSeconds: _strSubstr(string: $__timeAsString, offset: 6, length: 2)
 
    googleMap: metaValue(key: "google_map_field")
    colorPicker: metaValue(key: "color_picker_field")
  }
}

모든 필드 타입 변경(뮤테이션)

메타 필드를 사용하여 ACF 커스텀 필드 데이터를 변경(항목 추가, 수정, 삭제)할 수도 있습니다.

이 쿼리는 단일 JSON 객체를 updatePost 뮤테이션에 전달하여 여러 ACF 커스텀 필드를 업데이트합니다.

JSON에는 값의 배열이 포함되며, 항목이 단일 값인 경우에도 마찬가지입니다.

mutation UpdatePost($postId: ID!) {
  updatePost(
    input: {
      id: $postId
      meta: {
        text_field: ["New text value"],
        textarea_field: ["New textarea value"],
        select_field: ["New select value"],
        multi_select_field: ["Choice 1", "Choice 2"],
        number_field: [42],
        date_picker_field: ["20240320"],
      }
    }
  ) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    post {
      id
      text: metaValue(key: "text_field")
      textarea: metaValue(key: "textarea_field")
      select: metaValue(key: "select_field")
      multiSelect: metaValues(key: "multi_select_field")
      number: metaValue(key: "number_field")
      date: metaValue(key: "date_picker_field")
    }
  }
}

이 쿼리는 updateCustomPostMeta 뮤테이션을 사용하여 ACF 커스텀 필드를 일괄 업데이트합니다:

mutation UpdatePost($postId: ID!) {
  updateCustomPostMetas(inputs: [
    { id: $postId, key: "text_field", value: "New text value" },
    { id: $postId, key: "textarea_field", value: "New textarea value" },
    { id: $postId, key: "select_field", value: "New select value" },
    { id: $postId, key: "multi_select_field", value: ["Choice 1", "Choice 2"] },
    { id: $postId, key: "number_field", value: 42 },
    { id: $postId, key: "date_picker_field", value: "20240320" },
  ]) {
    status
    errors {
      __typename
      ...on ErrorPayload {
        message
      }
    }
    customPost {
      __typename
      id
      text: metaValue(key: "text_field")
      textarea: metaValue(key: "textarea_field")
      select: metaValue(key: "select_field")
      multiSelect: metaValues(key: "multi_select_field")
      number: metaValue(key: "number_field")
      date: metaValue(key: "date_picker_field")
    }
  }
}