Commons Demo: la herramienta gratuita detrás de las demos de nuestros add-ons

Una buena demo hace dos cosas a la vez: muestra el componente funcionando y muestra el código que lo hace funcionar. Quien evalúa un add-on quiere ver el resultado y después copiar el fragmento que lo produjo.

Hacerlo a mano es tedioso. Terminas pegando código en la página, y en cuanto el ejemplo cambia, el código pegado queda desactualizado. Multiplica eso por decenas de add-ons y varias versiones de Vaadin, y mantener las demos consistentes se vuelve un trabajo en sí mismo.

Por eso construimos nuestras demos con la ayuda de Commons Demo, una pequeña biblioteca de código abierto que hace ese trabajo por ti. En este artículo te la presentamos, te mostramos dónde verla en acción y te explicamos cómo usarla en tus propios proyectos.

Qué es Commons Demo

Commons Demo es una biblioteca Java de clases de UI para construir demos con Vaadin Flow. Tiene licencia Apache 2.0 y está publicada en Maven Central. La versión 5.x es compatible con Vaadin 24 y 25, y la versión 3.x con Vaadin 14 a 23.

Qué hace por tus demos

Commons Demo se ocupa de todo lo que rodea a tus ejemplos: el layout, el código fuente y los temas. Tú escribes el ejemplo, y la demo se arma sola a su alrededor.

Una demo que parece un producto

Quien visita la demo llega a una página cuidada, no a un entorno de pruebas.

• Una pestaña por ejemplo. Cada ejemplo tiene su propia pestaña, con el nombre de su título de página, y su propia URL, así que puedes enlazar directamente a la funcionalidad que quieres mostrar. Cuando los ejemplos no entran en la barra de pestañas, los que sobran pasan a un menú, y una demo con un solo ejemplo puede ocultar las pestañas por completo.
• Verlo y leerlo al mismo tiempo. El ejemplo funcionando está al lado de su código. Con un clic se oculta el código, se pasa al otro lado o se alterna entre una vista lado a lado y una apilada. La elección se mantiene al pasar de un ejemplo a otro.
• Funciona en cualquier pantalla. En orientación vertical el layout se apila, y en los teléfonos el código arranca oculto para dejarle el espacio al componente.
• Claro, oscuro, Lumo o Aura. Quien visita la demo puede pasar al modo oscuro y, en Vaadin 25, cambiar entre Lumo, Aura y los estilos base, sin recargar la página. Es la forma más rápida de comprobar que un componente se ve bien en todos los casos.
• Siempre la versión correcta. El pie muestra el nombre y la versión del add-on, leídos del jar, así quien visita la demo sabe exactamente qué versión está probando.
• Se adapta a tu aplicación. Si quieres tus propios controles, el layout ofrece una API para eso. Nuestro sitio de add-ons la usa para llevar el selector de tema a su encabezado.

Código en el que puedes confiar

El código que se ve en pantalla es el código que se ejecuta.

• Siempre sincronizado. Commons Demo lee el código del propio archivo fuente del ejemplo en tu repositorio de GitHub, así quien visita la demo siempre ve el archivo real, nunca una copia pegada que queda desactualizada.
• En vivo mientras desarrollas. Cuando corres la demo en tu máquina, lee tus archivos locales, así ves tus cambios antes de subirlos.
• Código desde cualquier lugar. Si tu código está en otro lado, puedes conectar tu propio resolver. Nuestro sitio de add-ons usa uno para servir el código de cada add-on directamente desde su jar.

Código que se lee como un ejemplo

Las clases reales de una demo traen ruido: líneas de paquete, encabezados de licencia, anotaciones de ruteo, llamadas auxiliares. Quien visita la demo solo necesita la parte que vale la pena copiar.

• Limpio por defecto. El visor quita ese ruido y reduce la licencia a dos líneas.
• Tú decides qué se muestra. Agrega // hide-source a una línea que el lector no necesita, como un workaround o una preparación para tests, y desaparece del visor. Escribe // show-source seguido de código, y el visor muestra ese código aunque nunca se compile, algo útil cuando la llamada real tiene que hacerse por reflexión. Encierra líneas entre // #if vaadin ge 24 … // #else … // #endif, y quien visita la demo solo ve la rama de la versión de Vaadin en la que corre.
• Resalta lo importante. Marca la parte del código que hay detrás de una funcionalidad que vale la pena señalar. Al pasar el mouse o hacer clic sobre el componente, se resaltan las líneas correspondientes y se desplazan a la vista, incluso cuando están en otro archivo, como el CSS que le da estilo.
• Todos los archivos que necesite. Un ejemplo puede mostrar todos los archivos que necesite, Java, CSS o JavaScript, cada uno en su propia pestaña y con resaltado de sintaxis.

Novedad en 5.5: el código viaja con la demo

El código dentro del jar. Commons Demo 5.5 incorpora commons-demo-processor, un procesador de anotaciones que copia los archivos fuente de tus ejemplos dentro del jar al compilar. Combinado con un resolver que los lea desde el jar, como el de nuestro sitio de add-ons, la demo muestra el código exacto de la versión con la que se construyó, en lugar de lo que haya en la rama de GitHub. Esta es ahora la forma recomendada de usar Commons Demo, y nuestros add-ons ya lo usan al construir sus jars de demo.

Dónde puedes verla

Commons Demo impulsa dos sitios públicos de demos:

• Flowing Code Add-ons. Nuestro sitio de add-ons, construido con Commons Demo, reúne las demos de más de 35 add-ons de código abierto, desde Grid Exporter y Google Maps hasta Image Crop y XTerm. Todas las páginas de demo usan el mismo layout, así que pasar de un add-on a otro resulta familiar.
• Vaadin Component Factory Add-ons. También mantenemos el sitio de demos de los add-ons de Vaadin Component Factory. Hoy muestra más de 20, entre ellos Enhanced Grid, Autocomplete, PDF Viewer y Timeline, con el mismo layout de pestañas y el mismo visor de código.

En los dos sitios, cada add-on tiene su propia página con pestañas. Puedes probar cada ejemplo, leer el código exacto que hay detrás y cambiar el tema para ver cómo se ve el componente en modo claro u oscuro.

Cómo usarla

Para empezar alcanza con una dependencia y dos clases pequeñas.

Agrega la dependencia (en un proyecto de add-on, con scope test):

<dependency>
  <groupId>com.flowingcode.vaadin.addons.demo</groupId>
  <artifactId>commons-demo</artifactId>
  <version>5.5.0</version>
</dependency>

Crea una vista con pestañas que apunte a tu repositorio, y anota cada ejemplo con @DemoSource:

import com.flowingcode.vaadin.addons.GithubBranch;
import com.flowingcode.vaadin.addons.GithubLink;
import com.flowingcode.vaadin.addons.demo.TabbedDemo;

@Route("my-addon")
@GithubLink("https://github.com/your-org/my-addon")
@GithubBranch("master")
public class MyAddonDemoView extends TabbedDemo {

  public MyAddonDemoView() {
    addDemo(BasicDemo.class);
  }
}

import com.flowingcode.vaadin.addons.demo.DemoSource;
import com.flowingcode.vaadin.addons.demo.SourceCodeViewer;
import com.vaadin.flow.component.button.Button;
import com.vaadin.flow.component.notification.Notification;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.PageTitle;
import com.vaadin.flow.router.Route;

@DemoSource
@PageTitle("Basic")
@Route(value = "my-addon/basic", layout = MyAddonDemoView.class)
public class BasicDemo extends VerticalLayout {

  public BasicDemo() {
    // begin-block button
    Button button = new Button("Say hello", e -> Notification.show("Hello!"));
    button.setId("hello-button"); // hide-source
    SourceCodeViewer.highlightOnHover(button, "button");
    add(button);
    // end-block
  }
}

El visor oculta la línea del setId y la llamada a highlightOnHover, así que quien visita la demo solo ve el botón.

Ejecuta la aplicación, abre /my-addon y el ejemplo aparece junto a su código. El README cubre todo lo demás.

Gratis también para tus proyectos

Commons Demo no es solo para los add-ons de Flowing Code. Es gratuita y de código abierto, con licencia Apache 2.0, así que cualquiera puede usarla. Si desarrollas add-ons de Vaadin, o quieres mostrar los componentes de tu propia aplicación, te da una demo cuidada con código fuente en vivo sin que tengas que escribir nada de esa infraestructura.

Pruébala y cuéntanos qué te parece. ¿Hay alguna funcionalidad que extrañas, o algo que te facilitaría armar tus demos? Abre un issue en GitHub y cuéntanos. Los reportes de bugs y los pull requests también son bienvenidos. Nos encantaría ver lo que construyes con ella.