Content Fragments & GraphQL#

#0) Tóm tắt

• Content Fragment (CF) = structured content (data) trong DAM, không gắn layout.
• GraphQL = API tự sinh từ Content Fragment Models.
• Prod: persisted queries (GET) + cache (Dispatcher/CDN).

#1) Content Fragments vs Pages

#2) Content Fragment Models (schema)

#2.1 Tạo model

Tools → General → Content Fragment Models

• chọn config folder (/conf/<site>)
• Create → name (vd Article)
• Open → add fields

#2.2 Field types hay dùng

Ghi chú: “JSON Object field” phụ thuộc version/setup; on-prem 6.5 thường không đặt làm mặc định như Cloud. Nếu cần kiểu JSON, ưu tiên modelling bằng fields hoặc store text + parse.

#2.3 Model mẫu: Article

#2.4 Model mẫu: Author

#3) Tạo Content Fragments

Assets → Files:

• folder (vd /content/dam/<site>/articles)
• Create → Content Fragment
• chọn model (vd Article)
• đặt name + fill fields

#3.1 Variations

#4) GraphQL API

#4.1 Endpoint (pattern)

Endpoint thường gắn theo configuration:

http://localhost:4502/content/_cq_graphql/<configuration>/endpoint.json

Notes:

• path cụ thể có thể khác theo setup/SP → verify trong UI GraphQL tooling.
• dùng GraphiQL để xem schema + thử query.

#4.2 Field name mapping

• label field trong model → GraphQL field camelCase
• case-sensitive
• debug bằng schema explorer trong GraphiQL

#5) Query patterns (copy/paste)

#5.1 List articles

{
  articleList {
    items {
      _path
      title
      slug
      excerpt
      publishDate
      featured
      category
    }
  }
}

#5.2 Get by path

{
  articleByPath(_path: "/content/dam/<site>/articles/getting-started") {
    item {
      title
      slug
      body {
        html
        plaintext
      }
      publishDate
      author {
        name
        bio
      }
    }
  }
}

#5.3 Filtering

{
  articleList(
    filter: {
      category: { _expressions: [{ value: "tech", _operator: EQUALS }] }
      featured: { _expressions: [{ value: true, _operator: EQUALS }] }
    }
  ) {
    items {
      title
      excerpt
      publishDate
    }
  }
}

#5.4 Sorting + pagination

{
  articleList(sort: "publishDate DESC", limit: 10, offset: 0) {
    items {
      title
      publishDate
    }
  }
}

#5.5 Rich text formats (tuỳ version/setup)

{
  articleByPath(_path: "/content/dam/<site>/articles/example") {
    item {
      body {
        html
        plaintext
        json
      }
    }
  }
}

#5.6 Fragment references (nested)

{
  articleList {
    items {
      title
      author {
        name
        bio
        avatar {
          ... on ImageRef {
            _path
            width
            height
          }
        }
      }
    }
  }
}

#6) Persisted queries (prod default)

#6.1 Execute (ví dụ)

# Author (local) - cần auth
curl -u admin:admin "http://localhost:4502/graphql/execute.json/<conf>/article-list"

# Publish - public persisted query (tuỳ security)
curl "http://localhost:4503/graphql/execute.json/<conf>/article-list"

Naming:

• versioned name: article-list-v1
• giữ response shape tối thiểu

#7) Production hardening checklist (headless)

#8) Headless delivery flow (frontend)

const res = await fetch(
  "https://publish.<site>.com/graphql/execute.json/<conf>/article-list"
);
const json = await res.json();
const items = json.data.articleList.items;

#9) Render CF “truyền thống” trên Page

Content Fragment Core Component:

• add component lên page
• select fragment
• chọn fields render
• chọn variation (optional)

Use case:

• hybrid: page-based layout + structured CF data

#Liên kết nội bộ

• Content Fragment
• Headless GraphQL (on-prem)
• MSM