헤드리스 Oracle Content Management로 Next.js 방식으로 최소 사이트 구축

소개

Next.js는 서버측 렌더링, React 기반 웹 애플리케이션용 정적 웹 사이트 생성 등의 기능을 지원하는 오픈 소스 React 프론트 엔드 개발 웹 프레임워크입니다.

Next.js 애플리케이션에서 Oracle Content Management 콘텐츠를 사용하려면 GitHub에서 제공되는 오픈 소스 저장소로 Next.js 최소 샘플을 사용할 수 있습니다.

이 사용지침서에서는 Oracle Content Management를 헤드리스 CMS로, JavaScript에서 콘텐츠 전달을 위해 SDK(소프트웨어 개발 키트)를 활용하여 Next.js에서 간단한 최소 사이트를 구축합니다. 이 Next.js 샘플은 GitHub에서 사용할 수 있습니다.

이 튜토리얼은 다음 세 가지 작업으로 구성됩니다.

1. Oracle Content Management 준비
2. Next.js에서 최소 사이트 구축
3. 배치할 애플리케이션 준비

필요 조건

이 튜토리얼을 계속하기 전에 먼저 다음 정보를 읽는 것이 좋습니다.

• 주요 개념
• 자산 저장소

이 자습서를 따르려면 다음이 필요합니다.

• Oracle Content Management 가입
• 콘텐츠 관리자 롤이 있는 Oracle Content Management 계정
• 노드 버전이 10 이상인 Windows 또는 Mac 컴퓨터

우리가 구축하고 있는 것

Next.js를 최소화하면 Oracle Content Management 저장소에서 이미지와 기타 콘텐츠를 쉽게 검색할 수 있습니다.

구축 중인 내용을 확인하려면 다음 자습서의 최종 상태, Oracle Content Management의 콘텐츠를 사용하는 기본 Next.js 최소 사이트입니다.

https://headless.mycontentdemo.com/samples/oce-nextjs-minimal-sample

다음은 이 자습서의 마지막 부분인 홈 페이지입니다.

이 자습서의 마지막 부분에서는 연락처 페이지에 문의합니다.

계속하려면 Oracle Content Management에 대한 활성 구독이 있어야 하며 콘텐츠 관리자 역할로 로그인해야 합니다.

작업 1: Oracle Content Management 준비

Oracle Content Management 인스턴스가 아직 없는 경우 빠른 시작을 참조하여 Oracle Cloud에 등록하고, Oracle Content Management 인스턴스를 프로비전하고, 헤드리스 CMS로 Oracle Content Management를 구성하는 방법을 알아보십시오.

이 자습서에서는 콘텐츠 모델을 생성해야 합니다. 빈 저장소를 콘텐츠 유형 및 연관된 콘텐츠로 채울 수 있는 다운로드 가능 자산 팩이 있습니다.

Oracle Content Management를 준비하려면 다음을 수행합니다.

1. 채널 및 자산 저장소 생성.
2. Oracle Content Management 샘플 자산 팩 임포트

채널 및 자산 저장소 생성

먼저 콘텐츠를 게시할 수 있도록 Oracle Content Management에서 채널과 자산 저장소를 생성해야 합니다.

Oracle Content Management에서 채널 및 자산 저장소를 생성하려면 다음과 같이 하십시오.

1. Oracle Content Management 웹 인터페이스에 관리자로 로그인합니다.

2. 왼쪽 탐색 메뉴에서 콘텐츠를 선택하고 페이지 헤더의 선택 목록에서 채널 게시를 선택합니다.

   

3. 오른쪽 상단 모서리에서 생성을 눌러 새 채널을 생성합니다. 이 자습서의 목적을 위해 채널 이름을 'OCEMinimalChannel'로 지정하고 액세스를 공개로 유지합니다. 저장을 눌러 채널을 생성합니다.

   

4. 왼쪽 탐색 메뉴에서 콘텐츠를 선택하고 페이지 헤더의 선택 목록에서 저장소를 선택합니다.

   

5. 오른쪽 상단 모서리에서 생성을 눌러 새 자산 저장소를 생성합니다. 이 자습서의 목적을 위해 자산 저장소 이름을 'OCEMinimalRepository'로 지정합니다.

   

6. 채널 게시 필드에서 OCEMinimalRepository 저장소의 콘텐츠를 OCEMinimalChannel 채널에 게시할 수 있도록 Oracle Content Management에 표시할 OCEMinimalChannel 채널을 선택합니다. 완료되면 저장을 누릅니다.

   

컨텐트 모델 생성

다음 작업은 컨텐트 모델을 생성하는 것입니다. 다음 두 가지 방법 중 하나를 사용할 수 있습니다.

• 방법 1: Oracle Content Management 샘플 자산 팩 임포트
• 방법 2: 고유한 콘텐츠 모델 생성

Oracle Content Management 샘플 자산 팩 임포트

이 자습서에 필요한 모든 콘텐츠 유형 및 자산이 포함된 미리 구성된 Oracle Content Management 샘플 자산 팩을 다운로드할 수 있습니다. 원하는 경우 샘플 자산 팩을 다운로드하지 않고 고유 콘텐츠 모델을 생성할 수도 있습니다.

Oracle Content Management 샘플 자산 팩에서 이 자습서에서 사용 중인 콘텐츠의 복사본을 업로드할 수 있습니다. 이렇게 하면 콘텐츠 유형을 실험하고 콘텐츠를 수정할 수 있습니다. Oracle Content Management 샘플 자산 팩을 임포트하려면 자산 팩 아카이브 OCESamplesAssetPack.zip를 다운로드하여 선택한 디렉토리로 추출할 수 있습니다.

1. Oracle Content Management 다운로드 페이지에서 Oracle Content Management 샘플 자산 팩(OCESamplesAssetPack.zip)을 다운로드합니다. 다운로드한 zip 파일을 컴퓨터의 위치에 추출합니다. 압축을 푼 후 이 위치에 OCEMinimal_data.zip이라는 파일이 포함됩니다.

2. Oracle Content Management 웹 인터페이스에 관리자로 로그인합니다.

3. 왼쪽 탐색 메뉴에서 콘텐츠를 선택하고 페이지 헤더의 선택 목록에서 저장소를 선택합니다. 이제 OCEMinimalRepository을 선택하고 위쪽 작업 표시줄에서 콘텐츠 임포트 단추를 누릅니다.

   

4. 로컬 컴퓨터에서 문서 폴더로 OCEMinimal_data.zip을 업로드합니다.

   

5. 업로드되면 OCEMinimal_data.zip을 선택하고 확인을 눌러 콘텐츠를 자산 저장소로 임포트합니다.

   

6. 콘텐츠를 성공적으로 임포트한 후 자산 페이지로 이동하여 OCEMinimalRepository 저장소를 엽니다. 이제 모든 관련 이미지와 콘텐츠 항목이 자산 저장소에 추가되었음을 알 수 있습니다.

   

7. 왼쪽 상단의 모두 선택, 게시를 차례로 눌러 임포트한 모든 자산을 이전에 생성한 게시 채널 OCEGettingStartedChannel에 추가합니다.

   

8. 게시하기 전에 모든 자산을 검증해야 합니다. 먼저 OCEMinimalChannel을 선택한 채널로 추가하고 검증 단추를 누릅니다.

   

9. 자산이 검증되면 오른쪽 맨 위에 있는 게시 단추를 눌러 선택한 채널에 모든 자산을 게시할 수 있습니다.

   

모든 자산이 게시된 자산 페이지에서 확인할 수 있습니다. 자산 이름 위의 아이콘으로 알 수 있습니다.

Oracle Content Management 샘플 자산 팩을 임포트한 후 Next.js에서 최소 사이트 구축을 시작할 수 있습니다.

고유의 콘텐츠 모델 생성

Oracle Content Management 샘플 자산 팩 임포트 대신 고유한 콘텐츠 모델을 생성할 수도 있습니다.

이 자습서에서는 이 샘플의 기본 콘텐츠 유형으로 'MinimalMain'이라는 콘텐츠 유형을 사용합니다. 이 콘텐츠 유형은 머리글 및 바닥글 로고와 nav에 포함해야 하는 페이지 목록으로 구성됩니다.

콘텐츠 모델에 대한 콘텐츠 유형을 생성하려면 다음을 수행합니다.

1. Oracle Content Management 웹 인터페이스에 관리자로 로그인합니다.
2. 왼쪽 탐색 메뉴에서 콘텐츠를 선택하고 페이지 헤더의 선택 목록에서 자산 유형을 선택합니다.
3. 오른쪽 상단에서 생성을 누릅니다.
4. 디지털 자산 유형이 아닌 콘텐츠 유형을 생성하도록 선택합니다. 필요한 모든 콘텐츠 유형에 대해 이 작업을 반복합니다.

각각 고유한 필드 집합을 사용하여 세 가지 컨텐트 유형을 생성합니다.

• MinimalMain
• MinimalPage
• MinimalSection

첫번째 콘텐츠 유형 MinimalMain에는 다음 필드가 있어야 합니다.

표시 이름	필드 유형	필요	시스템 이름
headerLogo	단일 가치 매체 필드		headerLogo
footerLogo	단일 가치 매체 필드		footerLogo
페이지	다중 값 참조 필드		페이지

MinimalMain 콘텐츠 유형 정의는 다음과 같아야 합니다.

두번째 콘텐츠 유형 MinimalPage에는 다음 필드가 있어야 합니다.

표시 이름	필드 유형	필요	시스템 이름
섹션	다중 값 참조 필드		섹션

MinimalPage 콘텐츠 유형은 다음과 같아야 합니다.

세번째 및 최종 콘텐츠 유형 MinimalSection에는 다음 필드가 있어야 합니다.

표시 이름	필드 유형	필요	시스템 이름
type	단일 값 텍스트 필드	X	type
헤딩	단일 값 텍스트 필드		헤딩
body	단일 값 대형 텍스트 필드		body
이미지	단일 값 이미지 필드		이미지
작업	단일 가치가 포함된 콘텐츠 필드		작업

MinimalSection 콘텐츠 유형은 다음과 같아야 합니다.

콘텐츠 유형을 생성한 후에는 해당 콘텐츠 유형을 이전에 생성한 저장소(OCEMinimalRepository)에 추가할 수 있습니다.

1. Oracle Content Management 웹 인터페이스에 관리자로 로그인합니다.
2. OCEMinimalRepository으로 이동합니다.
3. 저장소를 편집하고 자산 유형에서 새로 생성된 세 개의 콘텐츠 유형을 모두 지정합니다. Save 버튼을 눌러 변경사항을 저장합니다.

저장소에 콘텐츠 유형을 추가한 후 자산 페이지에서 OCEMinimalRepository 저장소를 열고 모든 콘텐츠 유형에 대한 콘텐츠 항목 생성을 시작할 수 있습니다.

작업 2: Next.js에서 최소 사이트 생성

서버측 렌더링된 Next.js 애플리케이션에서 Oracle Content Management 콘텐츠를 소비하기 위해 GitHub에서 오픈 소스 저장소로 제공되는 Next.js 최소 사이트 샘플을 사용할 수 있습니다.

주: Next.js 샘플은 선택 사항이므로 이 자습서에서 사용하여 빠르게 시작할 수 있습니다. 고유의 Next.js 애플리케이션을 구축할 수도 있습니다.

Next.js에서 최소 사이트를 구축하려면 다음과 같이 하십시오.

1. 샘플 저장소 복제 및 설치 종속성
2. Next.js 애플리케이션 구성
3. Oracle Content Management Content SDK 사용
4. 콘텐츠 SDK를 사용하여 콘텐츠 인출

샘플 저장소 복제 및 설치 종속성

Next.js 최소 사이트 샘플은 GitHub에서 오픈 소스 저장소로 제공됩니다.

먼저 GitHub의 샘플을 로컬 컴퓨터로 복제하고 디렉토리를 저장소 루트로 변경해야 합니다.

git clone https://github.com/oracle/oce-nextjs-minimal-sample.git
    cd oce-nextjs-minimal-sample

이제 코드베이스가 있으므로 응용 프로그램에 대한 종속성을 다운로드해야 합니다. 루트 디렉토리에서 다음 명령을 실행합니다.

npm install

Next.js 애플리케이션 구성

이 Next.js 최소 사이트 샘플에서는 Oracle Content Management Content SDK(및 기타 모든 요청)가 올바른 채널 토큰을 사용하여 올바른 인스턴스 URL 및 API 버전을 대상으로 지정할 수 있도록 몇 가지 정보를 구성해야 합니다. 이러한 값은 스크립트/server-config-utils.js에서 새 전달 클라이언트를 인스턴스화하는 데 사용됩니다.

이 응용 프로그램은 Next.js에서 읽고 process.env를 사용하여 응용 프로그램 내의 코드에 사용 가능한 .env.local 파일을 사용합니다.

텍스트 편집기에서 .env.local 파일을 엽니다. 다음을 확인합니다.

# The connection details for the Oracle Content Management server to be used for this application
    SERVER_URL=https://samples.mycontentdemo.com
    API_VERSION=v1.1
    CHANNEL_TOKEN=ba0efff9c021422cb134c2fd5daf6015

각 키-값 쌍을 변경하여 인스턴스 URL, 대상으로 지정할 API 버전 및 게시 채널과 연관된 채널 토큰을 반영합니다. 이 자습서의 채널은 OCEMinimalChannel입니다.

Oracle Content Management Content SDK 사용

Oracle Content Management는 애플리케이션에서 콘텐츠를 검색하고 사용하는 데 도움이 되는 SDK를 제공합니다. SDK는 NPM 모듈로 게시되며 프로젝트는 GitHub에 호스팅됩니다.

여기서 SDK에 대해 자세히 알아보십시오.

SDK가 package.json 파일에서 이 프로젝트의 런타임 종속성으로 등록되었습니다.

콘텐츠 SDK를 사용하여 콘텐츠 인출

이제 Content SDK를 활용하여 콘텐츠를 인출하여 Next.js 애플리케이션에서 렌더링할 수 있습니다.

Content SDK는 DeliveryClient 객체를 사용하여 끝점을 지정합니다. 해당 클라이언트 객체를 사용하여 모든 요청을 생성할 수 있습니다.

스크립트 폴더에는 Content SDK를 사용하여 Oracle Content Management에서 데이터를 가져오는 코드가 포함되어 있습니다.

script/server-config-utils.js 파일은 Content SDK를 임포트한 다음 .env.local에 지정된 구성을 사용하여 전달 클라이언트를 생성합니다.

다음 명령은 SDK를 가져옵니다.

import { createDeliveryClient, createPreviewClient } from '@oracle/content-management-sdk';

다음 명령은 전달 클라이언트를 생성합니다.

return createDeliveryClient(serverconfig);

script/services.js 파일에는 이 Next.js 최소 응용 프로그램에 대한 데이터를 가져오는 함수가 포함되어 있습니다.

fetchOceMinimalMain() 메소드는 최소 메인의 슬러그로 콘텐츠 유형 MinimalMain을 검색합니다.

export async function fetchOceMinimalMain() {
      const data = await getItem('minimalmain', 'fields.headerlogo,fields.footerlogo,fields.pages');
      if (!data.hasError) {
        const { fields } = data;
        const { headerlogo, footerlogo } = fields;
        // Extract the sourceset for the headerImage and footerImage and put it back in the data
        data.headerRenditionURLs = getSourceSet(headerlogo);
        data.footerRenditionURLs = getSourceSet(footerlogo);
      }
      return data;
    }

이미지를 렌더링하기 위해 services.js는 자산의 변환에서 구성된 자산에 대한 소스 세트를 검색하는 도우미 메소드를 제공합니다.

function getSourceSet(asset) {
      const urls = {};
      urls.srcset = '';
      urls.jpgSrcset = '';
      if (asset.fields && asset.fields.renditions) {
        asset.fields.renditions.forEach((rendition) => {
          addRendition(urls, rendition, 'jpg');
          addRendition(urls, rendition, 'webp');
        });
      }
      // add the native rendition to the srcset as well
      urls.srcset += `${asset.fields.native.links[0].href} ${asset.fields.metadata.width}w`;
      urls.native = asset.fields.native.links[0].href;
      urls.width = asset.fields.metadata.width;
      urls.height = asset.fields.metadata.height;
      return urls;
    }

fetchPage() 메소드는 페이지의 슬러그 값을 사용하여 컨텐트 유형 MinimalPage을 검색합니다.

export async function fetchPage(pageslug) {
      // Get the page details
      const page = await getItem(pageslug, 'fields.sections');
      return page;
    }

getRenditionURLs() 메소드는 해당 이미지의 ID를 사용하여 섹션에 정의될 수 있는 이미지에 대한 변환 URL을 검색합니다.

export function getRenditionURLs(identifier) {
      const client = getClient();
      return client.getItem({
        id: identifier,
        expand: 'fields.renditions',
      }).then((asset) => getSourceSet(asset))
        .catch((error) => logError('Fetching Rendition URLs failed', error));
    }

이제 데이터 쿼리를 실행했으므로 Next.js 구성 요소에서 응답을 렌더링할 수 있습니다.

Next.js 구성 요소

Next.js는 React를 기반으로 하며 React는 JavaScript에 대한 HTML과 같은 구문 확장인 JSX라는 기술을 사용하여 컨텐츠를 렌더링합니다. 순수한 JavaScript를 작성하여 Oracle Content Management에서 데이터를 렌더링할 수 있지만 JSX를 사용하는 것이 좋습니다.

최소 사이트 응용 프로그램은 각 페이지를 여러 개의 작은 구성 요소로 나눕니다.

다음 몇 개의 섹션은 Next.js가 각 구성 요소에서 응용 프로그램을 렌더링하는 방법에 대한 개요를 구성합니다.

• 페이지 폴더
• 주 구성요소
• 페이지 구성요소
• 머리글 및 바닥글 구성요소
• 섹션 구성 요소
• 오류 구성요소

페이지 폴더

이 사이트에서는 1개의 경로 /페이지를 제공합니다. 요청은 pages/page/[[..slug]].jsx 파일에 정의된 기본 구성 요소로 전달됩니다. root 경로 요청은 next.config.js에서 재지정을 지정하여 /page로 재지정됩니다.

  async redirects() {
        return [
          {
            source: '/',
            destination: '/page/',
            permanent: true,
          },
        ]
      }

모든 페이지에는 회사 로고와 링크를 포함하는 머리글과 로고 및 소셜 미디어 아이콘이 포함된 바닥글이 있습니다. 페이지는 정적 URL을 통해 액세스되고 관련 데이터를 모든 하위 구성요소에 전달하기 전에 필요한 모든 데이터를 가져옵니다.

Next.js는 pages 디렉토리의 모든 페이지를 응용 프로그램의 경로로 처리합니다.

주 구성요소

모든 페이지는 page/page/[[..slug]].jsx에 있는 Main 구성 요소에 의해 렌더링됩니다. Next.js의 모든 경로는 큰따옴표([[...slug]])의 매개변수를 포함하여 선택 사항으로 설정됩니다. 페이지 목록의 첫번째 페이지로 기본 설정되는 루트 페이지에는 전달된 매개변수가 없으므로 슬러그 매개변수를 선택 사항으로 정의합니다.

구성요소는 API를 임포트하여 services.js 파일에서 데이터를 가져옵니다.

import { fetchOceMinimalMain, fetchPage, getRenditionURLs } from '../scripts/services';

페이지의 URL은 페이지 슬러그를 경로로 포함하는 동적 URL입니다. 예: URL 경로는

• /page/home
• /page/contact-us
• /page

Next.js가 동적 URL이 있는 페이지에 대해 정적 사이트 생성을 사용하는 경우 getStaticPaths()을 호출하여 해당 페이지의 모든 경로를 가져옵니다.

export async function getStaticPaths() {
      const appData = await fetchOceMinimalMain();
      const { fields } = appData;
    
      // Generate the paths we want to pre-render based on posts
      const paths = fields.pages.map((page) => ({
        params: { slug: [page.slug] },
      }));
      // Also add the path for the root /
      paths.push({
        params: { slug: [] },
      });
      return {
        paths,
        fallback: false,
      };
    }

getStaticProps() 함수는 페이지의 단일 인스턴스에 대한 데이터를 가져오는 데 사용됩니다. 페이지 슬러그는 메소드로 전달된 파라미터에서 가져옵니다. 그런 다음 이 페이지에 필요한 모든 데이터를 가져오는 데 페이지 슬러그가 사용됩니다.

export async function getStaticProps(context) {
      // fetch the minimal main data
      const appData = await fetchOceMinimalMain();
      // find the slug param from the context. If its null, default to the first page slug
      const { params } = context;
      let { slug } = params;
      if (slug == null) {
        slug = appData.fields.pages[0].slug;
      }
      // fetch the page corresponding to the slug
      const pageData = await fetchPage(slug);
      const { headerRenditionURLs, footerRenditionURLs, fields } = appData;
      const { sections } = pageData.fields;
    
      // for each section in the page, if a image is present, get the corresponding rendition urls
      // and insert it back into the section
      const promises = [];
      sections.forEach((section) => {
        // add a promise to the total list of promises to get any section rendition urls
        if (section.fields.image) {
          promises.push(
            getRenditionURLs(section.fields.image.id)
              .then((renditionURLs) => {
                // eslint-disable-next-line no-param-reassign
                section.renditionURLs = renditionURLs;
              }),
          );
        }
      });
    
      // execute all the promises and return all the data
      await Promise.all(promises);
      return {
        props: {
          headerRenditionURLs,
          footerRenditionURLs,
          pages: fields.pages,
          pageData,
        },
      };
    }

페이지 구성요소

Page 구성 요소는 페이지에 정의된 모든 섹션을 렌더링합니다. Components/Page.jsx에 있는 Page 컴포넌트를 엽니다. 단순히 Main 구성 요소에서 전달된 데이터를 사용합니다. 서버에서 추가 데이터를 가져오지 않습니다. 단면 구성요소를 사용하여 단면 데이터를 렌더링합니다.

Page.propTypes = {
      pageData: PropTypes.shape().isRequired,
    };

헤더 및 바닥글 구성요소

구성 요소/Header.jsx와 구성 요소/Footer.jsx에 있는 바닥글 구성 요소에 있는 Header 구성 요소는 단순히 기본 구성 요소에서 전달된 데이터를 사용합니다. 서버에서 추가 데이터를 가져오지 않습니다.

섹션 구성 요소

component/Section.jsx에 있는 섹션 구성요소는 Page 구성요소에서 사용되며 MinimalSection 유형의 콘텐츠 항목을 렌더링하는 데 사용됩니다.

이 구성요소에 페이지 구성요소에서 전달된 데이터가 있습니다.

오류 구성요소

구성 요소/Error.jsx에 있는 Error 구성 요소는 페이지 및 기본 구성 요소에 사용됩니다. 서버에 대한 호출 중에 오류가 발생한 경우 렌더링됩니다.

작업 3: 배치를 위한 응용 프로그램 준비

이제 Next.js 블로그 사이트를 구축했으므로 이제 로컬 개발 서버에서 이 사이트를 확인해야만 문제를 디버그하고 애플리케이션을 미리 볼 수 있습니다.

다음 두 단계로 응용 프로그램을 배치하도록 준비합니다.

1. 로컬 개발 서버 가동
2. 스크립트를 사용하여 개발 및 운용에서 애플리케이션 작성 및 실행

로컬 개발 서버 가동

다음 명령을 실행하여 개발 서버를 로컬로 시작할 수 있습니다.

npm run dev

그런 다음 http://localhost:3000에 브라우저를 열어 사용 중인 사이트를 확인합니다.

주: 페이지를 미리 렌더링하지 않습니다. 페이지를 미리 렌더링하려면 다음 섹션을 참조하십시오.

스크립트를 사용하여 개발 및 프로덕션에서 응용 프로그램 작성 및 실행

운용의 경우 빌드 스크립트를 사용하여 사이트를 정적으로 생성합니다.

npm run build

시작 스크립트는 정적으로 생성된 페이지를 제공하는 Node.js 서버를 시작하는 데 사용됩니다.

npm run start

---

제목 및 저작권 정보

헤드리스 Oracle Content Management로 Next.js 방식으로 최소 사이트 구축

F49321-01

2021년 10월

Copyright © 2021, Oracle and/or its affiliates.

주 저자: Oracle Corporation