Obtiene la ayuda de cada herramienta (plugins y controles), si la tiene disponible), y la muestra en una página HTML. Además permite mostrar contenido extra indicado por el usuario antes y/o después de la ayuda de las herramientas. También permite descargar la ayuda en formato PDF.
Para que el plugin funcione correctamente es necesario importar las siguientes dependencias en el documento html:
- help.ol.min.js
- help.ol.min.css
<link href="https://componentes.cnig.es/api-core/plugins/help/help.ol.min.css" rel="stylesheet" />
<script type="text/javascript" src="https://componentes.cnig.es/api-core/plugins/help/help.ol.min.js"></script>
Existe un histórico de versiones de todos los plugins de API-CNIG en api-ign-legacy para hacer uso de versiones anteriores. Ejemplo:
<link href="https://componentes.cnig.es/api-core/plugins/help/help-1.0.0.ol.min.css" rel="stylesheet" />
<script type="text/javascript" src="https://componentes.cnig.es/api-core/plugins/help/help-1.0.0.ol.min.js"></script>
El constructor se inicializa con un JSON con los siguientes atributos:
-
position: Indica la posición donde se mostrará el plugin.
- 'TL': (top left) - Arriba a la izquierda.
- 'TR': (top right) - Arriba a la derecha (por defecto).
- 'BL': (bottom left) - Abajo a la izquierda.
- 'BR': (bottom right) - Abajo a la derecha.
-
tooltip: Tooltip que se muestra sobre el plugin (Se muestra al dejar el ratón encima del plugin como información). Por defecto: 'Ayuda'.
-
header: Objeto para indicar:
- images: Array de URLs de imágenes para mostrar en la cabecera. Por defecto: ['https://componentes.cnig.es/api-core/img/logo_ge.svg', 'https://componentes.cnig.es/api-core/img/ign.svg']
- title: Título para mostrar en la cabecera. Por defecto: 'Ayuda API-CNIG'.
-
initialIndex: Indica en que índice se abrira la página de ayuda.
-
initialExtraContents: Contenido extra para mostrar antes de la ayuda de las herramientas. Permite un array de objetos con el siguiente formato: [{title: 'Texto', content: 'HTML en formato texto'}]. El objeto también puede contener subcontenido que consiste en un array de objetos. Ejemplo:
[ { title: 'Texto', content: 'HTML en formato texto', subContents: [{title: 'Texto 2', content: 'HTML en formato texto 2'}] }, ]
En caso de desear implementar varios idiomas el parámetro initialExtraContents permitirá recibir un objeto con los diferentes idiomas. Ejemplo:
{ es: [{ title: 'Texto en español', content: 'HTML en formato texto en español' }], en: [{ title: 'Texto en inglés', content: 'HTML en formato texto en inglés' }] }
Nota: mostará el idioma del visualizador.
-
finalExtraContents: funciona igual que initialExtraContents.
-
extendInitialExtraContents: Booleano que permite extender el contenido inicial con información definida de la API-CNIG. Por defecto: true.
URL_API?help=position*tooltip*extendInitialExtraContents
Parámetros | Opciones/Descripción | Disponibilidad |
---|---|---|
position | TR/TL/BR/BL | Base64 ✔️ | Separador ✔️ |
tooltip | Texto informativo | Base64 ✔️ | Separador ✔️ |
header | Cabecera para la página de ayuda | Base64 ✔️ | Separador ❌ |
initialExtraContents | Contido para añadir antes de la ayuda de las herramientas | Base64 ✔️ | Separador ❌ |
finalExtraContents | Contido para añadir después de la ayuda de las herramientas | Base64 ✔️ | Separador ❌ |
extendInitialExtraContents | Permite extender el parámetro initialExtraContents con información definida de la API-CNIG. | Base64 ✔️ | Separador ✔️ |
https://componentes.cnig.es/api-core/?help=TR*Obtener%20ayuda*true
Para la codificación en base64 del objeto con los parámetros del plugin podemos hacer uso de la utilidad M.utils.encodeBase64. Ejemplo:
M.utils.encodeBase64(obj_params);
Ejemplo del constructor:
{
position: "TR",
tooltip: "Obtener ayuda",
}
https://componentes.cnig.es/api-core/?help=base64=ewogIHBvc2l0aW9uOiAiVFIiLAogIHRvb2x0aXA6ICJPYnRlbmVyIGF5dWRhIiwKfQ==
const mp = new M.plugin.Help({
position: 'BL',
tooltip: 'Obtener ayuda',
images: [
'https://www.ign.es/iberpix/static/media/logo.72e2e78b.png',
],
title: 'Título definido por el usuario',
extendInitialExtraContents: true,
initialExtraContents: [
{ title: 'Apartado 1', content: '<div><h2 style="text-align: center; color: #fff; background-color: #364b5f; padding: 8px 10px;">Mi primer apartado</h2><div><p>Contenido extra definido por el usuario</p></div></div>',
}
],
finalExtraContents: [
{ title: 'Apartado final', content: '<div><h2 style="text-align: center; color: #fff; background-color: #364b5f; padding: 8px 10px;">Apartado final</h2><div><p>Contenido extra definido por el usuario</p></div></div>',
}
]
});
Las herramientas disponen de un estilo en el título para que aparezca más destacado que el contenido. Si se desea indicar en el contenido extra que añada el usuario se debe añadir la siguiente regla css en el elemento del título, normalmente en la etiqueta h2:
style="text-align: center; color: #fff; background-color: #364b5f; padding: 8px 10px;"
Cuando pulsamos en el botón para descargar el contenido en PDF podemos realizar más ajustes antes de generar el documento. Para ello, en la ventana que se abre al pulsar el botón, podemos acceder a "Más ajustes".
Se recomienda no utilizar imágenes que pesen más de 1,5 MB.
Para el stack de desarrollo de este componente se ha utilizado
- NodeJS Version: 14.16
- NPM Version: 6.14.11
- Entorno Windows.
Para descargar el repositorio en otro equipo lo clonamos:
git clone [URL del repositorio]
npm i
npm start:ol
npm start:cesium
/
├── src 📦 # Código fuente
├── task 📁 # EndPoints
├── test 📁 # Testing
├── webpack-config 📁 # Webpack configs
└── ...
Metodologías y herramientas usadas en el proyecto para garantizar el Quality Assurance Code (QAC)
- ESLint
Para la revisión y actualización de las dependencias de los paquetes npm es necesario instalar de manera global el paquete/ módulo "npm-check-updates".
# Install and Run
$npm i -g npm-check-updates
$ncu