Saltar al contenido principal

Modificar o crear páginas de herramientas

Para crear o modificar una página de herramienta en el sitio web se necesita entender la estructura de componentes y archivos que conforman el sistema. A diferencia de los proyectos, las herramientas utilizan un sistema más avanzado con componentes React especializados y configuración JSON centralizada.

Estructura de archivos​

Archivos principales​

  • Punto de entrada: src/pages/repo/[nombre-herramienta].js
  • Componente principal: src/components/ToolPage/Prototipo1/index.js
  • Configuración de datos: static/json/tools-page.json
  • Estilos: src/components/ToolPage/Prototipo1/styles.module.css

Arquitectura del sistema​

Las herramientas siguen un patrón diferente al de los proyectos:

  1. Archivo de entrada JavaScript: Define la ruta y parámetros
  2. Configuración JSON centralizada: Contiene todos los datos de la herramienta
  3. Componente React avanzado: Renderiza dinámicamente basado en la configuración

Crear una nueva herramienta​

1. Crear el archivo de entrada​

Primero, necesitas crear un archivo JavaScript en src/pages/repo/ con el nombre de tu herramienta:

import React from 'react';
import ToolPage from '../../components/ToolPage/Prototipo1';
import { useLocation } from '@docusaurus/router';

export default function MiHerramientaPage() {
  const location = useLocation();
  const searchParams = new URLSearchParams(location.search);
  const toolId = searchParams.get('id') || 'mi-herramienta'; // ID por defecto
  
  return (
    <div>
      <ToolPage id={toolId} />
    </div>
  );
}

2. Configurar la herramienta en el JSON​

En el archivo static/json/tools-page.json, añade la configuración de tu herramienta:

{
  "id": "mi-herramienta",
  "bannerProps": {
    "title": "Mi Herramienta",
    "subtitle": "Descripción breve de la herramienta",
    "background": "mi-herramienta/background.jpg",
    "image": "mi-herramienta/logo.png",
    "darkness": 0.3,
    "logoUrl": "mi-herramienta/logo-nav.png"
  },
  "theme": {
    "accentColor": "#00577f",
    "secondaryColor": "#1D78A9",
    "backgroundColor": "#1b1b1d",
    "titleColor": "#fff",
    "companyLogo": {
      "show": true,
      "url": "logo.png",
      "link": "http://example.com"
    },
    "tabsTextColor": "white"
  },
  "highlightCards": [
    {
      "icon": "fas fa-cubes",
      "title": "Característica Principal",
      "description": "Descripción de la característica destacada"
    }
  ],
  "sections": [
    { "id": "description", "label": "Description" },
    { "id": "architecture", "label": "Architecture" }
  ],
  "content": {
    "description": {
      "title": "Descripción",
      "content": "<p>Contenido de la sección</p>"
    }
  },
  "footerLogo": "logo-footer.png"
}

3. Organizar recursos​

Crea una carpeta para tu herramienta en static/img/toolpage/mi-herramienta/ y coloca allí:

  • background.jpg: Imagen de fondo del banner (1920x1080px recomendado)
  • logo.png: Logo principal de la herramienta
  • logo-nav.png: Logo pequeño para la navegación
  • Otras imágenes que necesites

Estructura del banner​

El banner es la cabecera principal de la herramienta con soporte para parallax:

Banner de herramienta

Propiedades del banner:​

"bannerProps": {
  "title": "Nombre de la Herramienta",
  "subtitle": "Descripción breve que aparece debajo del título",
  "background": "mi-herramienta/background.jpg",
  "image": "mi-herramienta/logo.png",
  "darkness": 0.3,
  "logoUrl": "mi-herramienta/logo-nav.png"
}
  • title: Nombre principal de la herramienta
  • subtitle: Descripción breve que aparece debajo del título
  • background: Imagen de fondo del banner (ruta relativa desde static/img/toolpage/)
  • image: Logo principal que aparece en el banner
  • darkness: Nivel de oscurecimiento del fondo (0.0 - 1.0)
  • logoUrl: Logo que aparece en la navegación superior pegajosa

Sistema de temas​

Cada herramienta puede tener su propio esquema de colores:

"theme": {
  "accentColor": "#00577f",
  "secondaryColor": "#1D78A9", 
  "backgroundColor": "#1b1b1d",
  "titleColor": "#fff",
    "companyLogo": {
      "show": true,
      "url": "logo.png",
      "link": "http://example.com"
    },
    "tabsTextColor": "white"
}
  • accentColor: Color principal usado en tabs, enlaces, botones e indicadores
  • secondaryColor: Color secundario para efectos hover
  • backgroundColor: Color de fondo de toda la página
  • titleColor: Color del texto de los títulos
  • companyLogo: Permite añadir un logo extra a la vista de tabs. Se compone de tres parámetros y se puede omitir si no se quiere personalizar.
    • show: Activa (true) o desactiva (false) el logo extra. Por defecto, si no sé declara esta parte, esta activo y muestra el logo de ACG (versión blanco) para redirigir a la web.
    • url: Imagen para el logo secundario (ruta relativa desde static/img/toolpage/)
    • link: Dirección para redirigir a web deseada.
  • tabsTextColor: Modifica el color del texto de las tabs de navegación. Puede omitirse y se calculará un umbral según el color de acento para legibilidad, pero se puede personalizar con la palabra white para texto blanco, black para texto en negro o un hexadecimal cualquiera (ej. #8372d0) para tener una personalización completa del color.

Tarjetas destacadas (Highlight Cards)​

Las tarjetas destacadas aparecen justo después del banner y resaltan las características principales:

Tarjetas destacadas

"highlightCards": [
  {
    "icon": "fas fa-cubes",
    "title": "Arquitectura de Microservicios",
    "description": "Construido sobre una arquitectura escalable de microservicios"
  },
  {
    "icon": "fas fa-globe", 
    "title": "Web of Things (WoT)",
    "description": "Implementa el estándar W3C Web of Things"
  },
  {
    "icon": "fas fa-rocket",
    "title": "Alto Rendimiento", 
    "description": "Maneja grandes volúmenes de peticiones simultáneas"
  }
]

Limitación: Solo se mostrarán las primeras 3 tarjetas.

La navegación utiliza un sistema de pestañas pegajosas que siguen al usuario mientras hace scroll:

Navegación de pestañas

"sections": [
  { "id": "description", "label": "Descripción" },
  { "id": "metamodel", "label": "Metamodelo" },
  { "id": "architecture", "label": "Arquitectura" },
  { "id": "github", "label": "GitHub" }
]

Cada sección debe tener:

  • id: Identificador único usado para el scroll automático
  • label: Texto que aparece en la pestaña

Tipos de contenido por sección​

Sección básica con texto e imagen​

"description": {
  "title": "Descripción",
  "content": "<p>Contenido HTML de la sección</p>",
  "image": "mi-herramienta/architecture.png"
}
  • title: Título de la sección
  • content: Contenido HTML
  • image: Imagen que se puede ampliar con lightbox

Sección con columnas​

"github": {
  "title": "GitHub & Recursos",
  "columns": [
    {
      "title": "Código Fuente",
      "content": "<div class=\"github-card\"><i class=\"fa-brands fa-github\"></i><h4>Repositorio Principal</h4><p>Repositorio con la funcionalidad principal</p><a href=\"https://github.com/ejemplo\" class=\"github-link\">Visitar Repositorio</a></div>"
    }
  ]
}

Sección con galería de imágenes​

"example": {
  "title": "Ejemplo",
  "content": "<p>Descripción del ejemplo</p>",
  "gallery": {
    "items": [
      {
        "type": "image",
        "title": "Diagrama del Circuito",
        "src": "mi-herramienta/circuit.jpg",
        "description": "Diagrama completo del circuito del ejemplo"
      }
    ]
  }
}

Sección con videos​

"videos": {
  "title": "Tutoriales en Video",
  "content": "<p>Guías completas para configurar y usar la herramienta</p>",
  "videos": [
    {
      "type": "youtube",
      "title": "Configurando la Herramienta",
      "description": "Guía completa para configurar el entorno",
      "youtubeId": "_KkkUdqSMsU",
      "poster": "/img/tools/mi-herramienta/setup-poster.jpg"
    }
  ]
}

Sección con hitos (Milestones)​

"milestones": {
  "title": "Hitos del Desarrollo",
  "content": "<p>Los siguientes hitos representan los principales desarrollos</p>",
  "milestones": [
    {
      "title": "WoTnectivity",
      "content": "<p>Biblioteca multi-protocolo para IoT</p>",
      "image": "mi-herramienta/wotnectivity.png"
    }
  ]
}

Sección con publicaciones​

Para mostrar publicaciones relacionadas con la herramienta:

"github": {
  "title": "GitHub & Recursos",
  "publicationIds": ["228", "174", "197"]
}

También puedes definir publicaciones específicas:

"github": {
  "title": "Recursos",
  "publication": {
    "title": "Towards high-availability cyber-physical systems",
    "authors": "M. Mena, J. Criado, L. Iribarne",
    "journal": "Computing, Springer",
    "year": "2023",
    "link": "https://doi.org/10.1007/s00607-023-01165-x",
    "image": "img/tools/mi-herramienta/publication.jpg"
  }
}

El sistema incluye un lightbox automático para ampliar imágenes. Cualquier imagen en las secciones será clickeable y se podrá ampliar:

Lightbox de imagen

  • Imágenes individuales: Se amplían automáticamente
  • Galerías: Cada elemento de la galería se puede ampliar
  • Videos: Los videos de YouTube y normales se abren en lightbox

Publicaciones automáticas​

Si especificas publicationIds, el sistema buscará automáticamente en publicaciones.json y mostrará las publicaciones con formato estándar:

"publicationIds": ["228", "174", "197"]

Ejemplo completo de herramienta​

Aquí tienes un ejemplo completo de configuración para una herramienta:

{
  "id": "digital-dice",
  "bannerProps": {
    "title": "Digital Dice",
    "subtitle": "Virtual abstraction of IoT devices based on microservices",
    "background": "digitaldice/background-darkblue.jpg",
    "darkness": 0.3,
    "image": "digitaldice/DD_Logo.png",
    "logoUrl": "digitaldice/DD_CropLogo.png"
  },
  "theme": {
    "accentColor": "#00577f", 
    "secondaryColor": "#1D78A9",
    "backgroundColor": "#1b1b1d",
    "titleColor": "#fff"
  },
  "highlightCards": [
    {
      "icon": "fas fa-cubes",
      "title": "Microservices Architecture",
      "description": "Built on a scalable microservices architecture"
    }
  ],
  "sections": [
    { "id": "description", "label": "Description" },
    { "id": "architecture", "label": "Architecture" },
    { "id": "github", "label": "GitHub" }
  ],
  "content": {
    "description": {
      "title": "Description",
      "content": "<p>Digital Dice is a virtual abstraction of IoT devices...</p>"
    },
    "architecture": {
      "title": "Architecture",
      "content": "<p>The architecture shows how different components interact...</p>",
      "image": "digitaldice/DD_Architecture.png"
    },
    "github": {
      "title": "GitHub & Resources",
      "columns": [
        {
          "content": "<div class=\"github-card\">...</div>"
        }
      ],
      "publicationIds": ["228", "174", "197"]
    }
  },
  "footerLogo": "logoACGblanco.png"
}

Características avanzadas​

Soporte multiidioma​

El sistema detecta automáticamente el idioma de la URL (/en/ para inglés) y puedes crear contenido específico por idioma añadiendo el sufijo del idioma:

"content": {
  "description": {
    "title": "Description",
    "content": "<p>English content</p>"
  },
  "description_es": {
    "title": "Descripción", 
    "content": "<p>Contenido en español</p>"
  }
}

La navegación de pestañas es completamente táctil en dispositivos móviles, con scroll horizontal y hints visuales.