Saltar al contenido principal

ADR-004: Sidebar de gamificación vía overrides de theme + mini-bloque (Alcance 1)

Estado: Aceptado | Fecha: 2026-07-14 | Autores: Equipo Campus Virtual

Contexto​

El Alcance 1 (Gamificación) era deliberadamente no-code: block_xp Community + badges nativas + block_stash, solo configuración. El diseño Figma del Gamification Sidebar (node 19829-3930) rediseña el drawer del curso con 3 tarjetas: la gema de experiencia (datos de block_xp), la colección de logros del curso (badges ganadas/bloqueadas) y un CTA de insignias. Ese nivel de presentación no es alcanzable solo con configuración, y las reglas del proyecto prohíben tocar core o el código de plugins de comunidad.

Opciones consideradas​

Opción 1: Fork de block_xp​

  • Ventajas: control total sobre plantillas y renderer.
  • Desventajas: rompe la vía de actualización del plugin (v19 → v20 exigiría re-aplicar el fork); pasa a ser código propio con la superficie completa del plugin; contradice la preferencia por community plugins sin modificar.

Opción 2: block_badges core para la colección de logros​

  • Ventajas: cero código nuevo.
  • Desventajas: solo lista insignias ganadas vía core_badges_renderer::print_badges_list (renderer compartido con perfil y mybadges); no muestra bloqueadas, contador ni CTA; restylearlo afectaría otras páginas.

Opción 3 (elegida): overrides de theme para block_xp + mini-bloque nuevo​

  • Card 1: theme_cdigital ya usa theme_overridden_renderer_factory; el renderer legacy de block_xp (block_xp_renderer, no namespaced) se extiende con la clase autoloaded theme_cdigital\output\block_xp_renderer (override de level_name(), delegando al padre cuando $force=true), más copias adaptadas de block_xp/xp-widget.mustache y block_xp/progress-bar.mustache en el theme.
  • Cards 2+3: bloque nuevo block_pccntr8203403_logros (solo lectura sobre badgeslib.php: badges_get_badges con $perpage=0 + badges_get_user_badges), sin settings, sin AMD, sin styles propios.
  • Estilos: theme/cdigital/scss/gamification.scss concatenado en theme_cdigital_get_main_scss_content(); Lexend auto-hospedada.

Decisión​

Opción 3. El motor de gamificación sigue siendo configuración (block_xp + badges nativas); el código nuevo se limita a la capa de presentación en el theme y a un bloque de solo lectura, ambos actualizables de forma independiente de block_xp.

Consecuencias​

  • Acoplamiento blando al contrato interno de block_xp: las plantillas copiadas consumen las variables que exporta xp_widget::export_for_template() y el override depende de la firma de level_name(). Si v20 las cambia, la tarjeta degrada al aspecto por defecto (sin pérdida de datos ni errores fatales).
  • Checklist de upgrade de block_xp (ejecutar en cada actualización del plugin):
    1. Diff de blocks/xp/templates/xp-widget.mustache y progress-bar.mustache contra las copias en theme/cdigital/templates/block_xp/.
    2. Verificar la firma de block_xp_renderer::level_name() y que el renderer siga siendo legacy (no namespaced); si migra a namespaced, adaptar la clase del theme.
    3. Verificar que xp() siga envolviendo los puntos en .block_xp-xp .pts/.sign (el SCSS los recolorea).
    4. Purga de cachés + smoke test visual en el curso piloto.
  • El bloque de logros solo depende de APIs públicas estables de badges (badgeslib.php), sin riesgo equivalente.