{"id":21674218,"url":"https://github.com/aehrc/redcap_simple_ontology_provider","last_synced_at":"2025-05-08T22:27:38.168Z","repository":{"id":68118992,"uuid":"158644247","full_name":"aehrc/redcap_simple_ontology_provider","owner":"aehrc","description":"REDCap external module provides simple implementation of the ontology provider mechanism.","archived":false,"fork":false,"pushed_at":"2021-05-03T22:47:14.000Z","size":1328,"stargazers_count":6,"open_issues_count":4,"forks_count":0,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-03-31T18:51:43.905Z","etag":null,"topics":["redcap","redcap-external-module","redcap-repo"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aehrc.png","metadata":{"files":{"readme":"README.es.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-22T04:57:25.000Z","updated_at":"2025-01-30T18:57:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"cdce932b-328a-433d-86ce-cc39606a9b9a","html_url":"https://github.com/aehrc/redcap_simple_ontology_provider","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aehrc%2Fredcap_simple_ontology_provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aehrc%2Fredcap_simple_ontology_provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aehrc%2Fredcap_simple_ontology_provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aehrc%2Fredcap_simple_ontology_provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aehrc","download_url":"https://codeload.github.com/aehrc/redcap_simple_ontology_provider/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253156912,"owners_count":21863022,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["redcap","redcap-external-module","redcap-repo"],"created_at":"2024-11-25T13:43:30.518Z","updated_at":"2025-05-08T22:27:38.148Z","avatar_url":"https://github.com/aehrc.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Módulo Externo de Ontología Simple\n\nEste módulo externo de REDCap permite definir un conjunto personalizado de ‘ontologías’ que se puede utilizar para \nproveer funcionalidad de autocompletar un campo de texto. Las ontologías se pueden definir a nivel de sitio o proyecto \ny se puede especificar un valor por defecto que se debe desplegar si no se encuentran resultados. Desde la version 0.4, \nse agregó una opción para intercambiar entre búsqueda por palabras y búsqueda por el texto completo. \n\nLa versión 0.5 introduce soporte para sinónimos y marcando entradas como inactivas.\n\nLa licencia de este módulo se encuentra bajo el Acuerdo de Licencia de Código Abierto de CSIRO (una variación de la licencia BSD/MIT).\n\nEste módulo externo es un ejemplo muy sencillo que demuestra la funcionalidad autocompletar.  Se puede configurar para aportar una colección de valores para toda la instalación de REDCap o a nivel de proyecto que se pueden referenciar dentro de los formularios.\n\n\n## Configuración del módulo\nOpción predeterminada: descargue el módulo desde el Repositorio de módulos externos de REDCap\n\nOpción 2: descargue el módulo de Github y colóquelo descomprimido en la carpeta de módulos, por ej., redcap/modules/simple_ontology_provider_v0.5. El módulo se volverá visible en REDCap, dentro de los Módulos Externos, para que lo pueda habilitar y acceder a notificaciones cuando hay actualizaciones disponibles.\n\nLa configuración se usa para seleccionar las ontologías que usará localmente. Si la ontología se añade en la configuración del Centro de Control estará disponible en todos los proyectos. Las ontologías específicas para el proyecto se añaden como ajustes del proyecto para el módulo. Si coloca la misma ontología en los módulos externos del centro de control y del proyecto, usará la del proyecto.\n\nNo hay límite en el número de ontologías que puede agregar, usando los siguientes campos:\n\n * `Categoría de la ontología` - Este es el nombre interno para la ontología y debe ser exclusiva para esa ontología.\n * `Nombre de la ontología` - Este es el nombre que se presentará cuando seleccione la ontología en el Diseñador en-línea.\n * `Tipo de búsqueda` - Este menú desplegable se utiliza para seleccionar el algortimo de búsqueda que se quiere utilizar. Las opciones son:\n    * `Basado en palabras` - Este es el mecanismo de búsqueda introducido en la versión 0.3 en el cual cada palabra se busca por separado.\n    * `Texto completo` - La búsqueda se realiza usando el texto completo sin ningún comportamiento especial para las palabras.\n * `Avisar cuando no hay resultado 'Sin resultado'` - Esta casilla se usa para indicar que debe retornar un valor especial si la búsqueda no obtiene resultados.\n El propósito de esto es permitir que se seleccione la opción y luego activar un campo adicional a través de lógica de ramificación para recibir datos adicionales.\n También se puede usar para seleccionar un valor predeterminado.\n * `Mensaje cuando no hay resultado` - El valor a mostrar para el valor especial devuelto si se habilita la opción `Responder que no se hallaron resultados`.\n * `Código cuando no hay resultado` - El valor a mostrar para el valor especial devuelto si se habilita la opción `Responder que no se hallaron resultados`.\n * `Opciones de valores` - Esto se usa para indicar cómo se presentarán los valores. Las opciones son:\n    * `list` - Una lista de valores, separados por una línea nueva. El valor y la descripción son iguales.\n    * `bar` - Una lista de códigos y descripciones usando '|' como separador. Cada uno está separado con una línea. OJO: la búsqueda se hace sobre la descripción, no sobre el código.\n    * `json` - Un grupo de objetos JSON con valor y descripción. Puede contener otros campos, pero solo se usará el código (code) y la descripción (display). Por ejemplo:\n```\n[\n { \"code\" : \"Primer Director\",      \"display\" : \"William Hartnell\",      \"periodo\" : \"1963-11-23 1966-10-29\" },\n { \"code\" : \"Segundo Director\",     \"display\" : \"Patrick Troughton\",     \"periodo\" : \"1966-10-29 1969-06-21\" },\n { \"code\" : \"Tercer Director\",      \"display\" : \"Jon Pertwee\",           \"periodo\" : \"1970-01-03 1974-06-08\" },\n { \"code\" : \"Cuarto Director\",      \"display\" : \"Tom Baker\",             \"periodo\" : \"1974-06-08 1981-03-21\" },\n { \"code\" : \"Quinto Director\",      \"display\" : \"Peter Davison\",         \"periodo\" : \"1981-03-21 1984-03-16\" },\n { \"code\" : \"Sexto Director\",       \"display\" : \"Colin Baker\",           \"periodo\" : \"1984-03-16 1986-12-06\" },\n { \"code\" : \"Séptimo Director\",     \"display\" : \"Sylvester McCoy\",       \"periodo\" : \"1987-09-07 1989-12-06\" }\n]\n```\n * `Valores` - Los valores que se importarán en la ontología. El formato depende del tipo de valores seleccionado.\n\n### Sinónimos\n\nLa versión 0.5 de este modulo introduce soporte para sinónimos. Un sinónimo es una representación textual alternativa \npara un código. El texto del sinónimo también puede ser parte de las búsquedas, pero el rótulo principal siempre será \ndevuelto.\n\nLos sinónimos se puede adicionar utilizando los formatos de barras y JSON. Para el formato de barras, los  sinónimos \nse adicionan utilizando barras verticales para separar los sinónimos. Por ejemplo,\n\n```text\nfan|Robert Fanning|Bob Fanning|fan\nche|Justine Brown|Justine Chen|Jai Li Chen|che\ncoo|Cooper Derricks|coo\ncol|Morty Cole|col\n```\n\nadiciona el código con un término de búsqueda pero también adiciona versiones alternativas de los nombres. Cualquier \nnúmero de sinónimos pueden ser adicionados, pero para este formato deben estar en la misma línea. \nEn el formato JSON, el atributo ‘synonyms’ se utiliza para proveer una lista de sinónimos. La siguiente es la \ndefinición equivalente en formato JSON:\n\n\n```json\n[\n{\"code\": \"fan\", \"display\": \"Robert Fanning\", \"synonyms\": [\"Bob Fanning\", \"fan\"]},\n{\"code\": \"che\", \"display\": \"Justine Brown\", \"synonyms\": [\"Justine Chen\", \"Jai Li Chen\", \"che\"]},\n{\"code\": \"coo\", \"display\": \"Cooper Derricks\", \"synonyms\": [\"coo\"]},\n{\"code\": \"col\", \"display\": \"Morty Cole\", \"synonyms\": [\"col\"]}\n]\n```\n\n![Searching with a synonym](SimpleOntologySynonym.png)\n\n### Bandera Activo\n\n\nLa versión 0.5 del módulo introduce soporte para una bandera que indica si una entrada está activa. Una entrada donde \nla bandera esté desactivada (active  = false) no aparecerá en los resultados de búsqueda pero todavía es un miembro \nde la ontología y por lo tanto todavía aparecerá si ha sido utilizada en el pasado.\n\nLa forma de indicar si una entrada esta activa o no depende del formato utilizado para ingresar los valores. Si el tipo \nde valor es lista o barra entonces la entrada se marca como inactiva adicionando el símbolo `!` al comienzo de la línea. \nSi el código comienza con un `!` entonces puede ser escapado con un `\\`\n\n```text\nfan|Robert Fanning|Bob Fanning|fan\nche|Justine Brown|Justine Chen|Jai Li Chen|che\ncoo|Cooper Derricks|coo\n!col|Morty Cole|col\n\\!escape|Code with an leading !\n```\n\nEn el ejemplo de barras de arriba, Morty Cole se considera inactive y no aparecerá como una opción cuando se esté \nseleccionado un elemento de la ontología. El código `!escape` debe ser escapado con un `\\`\n\nPara valores json, el valor se adiciona a través del atributo activo.\n\n```json\n[\n{\"code\": \"fan\", \"display\": \"Robert Fanning\", \"synonyms\": [\"Bob Fanning\", \"fan\"]},\n{\"code\": \"che\", \"display\": \"Justine Brown\", \"synonyms\": [\"Justine Chen\", \"Jai Li Chen\", \"che\"]},\n{\"code\": \"coo\", \"display\": \"Cooper Derricks\", \"synonyms\": [\"coo\"]},\n{\"code\": \"col\", \"display\": \"Morty Cole\", \"active\": false, \"synonyms\": [\"col\"]}\n]\n```\n\nEste es el equivalente en formato json. Si el atributo active no está presente o su valor es diferente a false la \nentrada se considerará activa.\n\n![SimpleOntology Settings](SimpleOntologySettings_v0.4.es.png)\n\n## Búsqueda basada en palabras\nLa funcionalidad de autocompletar implementada por el módulo siempre hará una búsqueda de texto simple en el texto de despliegue para el texto ingresado. En la versión 0.3, un mecanismo basado en palabras fue implementado, pero en la versión 0.4 una nueva opción ha sido agregada para seleccionar entre búsqueda por palabras y búsqueda por el texto completo.\nPara la búsqueda basada en palabras, en vez de buscar una cadena de texto que corresponda de manera exacta, el módulo buscará cada palabra en la consulta por separado y devolverá todos los resultados ordenados por el número de palabras que coincidieron y después por la posición donde fueron encontradas.\nEste comportamiento tiene el effecto secundario de que algunos resultados parciales pueden no ser resaltados en la interfaz gráfica. La interfaz gráfica de autocompletar en REDCap toma el término de búsqueda utilizado y resalta la parte correspondiente del texto en el menú deplegable.\n\nPor tanto, si busca coronav obtiene como resultado:\n- *Coronav*irus aviar\n- *Coronav*irus bovino\n- *Coronav*irus canino\n\nLa porción 'coronav' de cada opción quedará resaltada.\n\nPero si busca 'tuberculosis bacteria' y obtiene como resultado:  \n- 10044772: Tuberculosis suprarrenal, confirmada por cultivo bacteriano\n- 10044780: Tuberculosis vesical, confirmada por cultivo bacteriano\n- 10044799: Tuberculosis ótica, confirmada por cultivo bacteriano\n\nNo se resaltará ningún resultado, por cuanto se resaltan solamente los resultados coincidentes. \n\n\n\nEl modulo procesa los códigos y los rótulos en un arreglo asociativo antes de retornar los resultados de búsqueda. \nSi varias entradas tienen el mismo código entonces la última entrada sobrescribirá las entradas existentes.\n\n## Soporte de @HIDECHOICE\n\nParte de la funcionalidad que se ah adicionado a este módulo es soportar la etiqueta de acción (action tag) @HIDECHOICE. \nEsta etiqueta está disponible para los campos de selección para indicar que una opción no debe ser mostrada. Esto se \npuede lograr de manera global en este módulo utilizando la bandera active para marcar un código como inactivo. \nLa etiqueta @HIDECHOICE, sin embargo, se especifica a nivel de campo. El valor solo se dejará de mostrar para el campo \ndonde se utilizó la etiqueta. El conjunto de valores que se quieren esconder se especifican utilizando una lista \nseparada por comas. El módulo considera todas las entradas @HIDECHOICE encontradas en las propiedades de anotación del campo.\n\n```text\n@HIDECHOICE='code1,code2'\n```\n![Adding the @HIDECHOICE action tag](SimpleOntologyHideChoice.png)\n\n## Proveedor de ontología\n\nComo parte de REDCap v8.8.1 se agregó un punto de extensión para permitir que los módulos externos puedan ofrecer servicios de ontologías (*'Ontology Provider'*). Funciona de manera similar al mecanismo del BioPortal de ontologías, pero permite cargar terminologías/vocabularios alternativos. La función principal de un Proveedor de ontologías es la de recibir un término de búsqueda y mostrar las coincidencias de código y descripción.\n\nEste módulo es un ejemplo muy sencillo de un módulo externo que aporta esta funcionalidad. \n\nPara funcionar como Proveedor de ontologías, el módulo externo debe:\n\n  * Implementar la interfaz de Proveedor de ontología\n  * Registrarse con el Gestor de ontologías\n  * Registrarse para cada *'page hook'*. (El Diseñador en línea no tiene sus propios ganchos o *'hooks'*)\n\n### Interfaz del Proveedor de ontologías\n\nUn Proveedor de ontologías permite que un tercero ofrezca una o más ontologías, como lo hace Bioportal o fhir.\n\nEsta ontología se especifica en la definición de un campo como el *'enum_element'* y se mantendrá persistente usando la forma servicio:categoría\n\nEl nombre del servicio seleccionado determinará cuál proveedor de ontología será usado.\n\n#### Seleccionando la ontología:\n\nSeleccionar la ontología es un proceso de dos pasos, primero se selecciona un servicio de la lista de proveedores disponibles y esto permitirá la selección de una categoría del servicio. El proveedor debe producir una secuencia que existirá dentro de \nun div oculto para el servicio que que se mostrará cuando el servicio se muestre, este div contendrá los elementos ui para seleccionar la categoría del servicio. Una vez hecha la selección, la ui debe llamar una función javascript update_ontology_selection($service, $category), que habilitará un elemento de forma oculto usado para configurar el valor en el campo. De manera adicional, el proveedor podría querer incluir una función javascript\nque será llamada cuando el campo se poble para que la ui pueda reflejar la selección actual. Esta función debe tomar la forma \u003cservice\u003e_ontology_changed(service, category).\n\n#### Búsqueda dentro de una ontología:\n\n   El proveedor aporta el mecanismo usado por autocompletar para que busque la ontología. Este método hace que cualquier petición ajax devuelva los valores y la etiqueta que va junto con la selección.\n\n## Configuración predeterminada\n\nEstos son los valores predeterminados. No hace falta modificarlos en una instalación normal\n\n```\ninterface OntologyProvider {\n\n  /**\n    * return the name of the ontology service as it will be display on the service selection\n    * drop down.\n    */\n  public function getProviderName();\n\n  /**\n    return the prefex used to denote ontologies provided by this provider.\n   */\n  public function getServicePrefix();\n\n  /**\n    * Return a string which will be placed in the online designer for\n    * selecting an ontology for the service.\n    * When an ontology is selected it should make a javascript call to \n    * update_ontology_selection($service, $category)\n    *\n    * The provider may include a javascript function\n    * \u003cservice\u003e_ontology_changed(service, category)\n    * which will be called when the ontology selection is changed. This function\n    * would update any UI elements is the service matches or clear the UI elemements\n    * if they do not.\n    */\n  public function getOnlineDesignerSection();\n\n  /**\n   * Search API with a search term for a given ontology\n   * Returns array of results with Notation as key and PrefLabel as value.\n   */\n  public function searchOntology($category, $search_term, $result_limit);\n\n\n  /**\n   *  Takes the value and gives back the label for the value.\n   */\n  public function getLabelForValue($category, $value);\n```\n\n### Registro con el Gestor de ontologías\n\nUna vez que un módulo externo tiene la implementación de Proveedor de ontologías, el siguiente paso es asegurar que el proveedor está registrado para el uso. Esto se hace usando el código \n```\n      // register with OntologyManager\n      $manager = \\OntologyManager::getOntologyManager();\n      $manager-\u003eaddProvider($provider);\n```\n\n### Registro para un 'every page hook'\nPara que el proveedor de ontologías esté disponible el módulo externo necesita registrarse para redcap_every_page hook. En este módulo el proveedor de ontologías está registrado cuando se construye el módulo, por lo que nada debe suceder durante la función hook, puesto que el registro ya se llevó a cabo.\n\nEn el archivo config.json del módulo externo añada:\n```\n\"permissions\": [\n        \"redcap_every_page_before_render\"\n    ],\n```\n\nEn el módulo externo añada:\n```\n public function redcap_every_page_before_render ( $project_id ){\n  }\n```\nTraducido: 2020-07-31 para la v0.4\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faehrc%2Fredcap_simple_ontology_provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faehrc%2Fredcap_simple_ontology_provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faehrc%2Fredcap_simple_ontology_provider/lists"}