Criar uma Galeria de Imagens no Next.js com o Oracle Content Management sem Interface do Usuário

Introdução

O Next.js é uma estrutura web de desenvolvimento de front-end React de código aberto que permite funcionalidades como renderização do servidor e geração de sites estáticos para aplicativos Web baseados em React.

Este tutorial apresentará as etapas básicas da criação de um visualizador de imagem usando o Next.js, com o Oracle Content Management como o sistema de gerenciamento de conteúdo e seu Content SDK. Você verá como as taxonomias podem ser usadas para categorizar conteúdo e como diferentes renderizações de ativos digitais podem ser usadas para vários casos de uso. Este exemplo do Next.js está disponível no GitHub.

O tutorial consiste em três tarefas:

Preparar o Oracle Content Management
Criar a Galeria de Imagens no Next.js
Prepare seu aplicativo para implantação

Pré-requisitos

Antes de continuar com este tutorial, recomendamos que você leia as seguintes informações primeiro:

Para seguir este tutorial, você precisará de:

uma assinatura do Oracle Content Management
uma conta do Oracle Content Management com a atribuição de Administrador de Conteúdo
um computador Windows ou Mac com Node versão 10 ou superior

O que estamos construindo

Nossa galeria de imagens consistirá em várias páginas de imagens de alimentos e bebidas disponíveis em uma cafeteria.

Esta imagem mostra uma galeria de imagens com diferentes tipos de bagéis, alguns com creme ou cima, ou ambos.

Para dar uma olhada no que estamos construindo, aqui está o estado final de nosso tutorial, uma versão ao vivo deste site de galeria de imagens:

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

As categorias são nós filho de uma taxonomia e podem ser organizadas em hierarquias. Na galeria de imagens, queremos mostrar todas as categorias disponíveis, independentemente da organização. Para fazer isso, primeiro precisamos encontrar as taxonomias disponíveis, que fazemos usando o método getTaxonomies() do Content SDK.

Observação: A implementação de getTaxonomies usa o recurso de API REST GET /published/api/v1.1/taxonomies.

Em seguida, precisamos obter o conjunto de categorias para cada uma das taxonomias. Isso é feito usando o método queryTaxonomyCategories() do Content SDK.

Observação: A implementação de queryTaxonomyCategories usa o GET da API REST /published/api/v1.1/taxonomies/{id}/categories.

Para criar a visualização de uma categoria, como Bagels, precisamos obter uma contagem do número de imagens e dos URLs das quatro primeiras imagens.

Esta imagem mostra imagens na categoria Bolsas.

Nossa solicitação para localizar os ativos publicados na categoria especifica os critérios de categoria por meio de uma string de consulta, da seguinte forma:

"(taxonomies.categories.nodes.id eq 892CD6BC4F654249A00CB7942EE8C773)"

Para otimizar o carregamento de imagens, usaremos uma renderização da imagem chamada 'Miniatura'. Consulte retrieveThumbnailURL(), em scripts/services.js, para o código que examina o conjunto de renderizações disponíveis para cada imagem.

Observação: além de publicar os ativos digitais que queremos exibir, você também precisa publicar as taxonomias para o canal.

Para prosseguir, será necessário ter uma assinatura ativa do Oracle Content Management e efetuar log-in com a atribuição de Administrador de Conteúdo.

Tarefa 1: Preparar o Oracle Content Management

Este tutorial se baseia na suposição de que você criou o repositório de ativos e atualmente tem um modelo de conteúdo vazio (ou seja, nenhum tipo de conteúdo criado).

Se você ainda não tiver uma instância do Oracle Content Management, consulte o Início Rápido para saber como se registrar no Oracle Cloud, provisionar uma instância do Oracle Content Management e configurar o Oracle Content Management como um CMS sem supervisão.

Para este tutorial, você precisará criar um modelo de conteúdo de duas maneiras. Há um pacote de ativos transferível para download disponível que preencherá seu repositório vazio com tipos de conteúdo e conteúdo associado, ou você poderá criar seu próprio modelo de conteúdo e conteúdo.

Para preparar o Oracle Content Management:

Crie um repositório de canais e ativos.
Importar o Pacote de Ativos de Amostras do Oracle Content Management
Fazer Upload dos Seus Próprios Ativos de Imagem
Criar Taxonomias e Vinculá-las a Ativos de Imagem

Criar um Repositório de Canal e Ativos

Primeiro, você precisa criar um canal e um repositório de ativos no Oracle Content Management para publicar conteúdo.

Para criar um canal e um repositório de ativos no Oracle Content Management:

Efetue log-in na interface Web do Oracle Content Management como administrador.
Escolha Conteúdo no menu de navegação à esquerda e escolha Publicando Canais na lista de seleção no cabeçalho da página.
No canto superior direito, clique em Criar para criar um novo canal. Nomeie o canal 'OCEImageGalleryChannel' com a finalidade deste tutorial e mantenha o acesso público. Clique em Salvar para criar o canal.
Escolha Conteúdo no menu de navegação à esquerda e escolha Repositórios na lista de seleção no cabeçalho da página.
No canto superior direito, clique em Criar para criar um novo repositório de ativos. Nomeie o repositório de ativos 'OCEImageGalleryRepository' com a finalidade deste tutorial.
No campo Publicando Canais, selecione OCEImageGalleryChannel para indicar ao Oracle Content Management que o conteúdo no repositório OCEImageGalleryRepository pode ser publicado no canal OCEImageGalleryChannel. Clique em Salvar quando concluir.

Importar o Pacote de Ativos de Amostras do Oracle Content Management

Você pode fazer download de um pacote de ativos de amostra pré-configurado do Oracle Content Management que contenha todos os tipos de conteúdo e ativos necessários para este tutorial.

Você pode fazer upload de uma cópia do conteúdo que estamos usando neste tutorial no Pacote de Ativos de Amostras do Oracle Content Management. Isso permitirá que você experimente os tipos de conteúdo e modifique o conteúdo. Você pode fazer download do arquivo compactado do pacote de ativos, OCESamplesAssetPack.zip, e extraí-lo para um diretório de sua escolha:

Faça download do Oracle Content Management Samples Asset Pack (OCESamplesAssetPack.zip) na página downloads do Oracle Content Management. Extraia o arquivo zip baixado para um local no computador. Após a extração, esse local incluirá um arquivo chamado OCEImageGallery_data.zip.
Efetue log-in na interface Web do Oracle Content Management como administrador.
Escolha Conteúdo no menu de navegação à esquerda e escolha Repositórios na lista de seleção no cabeçalho da página. Agora selecione OCEImageGalleryRepository e clique no botão Importar Conteúdo na barra de ação superior.
Faça upload do OCEImageGallery_data.zip do seu computador local para a pasta Documentos.
Depois de fazer upload, selecione OCEImageGallery_data.zip e clique em OK para importar o conteúdo para o repositório de ativos.
Após a importação bem-sucedida do conteúdo, navegue até a página Ativos e abra o repositório OCEImageGalleryRepository. Você verá que todas as imagens relacionadas e os itens de conteúdo foram adicionados ao repositório de ativos.
Clique em Selecionar Tudo no canto superior esquerdo e em Publicar para adicionar todos os ativos importados ao canal de publicação criado anteriormente, OCEImageGalleryChannel.
Antes da publicação, é necessário validar todos os ativos. Primeiro adicione OCEImageGalleryChannel como canal selecionado e, em seguida, clique no botão Validar.
Depois que os ativos tiverem sido validados, você poderá publicar todos os ativos no canal selecionado clicando no botão Publicar no canto superior direito.

Quando terminar, você poderá ver na página Ativos que todos os ativos foram publicados. (Você pode informar pelo ícone acima do nome do ativo.)

Esta imagem mostra a página Ativos, com todos os ativos suspensos.

After importing the Oracle Content Management Samples Asset Pack, you can start building the image gallery in Next.js.

Fazer Upload dos Seus Próprios Ativos de Imagem

Para este tutorial, estamos usando um repositório de ativos chamado 'OCEImageGalleryRepository' para criar a página inicial de nosso site na galeria. Esta home page consiste no título "Image Gallery" bem como em álbuns de coleção de imagens que têm ativos de imagem dentro.

Esta imagem mostra a página inicial da galeria de imagens, com imagens de várias categorias de imagem: sanduíches, bebidas, sobremesa, café da manhã e comida.

Para adicionar ativos de imagem ao repositório de ativos da galeria:

Efetue log-in na interface Web do Oracle Content Management.
Clique em Ativos no menu de navegação à esquerda.
Abra o repositório OCEImageGalleryRepository.
Clique em Adicionar no canto superior direito da página para adicionar ativos de imagem ao repositório de ativos da galeria.
Faça upload de seus próprios ativos novos em seu computador local ou escolha os ativos existentes já existentes no Oracle Content Management.

Criar Taxonomias e Vinculá-las a Ativos de Imagem

Você precisa criar uma taxonomia no Oracle Content Management e, em seguida, atribuir categorias aos ativos no seu repositório.

Para criar uma taxonomia no Oracle Content Management:

Efetue log-in na interface Web do Oracle Content Management como administrador.
Escolha Conteúdo no menu de navegação à esquerda e escolha Taxonomias na lista de seleção no cabeçalho da página.
No canto superior direito, clique em Criar para criar uma nova taxonomia. Nomeie o canal 'OCEImageGalleryTaxonomy' com a finalidade deste tutorial.
Clique em Criar.
Agora crie sua taxonomia adicionando categorias. Clique em Adicionar uma categoria.
Nomeie o item de categoria pai 'Alimentos' e adicione as seguintes categorias filho:
- Breve
- Dessert
- Bebidas
- Sandwiches
Clique em Concluído no canto superior direito da tela.
Na página Taxonomias, selecione a taxonomia OCEImageGalleryTaxonomy e clique em Promover na barra de ações para disponibilizá-la para uso em seus repositórios de ativos.

Em seguida, edite o repositório OCEImageGalleryRepository para ativar a taxonomia OCEImageGalleryTaxonomy desse repositório:

Efetue log-in na interface Web do Oracle Content Management como administrador.
Escolha Conteúdo no menu de navegação à esquerda e escolha Repositórios na lista de seleção no cabeçalho da página.
Selecione e edite o repositório OCEImageGalleryRepository.
No campo Taxonomias, selecione OCEImageGalleryTaxonomy, para que você possa atribuir categorias dessa taxonomia aos ativos no repositório OCEImageGalleryRepository.
Clique em Salvar.

Em seguida, atribua categorias de taxonomia a cada um dos ativos de imagem no repositório OCEImageGalleryRepository:

Efetue log-in na interface Web do Oracle Content Management.
Clique em Ativos no menu de navegação à esquerda.
Abra o repositório OCEImageGalleryRepository.
Selecione um ou mais ativos de imagem, clique em Mais na barra de ações e escolha Categorias no menu.
No painel Categorias, clique em Adicionar Categoria. Procure o nome da categoria na barra de pesquisa ou selecione uma categoria na estrutura hierárquica da taxonomia e clique em Adicionar para atribuir a categoria selecionada. Você pode designar várias categorias a um ativo.
Depois de concluir a atribuição de taxonomias a todos os ativos de imagem, selecione todos os ativos no seu repositório e publique-os no canal OCEImageGalleryChannel.

Tarefa 2: Criar a Galeria de Imagens no Next.js

Para consumir o conteúdo do Oracle Content Management em um aplicativo Next.js, podemos usar a amostra da galeria de imagens Next.js, que está disponível como repositório de código-fonte aberto no GitHub.

Observação: Lembre-se de que o uso da amostra Next.js é opcional e que o usamos neste tutorial para começar rapidamente. Você também pode criar seu próprio aplicativo Next.js.

Para criar a galeria de imagens no Next.js:

Clonar o repositório de amostra e instalar dependências
Configurar o aplicativo Next.js
Trabalhar com o SDK do Oracle Content Management Content
Usar o Content SDK para Obter Conteúdo

Clonar o Repositório de Amostra e Instalar Dependências

A amostra de blog Next.js está disponível como repositório de código aberto no GitHub.

Primeiro você precisará clonar a amostra do GitHub no seu computador local e alterar seu diretório para a raiz do repositório:

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

Agora que você tem sua base de código, é necessário fazer download de dependências para o aplicativo. Execute o seguinte comando no diretório raiz:

npm install

Configurar o Aplicativo Next.js

Nesta amostra da galeria de imagens do Next.js, você precisa configurar algumas informações para que o Oracle Content Management Content SDK (e quaisquer outras solicitações) possa direcionar o URL de instância correto e a versão da API com o token de canal correto. Esses valores são usados em scripts/server-config-utils.js para instanciar um novo cliente de entrega.

Este aplicativo usa um arquivo .env.local que é lido pelo Next.js e disponibilizado para o código dentro do aplicativo com process.env.

Abra o arquivo .env.local em um editor de texto. Você verá as seguintes informações:

# 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=e0b6421e73454818948de7b1eaddb091

Altere cada par de chave/valor para refletir o URL da sua instância, a versão da API que você deseja direcionar e o token do canal associado ao seu canal de publicação. O canal deste tutorial é OCEImageGalleryChannel.

Trabalhar com o SDK do Oracle Content Management Content

O Oracle Content Management oferece um SDK para ajudar a descobrir e usar conteúdo em seus aplicativos. O SDK é publicado como um módulo NPM e o projeto é hospedado no GitHub.

Saiba mais sobre o SDK aqui.

O SDK foi registrado como uma dependência de runtime deste projeto no arquivo package.json.

Usar o Content SDK para Obter Conteúdo

Agora podemos aproveitar o Content SDK para extrair o conteúdo para que possamos renderizá-lo em nosso aplicativo Next.js.

A pasta de scripts contém o código para obter dados do Oracle Content Management usando o Content SDK.

O arquivo scripts/server-config-utils.js importa o Content SDK e cria um cliente de entrega usando a configuração especificada em .env.local.

O seguinte comando importa o SDK:

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

O seguinte comando cria o cliente de entrega:

return createDeliveryClient(serverconfig);

O arquivo scripts/services.js contém todo o código para obter dados do aplicativo. Há uma função principal para cada componente de página do aplicativo para obter todos os dados dessa página.

Para renderizar as imagens, o services.js fornece um método auxiliar para recuperar o conjunto de origens de um ativo que é construído a partir das renderizações do ativo.

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;
    }

Dados da página inicial

A home page requer várias chamadas de dados para obter todos os seus dados:

Primeiro carregamos as taxonomias para o canal especificado no .env.
Para cada uma das taxonomias, obtemos todas as categorias nessa taxonomia.
Para cada categoria, obtemos quatro itens de conteúdo nessa categoria.
Para cada um desses itens, obtemos seus URLs de renderização.

Abra src/scripts/services.js e localize a função getHomePageData(), que é usada para obter todos os dados da home page.

export function getHomePageData() {
      const deliveryClient = getClient();
      // get the categories for all taxonomies then add all the category items to each category
      return fetchAllTaxonomiesCategories(deliveryClient).then(
        (initialCategories) => addItemsToCategories(deliveryClient, initialCategories).then(
          (categories) => {
            // pull out all of the items for all of the categories then
            // append the computed renditionUrls to each item.
            const allItems = categories.map((category) => category.items);
            const items = flattenArray(allItems);
            // for each item, retrieve the rendition urls and add it to the item
            items.forEach((item) => {
              item.renditionUrls = getSourceSet(item);
            });
            return { categories };
          },
        ),
      );
    }

getHomePageData() chama fetchAllTaxonomiesCategories() para obter todas as categorias em todas as taxonomias.

export function fetchAllTaxonomiesCategories(client) {
      return client
        .getTaxonomies()
        .then((topLevelItem) => {
          const taxonomyIds = topLevelItem.items.map((taxonomy) => taxonomy.id);
    
          const promises = [];
          // loop over each taxonomy id
          taxonomyIds.forEach((taxonomyId) => {
            // add a promise to the total list of promises to get the categories
            // for the specific taxonomy id
            promises.push(
              fetchCategoriesForTaxonomyId(client, taxonomyId)
                .then((categoriesTopItem) => categoriesTopItem.items),
            );
          });
    
          // execute all the promises returning a single dimension array of all
          // of the categories for all of the taxonomies (note: no taxonomy information)
          // is returned.
          return Promise.all(promises)
            .then((arrayOfCategoryArray) => flattenArray(arrayOfCategoryArray));
        })
        .catch((error) => logError('Fetching taxonomies failed', error));
    }

fetchAllTaxonomiesCategories() chama fetchCategoriesForTaxonomyId() para obter todas as categorias em uma taxonomia específica.

function fetchCategoriesForTaxonomyId(client, taxonomyId) {
      return client
        .queryTaxonomyCategories({
          id: `${taxonomyId}`,
        })
        .then((topLevelItem) => topLevelItem)
        .catch((error) => logError('Fetching categories for taxonomy failed', error));
    }

A função addItemsToCategories é chamada para adicionar os quatro itens de categoria a cada categoria.

function addItemsToCategories(client, categories) {
      const promises = [];
    
      // loop over each category
      categories.forEach((category) => {
        // add a promise to the total list of promises to get the items
        // for the specific category
        promises.push(
          fetchItemsForCategory(client, category.id, true).then(
            (topLevelItem) => {
              // add the item to the category before returning it
              category.items = topLevelItem.items;
              category.totalResults = topLevelItem.totalResults;
              return {
                ...category,
              };
            },
          ),
        );
      });
    
      // execute all the promises before returning the data
      return Promise.all(promises).then((arrayOfItems) => flattenArray(arrayOfItems));
    }

Por fim, getSourceSet visto anteriormente é chamado para obter os URLs de renderização de cada item.

Dados da Página Grade da Imagem

A página de grade de imagens recebe um ID categoria e requer várias chamadas de dados para obter todos os seus dados:

Obtenha todos os itens para a categoria especificada.
Para cada item, obtenha seus URLs de renderização.

Abra src/scripts/services.js e localize a função getImageGridPageData(), que é usada para obter todos os dados da página de grade de imagens.

export function getImageGridPageData(categoryId) {
      const client = getClient();
    
      return fetchItemsForCategory(client, categoryId, false).then(
        (topLevelItem) => {
          const { totalResults } = topLevelItem;
          // for each item, retrieve the rendition urls and add it to the item
          topLevelItem.items.forEach((item) => {
            item.renditionUrls = getSourceSet(item);
          });
          return {
            totalResults,
            items: topLevelItem.items,
          };
        },
      );
    }

Ele chama fetchItemsForCategory, como a home page, mas sem limite, para que todos os itens sejam retornados, e não apenas quatro.

Agora que temos nossas consultas de dados, podemos renderizar as respostas em nossos componentes do Next.js.

Componentes do Next.js

O Next.js é baseado em React e React usa uma tecnologia conhecida como JSX, que é uma extensão de sintaxe semelhante a HTML para JavaScript, para renderizar conteúdo. Embora você possa escrever JavaScript puro para renderizar dados do Oracle Content Management, recomendamos que você use o JSX.

O aplicativo de galeria de imagens divide cada página em vários componentes menores, alguns dos quais são usados nas páginas de grade de casa e imagem.

As próximas seções fornecem uma visão geral de como o Next.js processa nosso aplicativo em cada um de nossos componentes:

Pasta Páginas
Componente do Índice
Componente da Galeria
Componente ImageGridPage

Pasta Páginas

Em nosso site, queremos fornecer duas rotas:

A página inicial, que mostra uma lista de categorias de imagem
A página da grade de imagens, que exibe todos os itens de um determinado id de categoria

Qualquer página no diretório de páginas Next.js será tratada como uma rota para o aplicativo.

Componente do Índice

A página inicial consiste em uma lista de categorias para uma taxonomia, com uma visualização de quatro itens nessa categoria. Ele é renderizado pelo componente Índice, localizado nas páginas/index.jsx.

O componente importa a API para obter dados do arquivo services.js.

import { getHomePageData } from '../scripts/services';

Em getStaticProps(), chamado durante o tempo de construção, o componente obtém todos os dados necessários para renderizar a home page.

export async function getStaticProps() {
      const data = await getHomePageData();
      return {
        props: { data },
      };
    }

Componente da Galeria

O componente Galeria representa a categoria individual na lista. Ela exibe uma visualização de quatro dos itens na categoria.

Ele está localizado em src/components/Gallery.jsx e recebe todos os seus dados como propriedades. Ele não obtém dados adicionais do servidor.

Componente ImageGridPage

O componente Página Grade de Imagem exibe os itens na categoria cujo ID é passado para o componente no URL. Ele é renderizado pelo componente ArticleListPage, localizado em pages/category/[id].jsx.

O componente importa a API para obter dados do arquivo services.js.

import { fetchAllTaxonomiesCategories, getImageGridPageData } from '../../scripts/services';

Os URLs da Página Grade de Imagem são URLs dinâmicos que contêm o id da categoria e o nome como um caminho, exemplos de caminhos de URL são

/category/categoryId1-name1
/category/categoryId2-name2
/category/categoryId3-name3

Quando o Next.js usa a geração de site estático para páginas com URLs dinâmicos, ele chama getStaticPaths() para obter todos os caminhos dessa página.

export async function getStaticPaths() {
      const categories = await fetchAllTaxonomiesCategories();
      return {
        paths: categories.map((category) => ({
          params: { id: `${category.id}-${category.name}` },
        })),
        fallback: true,
      };
    }

A função getStaticProps() é usada para obter os dados de uma única instância da página Grade de Imagem. O id e o nome da categoria são obtidos do parâmetro passado para o método. O id da categoria é usado para obter todos os dados necessários para esta página.

export async function getStaticProps(context) {
      const { params } = context;
    
      const { id } = params;
      const arr = id.split('-');
      const categoryName = arr[1];
      const categoryId = arr[0];
      const data = await getImageGridPageData(categoryId);
      return {
        props: {
          data,
          categoryName,
        },
      };
    }

Tarefa 3: Preparar Seu Aplicativo para Implantação

Agora que construímos nosso site de blog Next.js, precisamos vê-lo em um servidor de desenvolvimento local para que possamos depurar quaisquer problemas e visualizar o aplicativo antes de ele entrar em operação.

Prepare o aplicativo para implantação em duas etapas:

Criou um servidor de desenvolvimento local
Usar scripts para criar e executar o aplicativo em desenvolvimento e produção

Desenvolver um Servidor de Desenvolvimento Local

Você pode iniciar um servidor de desenvolvimento localmente executando o comando a seguir.

npm run dev

Em seguida, abra seu navegador para http://localhost:3000 para ver seu site em ação.

Observação: Isso não fará pré-render as páginas, para pré-render as páginas, consulte a próxima seção.

Use Scripts para Criar e Executar o Aplicativo em Desenvolvimento e Produção

Para produção, o script de construção seria usado para gerar estaticamente o site.

npm run build

O script inicial é usado para iniciar um servidor Node.js atendendo às páginas geradas estaticamente.

npm run start

Título e Informações de Copyright

Criar uma Galeria de Imagens no Next.js com o Oracle Content Management sem Interface do Usuário

F49331-01

Outubro de 2021

Autor Principal: Oracle Corporation