Tutorial - Aggiungere contenuto dinamico in una pagina Web statica generata con Cecil

Obiettivo

Questa guida ti mostra come utilizzare il generatore del sito Cecil per visualizzare il contenuto di una pagina dinamica. Il tutto chiamando un'API per recuperare e visualizzare le informazioni su una pagina generata via Cecil.

Questa guida ti mostra come aggiungere una chiamata verso un'API esterna dalla tua pagina Web statica.

Prerequisiti

• Disporre di una soluzione di hosting Web OVHcloud che include un accesso SSH Questo accesso permette di installare, da riga di comando, una o più soluzioni alternative a quelle proposte di default nelle nostre offerte di hosting Web.
• Aver familiarità con l'inserimento da riga di comando
• Aver installato e configurato l'applicazione Cecil sul tuo hosting (consulta la nostra guida sull'installazione e la configurazione di Cecil)

Procedura

L'esempio scelto è l'utilizzo di una delle API di un servizio che fornisce dati meteorologici. Questo in base a una città presa dall'utente.

Gli step sono i seguenti:

• creare una nuova pagina su Cecil e aggiungere questa pagina al menu del sito web
• creare un account e recuperare la chiave per effettuare richieste sull'API meteo
• modificare il file.md creato aggiungendo il codice HTML
• aggiungere assets (JavaScript e CSS)
• generare e testare la soluzione.

Crea una nuova pagina

Prepara il tuo ambiente di sviluppo accedendo in SSH sul tuo hosting Web e consulta la guida Installare e configurare Cecil per installare la tua applicazione Cecil in una directory dedicata.

Crea una directory e inserisci:

mkdir myWebSite
cd myWebSite

Utilizzo dell'API OpenWeather

In questa guida utilizzeremo un'API fornita dal sito OpenWeather. In questo modo è possibile conoscere le informazioni meteorologiche in base al nome di una città.

Crea un account su https://home.openweathermap.org/users/sign_up
Una volta confermato l'account (tramite email di conferma), accedi al menu "My API keys". Una chiave è stata generata di default, recuperala e conservala per il seguito di questa guida.

Aggiunta del codice HTML

Crea una nuova pagina con il seguente comando:

php cecil.phar new:page weather.md

Modifica la pagina generata:

nano pages/weather.md

Modifica l'intestazione del file per far apparire la pagina nel menu:

---
title: "Weather"
data: 2022-11-28
published: true
menu: mano
---

Dopo l'intestazione, aggiungi il codice HTML per visualizzare la città che hai scelto, le temperature reindirizzate dall'API e un pulsante per cambiare parametro:

---
title: "Weather"
date: 2022-11-28
published: true
menu: main
---
<h1>Weather</h1>
<div>
    <span id="city">Roubaix</span>
    <div id="temperature"><span id="temperatureValue"></span> °C</div>
    <div id="modify">Change city</div>
</div>

Genera la pagina HTML con il seguente comando:

php cecil.phar build

Verifica il risultato nel browser e clicca sul link "Weather" che è stato aggiunto nel menu principale:

Aggiungi il codice JavaScript

Non è possibile aggiungere un tag <script> in un file Markdown. Dovrai modificare il template fornito di default.

Modifica il template

I template sono disponibili nella directory layout. Per visualizzarli, esegui questo comando:

ls -la layout

Il file contiene una directory blog e un file index.html.twig:

Apri il file index.html.twig:

Il file si riferisce a un template che non è presente nella directory. Questo file (e altri) sono in realtà nel file cecil.phar. Le estensioni.phar designano archivi di file PHP che possono essere manipolati senza decomprimerli. Elimina i file di questo archivio per renderli visibili:

php cecil.phar util:extract

Mostra nuovamente il contenuto della directory layout:

Modifica il template di default per inserire un tag <script> che contenga il codice che permette la chiamata all'API:

nano layouts/_default/page.html.twig

Il tag e il suo contenuto devono essere posizionati prima del tag </body> in fondo alla pagina:

    </footer>
    {%- include 'partials/googleanalytics.js.twig' with {site} only ~%}
    {% block javascript %}
    <script src="{ asset( script.js', {minify: true})}"></script>
    {% endblock %}
  </body>
</html>

Quando uno o più file assets sono modificati, ricostruisci la cache con il seguente comando:

php cecil.phar cache:clear:assets

Se le modifiche non sono effettive sul tuo browser, svuota la cache del browser. Puoi anche eliminare i file generati sul tuo hosting Web:

php cecil.phar clear

Per ricostruire la tua soluzione utilizza questo comando:

php cecil.phar build

Aggiungi il file JavaScript

I file JavaScript, come i file CSS, devono essere inseriti nella directory assets. Puoi organizzarli in diverse directory.

Crea il file script.js menzionato in precedenza alla root della directory assets:

nano assets/script.js

Sostituisci il valore della variabile apiKey con la chiave recuperata precedentemente sul sito OpenWeather

let apiKey = '123456789'; // Sostituisci questo valore
let city = 'Roubaix'; // Indica qui la città di default che verrà visualizzata sulla pagina meteo
getTemperature(city);  // Chiamata della funzione che chiama l'API con il parametro 'city'

// Aggiunta di un evento sul click del pulsante "Change city"
let button = document.querySelector('#modify');
button.addEventListener('click', () => {
    city = prompt('Choose a city');
    getTemperature(city);
});

// Funzione di chiamata all'API utilizzando un oggetto XMLHttpRequest per una richiesta asincrona
function getTemperature(city) {
    let url = 'https://api.openweathermap.org/data/2.5/weather?q=' + city + '&appid=' + apiKey + '&units=metric';
    let xhrQuery = new XMLHttpRequest();
    xhrQuery.open('GET', url);
    xhrQuery.responseType = 'json';
    xhrQuery.send();

    xhrQuery.onload = function() {
        if (xhrQuery.readyState === XMLHttpRequest.DONE) {
            if (xhrQuery.status === 200) {
                let city = xhrQuery.response.name;
                let temperature = xhrQuery.response.main.temp;
                document.querySelector('#city').textContent = city;
                document.querySelector('#temperatureValue').textContent = temperature;
            } else {
                alert('A problem has occurred, please come try later.');
            }
        }
    };
}

Test

Consulta il tuo sito Web tramite browser:

Clicca su "Cambia città" e inserisci il nome di un comune:

Conclusione

Questa guida ti mostra un esempio di integrazione di dati dinamici recuperati da fonti esterne tramite API. Costruisci e fai vivere un sito web modificando manualmente il contenuto di queste pagine o creandone di nuove. Il tutto arricchendo il loro contenuto da altri siti web.

Per saperne di più

• Alcune API da testare sul tuo sito Web
  • API Numbers
  • NASA
  • News API
  • Polygon.io
  • una lista di API pubbliche
• I comandi Cecil.

Per prestazioni specializzate (referenziamento, sviluppo, ecc...), contatta i partner OVHcloud.

Per usufruire di un supporto per l'utilizzo e la configurazione delle soluzioni OVHcloud, consulta le nostre soluzioni di supporto.

Contatta la nostra Community di utenti.