DEV Community: Luca Minuti

Cosa sono gli embeddings?

Luca Minuti — Mon, 23 Feb 2026 07:29:08 +0000

Note: Questo articolo è parte del corso AI con Delphi tenuto a febbraio da Wintech Italia. Per conoscere le prossime date, consultate il sito oppure contattate direttamente Wintech Italia.

Nell'ambito dell'intelligenza artificiale si sente spesso parlare del concetto di embedding, sia per il funzionamento dei modelli di linguaggio generativi (LLM) sia per alcune loro applicazioni, per esempio i RAG (Retrieval Augmented Generation). Ma cosa sono gli embeddings? In termini molto semplici potremmo dire che un embedding è un vettore (una sequenza di numeri) che cattura il senso di una parola o di una frase. Questo, nel campo dei modelli di linguaggio, è fondamentale, infatti è necessario trovare un modo per rappresentare le parole tramite dei numeri per poter usare le reti neurali alla base di questi sistemi. Il primo approccio che potrebbe venire in mente è creare una associazione che segua l'ordine alfabetico:

#	Parola
1	Abaco
2	Abate
3	Abbagliare
4	Abbaiare
5	Abate
?	.....
15000	Zolfo

Il problema è che le reti neurali eseguono dei calcoli e in un esempio come il precedente anche una banale somma non avrebbe senso: aumentare di poco un valore non porterebbe a una parola dal significato più vicino rispetto ad una somma con un valore più grande. Per esempio se "Abaco" è 1 e "Abate" è 2, il fatto che siano numericamente vicini non indica nulla del loro significato.

Cosa servirebbe

A questo punto quello che ci serve è un modo per classificare le parole in base a dei criteri. Per fare un esempio potremmo usare come criteri peso e altezza.

Dal grafico è evidente che le distanze tra le parole hanno un significato concreto. Il problema è che con vettori che rappresentano peso e altezza possiamo esprimere dei concetti molto limitati. Quindi quali criteri usare?

Come vengono calcolati

Una delle tecniche usate per calcolare questi vettori che catturano il senso delle parole è Word2Vec. Word2Vec si basa sul concetto che parole simili si usano in frasi simili. In pratica con questo approccio si addestra una rete neurale a trovare la parola mancante in frasi da cui è stata tolta una parola (in gergo Filling the blank).

Frase	Parola mancante
L'acqua del mare è _______	salata
Il _______ abbaia al postino	cane
In inverno cade la _______ dal cielo	neve
Ho bevuto un bicchiere di _______ a cena	vino
Ho bevuto un bicchiere di _______ a cena	birra

Come si vede dall'esempio nell'ultima frase ci sono più parole che possono andare bene e quello che ci aspettiamo è che i calcoli (e di conseguenza i pesi) della rete per quelle due parole dovranno essere simili.

Usando Word2Vec si crea una rete che nello strato di input e di output ha un numero di neuroni pari alle parole del vocabolario, il primo neurone sarà associato alla prima parola, il secondo alla seconda, e così via. Durante l'allenamento si passano le frasi ponendo a 1 i neuroni associati alle parole presenti nella frase e ci aspettiamo che nello strato di output venga posto a 1 il neurone associato alla parola da cercare.

Una volta che la rete è stata addestrata non ci interessa tanto la rete in sé, ma i pesi associati a ciascun neurone dello strato di input (quindi alle parole del vocabolario). Questi pesi sono gli embeddings.

Ma mentre nell'esempio precedente i valori rappresentavano peso e altezza, i valori che abbiamo trovato cosa rappresentano? In realtà nessuno lo sa in maniera chiara. Quello che conta però è che se proviamo a metterli in un grafico vediamo che effettivamente parole simili hanno dei vettori che si trovano vicini.

Conclusione

Gli embeddings sono quindi una rappresentazione numerica del significato delle parole, ottenuta addestrando una rete neurale su grandi quantità di testo. Anche se non sappiamo esattamente cosa rappresenti ciascun valore, il risultato è che parole con significati simili si trovano vicine nello spazio vettoriale, permettendo ai modelli di linguaggio di "comprendere" le relazioni tra i concetti e di lavorare efficacemente con il linguaggio naturale.

MCPConnect (EN)

Luca Minuti — Mon, 12 Jan 2026 08:32:23 +0000

Note: This is an automated translation from the original Italian article.

Delphi MCP Connect (MCPConnect) is a lightweight yet robust framework designed to dramatically simplify the creation of Model Context Protocol (MCP) Servers using Embarcadero Delphi. By leveraging attributes, the framework allows you to reuse existing logic and standard Delphi classes, transforming them into protocol-aware server components. MCPConnect handles the serialization, routing, and context management required for the server-side implementation of the MCP protocol.

Introduction to MCP

The Model Context Protocol is a framework developed by Anthropic in 2024. Its purpose is to standardize how large language models (LLMs) communicate and interact with external sources. This is necessary because LLM capabilities are often limited by their ability to produce text (tokens) without being able to act on the external world or generate responses based on anything beyond their training data.

Actually, back in 2023, OpenAI had already attempted to expand the capabilities of their LLMs with a similar approach through a technology called "function-calling". The problem was that this technology, copied by most other vendors, was tied to individual product APIs. This meant anyone wanting to use it was forced to write multiple integrations.

Some typical MCP use cases include:

Local database access - Directly query PostgreSQL, MySQL, or SQLite databases for data analysis and complex queries
Filesystem integration - Gain the ability to read, search, and analyze files in your local system for development support or project analysis
Browser automation - Control a browser for web scraping, automated testing, or interaction with web applications
Third-party APIs - Integrate external services like Slack, GitHub, Linear, or Jira to manage tasks and communications
Custom enterprise tools - Expose internal organizational APIs and tools to allow the LLM to interact with proprietary systems
Complex data manipulation - Process Excel, CSV, or other structured formats with custom logic not available in standard tools

The Architecture

To achieve these capabilities, the MCP architecture is divided into three blocks:

MCP Host: The AI application that will use MCP, for example Claude Desktop
MCP Client: The component that connects to the MCP server and sends the new context (data retrieved from the server) to the host
MCP Server: The program that provides the context. It essentially responds to calls by providing the information requested by the host through the client

The Server

The server is the heart of the MCP protocol, the part that actually performs the necessary tasks. It can execute multiple functions: access filesystem documents, execute database queries, send messages via email or messaging systems, sync with a calendar, etc.

To perform these tasks, the protocol defines three types of building blocks:

Tools: functions that the LLM can decide to call. Tools can interact with a database, call external APIs, modify files, or execute any type of logic.
Resources: read-only datasets that can be requested by the LLM to insert information into the context. They can be documents, files, or any other type of structured data. (currently not supported by MCPConnect)
Prompts: templates that can be invoked by the user (usually by writing the template name preceded by a slash) to generate a specific prompt for a particular operation. (currently not supported by MCPConnect)

Assuming you have a TDocumentService class that implements some tools, you can configure the MCPConnect server like this:

uses
  MCPConnect.JRPC.Server, 
  MCPConnect.MCP.Server.Api, // This register the standard MCP API
  MCPConnect.Configuration.MCP,

  Demo.DocumentService; // Unit with your MCP classes

// Create the JSON-RPC Server
FJRPCServer := TJRPCServer.Create(Self);
FJRPCServer
  .Plugin.Configure<IMCPConfig>
    .SetServerName('delphi-mcp-server')
    .SetServerVersion('2.0.0')
    .RegisterToolClass(TDocumentService)  // Register your tool class here
    .ApplyConfig;

Transport

The MCP protocol uses JSON-RPC to encode messages passing between client and server, while for the actual transport it supports two types of channels:

Stdio: standard input and output similar to old CGI: essentially the application will be console-based with requests arriving entirely on standard input and responses sent to standard output.
Streamable HTTP: HTTP communication with the ability to keep the channel open to allow the server to directly send notifications to the client without polling.

MCP Connect supports both operating modes, and the choice depends on the project type and also the development phase. For example, debugging is generally much simpler in an HTTP application compared to one using stdio. The same application could also work in both modes depending on configuration or a startup parameter.

Aspect	stdio	Streamable HTTP
Scope	Local	Local + remote
Complexity	⭐ Low	⭐⭐⭐ High
Scalability	❌ No	✅ Yes
Security	Implicit	Must configure
Streaming	Limited	Advanced
Debug	Complex	Simple
Typical use	Dev / local tools	Production / cloud

Continuing with the previous example, with MCPConnect you can set HTTP as the transport mechanism by specifying the technology (Indy or WebBroker) to use. For example, if you want to use WebBroker, the configuration is as follows:

uses
  MCPConnect.JRPC.Server, 
  MCPConnect.MCP.Server.Api, // This register the standard MCP API
  MCPConnect.Transport.WebBroker, 
  MCPConnect.Configuration.MCP,

  Demo.DocumentService; // Unit with your MCP classes

// Create the JSON-RPC Server
FJRPCServer := TJRPCServer.Create(Self);
FJRPCServer
  .Plugin.Configure<IMCPConfig>
    ....

// Create and configure the Dispatcher
FJRPCDispatcher := TJRPCDispatcher.Create(Self); // Self should be the TWebModule
FJRPCDispatcher.PathInfo := '/mcp';  // Set the endpoint path
FJRPCDispatcher.Server := FJRPCServer;  // Connect to the server

With the previous code, FJRPCDispatcher will handle all incoming calls to the /mcp path through the previously configured JRPC server.

Tools with MCP Connect

The most interesting aspect of MCPConnect is that it allows you to write MCP servers without worrying about the protocol architecture details. For example, suppose you want to provide information to the LLM based on a category. In Delphi, you could write a class like this:

  TDocumentService = class
  public
    function ListDocument(const ACategory: string): string;
  end;

Since the information will end up in an LLM's context, even though MCPConnect also handles more complex return values (e.g., TArray<TDocument>, TStringList, TImage, etc.), returning a string is often more than sufficient.

Returning to our example, it doesn't matter how the ListDocument method returns the data - MCPConnect will describe it to the LLM so it can decide how and when to call it.

To do this, however, you need to "explain" to the LLM what the class is for and in particular what the method in question does. With MCPConnect, this is done primarily through attributes. This way, the class declaration will be enriched as follows:

  TDocumentService = class
  public
    // This method is published as an MCP tool
    [McpTool('doclist', 'List all the available documents')]
    function ListDocument(
      [McpParam('category', 'Document Category')] const ACategory: string
    ): string;

    // This method is NOT exposed because it lacks the [McpTool] attribute
    procedure InternalStuff;
  end;

The McpTool and McpParam attributes take two parameters: the method name and the description. The description is essential - it's precisely based on this that the LLM understands what the element is for, whether to use it, and how to use it. Therefore, it's crucial to be as clear as possible in formulating the text.

Tool Results

In the example we've seen, the tool returns a string, which can often be sufficient, but obviously depends on the tool's purpose. We can divide tools into two broad groups:

Operational: whose main purpose is to perform a concrete action. They can write files, modify database state, send emails, etc. In this case, the output could even be simply an indication of the operation's outcome, for example a boolean, or a string indicating the problem detected in case of error.
Informational: in this case, the tool searches for data and injects it into the context. Depending on the nature of the data, it might be sufficient to return it as a string or in a structured format.

MCP Connect handles this transparently, so if the function returns a complex object, it will automatically convert it to the appropriate format.

However, there's a particular case worth mentioning, which is the TContentList class. This class maps fairly low-level to the output expected by MCP. In this case, the response can be composed of various sections, each of different type (text, image, audio, link, blob). MCPConnect allows you to simplify the use of this class through TToolResultBuilder as you can see in the following example:

function TDelphiDayTool.BuyTicket(AId, AQuantity: Integer): TContentList;
begin
  var LTicketStream := FCart.BuyTicket(AId, AQuantity);
  FGC.Add(LTicketStream); // Add the stream to the garbage collector

  var LResultBuilder := TToolResultBuilder.CreateInstance;

  LResultBuilder.AddText('Purchase completed successfully.');
  LResultBuilder.AddImage('image/png', LTicketStream);

  Result := LResultBuilder.Build;
end;

Session Management

An essential feature of MCP is session management, which is implicit with stdio transport and explicit when using Streamable HTTP. MCP Connect handles all this transparently, and in any tool you'll be able to retrieve data from the current session. Depending on the configuration, the session can be an instance of the TSessionData object (which actually saves information in JSON) or any object derived from TSessionBase.

The following code shows how to configure an application to use a custom session (TShoppingSession) to save the necessary information during the order creation process.

uses
  ...
  MCPConnect.Configuration.Session;

begin
  ...
  FJRPCServer
    .Plugin.Configure<ISessionConfig>
      .SetLocation(TSessionIdLocation.Header) // default
      .SetHeaderName('Mcp-Session-Id') // default
      .SetTimeout(30)  // 30 minutes timeout (default)
      .SetSessionClass(TShoppingSession)  // Use custom typed session
      .ApplyConfig

Conclusion

MCP Connect is a young but already quite extensive library. In this article, I've quickly covered some of the main topics without going into too much detail. More comprehensive documentation can be found on the GitHub page. Additionally, the demos included in the sources present numerous cases from which you can learn some techniques for creating simple MCP servers.

Other features of MCP Connect that I haven't discussed but plan to write about soon include:

Context injection
Fluent-configuration
Garbage collection
Tools namespacing
JSON-RPC only server (no MCP)
VCL/Firemonkey support

MCP Connect

Luca Minuti — Mon, 12 Jan 2026 08:17:08 +0000

Read this article in English

Delphi MCP Connect (MCPConnect) è un framework leggero e robusto progettato per semplificare drasticamente la creazione di Server Model Context Protocol (MCP) utilizzando Embarcadero Delphi. Sfruttando gli attributi, il framework consente di riutilizzare la logica esistente e le classi Delphi standard, trasformandole in componenti server consapevoli del protocollo. MCPConnect gestisce la serializzazione, il routing e la gestione del contesto richiesti per l'implementazione lato server del protocollo MCP.

Introduzione a MCP

Il Model Context Protocol è un framework sviluppato da Anthropic nel 2024. Il suo scopo è standardizzare il modo in cui i modelli linguistici di grandi dimensioni (LLM) comunicano e interagiscono con le fonti esterne. Questo perché in molti casi le possibilità degli LLM sono vincolate dal fatto di poter produrre del testo (token) senza però poter agire in qualche modo sul mondo esterno o produrre risposte basate su qualcosa che non provenga dai loro dati di addestramento.

In realtà nel 2023 OpenAI aveva già provato ad espandere le possibilità dei propri LLM con un approccio simile, tramite una tecnologia denominata "function-calling". Il problema è che questa tecnologia, copiata dalla maggior parte degli altri produttori era legata alle API dei singoli prodotti. Per questo chi avesse voluto usarla era obbligato a scrivere diverse integrazioni.

Alcuni casi d'uso tipici di MCP possono essere:

Accesso a database locali - Permettere di interrogare direttamente database PostgreSQL, MySQL o SQLite per analisi dati e query complesse
Integrazione con filesystem - Ottenere la capacità di leggere, cercare e analizzare file nel tuo sistema locale per supporto allo sviluppo o analisi di progetti
Automazione browser - Controllare un browser per web scraping, testing automatizzato o interazione con applicazioni web
API di terze parti - Integrare servizi esterni come Slack, GitHub, Linear o Jira per gestire task e comunicazioni
Tool personalizzati aziendali - Esporre API e strumenti interni all'organizzazione per permettere all'LLM di interagire con sistemi proprietari
Manipolazione dati complessi - Processare file Excel, CSV o altri formati strutturati con logica personalizzata non disponibile nei tool standard

L'architettura

Per ottenere queste possibilità l'architettura di MCP è divisa in tre blocchi:

MCP Host: L'applicazione AI che userà MCP, per esempio Claude Desktop
MCP Client: Il componente che si connette con il server MCP e invia all'host il nuovo contesto (dati ricavati dal server)
MCP Server: Il programma che fornisce il contesto. In pratica risponde alle chiamate fornendo le informazioni richieste dall'host tramite il client

Il Server

Il server è il cuore del protocollo MCP, la parte che concretamente esegue i compiti necessari. Le funzioni che può eseguire sono molteplici: accedere ai documenti del file system, eseguire delle query su un database, inviare messaggi tramite mail o sistemi di messaggistica, sincronizzarsi con un calendario, ecc.

Per eseguire questi compiti il protocollo prevede tre tipi di blocchi:

Tools: funzioni che l'LLM può decidere di chiamare. I tool possono interagire con un database, chiamare API esterne, modificare file o eseguire un qualsiasi tipo di logica.
Risorse: sono dei dataset read-only che possono essere richiesti dal LLM per inserire informazioni nel contesto. Possono essere documenti, file o qualsiasi altro tipo di dato strutturato. (attualmente non supportato da MCPConnect)
Prompts: sono dei template che possono essere richiamati dall'utente (di solito scrivendo il nome del template preceduto da uno slash) per generare un prompt specifico per una particolare operazione. (attualmente non supportato da MCPConnect)

Supponendo di avere una classe TDocumentService che implementa alcuni tool è possibile configurare il server di MCPConnect in questo modo:

uses
  MCPConnect.JRPC.Server, 
  MCPConnect.MCP.Server.Api, // This register the standard MCP API
  MCPConnect.Configuration.MCP,

  Demo.DocumentService; // Unit with your MCP classes

// Create the JSON-RPC Server
FJRPCServer := TJRPCServer.Create(Self);
FJRPCServer
  .Plugin.Configure<IMCPConfig>
    .SetServerName('delphi-mcp-server')
    .SetServerVersion('2.0.0')
    .RegisterToolClass(TDocumentService)  // Register your tool class here
    .ApplyConfig;

Il trasporto

Il protocollo MCP usa JSON-RPC per codificare i messaggi che passano tra il client e il server mentre per quanto riguarda il trasporto vero e proprio supporta due tipo di canali:

Stdio: lo standard input e output in maniera analoga ai vecchi CGI: in pratica l'applicazione sarà di tipo consolle con le richieste che arrivano interamente sullo standard input e le risposte inviate sulla standard output.
Streamable HTTP: una comunicazione HTTP con la possibilità di mantenere aperto il canale per permettere al server di inviare direttamente notifiche al client senza bisogno di fare polling.

MCP Connect supporta entrambe le modalità di funzionamento e la scelta dipende dal tipo di progetto e anche dalla fase di sviluppo. Per esempio in genere il debug è molto più semplice in una applicazione HTTP rispetto ad una che fa uso di stdio. La stessa applicazione potrebbe anche funzionare in entrambe le modalità a seconda della configurazione o un parametro passato all'avvio.

Aspetto	stdio	Streamable HTTP
Ambito	Locale	Locale + remoto
Complessità	⭐ Bassa	⭐⭐⭐ Alta
Scalabilità	❌ No	✅ Sì
Sicurezza	Implicita	Da configurare
Streaming	Limitato	Avanzato
Debug	Complesso	Semplice
Uso tipico	Dev / tool locali	Produzione / cloud

Riprendendo l'esempio precedente con MCPConnect è possibile impostare HTTP come meccanismo di trasporto specificando la tecnologia (Indy o WebBroker) da usare. Per esempio volendo usare WebBroker la configurazione è la seguente:

uses
  MCPConnect.JRPC.Server, 
  MCPConnect.MCP.Server.Api, // This register the standard MCP API
  MCPConnect.Transport.WebBroker, 
  MCPConnect.Configuration.MCP,

  Demo.DocumentService; // Unit with your MCP classes

// Create the JSON-RPC Server
FJRPCServer := TJRPCServer.Create(Self);
FJRPCServer
  .Plugin.Configure<IMCPConfig>
    ....

// Create and configure the Dispatcher
FJRPCDispatcher := TJRPCDispatcher.Create(Self); // Self should be the TWebModule
FJRPCDispatcher.PathInfo := '/mcp';  // Set the endpoint path
FJRPCDispatcher.Server := FJRPCServer;  // Connect to the server

Con il codice precedente FJRPCDispatcher si farà carico di rispondere a tutte le chiamate in arrivo al path /mcp tramite il server JRPC configurato in precedenza.

Tools con MCP Connect

L'aspetto più interessante di MCPConnect è il fatto che permette di scrivere dei server MCP senza doversi preoccupare dei dettagli dell'architettura del protocollo. Supponiamo per esempio di voler fornire all'LLM delle informazioni in base a una categoria. In Delphi potremmo scrivere una classe di questo genere:

  TDocumentService = class
  public
    function ListDocument(const ACategory: string): string;
  end;

Le informazioni finiranno nel contesto di un LLM quindi, anche se MCPConnect gestisce anche dei valori di ritorno più complessi (es. TArray<TDocument>, TStringList, TImage, ecc.), molto spesso restituire una stringa è più che sufficiente.

Ritornando al nostro esempio non è importante come il metodo ListDocument restituisca i dati MCPConnect si occuperà di descriverlo all'LLM perché possa decidere come e quando chiamarlo.

Per poterlo fare però è necessario "spiegare" all'LLM a cosa serve la classe e in particolare il metodo in questione. Questo con MCPConnect avviene principalmente attraverso degli attributi. In questo modo la dichiarazione della classe verrà arricchita come segue:

  TDocumentService = class
  public
    // This method is published as an MCP tool
    [McpTool('doclist', 'List all the available documents')]
    function ListDocument(
      [McpParam('category', 'Document Category')] const ACategory: string
    ): string;

    // This method is NOT exposed because it lacks the [McpTool] attribute
    procedure InternalStuff;
  end;

Gli attributi McpTool e McpParam prevedono due parametri: il nome del metodo e la descrizione. La descrizione è essenziale, infatti è proprio in base a questa che LLM capisce a cosa serve l'elemento in questione, se deve usarlo e come usarlo. Quindi è fondamentale essere il più possibile chiari nella formulazione del testo.

Il risultato dei tool

Nell'esempio che abbiamo visto il tool restituisce una stringa, molto spesso questo può essere sufficiente, ma ovviamente dipende dallo scopo del tool. Possiamo dividere i tool in due macro gruppi:

Operativi: il cui scopo principale è compiere un'azione concreta. Possono scrivere dei file, modificare lo stato di un database, inviare una mail, ecc. In questo caso l'output potrebbe anche essere semplicemente un indicazione dell'esito dell'operazione, ad esempio un booleano, oppure una stringa che indichi il problema rilevato in caso di errore.
Informativi: in questo caso il tool si occupa di cercare dei dati e di iniettarli nel contesto. A seconda della natura del dato potrebbe essere sufficiente restituirlo sotto forma di stringa o in formato strutturato.

MCP Connect si occupa di questo in maniera trasparente quindi in caso la funzione restituisca un oggetto complesso automaticamente lo convertirà nel formato appropriato.

C'è però un caso particolare che vale la pena accennare ed è la classe TContentList. Questa classe mappa abbastanza a basso livello l'output previsto da MCP. In questo caso la risposta può essere composta da varie sezioni, ognuna di tipo diverso (text, image, audio, link, blob). MCPConnect permette di semplificare l'utilizzo di questa classe tramite TToolResultBuilder come è possibile vedere nell'esempio seguente:

function TDelphiDayTool.BuyTicket(AId, AQuantity: Integer): TContentList;
begin
  var LTicketStream := FCart.BuyTicket(AId, AQuantity);
  FGC.Add(LTicketStream); // Add the stream to the garbage collector

  var LResultBuilder := TToolResultBuilder.CreateInstance;

  LResultBuilder.AddText('Purchase completed successfully.');
  LResultBuilder.AddImage('image/png', LTicketStream);

  Result := LResultBuilder.Build;
end;

Gestione della sessione

Una funzione essenziale di MCP è la gestione delle sessioni, che sono implicite con il trasporto stdio e esplicite se si usa Streamable HTTP. MCP Connect gestisce tutto questo in maniera trasparente e in qualsiasi tool sarà possibile andare a recuperare i dati dalla sessione corrente. A seconda della configurazione la sessione potrà essere una istanza dell'oggetto TSessionData (che concretamente salva le informazioni in un JSON) o da un qualsiasi oggetto che derivi da TSessionBase.

Il seguente codice mostra come configurare un'applicazione per usare una sessione custom (TShoppingSession) per salvare le informazioni necessarie durante il processo di creazione di un ordine.

uses
  ...
  MCPConnect.Configuration.Session;

begin
  ...
  FJRPCServer
    .Plugin.Configure<ISessionConfig>
      .SetLocation(TSessionIdLocation.Header) // default
      .SetHeaderName('Mcp-Session-Id') // default
      .SetTimeout(30)  // 30 minutes timeout (default)
      .SetSessionClass(TShoppingSession)  // Use custom typed session
      .ApplyConfig

Conclusione

MCP Connect è una libreria giovane ma già piuttosto vasta. In questo articolo ho trattato in maniera rapida alcuni degli argomenti principali senza entrare troppo nel dettaglio. Una documentazione più esaustiva può essere trovata nella pagina GitHub. Inoltre i demo presenti nei sorgenti presentano numerosi casi da cui è possibile imparare alcune tecniche per creare semplici server MCP.

Altre caratteristiche di MCP Connect di cui non ho parlato ma penso di scrivere qualcosa quanto prima sono:

Context injection
Fluent-configuration
Garbage collection
Tools namespacing
JSON-RPC only server (no MCP)
VCL/Firemokey support

WiRL e WebBroker

Luca Minuti — Wed, 17 Dec 2025 08:33:15 +0000

Introduzione a WebBroker

WebBroker è probabilmente la prima tecnologia sviluppata da Embarcadero (all'epoca ancora Borland) che ha cercato di integrare la programmazione Web con Delphi. Il sistema si basa sul componente TWebModule (un particolare tipo di DataModule) che è in grado di smistare le singole chiamate. Per fare questa operazione può agire in due modi:

WebAction: facendo doppio click sul WebModule viene aperta una finestra popup dove è possibile creare una o più WebAction, per ognuna di esse è possibile definire dei criteri per fare match con la richiesta HTTP (metodo, url, ecc) e gestire un evento dove definire la risposta.
Dispatcher: in alternativa è possibile scrivere una classe che implementi l'interfaccia IWebDispatch e registrarla sul WebModule.

WiRL e WebBroker

WiRL usa quest'ultimo approccio. In effetti con l'ultima versione è stato introdotto un nuovo componente TWiRLDispatcher che permette di inoltrare tutte le chiamate fatte a WebBroker verso WiRL.

Il dispatcher poi verificherà se esiste un engine di WiRL configurato per gestire quella specifica richiesta. In caso positivo demanderà all'engine il compito di gestire la risposta altrimenti notificherà WebBroker di non essere in grado di produrla. In quest'ultimo caso WebBroker proverà con altri dispatcher o WebAction configurati.

Dal punto di vista del codice quello che è necessario fare è creare una normalissima applicazione WebBroker (magari usando il wizard dedicato: File → New → Others → Web → Web Server Application) ed istanziare TWiRLServer e TWiRLDispatcher.

interface

uses
  // .............
  WiRL.http.Server,
  WiRL.http.Server.WebBroker;

type
  TMainWebModule = class(TWebModule)
  private
    FWiRLServer: TWiRLServer;
    FDispatcher: TWiRLDispatcher;
  public
    constructor Create(AOwner: TComponent); override;
    destructor Destroy; override;
  end;

var
  WebModuleClass: TComponentClass = TMainWebModule;

implementation

{$R *.dfm}

constructor TMainWebModule.Create(AOwner: TComponent);
begin
  inherited;
  FWiRLServer := TWiRLServer.Create(Self);

  FWiRLServer.AddEngine<TWiRLRESTEngine>('/rest')
    .SetEngineName('RESTEngine')
    .AddApplication('/app')
      .SetResources('*')
      .SetFilters('*');

  FWiRLServer.Active := True;

  // È fondamentale che l'owner dei dispatcher sia Self, che deriva da TWebModule
  // In questo modo il dispatcher viene automaticamente registrato sul WebModule
  FDispatcher := TWiRLDispatcher.Create(Self);
  FDispatcher.Server := FWiRLServer;  
end;

Vantaggi e svantaggi di WebBroker con WiRL

A questo punto ci si potrà chiedere quali sono i vantaggi nell'usare una soluzione basata su WebBroker piuttosto che quella classica basata sui componenti Indy.

I vantaggi principali sono i seguenti:

Possibilità di integrare servizi REST in applicazioni WebBroker preesistenti.
La possibilità di generare applicazioni integrate con le architetture supportate da WebBroker: Moduli Apache, ISAPI, CGI, FastCGI (introdotta da Delphi 13), Standalone.
Usare le funzionalità specifiche di WebBroker: logging nativo e sessioni.

Gli svantaggi sono principalmente relativi ad un certo aumento di complessità che l'uso di WebBroker comporta e ad alcune funzionalità non disponibili, come ad esempio SSE (Server-Sent Events) e chunked transfer encoding.

Personalmente consiglio di utilizzare l'architettura tradizionale basata su Indy per i nuovi progetti WiRL, a meno che non si debba integrare servizi ReST in un'applicazione WebBroker preesistente o si abbia l'esigenza specifica di utilizzare una delle architetture supportate da WebBroker (come moduli Apache, ISAPI, CGI o FastCGI). L'approccio con Indy risulta infatti più semplice da configurare e gestire, ed offre il pieno supporto di tutte le funzionalità di WiRL.

Nested ExtJS Form Data

Luca Minuti — Wed, 21 May 2025 15:19:10 +0000

Introduction

When developing web applications, handling form data effectively is often an important aspect of the development process. This article explores how to transform flat form data into structured JSON objects with nested properties and arrays. While ExtJS has excellent built-in form capabilities, converting form values into complex JSON structures requires additional processing that isn't provided out of the box.

Forms

ExtJS has very powerful support for HTML Forms. It offers many components under the Ext.form.* namespace that can help build complex layouts and handle common needs. However, sometimes we want not only a specific layout but also a custom JSON structure from the form.

Let's take a look at the following image:

This can be achieved with this code:

{
    xtype: 'formpanel',
    title: 'Form',
    items: [{
        name: 'name',
        label: 'Name',
        xtype: 'textfield',
        value: 'Luca'
    }, {
        xtype: 'fieldcontainer',
        label: 'Credit card',
        items: [{
            xtype: 'textfield',
            name: 'brand',
            value: 'VISA'
        },{
            xtype: 'textfield',
            name: 'number',
            flex: 1,
            value: '1234567890'
        }]
    }],
    buttons: [{
        text: 'Submit',
        handler: ...
    }]
}

As you can see, there are a couple of fields: name and credit card. The credit card field is composed of two "subfields": brand and number. If we try to get the values from the form (for example, using the getValues method), we get a flat object like this:

{
    "name": "Luca",
    "brand": "VISA",
    "number": "1234567890"
}

Let's consider an even more complex form, for example, one where we have more than one credit card:

With some minor changes to the previous code, we would get an object like this:

{
    "name": "Luca",
    "brand1": "VISA",
    "number1": "1234567890",
    "brand2": "VISA",
    "number2": "0987654321"
}

But this object structure is not ideal. A better object should have a shape like this:

{
    "name": "Luca",
    "card": [
        {
            "brand": "VISA",
            "number": "1234567890"
        },
        {
            "brand": "VISA",
            "number": "0987654321"
        }
    ]
}

How can we transform the first object to the second one? Let's look at the following form, paying particular attention to the field names:

{
    xtype: 'formpanel',
    title: 'Form',
    items: [{
        name: 'name',
        label: 'Name',
        xtype: 'textfield',
        value: 'Luca'
    }, {
        xtype: 'fieldcontainer',
        label: 'Credit card',
        items: [{
            xtype: 'textfield',
            name: 'card.0.brand',
            value: 'VISA'
        },{
            xtype: 'textfield',
            name: 'card.0.number',
            flex: 1,
            value: '1234567890'
        }]
    }, {
        xtype: 'fieldcontainer',
        label: 'Credit card',
        items: [{
            xtype: 'textfield',
            name: 'card.1.brand',
            value: 'VISA'
        },{
            xtype: 'textfield',
            name: 'card.1.number',
            flex: 1,
            value: '0987654321'
        }]
    }],
    buttons: [{
        text: 'Submit',
        handler: ...
    }]
}

The object we get from this form looks like this:

{
    "name": "Luca",
    "card.0.brand": "VISA",
    "card.0.number": "1234567890",
    "card.1.brand": "VISA",
    "card.1.number": "0987654321"
}

This is still not ideal, but by following this "dot notation" convention, we can easily transform this object into the structured version we want.

Converting Dot Notation to Nested Objects

The key to solving this problem is to create a utility function that can parse field names with dot notation and transform them into a nested object structure. The function below, that I call nestify (suggestion are welcome), recursively processes the form values and builds the desired nested JSON structure.

/**
 * This procedure transforms objects by splitting properties that have
 * a dot (.) in their name into sub-properties. For example, an object like this:
 * {
 *     test: 'value',
 *     'group.first': 1,
 *     'group.second': 'other',
 * }
 * will be transformed as follows:
 * {
 *     test: 'value',
 *     group: {
 *         first: 1,
 *         second: 'other',
 *     }
 * }
 * If the property name contains a number, an array will be created:
 * {
 *     test: 'value',
 *     'group.1': 1,
 *     'group.2': 'other',
 * }
 * will be transformed as follows:
 * {
 *     test: 'value',
 *     group: [1, 'other']
 * }
 * @param {*} values The object to process
 */
function nestify(values) {

    // This function takes a single property and breaks it into sub-objects
    function encodeKeyValues(values, key, keysList, value) {
        if (keysList.length < 1) {
            throw new Error('nestify: wrong property name');
        }
        // If the property has no sub-components, assign the value
        if (keysList.length === 1) {
            // If the value is an object, decompose it recursively
            if (Ext.isObject(value)) {
                encodeValue(value);
            }
            if (Ext.isArray(values)) {
                // If values is an array, append the value
                if (value) {
                    values.push(value);
                }
            } else {
                // Otherwise create a new property
                values[keysList[0]] = value;
            }
            return;
        }
        // If the property doesn't exist, create it
        if (!values[keysList[0]]) {
            if (Ext.isNumeric(keysList[1])) {
                // Create an array if the sub-property name is numeric (e.g., "prop.1")
                values[keysList[0]] = [];
            } else {
                // Otherwise create an object
                values[keysList[0]] = {};
            }
        }
        // If there are multiple levels (e.g., 'prop.subprop.innerprop'), call itself recursively
        encodeKeyValues(values[keysList[0]], key, keysList.splice(1), value);
        delete values[key];

    }

    // This function processes all properties of "values" and passes them
    // to the encodeKeyValues function
    function encodeValue(values) {
        Ext.Object.each(values, (key, value) => {
            const keysList = key.split('.');
            encodeKeyValues(values, key, keysList, value);
        });
    }

    encodeValue(values);

    return values;

}

Conclusion

I think the dot notation in field names provides a clear and intuitive way to define the desired output structure directly in your form definition.

This approach is particularly useful for complex forms where you need to collect hierarchical data or arrays of objects. It eliminates the need for manual post-processing of form data before sending it to your backend services, making your code cleaner and more maintainable.

WIRL - Chunked encoding e SSE

Luca Minuti — Wed, 02 Apr 2025 06:15:07 +0000

Nell'ultima versione di WiRL è stato inserito il supporto per SSE (Server-sent events o eventi lato server) e per la modalità di trasferimento chunked, che permette di inviare una risposta dividendola in vari blocchi/chunks.

SSE - Server-sent events

SSE è una tecnologia molto interessante che permette di inviare degli eventi dal server al client, cosa che con HTTP normalmente sarebbe impossibile. Quello che avviene è che il client si collega ad un particolare endpoint del server e mantiene la connessione perennemente aperta, anche in caso di disconnessione (per problemi di rete o quant'altro) il client si deve occupare di ripristinarla non appena possibile.

Implementazione

Anche dal punto di vista di WiRL la risorsa che implementa questi eventi deve essere costruita in maniera un po' particolare visto che non si tratta di inviare un semplice oggetto al client. Vediamo innanzitutto come si dichiara il metodo che andrà ad implementare la risorsa:


    [GET]
    [Produces(TMediaType.TEXT_EVENT_STREAM)]
    function ServerSideEvents([QueryParam('tag')] const ATag: string): TWiRLSSEResponse;

La prima cosa che si nota è l'attributo Produces con il valore TEXT_EVENT_STREAM, questo perché il protocollo prevede una specifico content-type da usare per SSE. Il metodo HTTP in questo caso è GET; tecnicamente potrebbe essere usato anche un altro metodo ma se il client è scritto in JavaScript la libreria standard supporta solo GET. Di seguito vediamo dei parametri, che possono essere di qualunque tipo, e infine il tipo di risposta che deve essere per forza TWiRLSSEResponse.

Vediamo adesso l'implementazione:

function TMyResource.ServerSideEvents(const ATag: string): TWiRLSSEResponse;
begin
  Result := TWiRLSSEResponse.Create(
    procedure (AWriter: IWiRLSSEResponseWriter)
    var
      LMessage: string;
    begin
      // Continua finche il server è "vivo"
      while FServer.Active do
      begin
        // Legge un messaggio dalla coda
        LMessage := MessageQueue.PopItem;
        if LMessage <> '' then
          // Se lo trova lo invia al client
          AWriter.Write(LMessage);
      end;
    end
  );
end;

Come si vede nell'esempio la classe TWiRLSSEResponse prende come primo parametro un metodo anonimo che provvederà ad inviare gli eventi. Il metodo anonimo prosegue finche il server è "vivo" (l'oggetto FServer può essere recuperato tramite la Context Injection di WiRL). In questo caso i messaggi sono nell'oggetto MessageQueue (definito come una coda thread-safe: TThreadedQueue<string>). Il programma tenta di estrarre un messaggio dalla coda e se lo trova lo invia al client tramite l'oggetto referenziato dall'interfaccia IWiRLSSEResponseWriter. Ma vediamo quali metodi fornisce questa interfaccia:

procedure Write(const AValue: string);

Questa è la funzione base che permette di inviare un evento al client. Notare che il contenuto di un evento può essere esclusivamente una stringa. Per inviare oggetto più complessi è necessario usare qualche codifica, come da esempio Base64 nel caso volessimo inviare un dato binario.

procedure Write(const AEvent, AValue: string);

Questo metodo è simile al precedente ma ha in più il parametro event che permette di "categorizzare" il messaggio. In effetti l'API JavaScript permette al client di ricevere solo i messaggi appartenenti ad una certa categoria.

procedure Write(const AEvent, AValue: string; ARetry: Integer);

Questa versione di Write ha in più il parametro ARetry che indica al client quanto tempo aspettare prima di aprire una nuova connessione una volta che quella corrente venga chiusa. In effetti, a parte errori di rete, il server potrebbe benissimo chiudera la connessione in qualunque momento.

procedure WriteComment(const AValue: string);

Questo metodo invia un commento, in generale il client dovrebbe ignorarlo, lo scopo è di solito quello di tenere la connessione attiva, questo perché se in una connessione aperta non possano dati per troppo tempo il client o anche un eventuale proxy potrebbero decidere di chiuderla.

Il client

Attualmente WiRL non fornisce un modo semplice per leggere gli eventi in arrivo tramite SSE, anche se è ovviamente possibile usare i componenti Indy (TIdHTTP) o il nuovo THttpClient.

Se invece il cilent è il browser è possibile usare l'oggetto EventSource che serve proprio a questo.

const evtSource = new EventSource("/rest/app/myevent");

evtSource.onmessage = (event) => {
  console.log(event.data);
};

Chunked transfer encoding

L'altra possibilità inserita con l'ultima versione è quella di usare il transfer encoding di tipo chunked. Questa funzione permette di inviare i dati dal server al client a blocchi. Questo può essere utile in diversi casi:

Quando la dimensione totale del contenuto non è nota in anticipo, per esempio durante la generazione dinamica di pagine web o contenuti.
Per lo streaming di dati in tempo reale, consentendo al client di iniziare a elaborare i dati mentre vengono ancora trasmessi.
Per migliorare i tempi di risposta percepiti, poiché il browser può iniziare a renderizzare parti della pagina mentre altre sono ancora in fase di download.
Nei casi di grandi trasferimenti di file, dove inviare il contenuto in chunk (blocchi) può essere più efficiente della trasmissione di un singolo blocco grande.

Implementazione

Implementare una risorsa che faccia uso di Chunked transfer encoding non è troppo diverso dal caso di SSE, in effetti in entrambi i casi abbiamo una risorsa che produce un risultato in maniera diluita nel tempo. Vendiamo innanzitutto l'interfaccia del metodo che implementa la risorsa:

    [GET]
    [Produces(TMediaType.TEXT_PLAIN)]
    function Chunks([QueryParam('chunks'), DefaultValue('5')] ANumOfChunks: Integer): TWiRLChunkedResponse;

In questo caso il metodo HTTP è una GET ma può essere qualunque; anche il Content-Type, al quale l'attributo Produces fa riferimento, può essere qualunque, e non si riferisce al singolo chunk ma all'intero output della risorsa. I parametri possono chiaramente essere di qualsiasi tipo mentre quello che distingue una risorsa chunked è il tipo restituito, che deve essere TWiRLChunkedResponse.

L'implementazione, come nel caso precedente, dovrà fornire al costruttore di TWiRLChunkedResponse una procedura anonima che invierà i singoli chunk al client.

function TMyResource.Chunks(ANumOfChunks: Integer): TWiRLChunkedResponse;
begin
  Result := TWiRLChunkedResponse.Create(
    procedure (AWriter: IWiRLResponseWriter)
    var
      LCounter: Integer;
    begin
      // Invia i dati in ANumOfChunks chunks
      for LCounter := 1 to ANumOfChunks do
      begin
        // Invia il singolo chunk
        AWriter.Write(IntToStr(LCounter));
        // Simula l'attesa necessaria per ottenere il dato successivo
        Sleep(1000);
      end;
    end
  );
end;

In questo caso la risposta viene inviata suddivisa in diversi chunk decisi dal client. Un singolo chunk contiene un dato binario. L'oggetto referenziato dall'interfaccia IWiRLResponseWriter ha però diversi metodi:

procedure Write(const AValue: string; AEncoding: TEncoding = nil);

Permette di inviare una stringa trasformandola il binario con l'encoding specificato. In assenza di encoding viene usato UTF-8.

procedure Write(const AValue: TBytes);

Questo metodo permette di inviare dati binary usando direttamente TBytes.

Client

Al momento TWiRLClient non prevede nessun meccanismo particolare per la lettura dei dati divisi in chunk. Il componete restituirà l'intera risposta una volta avvenuta la ricezione di tutti i chunks. Però sia il componente TIdHTTP che THttpClient tramite degli eventi possono leggere i chunk man mano che arrivano. Per esempio è possibile usare il componente TIdHTTP in questo modo:

procedure TForm1.ButtonIdHTTP1Click(Sender: TObject);
begin
  // Aggancia l'evento OnChunkReceived
  IdHTTP1.OnChunkReceived := IdHTTP1ChunkReceived;
  // Effettua la chiamata
  IdHTTP1.Get('http://localhost:8080/rest/app/chunk');
end;

procedure TForm1.IdHTTP1ChunkReceived(Sender: TObject;
  var Chunk: TIdBytes);
var
  LText: string;
begin
  // Converte il chunk in stringa
  LText := IndyTextEncoding_UTF8.GetString(Chunk);
  // e lo aggiunge ad un memo
  MemoLog.Lines.Text := MemoLog.Lines.Text + LText;
end;

Conclusione

In questo articolo ho cercato di fornire una panoramica sull'utilizzo di chunk e SSE con l'ultima versione di WiRL. Scaricando i sorgenti da GitHub è possibile testare il Demo 23.Chunks che fornisce vari esempi d'uso. Al momento la parte client è un po' debole ma con le prossime release verrà fornito anche un supporto migliorato per il componente TWiRLClient.

Siti statici con AWS e CloudFront

Luca Minuti — Thu, 23 Jan 2025 21:24:51 +0000

Introduzione

Negli ultimi mesi ho deciso di trasferire il mio sito ufficiale da una macchina virtuale EC2 di AWS a S3 sempre su AWS. Il motivo è banalmente la semplicità di gestione, infatti, se il sito comprende solo una serie di pagine statiche, fare un upload (eventualmente anche automatizzabile) su S3 è molto più semplice che avere un'intera macchina da amministrare. Lo svantaggio ovviamente è la flessibilità: avere un'intera macchina virtuale ci da certamente più possibilità.

In questo articolo vedremo prima come preparare il bucket di S3 per ospitare e rendere pubbliche le nostre pagine e poi come abilitare HTTPS attraverso CloudFront (sempre su AWS). In un prossimo articolo vedremo anche come fare tutto il processo su CloudFlare liberandoci completamente di AWS e semplificando molto la configurazione (di contro ci perdiamo tutte le funzionalità di AWS). Quest'ultima soluzione è quella che abbiamo usato per la documentazione di WiRL.

Prerequisiti

In questa guida darò per scontato che sia già presente un account su AWS. La creazione del account è gratuita e ci sono vari piani gratuiti o a basso costo su entrambe le piattaforme. Ovviamente dipende dalla dimensione del vostro sito e soprattutto dal traffico generato.

Creare un nuovo bucket su S2

Per prima cosa è necessario creare il bucket su S3. La scelta del nome del bucket è fondamentale infatti se vogliamo che sia raggiungibile da http://lucaminuti.it/ deve chiamarsi lucaminuti.it, se invece il sito sarà per esempio https://my.project.com/ il bucket dovrà chiamarsi my.project.com (Guida ufficiale).

Nel mio caso il sito sarà https://lucaminuti.it per cui chiamo il bucket lucaminuti.it.

Innanzitutto aprite la console di AWS sulla pagina relativa a S3 e premete il pulsante Crea bucket. Vi si dovrebbe presentare una pagina come questa:

Dato che deve essere ad accesso pubblico sblocco tutti gli accessi:

Una volta creato il bucket è possibile caricare i file (io uso WinSCP ma è anche possibile usare la CLI di AWS). Per ottenere l’accesso tramite browser sono necessari altri due passaggi. Nella pagina “Autorizzazioni” modifico le policy del bucket in modo da ottenere l’accesso in lettura. Attenzione al ARN del bucket.

Qui il JSON grezzo:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AddPerm",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::lucaminuti-it/*"
        }
    ]
}

Poi è necessario nella pagina “properties” modificare la voce "Hosting di siti Web statici” in questo modo:

A questo, punto una volta fatto l'upload dei vostri contenuti nel bucket, il sito dovrebbe essere accessibile. È possibile trovare l’URL di accesso nelle “properties” del bucket.

L'URL sarà una cosa del tipo:

http://lucaminuti.it.s3-website.amazonaws.com/

Non proprio semplice da raggiungere e senza supporto per HTTPS. Per risolvere il problema possiamo usare CloudFront, per restare in casa AWS o usare un servizio esterno come CloudFlare.

Creazione del certificato

Per prima cosa dalla console di AWS apriamo la pagina "AWS certificate manager" e da li selezioniamo "richiedi certificato". Ne scegliamo uno pubblico, gli indichiamo il nome del dominio (es. lucaminuti.it) e lasciamo tutti i default. Attenzione: il certificato deve essere creato nella regione us-east-1.

Una volta effettuata la richiesta create il record CNAME di conferma come specificato attraverso l'interfaccia con cui gestite il vostro dominio.

Entro pochi minuti (<5) dovrebbe essere approvato.

Configurazione di CloudFront

Apriamo la pagina di "CloudFront" su AWS e selezioniamo "Create distribution". Qui possiamo impostare il dominio il protocollo è la porta che abbiamo usato nella fase precedete.

Attiviamo il redirect:

Impostiamo il dominio dal quale raggiungere l'origine inserita nella fase precedente:

Gli associamo il certificato creato in precedenza:

E l’oggetto di default:

A questo punto l'ultima cosa da fare è andare sulla gestione del vostro DNS e associarla al dominio creato da CloudFrond. In particolare è necessario creare un record CNAME che punti al dominio creato da CloundFront (Distribution domain name nelle proprietà della distribuzione CloudFront). Attenzione: per l'attivazione di CloudFront attendere qualche minuto per il deployment.

Conclusioni

Come penso sia chiaro il processo non è esattamente semplice. Nel prossimo articolo proveremo a fare la stessa cosa usando CloudFlare, decisamente più semplice, ma che richiede il trasferimento della gestione del dominio su CloudFlare.

Appunti su VitePress

Luca Minuti — Mon, 02 Dec 2024 07:26:35 +0000

Dopo il precedente articolo su VitePress mi sono state fatte un po' di domande su come configurarlo e come attivare alcune funzionalità specifiche. Approfitto di questo spazio per raccogliere i miei appunti. Per ogni voce ho messo il link alla guida ufficiale per approfondire.

Dove posizionare immagini e altri asset

Le immagini o altri asset referenziate all'interno dei file markdown dovrebbero sempre essere indicate tramite un path relativo:

![An image](./image.png)

VitePress si occuperà in fase di build di metterli nel posto giusto. Se invece si desidera caricare un file che non viene usato da nessun markdown nella root del sito (es. robot.txt, favicon, ecc.) deve essere posizionato nella directory ./docs/public.

https://vitepress.dev/guide/asset-handling#referencing-static-assets

Logo

È possibile inserire un logo a destra della pagina andando a modificare la sezione hero della pagina index.md:

hero:
  image:
    src: /BigLogo.png
    alt: Logo
  name: "MyApp"

L’immagine deve essere inserita nella directory ./docs/public e dovrebbe essere di almeno 192x192 pixel.

https://vitepress.dev/reference/default-theme-home-page#hero-section

Un logo più piccolo può essere messo in alto a sinistra su tutte le pagine andando a modificare la configurazione .vitepress/config.js:

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  themeConfig: {
    logo: "/small-logo.png",
  }
});

https://vitepress.dev/reference/default-theme-nav#site-title-and-logo

Come personalizzare i CSS

Per personalizzare i colori o altre caratteristiche estetiche del sito è possibile modificare il tema aggiungendo un CSS custom.

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

// .vitepress/theme/custom.css
:root {
    --vp-c-brand-1: #d65a4a;
    --vp-c-brand-2: #005d97;
  }

https://vitepress.dev/guide/extending-default-theme

Base URL

Se il sito verrà messo in un URL che non è la root del sito è necessario indicarlo nell’opzione base in .vitepress/config.js. Per esempio se il vostro sito è accessibile all’URL https://foo.github.io/bar/ allora base deve essere uguale a /base/ (deve sempre iniziale con slash).

https://vitepress.dev/guide/asset-handling#base-url

Ricerca integrata nel sito

Se si desidera attivare una barra di ricerca è sufficiente inserire in configurazione:

// .vitepress/config.js
import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

In questo modo la ricerca è fatta localmente, se la documentazione fosse molto estesa è preferibile usare un sito esterno. VitePress si integra perfettamente con Algolia.

Vedi: https://vitepress.dev/reference/default-theme-search#algolia-search

Inserire la favicon

Il modo più semplice per aggiungere una favicon è copiarla della directory ./docs/public/ e aggiungere questa configurazione:

// .vitepress/config.js
import { defineConfig } from 'vitepress'

export default defineConfig({
  head: [["link", { rel: "icon", href: "/favicon.ico" }]],
})

https://vitepress.dev/reference/site-config#example-adding-a-favicon

Aggiungere il supporto a Mermaid

Se si vuole aggiungere il supporto a Mermaid per i grafici è necessario come prima cosa aggiungere il plugin:

npm i vitepress-plugin-mermaid

e poi modificare la configurazione come segue:

// .vitepress/config.js
import { defineConfig } from "vitepress";
import { withMermaid } from "vitepress-plugin-mermaid";

export default withMermaid(
  defineConfig({
    title: "...",
    ...
  })
);

Icone social personalizzate

In alto a destra sul sito sono presenti le icone per i social; è possibile aggiungerle modificando la configurazione:

    socialLinks: [
      { icon: 'github', link: 'https://github.com/foo/bar' },
      { icon: 'youtube', link: 'https://youtube.com/foo/' },
    ]

Le icone utilizzabili sono tutte quelle presenti su https://simpleicons.org/. Se non fossero sufficienti è possibile usare qualunque immagine in formato SVG (per esempio da https://iconify.design/) in questo modo:

 socialLinks: [
      { icon: 'github', link: 'https://github.com/EtheaDev/SVGIconImageList' },
      { icon: {
          svg: '<svg xmlns="http://www.w3.org/2000/svg" width="0.86em" height="1em" viewBox="0 0 440 512">  <path fill="currentColor" d="m188.1 318.863l-4.04-19.052l176.073-121.468l17.315 102.649zm151.193 148.26c-2.721 27.2-50.315 44.877-50.315 44.877l-84.315-183.43l25.839-4.08c40.831 49.843 85.165 50.51 108.79 142.634m-104.804 1.518c-35.834-7.263-63.108-9.73-83.65-9.73c-23.054 0-37.62 3.113-46.232 6.055l25.603-58.769l.093-.235c.097-.237 10.483-22.743 96.55-9.58l21.537 46.854zM80.649 223.858L31.276 126.47l53.036-53.036l24.478 108.112c-10.555 11.244-19.887 25.468-28.143 42.312m225.327-76.99l133.271-111.51L339.293 0l-94.77 129.473c20.274 2.15 43.096 10.268 61.453 17.396m-70.014-18.04L310.056 0h-96.552l-39.438 138.028c19.386-6.797 40.046-9.782 61.896-9.2m-68.695 11.24l14.279-118.99l-76.835 31.958l10.84 121.93c13.401-12.673 29.885-24.51 51.716-34.898m-97.69 190.4L4.08 310.055l14.958 44.876h58.296a165 165 0 0 1-7.756-24.465m11.112 32.175l-49.412 7.247l23.458 34.678l39.6-18.029a165 165 0 0 1-13.646-23.896M65.275 277.34L4.08 237.98L0 293.736l66.985 22.984c-1.661-12.666-2.19-25.81-1.71-39.38m8.838-43.44L25.84 165.648L4.08 218.941l61.196 52.28zm47.339 171.971c8.036-25.69 61.777-23.832 101.328-18.352l-28.32-61.61l-12.668 2.534l-6.84-32.263l163.834-113.023C234.333 93 146.248 154.418 115 187.667c-41.667 44.333-72.667 138 6.452 218.205" /></svg>'}, 
        link: 'https://github.com/EtheaDev/SVGIconImageList' 
      }
    ]

https://vitepress.dev/reference/default-theme-config#sociallinks

Footer

Inoltre è possibile inserire un footer personalizzato in home page in questo modo:

// .vitepress/config.js
export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2024-present Luca Minuti'
    }
  }
}

Sulle singole pagine della documentazione è possibile inserire sia la data di ultima modifica della pagina stessa che il link alla pagina su GitHub per poterla modificare:

// .vitepress/config.js
export default {
  lastUpdated: true,
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path'
    }
  }
}

https://vitepress.dev/reference/default-theme-edit-link

Documentazione con VitePress

Luca Minuti — Mon, 28 Oct 2024 07:12:56 +0000

Da qualche tempo ho cominciato a lavorare su diversi progetti Web con VueJS, devo dire che mi trovo molto bene, tanto che con Wintech Italia stiamo organizzando dei corsi e ne parleremo anche al prossimo Delphi Day.

Quasi subito ho notato che i siti ufficiali di Vue stesso e di gran parte dell'ecosistema Vue (Vue Router, Pinia, ecc.) sono molto simili e, a mio parere, molto ben fatti. Andando ad indagare ho scoperto che tutti usano VitePress.

Cos'è VitePress

VitePress è un generatore di siti statici, progettato specificamente per creare siti di documentazione tecnica. VitePress è stato sviluppato da Evan You, il creatore di Vue.js, garantendo una profonda integrazione con l'ecosistema Vue. Nonostante questo non richiede la conoscenza di Vue per essere usato, infatti permette di generare la documentazione a partire da una serie di pagine scritte in Markdown.

Devo dire che VitePress mi è piaciuto molto, soprattutto per la sua estrema semplicità d'uso e per la sua flessibilità, tanto che abbiamo deciso di usarlo per riscrivere e aggiornare tutta la documentazione di WiRL.

Come si usa

Se andate sul sito ufficiale troverete un'ottima guida all'installazione ma che purtroppo da per scontato abbiate già un progetto basato su npm. Qui invece voglio partire da zero per chi abbia un progetto che, come WiRL, non ha niente a che fare col mondo Web/JavaScript. In questo esempio creeremo un nuovo progetto contenete solo la documentazione, ma se volete inserire la documentazione in un progetto preesistente i passaggi sono analoghi.

Inizializzazione

Innanzitutto, se già non l'avete, è necessario installare NodeJS. Potete scaricarlo dal sito ufficiale. Quindi aprite un prompt dei comandi e digitate:

node -v

oppure:

npm -v

dovreste vedere le rispettive versioni. Se non funziona probabilmente non li avete installati correttamente o non sono stati aggiunti al path di sistema.

Creiamo il folder dove inserire il progetto e ci posizioniamo li:

mkdir MyNewProject
cd MyNewProject

a questo punto inizializziamo il progetto:

npm init

Npm chiederà un po' di informazioni: nome del progetto, versione, ecc. potete lasciare tutti i default premendo invio o modificarli a vostro piacimento. Al termine verrà creato un file package.json contenente tutte le informazioni richieste in precedenza, che eventualmente è possibile modificare.

Installazione di VitePress

Una volta inizializzato il package possiamo procedere all'installazione di VitePress digitando il seguente comando:

npm add -D vitepress

Questo andrà ad aggiungere al file package.json una dipendenza di sviluppo relativa a VitePress e provvederà anche a scaricare il pacchetto nella directory node_modules. Ricordate di inserire node_modules tra i file da ignorare se usate un version control.

Setup Wizard

Ora potremo andare direttamente a scrivere la configurazione di VitePress e la documentazione ma in realtà è decisamente più comodo farsi generare lo scheletro del codice direttamente dal wizard di VitePress:

npx vitepress init

Anche in questo caso vi verranno fatte alcune domande. Io di solito le confermo tutte tranne per la gestione dei TypeScript per la configurazione e la creazione dei file nella directory docs invece che sulla root.

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
│
◇  Use TypeScript for config and theme files?
│  ○ Yes
│  ● No
│  
◇  Add VitePress npm scripts to package.json?
│  ● Yes
│  ○ No  
└

Se avete risposto di sì alla domanda sulla generazione degli script potete già avviare il vostro nuovo sito con:

npm run docs:dev

In pochi secondi verrà avviato un server HTTP che potete usare per visualizzare le pagine puntando il browser all'URL indicato. Il server rimane attivo finche non premete q e se modificate o aggiungete una pagina andrà a forzare il caricamento automatico della nuova versione sul browser.

Creazione del sito

A questo punto si può precedere alla configurazione del sito vero è proprio. il wizard in effetti avrà creato diversi file che potete andare a modificare.

.
 ├─ .vitepress
 │  └─ config.mjs
 ├─ api-examples.md
 ├─ markdown-examples.md
 └─ index.md

In particolare:

index.md: contiene la home page
.vitepress/config.mjs: contiene l'indice di tutte le pagine
gli altri sono file di esempio che potete anche eliminare

Quindi semplicemente andando a scrivere le vostre pagine e aggiungendole all'indice potete creare la vostra guida. Tutte le pagine devono essere scritte in markdown, se non lo conoscete trovate una guida qui.

Deployment

Una volta creato un sito che vi soddisfa potete procedere al deployment:

npm run docs:build

Questo comando genererà tutti i file necessari nella directory .vitepress\dist. Potete semplicemente copiarli su qualsiasi sito che vi offre una spazio web e saranno visibili da chiunque.

Eventualmente sito ufficiale trovate una guida per fare deploment su una miriade di piattaforme:

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render
GitHub Pages
GitLab Pages
Azure Static Web Apps
Firebase
Surge
Heroku
Edgio
Kinsta Static Site Hosting
Stormkit
Nginx

Altro

Come dicevo all'inizio VitePress permette una serie infinita di personalizzazioni, alcune offerte direttamente e altre attraverso plugin di terze parti. Giusto per avere un'idea:

Internazionalizzazione
Temi custom
Motore di ricerca integrato
Supporto a mermaid
Generazione della sitemap
Supporto a Frontmatter
Utilizzo di Vue all'interno dei file markdown

ExtJS and Tailwind CSS

Luca Minuti — Mon, 14 Oct 2024 06:23:33 +0000

Over the past few months, I've been using Tailwind for some WebApp projects not related to ExtJS. Tailwind is a framework very different from Bootstrap or similar products. In fact, it uses a utility-first approach where CSS classes are linked to functionalities rather than components.

How Tailwind CSS Works

To try to clarify the concept a bit, I'll use the same example from the official website.

Let's take this component:

Using a traditional approach, we would need to use code like this:

<div class="chat-notification">
  <div class="chat-notification-logo-wrapper">
    <img class="chat-notification-logo" src="/img/logo.svg" alt="ChitChat Logo">
  </div>
  <div class="chat-notification-content">
    <h4 class="chat-notification-title">ChitChat</h4>
    <p class="chat-notification-message">You have a new message!</p>
  </div>
</div>

<style>
  .chat-notification {
    display: flex;
    align-items: center;
    max-width: 24rem;
    margin: 0 auto;
    padding: 1.5rem;
    border-radius: 0.5rem;
    background-color: #fff;
    box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
  }
  .chat-notification-logo-wrapper {
    flex-shrink: 0;
  }
  .chat-notification-logo {
    height: 3rem;
    width: 3rem;
  }
  .chat-notification-content {
    margin-left: 1.5rem;
  }
  .chat-notification-title {
    color: #1a202c;
    font-size: 1.25rem;
    line-height: 1.25;
  }
  .chat-notification-message {
    color: #718096;
    font-size: 1rem;
    line-height: 1.5;
  }
</style>

With Tailwind, however, something like this is enough:

<div class="p-6 max-w-sm mx-auto bg-white rounded-xl shadow-lg flex items-center space-x-4">
  <div class="shrink-0">
    <img class="size-12" src="/img/logo.svg" alt="ChitChat Logo">
  </div>
  <div>
    <div class="text-xl font-medium text-black">ChitChat</div>
    <p class="text-slate-500">You have a new message!</p>
  </div>
</div>

The purpose of this article is not to go into the details of how Tailwind works, but even at first glance, what we see is the difference in size of the code block, but also a series of horrible CSS classes.

Personally, I'm used to give classes a name that help me understand their meaning (button, card, grid, column, ...), and this certainly makes it easier to read the HTML code; in some way, it's like adding comments to the code. Instead, with Tailwind, the classes refer to a single specific aspect to assign to HTML tags. For each tag it's often necessary to insert more than one class, making the whole thing particularly complex.

The big advantage is that you practically don't write CSS anymore and use almost only Tailwind classes. In this way, besides not wasting time inventing class names, often even bizarre ones (item-inner-column-wrapper, etc.), you use conventions that help the site be more homogeneous and coherent.

Moreover Tailwind has a whole series of interesting features for supporting responsive sites, creating custom themes, dark mode, a plethora of plugins, and much more. For this refer to the official guide.

Tailwind and ExtJS

When some time ago I resumed an ExtJS project and found myself writing complex templates, with CSS classes and many styles, I realized I missed Tailwind. Let's take an example:

    items: [{
        xtype: 'list',
        store: ...,
        itemTpl: 
            '<div class="list-item">' +
                '<div class="item-icon {iconCls}"></div>' +
                '<div class="list-item-data">' +
                    '<div class="list-item-name">{name}</div>' +
                    '<div class="list-item-detail">{detail}</div>' +
                '</div>' +
            '</div>'
    }]

with its CSS:


.list-item {
    display: flex; 
    align-items: center;
    padding: 4px;
}

.list-item-data {
    display: flex; 
    flex-direction: column;
}

.list-item-name {
    font-size: 18px;
}

.list-item-detail {
    font-style: italic;
}

With Tailwind, the following code is enough without even touching the CSS files:

    items: [{
        xtype: 'list',
        store: ...,
        itemTpl: 
            '<div class="flex items-center p-1">' +
                '<div class="item-icon {iconCls}"></div>' +
                '<div class="flex flex-col">' +
                    '<div class="text-lg">{name}</div>' +
                    '<div class="italic">{detail}</div>' +
                '</div>' +
            '</div>'
    }]

Configuration

Using Tailwind with ExtJS is quite simple because in the end, what the engine does is scan all our code looking for Tailwind classes (flex, grid, text-lg, p-1, p-2, etc.) and generate a CSS file containing only the classes we've used. If you use the new Open tooling based on npm, you can follow Tailwind's installation guide. Otherwise, if you use SenchaCmd, the simplest thing to do is to download the CLI from here.

With this new CLI installed, you can initialize Tailwind by going to the root directory of your project and write:

# Create a tailwind.config.js file
./tailwindcss init

This will create the tailwind.config.js file. I changed it like this, but of course, it depends on your application:

/** @type {import('tailwindcss').Config} */
module.exports = {
    content: ['./app/**/*.{html,js}','./index.html'],
    // Remove all corePlugins
    corePlugins: {
      preflight: false,
    },
    // Remove all preset
    //presets: [],
    theme: {
        extend: {
          boxShadow: {
            'outline': '2px 2px 8px 0 rgba(0, 0, 0, 0.4)',
          }
        },
    },
    plugins: [],
};

The content option is the most important, where you must define the directories that Tailwind will scan to find CSS classes. With the corePlugins and plugins configuration, I removed all plugins to generate the lightest possible CSS. Finally, I added a customization to the theme to generate a new shadow-outline class with the specified configuration. If you will, you could remove the standard presets, but then some classes wouldn't work.

Then we can use the CLI again to generate the classes:

tailwindcss -o sass\src\tailwind.css --watch

With this command, Tailwind will constantly check the files specified in the configuration and generate the classes in the sass\src\tailwind.css file. Finally we have to tell ExtJS to use that CSS file. We need to modify the application configuration in the scss section of the app.json file:

    "sass": {
        ...
        "src": [
            "sass/src",
            "sass/src/tailwind.css"
        ]
    ]

Optionally, you can automate the creation of CSS during the production build by adding the following code to your build.xml file:

    <target name="-before-build">
        <if>
            <equals arg1="production" arg2="${build.environment}"/>
            <then>
                <x-echo message="Build CSS with Tailwind"/>
                <exec executable="tailwindcss">
                    <arg value="-o"/>
                    <arg value="sass\src\tailwind.css"/>
                </exec>
            </then>
        </if>

    </target>

Delphi WebStencils con WiRL

Luca Minuti — Mon, 23 Sep 2024 06:19:24 +0000

Da pochi giorni è uscita la versione 12.2 di Delphi, nonostante sia una dot release, dove il focus è principalmente sulla risoluzione dei bug, ci sono diverse novità interessanti. Le principali sono il supporto per vari sistemi di AI generativa e l'introduzione di una libreria denominata WebStenclis per la creazione HTML attraverso dei template.

In questo articolo volevo parlare di quest'ultima, in particola di come integrarla con WiRL. In realtà, con qualche accorgimento, il contenuto di questo articolo può essere adattato anche ad altre tecnologie.

WebStencils

Se volete un guida approfondita su WebStencils vi consiglio l'ottimo articolo di Marco Cantù, ma di base si tratta di un sistema per creare del codice HTML in base ad un template da applicare ad un oggetto Delphi.

Supponendo di avere un oggetto TPerson fatto in questo modo:

  TPerson = class
  private
    FName: string;
    FAge: Integer;
  public
    property Name: string read FName write FName;
    property Age: Integer read FAge write FAge;

    constructor Create(const AName: string; AAge: Integer);
  end;

e un template come questo (notare i valori che cominciano con @):

<section id="output1">
    <div>Name: <strong>@value.name</strong></div>
    <div>Age: <strong>@value.age</strong></div>
</section>

è possibile generare l'HTML corrispondente con questo codice:

    LPerson := TPerson.Create('Luca', 42);
    LStencil.InputFileName := LTemplateFileName;
    LStencil.AddVar('value', LPerson, False);
    LContent := LStencil.Content;

I template non si limitano a fare una sorta di "search & replace" ma possono avere anche del codice condizionale come:

Loop: per ripetere parti del template in caso di oggetto che contengono vari elementi come dataset o liste;
If: per includere una parte del template in base a qualche condizione;
Include: per includere porzioni di HTML;
loginrequired: per gestire le autorizzazioni;
e altro ancora.

WiRL

Ma come possiamo usare questa tecnologia con WiRL? Lo scopo di WiRL è quello di implementare una API ReST e in questo caso non stiamo affatto parlando di ReST. Certo, nessuno ci impedisce di restituire un HTML generato con WebStelcils da una risorsa ReST, ma non avrebbe molto senso.

A pensarci bene però i WebStencils, nell'ottica di WiRL, sono in pratica del Message Body Writer, cioè dei moduli che sono in grado di serializzare degli oggetti in un determinato formato, in questo caso HTML.

L'idea sarebbe quella di creare risorse WiRL in maniera tradizionale, quindi restituendo oggetti e trasformarli in HTML tramite un Message Body Writer specifico che utilizzi WebStencils.

La risorsa

La risorsa che andremo a creare sarà quindi una normalissima risorsa WiRL che restituisce un oggetto TPerson:

  [Path('/person')]
  TPersonResource = class(TObject)
  public
    [GET]
    [Produces(TMediaType.TEXT_HTML)]
    [Produces(TMediaType.APPLICATION_JSON)]
    function GetPerson(): TPerson;
  end;

L'implementazione è ancora più semplice:

function TPersonResource.GetPerson: TPerson;
begin
  Result := TPerson.Create('Luca', 42);
end;

Notate che nella dichiarazione abbiamo indicato che l'oggetto TPerson può essere serializzato sia un JSON che HTML (WiRL sceglierà uno o altro in base al header Accept della richiesta). Ora, mentre per il JSON non ci sono problemi, dato che WiRL lo supporta nativamente, per HTML dobbiamo dirgli come comportarsi. Ed è qui che entra in gioco il Message Body Writer.

Message Body Writer

Vediamo subito il codice:

procedure TWiRLStencilsWriter.WriteTo(const AValue: TValue;
  const AAttributes: TAttributeArray; AMediaType: TMediaType;
  AHeaders: IWiRLHeaders; AContentStream: TStream);
var
  LStencilName: string;
  LStencil: TWebStencilsProcessor;
  LContent: string;
  LBuffer: TBytes;
begin
  inherited;
  // Verifica se ci è stato passato un template specifico nell'header 'x-stencil'
  LStencilName := FRequest.Headers['x-stencil'];
  // altrimenti ne usa uno di default (nome della classe senza 'T')
  if LStencilName = '' then
    LStencilName := Copy(AValue.AsObject.ClassName, 2, 100).ToLower + '.html';
  LStencil := TWebStencilsProcessor.Create(nil);
  try
    // Carica il template
    LStencil.InputFileName := TPath.Combine(ExtractFileDir(ParamStr(0)), 'www', LStencilName);
    // Carica l'oggetto
    LStencil.AddVar('value', AValue.AsObject, False);
    // Applica il template
    LContent := LStencil.Content;
    // Mette il risultato nello stream della risposta HTTP
    LBuffer := TEncoding.UTF8.GetBytes(LContent);
    AContentStream.WriteBuffer(LBuffer[0], Length(LBuffer));
  finally
    LStencil.Free;
  end;
end;

L'idea è che per serializzare l'oggetto TPerson WiRL deve usare un template di nome person.html oppure il chiamante può indicare un template specifico tramite un header custom chiamato x-stencil. Il Message Body Writer non fa nient'altro che caricare il template e l'oggetto da serializzare nel WebStencils e chiedergli il risultato.

Come si può vedere il codice del Message Body Writer è molto semplice.

Questo uso di template e WebStencils può integrarsi con qualsiasi progetto Web ma è particolarmente interessante accoppiato con HTMX.

HTMX

Anche in questo caso non mi voglio soffermare troppo su HTMX, trovate diversi post di Embarcadero sull'argomento qui. Ma l'idea di base è quella di estendere l'HTML e riuscire a creare pagine dinamiche che interagiscono col server senza l'uso di JavaScript, quindi con un approccio puramente dichiarativo.

Per esempio il seguente frammento di HTMX alla pressione del pulsante chiamerà l'URL /clicked e sostituira il nodo con nome outerHTML con quanto arrivato dal server.

<button hx-post="/clicked" hx-swap="outerHTML">
  Click Me
</button>

Quindi si presume che il server generi frammenti di HTML, che è proprio quello che abbiamo fatto con i WebStencils.

Qui trovate il progetto di esempio con i sorgenti completi: https://github.com/lminuti/WebStencilsDemo

Nel progetto troverete una semplice pagina di esempio (ho usato PicoCSS giusto per avere un aspetto un minimo decente), dove ci sono tre DEMO:

Il primo contiene un pulsante fatto così:

    <button hx-get="rest/default/person"
            hx-trigger="click"
            hx-target="#output1"
            hx-swap="outerHTML">
        Click Me!
    </button>

In questo caso al click del pulsante viene chiamata la risorsa rest/default/person e il risultato va a sostituire l'elemento HTML chiamato output1. Il secondo è identico ma usa un template personalizzato:

    <button hx-get="rest/default/person"
            wirl-stencil="person_it.html"
            hx-trigger="click"
            hx-target="#output2"
            hx-swap="outerHTML">
        Click Me!
    </button>

Infatti con l'attributo wirl-stencil inviamo a WiRL in nome del template da usare. Il terzo è un po' più complesso, infatti il template permette di trasformare un dataset in una tabella HTML:

Inoltre cliccando su una specifica riga si può vedere il dettaglio dell'elemento selezionato:

Configurazione

Per ottenere questa integrazione tra HTMX e WiRL serve una piccola configurazione lato HTMX che è la seguente:

    document.body.addEventListener('htmx:configRequest', function(evt) {
        evt.detail.headers ['accept'] = 'text/html'; // force text/html
        if (evt.target.getAttribute('wirl-stencil')) {
            evt.detail.headers['x-stencil'] = evt.target.getAttribute('wirl-stencil'); // add x-stencil header
        }
    });

In pratica stiamo dicendo a HTMX che ogni volta che esegue una chiamata Ajax deve aggiungere due header:

accept: che indica a WiRL di restituire la risorsa serializzata in HTML. Questo perché WiRL di default la serializzerebbe in JSON;
x-stencil: in questo modo se abbiamo usato l'attributo wirl-stencil sul pulsante HTMX invia il nome dello template attraveso questo header.

Conclusioni

Penso che questo uso degli stencils con WiRL sia interessante e soprattutto che dimostri come è semplice personalizzare WiRL per fargli fare anche cose per cui chiaramente non è nato.

Trovate tutto il codice mostrato qui:

https://github.com/lminuti/WebStencilsDemo

Per poterlo compilare e provare è necessario scaricare e installare WiRL:

https://github.com/delphi-blocks/WiRL

La documentazione ufficiale di WiRL:

https://wirl.delphiblocks.dev/

Bruno vs Postman

Luca Minuti — Tue, 30 Jul 2024 07:17:41 +0000

Per chi sviluppa server ReST l’uso di un tool per testare le proprie API è fondamentale. Fino a poco tempo fa lo standard di fatto per questo tipo di applicazioni era Postman. Ultimamente però lo scenario è cambiato e si trovano diverse alternative, una delle più interessanti è Bruno.

Chi conosce Postman non farà fatica ad usare Bruno, infatti, l’interfaccia utente è molto simile e anche alcuni concetti come le Collection, Environment, Script e Test sono praticamente gli stessi. Però ci sono alcune differenze sostanziali. La più interessante è che, mentre Postman richiede la creazione di un account per condividere le collections, Bruno sfrutta Git (o qualunque altro version control). Questa caratteristica è molto interessante perché permette di “versionare” le collections e i vari test insieme alle API.

Bru Markup Language

In effetti quando viene salvata una collection vengono fisicamente salvati vari file in formato Bru in una cartelle del file system. La prima volta che ho visto il file Bru mi sono chiesto perché usare l’ennesimo formato custom simil JSON invece di JSON, YAML, TOML o qualcosa di già esistente.

Andando a leggere la documentazione e vari forum ho capito che c’era un ottimo motivo per questa scelta. E questo risiede sempre nella volontà di integrarsi con il version control. Infatti bisogna tener presente che nei file Bru ci sono alcune informazioni molto semplici — come metodo HTTP, headers, queryparams — che si prestano molto bene ad essere strutturate in un JSON; ma ci sono anche blocchi di codice JavaScript (per gli script e i test) e documentazione in Markdown o altro che inseriti in un JSON lo renderebbero pressoché illeggibile ostacolando notevolmente operazioni come diff o merge.

meta {
    name: Get Users
    type: http
    seq: 1
}

get {
    url: https://reqres.in/api/users
    body: none
}

assert {
    res.status: 200
}

tests {
    test("status code is 200", function() {
        expect(res.status).equal(200);
    });
}

Bru command line

Una caratteristica interessante di Bruno è la possibilità di automatizzare l’esecuzione delle varie collection dalla linea di comando. Per esempio questo comando lancerà tutte le richieste della collection:

bru run

Ovviamente è anche possibile lanciare una singola collection:

bru run request.bru

specificare un particolare environment:

bru run folder --env Local

e molto altro. Questo è un esempio dell’output del comando precedente:

Nella documentazione ufficiale sono specificati tutti i parametri.

Scripting

Bruno offre la possibilità di scrivere anche del codice JavaScript per automatizzare diverse operazioni per esempio:

Recuperare automaticamente il token di autenticazione
Generare dati fittizi
Validare la risposta
Integrare la richiesta con dati provenienti da altre API

Per esempio il codice seguente inserito in uno script “post response” permette di recuperare il token dalla risposta e inserirlo in una variabile in modo da poterlo usare in tutte le chiamate successive:

bru.setEnvVar("jwt_token", res.getBody().access_token);

Invece il codice seguente, inserito in uno script “Pre request” permette di popolare il corpo di una richiesta con dei dati fittizi:

const {faker} = require("@faker-js/faker");
const name = faker.name.fullName();
const email = faker.internet.email();

req.setBody({
    name,
    email
});

Notare che in quest’ultimo caso è stata usata una libreria esterna. Bruno infatti permette di usare una selezione di librerie JavaScript (ajx, axios, node-fetch, lodash, moment, ecc.) semplicemente importandole (require) oppure con un processo un po’ più complicato di usare qualunque libreria.

Link

Home page: https://www.usebruno.com/

Documentazione: https://docs.usebruno.com/introduction/getting-started

Discord: https://discord.com/invite/KgcZUncpjq