Manual del juego de rol Codex Estigma, por BasilioGarcia.
El manual puede ser consultado online AQUÍ ⤴.
- HTML5, CSS3, JavaScript y JQuery (ver sección: Uso real de JQuery)
- Sistema de plantillas propio creado en JS (uso de Promesas y caché de archivos).
- Diseño responsive con cinco breakpoints: <768px, 768px, 992px, 1200px y 1638px.
- Nesting CSS nativo. (ver sección: Por qué no BEM)
- Animaciones con CSS.
- Eliminado el scroll nativo del navegador, custom scroll en bloques de contenido, compatible con dispositivos móviles.
- Subsecciones del menú visibles con efecto onHover que es compatible con dispositivos móviles.
- Auto-creación de anchors internos
- Enlaces referenciales
Debido a que este manual ejecuta funciones avanzadas de JavaScript, requiere ser interpretado en un servidor web HTTP, como Apache, IIS o Ngnix.
Este manual usa un sistema de plantillas propio. En vez de tener que repetir todas las etiquetas HTML en cada página, usa un código HTML mínimo para crear los artículos y el motor en JavaScript de la plantilla se encarga de crear el resto del documento. El menú y el paginado se crean de forma automática configurando un archivo.
Note
Creé este sistema, porque a medida que el manual iba teniéndo más páginas se volvía un engorro tanto el modificar código que afectaba a muchas páginas, como el reestructurar el orden de las páginas (cuando tienes que cambiar la URL de un enlace en más de 100 páginas HTML, echas de menos los sistemas de plantillas propios de los backends).
Existen dos tipos de páginas, las individuales y las que tienen sub-páginas. Para crear una nueva página, hay que crear una nueva carpeta en la carpeta “pages”, situada en la raíz del proyecto.
Si la página nueva, es una página individual, dentro de la carpeta creada deben de añadirse dos documentos:
- index.html – Contendrá el HTML de la página.
- page.css – Contendrá el CSS específico de esa página. (en muchas páginas está en blanco)
El archivo index.html tendrá el siguiente esquema:
<!DOCTYPE html>
<meta charset="UTF-8" xmlns="http://www.w3.org/1999/html">
<script src="../../js/init.js"></script>
<page data-dir="../.." data-chapter="3">
HTML propio de ese artículo.
</page>
El código HTML de la página va dentro de la etiqueta page. Esta etiqueta tiene dos atributos: data-dir y data-chapter.
- data-dir : Indica la ruta a la raíz del proyecto, se usa para cargar correctamente los archivos. En las páginas individuales su valor es: “../..”
- data-chapter : Es un ID que indica con que entrada del archivo chapters.json (ver más adelante) se corresponde ésta página.
A continuación hay que añadir la entrada de la página al archivo de configuración de capítulos: chapters.json en ./js/db/chapters.json:
"0": {
"title": "Codex Estigma"
},
"1": {
"title": "Sobre Codex Estigma",
"url": "/pages/acerca-de"
},
"2": {
"title": "Tiro base",
"url": "/pages/tiro-base"
},
etc...El ID de cada entrada es un número “0”, “1”, “2”… que van ordenados de forma auto-incremental y comenzando siempre en cero. El cero es la portada y no será visible en el menú ni en el paginado. El orden del resto de entradas será con el que aparezcan en el menú y en el paginado. Así, en el ejemplo de arriba, la entrada con el ID 2, Tiro Base, sería el segundo enlace en el menú.
La entrada tiene dos atributos: title y url.
- title : Es el título de la página, se usa tanto en el menú, como en el encabezado de la página, como en la etiqueta <title>
- url : Es la URL de donde va a cargar los archivos. Se compone de la concatenación de /pages/ más el nombre de la nueva carpeta que se ha creado.
Si la página nueva, es una página con sub-páginas, dentro de la carpeta creada deben de añadirse, a su vez, una sub-carpeta por cada sub-página. Y dentro de cada sub-carpeta, deben de añadirse dos documentos:
- index.html – Contendrá el HTML de la página.
- page.css – Contendrá el CSS específico de esa página. (en muchas páginas está en blanco)
El archivo index.html tendrá el siguiente esquema:
<!DOCTYPE html>
<meta charset="UTF-8" xmlns="http://www.w3.org/1999/html">
<script src="../../../js/init.js"></script>
<page data-dir="../../.." data-chapter="7" data-section="1">
HTML propio de ese artículo.
</page>El código HTML de la página va dentro de la etiqueta page. Esta etiqueta tiene tres atributos: data-dir, data-chapter y data-section.
- data-dir : Indica la ruta a la raíz del proyecto, se usa para cargar correctamente los archivos. En las páginas con sub-páginas su valor es: “../../..”
- data-chapter : Es un ID que indica con que entrada del archivo chapters.json (ver más adelante) se corresponde ésta página.
- data-section : Es un ID que indica con que sección de la entrada se corresponde ésta página (ver más adelante).
A continuación hay que añadir la entrada de la página al archivo de configuración de capítulos: chapters.json en ./js/db/chapters.json:
...
"6": {
"title": "Habilidades",
"url": "/pages/habilidades"
},
"7": {
"title": "Maniobras",
"sections": {
"1": {
"title": "Adquirir maniobras",
"url": "/pages/maniobras/adquirir-maniobras"
},
"2": {
"title": "Filo largo",
"url": "/pages/maniobras/filo-largo"
},
"3": {
"title": "Filo corto",
"url": "/pages/maniobras/filo-corto"
}
}
},
...En el código de ejemplo anterior, la entrada del archivo con el ID 6 es una página individual, y la entrada con el ID 7 es una página con sub-páginas.
Las entradas con sub-páginas tiene dos atributos: title y sections.
- title : Es el título de la página, se usa en el menú.
- sections : Son las entradas de las sub-páginas. Sus IDs son auto-incrementales y comienzan en 1. A su vez, tienen dos atributos: title y url, funcionan como las páginas individuales.
Note
Aunque el proyecto usa la biblioteca JQuery, la mayoría del código es JavaScript vanilla, simplemente he usado JQuery por la sintaxis de selectores del DOM abreviada y por el bindeo de eventos con propagación, que funcionan muy bien, me parecen las funcionalidades mejor optimizadas de JQuery. No soy muy fan del resto de funcionalidades de JQuery y creo que las soluciones en vainilla JS no sólo obtienen mejor performance, sino que aportan una metodología más ordenada. Por eso no he creado los componentes usando el sistema de componentes de JQuery, no me aportaban nada.
Tip
BEM sigue siendo un estándar importante para coordinar proyectos grandes donde múltiples personas trabajarán con los archivos CSS. Sin embargo, desde que CSS incorporó el nesting de forma nativa en 2021, se han facilitado métodos alternativos para mantener un código CSS limpio y organizado.
Además, creo que existe un mito exagerado, mal entendido, con la especificidad de los selectores CSS, y que la propagación de BEM y las enseñanzas de ciertos “gurús” contribuyeron a ello. La especificidad es una característica buscada por el W3C y es MUY UTIL. Una cosa es tener un lío impresionante con la jerarquía de los selectores y otra es que no aproveches una característica perfectamente válida de las hojas de estilos.
Por todo ello, y porque es un proyecto personal, con el que no voy a entrar en conflicto con otros desarrolladores, he decidido usar, no solo native nesting, sino usar selectores con IDs y etiquetas genéricas como: <aside>, <header>…
Aún así, como se puede ver en la imagen inferior, el nivel de especificidad es bajo, se puede mantener un equilibrio entre utilidad jerárquica y código limpio y ordenado.
Nombre del componente: internal-anchors
Si a unas de las etiquetas usadas en los títulos (<h2>, <h3> o <h4>) se le coloca un atributo ID, automáticamente se convierte en un enlace interno a ese título de la página.
Nombre del componente: pages-links
En el archivo links.json se registran enlaces con un nombre de referencia, a modo de identificador. En las páginas del manual que lo necesiten se agrega el enlace por el nombre de referencia, así, si luego el enlace cambia, no hay que cambiarlo en cada página donde se usó, solo hay que cambiarlo en el archivo links.json.
Nombre del componente: tooltips
https://github.com/BasilioGarcia/CodexEstigma
Leave a Reply