Crea un sito minimale in Flutter con Oracle Content Management headless

Introduzione

Flutter è un framework open source di Google per sviluppare applicazioni belli, compilate in modo nativo e multipiattaforma da un singolo codebase. Il codice Flutter compila il codice ARM o Intel e JavaScript per prestazioni rapide su qualsiasi dispositivo. Flutter può essere uno strumento efficace per creare applicazioni che utilizzano contenuti di Oracle Content Management. Grazie al modello di contenuto appropriato, è possibile creare rapidamente un'interfaccia utente Flutter che costituisce un blog tipico.

In questa esercitazione viene descritta la procedura per creare un sito Web di dimensioni minime semplice in Flutter mediante l'utilizzo di Oracle Content Management come CMS headless. Questo esempio di Flutter è disponibile su GitHub.

Il tutorial prevede tre passi:

Prepara Oracle Content Management
Costruisci il sito minimo in Flutter
Prepara la tua applicazione per la distribuzione

Prerequisiti

Prima di procedere con questa esercitazione, si consiglia di leggere prima le seguenti informazioni:

Per seguire questa esercitazione, è necessario:

una sottoscrizione a Oracle Content Management
un account Oracle Content Management con il ruolo Amministratore contenuto;
un computer Windows o Mac con Node versione 10 o successiva

Quello che stiamo costruendo

Grazie a Flutter minim, è possibile recuperare facilmente immagini e altri contenuti dal repository di Oracle Content Management.

Per dare un'occhiata a cosa stiamo creando, ecco lo stato finale della nostra esercitazione: un sito Flutter minimo di base che consuma contenuti da Oracle Content Management.

Di seguito è riportato l'aspetto della schermata iniziale alla fine di questa esercitazione.

Questa immagine mostra una pagina di arrivo per un sito Flutter minimal.

Di seguito è riportato l'aspetto della schermata Contattateci.

Questa immagine mostra la pagina di contatto per un sito Flutter minimal.

Per continuare, è necessario disporre di una sottoscrizione attiva a Oracle Content Management ed eseguire il login con il ruolo Amministratore contenuto.

Task 1: Prepara Oracle Content Management

Se non si dispone già di un'istanza di Oracle Content Management, vedere Avvio rapido per informazioni su come effettuare la registrazione a Oracle Cloud, eseguire il provisioning di un'istanza di Oracle Content Management e configurare Oracle Content Management come CMS headless.

Per questa esercitazione, sarà necessario creare un modello di contenuto. È disponibile un asset pack scaricabile che riempirà il repository vuoto con i tipi di contenuto e il contenuto associato.

Per preparare Oracle Content Management:

Creare un canale e un repository di asset
Importa Asset Pack di esempio di Oracle Content Management

Creare un canale e un repository di asset

È innanzitutto necessario creare un canale e un repository di asset in Oracle Content Management in modo da poter pubblicare contenuti.

Per creare un canale e un repository di asset in Oracle Content Management, procedere come segue.

Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.
Scegliere Contenuto nel menu di navigazione a sinistra, quindi scegliere Pubblicazione dei canali dall'elenco di selezione nell'intestazione della pagina.
Nell'angolo in alto a destra fare clic su Crea per creare un nuovo canale. Assegnare un nome al canale 'OCEMinimalChannel' ai fini di questa esercitazione e mantenere l'accesso pubblico. Fare clic su Salva per creare il canale.
Scegliere Contenuto nel menu di navigazione a sinistra, quindi scegliere Repositori dall'elenco di selezione nell'intestazione della pagina.
Nell'angolo in alto a destra fare clic su Crea per creare un nuovo repository di asset. Assegnare un nome al repository asset 'OCEMinimalRepository' ai fini di questa esercitazione.
Nel campo Canali di pubblicazione selezionare il canale OCEMinimalChannel per indicare a Oracle Content Management che il contenuto del repository OCEMinimalRepository può essere pubblicato nel canale OCEMinimalChannel. Al termine, fare clic su Salva.

Importa Asset Pack di esempio di Oracle Content Management

È possibile scaricare un pacchetto di asset di esempio di Oracle Content Management preconfigurato contenente tutti i tipi di contenuto e gli asset necessari per questa esercitazione.

È possibile caricare una copia del contenuto utilizzato in questa esercitazione dal pacchetto di asset campione di Oracle Content Management. In questo modo sarà possibile sperimentare i tipi di contenuto e modificare il contenuto. Se si desidera importare il package di asset campione di Oracle Content Management, è possibile scaricare l'archivio del pacchetto di asset, OCESamplesAssetPack.zip e estrarlo in una directory di propria scelta:

Scaricare il package di asset (OCESamplesAssetPack.zip) di Oracle Content Management dalla pagina download di Oracle Content Management. Estrarre il file zip scaricato in una posizione del computer. Dopo l'estrazione, questa posizione includerà un file denominato OCEMinimal_data.zip.
Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.
Scegliere Contenuto nel menu di navigazione a sinistra, quindi scegliere Repositori dall'elenco di selezione nell'intestazione della pagina. Selezionare OCEMinimalRepository e fare clic sul pulsante Importa contenuto nella barra delle azioni superiore.
Caricare OCEMinimal_data.zip dal computer locale nella cartella dei documenti.
Una volta caricato, selezionare OCEMinimal_data.zip e fare clic su OK per importare il contenuto nel repository asset.
Dopo aver importato correttamente il contenuto, passare alla pagina Asset e aprire il repository OCEMinimalRepository. Tutte le immagini e gli elementi di contenuto correlati sono stati aggiunti al repository degli asset.
Fare clic su Seleziona tutto in alto a sinistra, quindi su Pubblica per aggiungere tutti gli asset importati al canale di pubblicazione creato in precedenza, OCEMinimalChannel.
Prima della pubblicazione, è necessario convalidare tutti gli asset. Aggiungere innanzitutto OCEMinimalChannel come canale selezionato, quindi fare clic sul pulsante Convalida.
Dopo la convalida degli asset, è possibile pubblicare tutti gli asset nel canale selezionato facendo clic sul pulsante Pubblica nell'angolo superiore destro.

Al termine, è possibile vedere nella pagina Asset che tutti gli asset sono stati pubblicati. È possibile visualizzare l'icona sopra il nome dell'asset.

Questa immagine mostra la pagina Asset, con tutti gli asset pubblicati.

Task 2: Creare il sito minimo in Flutter

Per utilizzare i contenuti di Oracle Content Management in un'applicazione Flutter, è possibile utilizzare l'esempio di sito Flutter minimo, che è disponibile come repository open source su GitHub.

Nota: l'utilizzo dell'esempio Flutter è facoltativo e viene utilizzato in questa esercitazione per iniziare rapidamente. Puoi anche creare la tua applicazione Flutter.

Costruire il sito minimo in Flutter è composto dai seguenti passaggi:

Installa Flutter
Duplica il repository di esempio e installa le dipendenze
Configurare l'applicazione Flutter
Utilizzare l'interfaccia API REST di Oracle Content Management per recuperare il contenuto

Installa Flutter

La prima cosa da fare per iniziare con Flutter è configurare l'ambiente. Le istruzioni per l'impostazione sono disponibili sul sito Web Fiutter. Utilizzare l'opzione corrispondente al sistema operativo in uso. Di seguito è riportato un riepilogo delle operazioni di installazione.

Scarica Flutter SDK.
Aggiornare la variabile di ambiente percorso.
Eseguire flutter doctor.
Segui i passaggi indicati sul sito web dedicato agli elementi di disturbo per installare un editor di tua scelta.
Aggiungere un plugin editor per Android Studio, IntelliJ, VS Code o Emacs. Le istruzioni specificano come installare i plugin Flutter e Dart nell'editor.
Modificare i valori nel file android.properties per fare riferimento alle posizioni appropriate, alle versioni sdk e kotlin. Potrebbe essere inoltre necessario modificare i valori nel file android.gradle per le versioni appropriate.

Duplica il repository di esempio e installa le dipendenze

L'esempio di sito Flutter minimo è disponibile come repository open source su GitHub.

Occorre prima copiare l'esempio da GitHub al computer locale e modificare la directory nella radice del repository:

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

Aprire il progetto da Android Studio o qualsiasi altro editor a scelta. Per ottenere tutti i pacchetti utilizzati nel progetto, fare clic sul pulsante Recupera pacchetti.

Configurazione dell'applicazione Flutter

In questo esempio di Flutter minimo, è necessario configurare alcune informazioni in modo che le richieste API REST possano indirizzare l'URL dell'istanza e la versione API corrette con il token di canale corretto. Questi valori definiti in lib/config/oce.dart vengono utilizzati dalle funzioni definite in lib/networking/content.dart per stabilire l'endpoint per l'API REST.

In lib/config/oce.dart saranno visualizzate le seguenti informazioni:

const Map<String, String> config = <String, String>{
  'serverUrl': 'https://samples.mycontentdemo.com',
  'apiVersion': 'v1.1',
  'channelToken': 'ba0efff9c021422cb134c2fd5daf6015'
};

Modifica ogni coppia chiave-valore per riflettere l'URL dell'istanza, la versione dell'API alla quale desideri assegnare la destinazione e il token del canale associato al canale di pubblicazione. Il canale di questa esercitazione è OCEMinimalChannel.

È inoltre necessario configurare le immagini da utilizzare in tutta l'applicazione. Nello stesso file vedrai quanto segue:

const Map<String, String> appConfig = <String, String>{
  'homePage': 'Banner1.jpg',
  'contactUs' : 'Banner2.jpg',
  'logo' : 'Logo.png',
  'footerLogo' : 'Powered_by_OCE.png',
};

Modificare il nome di ogni immagine in modo che rifletta i valori dell'istanza.

Utilizza l'interfaccia API REST di Oracle Content Management per recuperare i contenuti

L'API REST per la consegna dei contenuti consente di accedere agli asset pubblicati in Oracle Content Management. Gli asset pubblicati includono gli elementi di contenuto e gli asset digitali, nonché le relative rendition. Ora possiamo utilizzare l'API REST di Oracle Content Management per recuperare i contenuti in modo da renderli disponibili nella nostra applicazione Flutter minima.

Il file lib/networking/content.dart dispone di metodi per la connessione al server specificato nel file oce.dart utilizzando l'API REST e restituendo la risposta da esso.

  //Utility method to build up the URL for published content.
  String _getPublishedContentServerURL() {
    final String? serverUrl = data['serverUrl'] as String?;
    final String? apiVersion = data['apiVersion'] as String?;
    return '$serverUrl/content/published/api/$apiVersion/';
  }

  // Adds the channel token to the URL
  String _addChannelToURL(String currUrl) {
    final String? channelToken = data['channelToken'] as String?;
    return '$currUrl?channelToken=$channelToken';
  }

  //Make an http get call and return the response if successful
  Future<dynamic> _get(String url) async {
    dynamic responseJson;
    try {
      final Response response = await get(Uri.parse(url));
      responseJson = _returnResponse(response);
    } on SocketException {
      throw FetchDataException(kConnectionError);
    }
    return responseJson;
  }

  //Return the json decoded response body if response status is successful
  dynamic _returnResponse(Response response) {
    switch (response.statusCode) {
      case 200:
        final Map<String, dynamic>? responseJson =
            json.decode(response.body.toString()) as Map<String, dynamic>?;
        return responseJson;
      case 400:
        throw BadRequestException(response.body.toString());
      case 401:
      case 403:
        throw UnauthorizedException(response.body.toString());
      case 500:
      default:
        throw FetchDataException('StatusCode : ${response.statusCode}');
    }
  }

Per il rendering delle immagini, content.dart fornisce anche metodi di supporto per recuperare le varie rendition per un asset.

  String getMediumRenditionUrl(Map<String, String> args) {
    final String itemId = args['id'];
    if (itemId == null) return null;
    String url = _getPublishedContentServerURL();
    url = '${url}assets/$itemId/Medium';
    // add the channel token to the URL
    url = _addChannelToURL(url);
    url = '$url&format=jpg&&type=responsiveimage';
    return url;
  }

  String getRenditionURL(Map<String, String> args) {
    final String itemId = args['id'];
    if (itemId == null) return null;
    String url = _getPublishedContentServerURL();
    url = '${url}assets/$itemId/native';
    // add the channel token to the URL
    url = _addChannelToURL(url);
    return url;
  }

Il file lib/networking/services.dart contiene tutto il codice per ottenere i dati per l'applicazione.

Recupero dei dati dell'immagine

Apri lib/networking/services.dart e trova la funzione qui sotto, che aiuta a ottenere tutte le immagini per questa applicazione.

  // Get all the images needed for the app
  Future<AppImages> getAppImages() async {
    final Content content = Content();
    final String homepageImage = appConfig['homePage'];
    final String contactUsImage = appConfig['contactUs'];
    final String logoImage = appConfig['logo'];
    final String footerImage = appConfig['footerLogo'];
    AppImages images;
    try {
      final dynamic data = await content.queryItems(<String, String>{
        'q':
            '(name eq "$homepageImage" OR name eq "$contactUsImage" OR name eq "$logoImage" OR name eq "$footerImage")',
        'fields': 'all',
        'expand': 'all',
      });
      final List<dynamic> items = data['items'] as List<dynamic>;
      String homePageImageGUID,
          contactUsImageGUID,
          headerLogoGUID,
          footerLogoGUID;
      for (int i = 0; i < items.length; i++) {
        final String name = items[i]['name'] as String;
        final String id = items[i]['id'] as String;
        if (name == homepageImage) {
          homePageImageGUID = id;
        } else if (name == contactUsImage) {
          contactUsImageGUID = id;
        } else if (name == logoImage) {
          headerLogoGUID = id;
        } else if (name == footerImage) {
          footerLogoGUID = id;
        }
      }
      //If any of the image ids are null, let the user know but continue loading the app
      if (homePageImageGUID == null ||
          contactUsImageGUID == null ||
          headerLogoGUID == null ||
          footerLogoGUID == null) {
        print(kFileNameError);
      }
      images = AppImages(
        headerLogoUrl: content.getRenditionURL(<String, String>{'id': headerLogoGUID}),
        footerLogoUrl: content.getRenditionURL(<String, String>{'id': footerLogoGUID}),
        contactUsImageUrl:
            content.getMediumRenditionUrl(<String, String>{'id': contactUsImageGUID}),
        homePageImageUrl: content.getMediumRenditionUrl(<String, String>{'id': homePageImageGUID}),
      );
    } catch (exception) {
      rethrow;
    }
    return images;
  }
;

Ora che abbiamo le nostre query sui dati, possiamo rendere le risposte nei nostri componenti per gli elementi superflui.

Componenti Flutter

L'applicazione minima suddivide ogni pagina in una serie di componenti più piccoli.

Le prossime sezioni forniscono una panoramica del modo in cui Flutter rende la nostra applicazione in ognuno dei nostri componenti:

Componente LoadingScreen
Componente HomePage
Componente ContactUs

Componente LoadingScreen

LoadingScreen è un widget con conservazione dello stato visualizzato dal componente LoadingScreen, disponibile in lib/screens/loading_screen.dart.

Il file lib/screens/loading_screen.dart contiene tutto il codice per ottenere i dati per la schermata e chiama le funzioni definite in services.dart.

  Future<void> getData() async {
    final Services services = Services();
    try {
      final AppImages images = await services.getAppImages();
      if (images != null) {
        Navigator.push<dynamic>(context,
            MaterialPageRoute<dynamic>(builder: (BuildContext context) {
          return HomePage(appImages: images);
        }));
      }
    } catch (exception) {
      setState(() {
        this.exception = exception.toString();
      });
      print(exception.toString());
    }
  }

Il componente utilizza il metodo getData per ottenere i dati utilizzando il metodo definito nel file services.dart.

Componente HomePage

La schermata iniziale viene visualizzata dal componente HomePage, disponibile in lib/screens/home_page.dart.

Il componente HomePage viene avviato dal componente LoadingScreen che gli trasmette i dati. Non riceve dati aggiuntivi dal server.

Utilizza anche il componente ScreenLayout definito nel file lib/components/screen_layout.dart, nonché il componente ImageStack definito nel file lib/components/image_stack.dart.

Componente ContactUs

La schermata Per ulteriori informazioni viene visualizzata dal componente ContactUs, disponibile in lib/screens/contact_us.dart.

Il componente ContactUs viene avviato dal componente NavDrawer, definito nel file lib/components/navdrawer.dart, che gli trasmette i dati. Non riceve dati aggiuntivi dal server. Utilizza anche il componente ImageStack definito nel file lib/components/image_stack.dart.

Task 3: Preparazione dell'applicazione per la distribuzione

Ora che abbiamo costruito il nostro sito Flutter minimal, abbiamo bisogno di distribuirlo su un emulatore o dispositivo in modo da poter eseguire il debug di eventuali problemi e visualizzare in anteprima l'applicazione prima che diventi attiva.

Segui le istruzioni sul sito Web di Flutter per fare in modo che l'editor esegua l'applicazione.

Se si utilizza Android Studio come editor, individuare la barra degli strumenti principale di Android Studio.
Nel selettore di destinazione, selezionare un dispositivo Android per l'esecuzione dell'applicazione. Se nessuno è elencato come disponibile, selezionare Strumenti > Android > AVD Manager e crearne uno lì. Per dettagli, vedere Gestione degli AVD.
Fare clic sull'icona Esegui nella barra degli strumenti oppure richiamare la voce di menu Esegui > Esegui.

Conclusione

In questa esercitazione abbiamo creato un sito di dimensioni ridotte in Flutter, disponibile su GitHub. Questo sito utilizza Oracle Content Management come headless CMS. Dopo aver impostato e configurato Oracle Content Management con un canale di contenuto pubblicato per l'esercitazione minima del sito, è stato installato e eseguito il sito Flutter per recuperare il contenuto richiesto e creare il sito.

Per maggiori informazioni su Flutter, visitare il sito Web Flutter.

Per approfondimenti sui concetti importanti di Oracle Content Management nella documentazione.

Per ulteriori esempi, vedere la pagina Esempi di Oracle Content Management in Oracle Help Center.

Titolo e informazioni sul copyright

Crea un sito minimale in Flutter con Oracle Content Management headless

F55457-01

Marzo 2022

Autore principale: Oracle Corporation