Incluir archivos JavaScript y CSS propios en el CMS bluetronix
En este tutorial, incluirás un archivo JavaScript propio y una hoja de estilos propia en el diseño de tu sitio web. Aprenderás la regla _own y cómo la versionado de archivos ayuda con los cambios.
Requisitos y objetivo
Para este tutorial necesitas un acceso de desarrollador al CMS de bluetronix y deberías conocer la estructura de los layouts y carpetas de desarrollador. Aprenderás a integrar archivos JavaScript y CSS propios además de los archivos existentes del CMS, sin modificar los archivos del sistema originales.
Usamos los archivos mostrados en las capturas de pantalla BxHeadScript_own.js y BxStyle_own.css. Ambos archivos se integran explícitamente en el layout, para que el CMS los considere al cargar la página web.
1. Abrir diseño
Abre en el CMS el área Layout y selecciona Layout - HTML. Luego abre el layout en el que deseas integrar tus archivos JavaScript y CSS. En este ejemplo utilizamos el layout estándar.
En la definición del layout ya encontrarás integraciones para los archivos centrales del CMS, como BxHeadScript.js y BxStyle.css. Puedes agregar tus propios archivos adicionales directamente al lado.
2. Crear archivo JavaScript propio en el administrador de archivos
Abre el Administrador de Archivos y cambia al directorio de sistema marcado en rojo bx_script. Allí encontrarás los archivos JavaScript centrales del CMS de bluetronix y, si es necesario, variantes dependientes del idioma.
Crea el archivo propio BxHeadScript_own.js o selecciónalo si ya existe. Puedes copiar un archivo existente adecuado como plantilla.
Selecciona Editar para abrir el código JavaScript de tu propio archivo en el editor de texto.
En el ejemplo mostrado, el archivo contiene código JavaScript propio para seleccionar entre el Modo Oscuro y el Modo Claro. En el editor de texto puedes mantener tu código JavaScript específico del proyecto y luego guardarlo.
No modifiques el original BxHeadScript.js para tus propias extensiones. Los archivos dentro de las carpetas del sistema bx_ pueden ser sobrescritos en actualizaciones del CMS. Marca tus propios archivos allí con _own.
3. Incluir archivo JavaScript propio en el diseño
Regresa a Layout - HTML. Añade tu propio archivo JavaScript además del archivo existente del CMS. Si deseas que tu script se cargue temprano, lo añades como se muestra en la captura de pantalla en la sección head después del Head-Script existente.
<script src="__FV_/bx_script/BxHeadScript_own_min.js__"></script>
<script src="__FV_/bx_script/BxHeadScript_own.js__"></script>
La línea adicional carga tu propio código JavaScript. El original BxHeadScript.js permanece sin cambios. La ruta del archivo y la escritura de tu archivo propio deben coincidir con el archivo en el Administrador de Archivos.
4. Crear archivo CSS propio en el administrador de archivos
Abre en el Administrador de Archivos la carpeta del sistema bx_style. Aquí se encuentra, entre otros, la hoja de estilos central BxStyle.css. Para modificaciones propias utilizamos un archivo separado llamado BxStyle_own.css.
Crea el archivo BxStyle_own.css o abre el archivo propio existente. El archivo del sistema BxStyle.css se mantiene.
A través de Editar, puedes agregar y guardar tus propias reglas CSS en este archivo.
5. Incluir archivo CSS propio en el diseño
Abre nuevamente Layout - HTML. En la sección head, añade tu propio archivo CSS después de la hoja de estilos existente. El orden es importante si deseas que tus propias reglas sobrescriban la formateación estándar.
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own_min.css__">
<link rel="stylesheet" href="__FV_/bx_style/BxStyle_own.css__">
El archivo CSS estándar permanece, mientras que administras formatos adicionales o diferentes por separado en BxStyle_own.css.
6. Usar JavaScript en el encabezado o al final de la página
Los archivos JavaScript pueden ser integrados según su función en la sección head o al final de la página antes de la etiqueta de cierre body. El BxHeadScript_own.js mostrado se carga en el Head. Para otros scripts también puedes usar una carpeta de proyecto propia e integrarlo más tarde en el layout.
Ejemplo de un archivo adicional de una carpeta propia al final de la página:
<script src="__FV_/bx_script/BxScript_own_min.js__"></script>
<script src="__FV_/script/MyScript.js__"></script>Este ejemplo muestra un archivo adicional. Si deseas reemplazar un archivo del sistema por una versión propia, debes ajustar las integraciones correspondientes en el layout elegido y comprobar que no falten funciones necesarias del CMS.
7. Distinguir entre carpetas del sistema y carpetas de proyectos propios
Las carpetas bx_ marcadas en rojo pertenecen al CMS de bluetronix. Los archivos propios dentro de estas carpetas deben estar marcados con _own para que no sean tratados como archivos del sistema en actualizaciones regulares del CMS.
Puedes almacenar tus archivos JavaScript y CSS alternativamente en carpetas de proyecto creadas por ti sin el prefijo bx_, como /script/ o /my_scripts/. Allí la marcación _own no es estrictamente necesaria. El camino real deberás usarlo en tu definición de layout.
La marcación _own no sustituye la integración en el layout: un archivo creado por separado solo se carga cuando se integra mediante la línea de script o link adecuada.
8. Versionado automático de archivos
En las integraciones de diseño mostradas, el CMS bluetronix utiliza la marca __FV_…__. A través de esto, el CMS puede agregar un parámetro de versión basado en la fecha de modificación. Después de un cambio, el navegador carga el archivo JavaScript o CSS actual, en lugar de seguir usando una versión en caché anterior.
Ejemplo: una ruta original como /script/MyScript.js puede ser complementada con un parámetro de versión después del procesamiento. No necesitas actualizar manualmente el número de versión en cada archivo integrado.
9. Guardar y comprobar cambios
Primero, guarda tus propios archivos JavaScript y CSS y luego el diseño editado. Recarga tu página web y verifica si se ejecutan tus funciones JavaScript y se aplican tus propias reglas CSS.
Si un archivo no se carga, primero verifica el nombre del archivo, las mayúsculas y minúsculas, la ruta de la carpeta y la integración en el diseño. Si se usan varios diseños, verifica también si has editado el diseño asignado a la página correspondiente.
Resumen
Para tus propias extensiones, crea por ejemplo BxHeadScript_own.js en la carpeta bx_script y BxStyle_own.css en la carpeta bx_style. Luego, integra ambos archivos en Layout - HTML además de los archivos originales del CMS. De este modo, los archivos estándar permanecen sin cambios, mientras que gestionas el código JavaScript y CSS específico del proyecto de forma separada.
Preguntas Frecuentes
lo que los clientes nos preguntan con frecuencia
¿Necesito acceso de desarrollador para integrar mis propios archivos JavaScript y CSS?
Sí. Este tutorial está dirigido a desarrolladores que tienen acceso a la definición del diseño y las carpetas de desarrolladores del CMS de bluetronix.
¿Dónde encuentro las integraciones para JavaScript y CSS?
Abre Layout y elige Layout - HTML. Allí puedes complementar las integraciones en el diseño deseado.
¿Dónde guardo un archivo JavaScript propio?
En el ejemplo mostrado, creas BxHeadScript_own.js en la carpeta bx_script y lo integras junto a BxHeadScript.js en el diseño.
¿Dónde guardo un archivo CSS propio?
En el ejemplo mostrado, el archivo propio BxStyle_own.css se encuentra en la carpeta bx_style. En el diseño, se integra después del archivo de estilo existente.
¿Por qué deberían los archivos propios contener _own en el nombre dentro de las carpetas del sistema?
Las carpetas de sistema bx_ marcadas en rojo pueden ser sobrescritas durante las actualizaciones. Con _own identificas tus propios archivos específicos del proyecto.
¿Se carga automáticamente un archivo _own en cuanto se crea?
No. Debes complementar tu archivo JavaScript o CSS en el diseño deseado con una integración adecuada de script o link.
¿Puedo usar una carpeta propia en lugar de una carpeta de sistema bx_?
Sí. En una carpeta de proyecto creada por ti sin el prefijo bx_, _own no es obligatorio. Utiliza la ruta de archivo real en el diseño.
¿Debería cargar mi propio archivo CSS antes o después del archivo estándar?
En el ejemplo mostrado, BxStyle_own.css se integra después de BxStyle.css. De esta manera, las reglas propias pueden sobrescribir las reglas estándar previamente cargadas si tienen la misma especificidad.
¿Para qué sirve la marca __FV_…__ en los caminos de archivos?
El CMS de bluetronix puede agregar un parámetro de versión de archivo, de modo que los navegadores carguen el archivo actual después de un cambio.
¿Qué debo verificar si mi archivo propio no se hace efectivo?
Revisa el nombre del archivo, las mayúsculas y minúsculas, la ruta especificada y la integración y selección del diseño correcto.