Jump to content

Extensión:JsonConfig

Rastreador de problemas: #JsonConfig
From mediawiki.org
This page is a translated version of the page Extension:JsonConfig and the translation is 100% complete.
Languages:
Manual de extensiones de MediaWiki
JsonConfig
Estado de lanzamiento: estable
Implementación ContentHandler , MyWiki
Descripción Proporciona un sistema de configuración JSON basado en wiki
Autor(es) Yuri Astrakhan (yurikdiscusión)
Última versión 1.1.1
Política de compatibilidad Lanzamientos de screenshots junto con MediaWiki. Master no es compatible con versiones anteriores.
MediaWiki 1.38+
Cambios de la base de datos No
Licencia GNU Licencia Pública general 2.0 o posterior
Descarga
Descargar la extensión.
Git [?]:

RFC
Parámetros

  • $wgJsonConfigs
  • $wgJsonConfigModels
Hooks que usa
Descargas trimestrales 268 (Ranked 20th)
Wikis públicos que lo utilizan 897 (Ranked 264th)
Traduce la extensión JsonConfig si está disponible en translatewiki.net
Asuntos Tareas abiertas · Reportar un bug

La extensión JsonConfig permite a otras extensiones almacenar sus datos de configuración en forma de blob JSON dentro de una página wiki.

Funcionalidades disponibles y patrones de uso

Ejemplo de visualización de JSON generada por la extensión JsonConfig
  • Puedes usar JsonConfig para almacenar datos de varias maneras:
    • en una sola página de configuración, por ejemplo, una serie de ajustes para su extensión en Config:MyExtSettings (Config es el espacio de nombres predeterminado asociado con la extensión JsonConfig);
    • en un conjunto de páginas con estructura similar que residen en su propio espacio de nombres, por ejemplo, direcciones IP de proxies conocidos o esquemas de registros de eventos nombrados «Proxy:Opera» o esquemas nombrados Schema:AccountCreation
    • usarlo solo para páginas cuyo título se ajuste a un patrón regex, p. ej. Config:Proxy:Opera or Config:Opera.proxy. Esto evita llenar un wiki con numerosos espacios de nombres, uno por cada modelo de contenido.
  • Puedes proporcionar una clase de contenido para la validación de datos (más allá del JSON válido) y su normalización.
  • Puedes proporcionar una clase de visualización para personalizar la apariencia del HTML.
  • Puedes almacenar datos:
    • «uno por wiki», «uno por agrupación (clúster)» o incluso por «familia» (estructura diferente de la clave de caché para el memcached compartido);
    • en un wiki público o privado y accesible con credenciales;
    • en una agrupación separada, y notificar de los cambios de forma remota.

Uso dentro del wiki

Actual

  • Conjuntos de datos tabulares de Commons
  • Conjunto de datos en mapas de Commons
  • Configuraciones de dashboards Dashiki
  • ¿Otros?

En el pasado

Instalación

  • Descarga y extrae los archivos en un directorio denominado «JsonConfig» dentro de la carpeta extensions/.
    Developers and code contributors should install the extension from Git instead, using:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/JsonConfig
  • Añade el siguiente código en la parte final de tu archivo LocalSettings.php : 
    wfLoadExtension( 'JsonConfig' );
  • Configúralo según se requiera.
  • Yes Hecho – Navega a Special:Version en el wiki para verificar que la extensión se haya instalado correctamente.

Configuración

$wgJsonConfigs

Esta variable define perfiles para cada tipo de página de configuración. $wgJsonConfigs es una matriz asociativa de matrices, teniendo cada una de las cuales cero o más de los siguientes parámetros. Por defecto, JsonConfig usa una clave en forma de cadena de caracteres como identificador del modelo que este perfil representa, pero en caso de que desees reutilizar el mismo identificador de modelo en más de un perfil, puedes invalidarlo mediante el parámetro model.

parámetro tipo por defecto descripción
model string (clave en $wgJsonConfigs) Identificador del modelo que usar al crear una página nueva. Si no se proporciona ninguno, la clave de matriz de este perfil se convierte en el identificador del modelo. Si se establece el valor a null, se usará el identificador JsonConfig del módulo predefinido. El identificador del modelo también debe estar en la lista de $wgJsonConfigModels excepto para null o 'JsonConfig'.
namespace int NS_CONFIG (482) Espacio de nombres en que residirán estas configuraciones, o 'Config:' por defecto
nsName string/false Para espacios de nombres no predeterminados (es decir, distintos de NS_CONFIG 482), se le asigna un nombre canónico (en inglés). Si más de una matriz $wgJsonConfigs usa el mismo espacio de nombres, fija el nombre una sola vez. Si no se encuentra, se dará una advertencia y el espacio de nombres recibirá automáticamente el nombre «ConfigNNN». En caso de que no se almacene localmente esta configuración, se usará nsName como espacio de nombres remoto sin declaración local.

Si deseas compartir espacio de nombres con otras páginas que no sean de contenido JsonConfig, fija este valor a false.

nsTalk string nsName+_talk Para espacios de nombres no predeterminados, se asigna a sus páginas de discusión un nombre canónico (en inglés).
pattern string (all) Expresión regular para coincidir con el título de la página en el espacio de nombres dado. Si está vacío, la configuración se aplicará a todas las páginas del espacio de nombres. Para adoptar el antiguo comportamiento de «subespacios», para isSubspace=true, usa el patrón ^/^name:./, y para isSubspace=false, usa el patrón /^name$/.
isLocal bool true Si el valor es true, esta configuración no se compartirá por toda la agrupación, sino que cada wiki tendrá una configuración local. Si el valor es false, se pretende que esta configuración se comparta entre múltiples wikis, y para hacer que este wiki específico la almacene en local, fija el campo 'store'.
Esta bandera afecta a la clave de caché, de forma que una página de configuración con el mismo nombre será almacenada en memcached si el valor es false, pero será única por wiki si el valor es true.
cacheExp int 24*60*60 Duración (en segundos) del almacenamiento del valor en caché en memcached
cacheKey string Si se ha establecido el valor, añade esa cadena a la clave de caché. Usa cacheKey para invalidar los valores anteriores en caché: p. ej. cuando realices un cambio incompatible que modificaría los valores en caché y te preocupa la posibilidad de que necesites revertirlo. Esta clave también se puede usar para permitir que todos los wikis en distintos idiomas pertenecientes a la misma familia compartan el mismo valor en caché a la vez que se almacenan en la misma página pero en wikis diferentes. Por ejemplo, Wikipedia podría usar «wp» y Wikiquote «wq».
flaggedRevs bool false Si el valor es true, se intentará recuperar la última revisión que haya sido verificada mediante la extensión de revisiones marcadas (FlaggedRevs); si es null, se comprobará la revisión marcada, y, si está disponible, se usará. Si es false, se usará siempre la última revisión.
remote array Un objeto con parámetros que describen cómo acceder a la configuración desde otro wiki. Debe estar presente si no se ha inicializado 'store' y si el valor de isLocal es false.
  ‑ url string Punto de acceso distinto del predeterminado de la API desl que obtener la configuración del wiki remoto sólo para este perfil de configuración. Si no se especifica, se usará el valor de $wgJsonConfigApiUri.
  ‑ username string Si se da, se usará para la autenticación del usuario contra el almacenamiento de configuración remoto.
  ‑ password string Véase username.
store array Inicializa este valor a true o a una matriz para que que el wiki actual aloje estos datos de configuración. Este valor se rellenará automáticamente si está ausente y el valor de isLocal es true.
  ‑ cacheNewValue bool true Cómo debe cambiar la caché ante cambios de configuración. Si el valor es false, elimina el valor almacenado en caché forzando a otros wikis a volver a pedirlo. true fija el nuevo valor en la caché. Esto es útil sobre todo si el wiki que almacena esta configuración y los wikis que la consumen comparten la misma caché. Ten en cuenta que, en caso de false, si el wiki consumidor pide el nuevo valor demasiado rápido, podría obtenerlo de una base de datos esclava posiblemente obsoleta.
  ‑ notifyUrl string Especifica opcionalmente la URL de la API remota a la que se llamará ante un cambio de la configuración.
  ‑ notifyUsername string Nombre de usuario opcional para utilizar con notifyUrl
  ‑ notifyPassword string Contraseña opcional para utilizar con notifyUrl

$wgJsonConfigModels

Esta variable define qué clase de contenido personalizada manejará qué identificador de modelo (modelID). Una misma clase de contenido puede manejar más de un identificador de modelo. Todas las clases de contenido deben derivarse de la clase JCContent; si el modelID corresponde a null, entonces la clase por defecto JCContent manejará el identificador de modelo.

Ejemplo: 

$wgJsonConfigModels['Config.MyExtSettings'] = 'MyExt\MyContentClass';

Si implementas una clase separada para renderizar el HTML, puedes especificar el modelo de configuración como una matriz con la clase adicional view: 

$wgJsonConfigModels['Config.MyExtSettings'] = [
    'class' => 'MyExt\MyContentClass',
    'view'  => 'MyExt\MyContentViewClass', // easier to extend JCDefaultObjContentView or JCDefaultContentView
];

Ejemplos

Antes de la versión 1.0.0, JsonConfig utilizaba los valores name y isSubspace para personalizar qué páginas pertenecían al modelo de contenido dado. Los dos se han eliminado en la versión 1.0.0, siendo reemplazados por el parámetro pattern, que acepta una expresión regular. Asegúrate de delimitar tus patrones con los símbolos ^ y $, y añade barras oblicuas (estilo PHP)

Hola mundo

El caso más simple es una sola página de configuración sin validación alguna almacenada de forma local en cada wiki. Simplemente añade estas declaraciones a LocalSettings.php 

// Content model is 'JsonConfig.MySettings'
// Model class is set to NULL to allow non-validated data
$wgJsonConfigModels['JsonConfig.MySettings'] = null;

$wgJsonConfigs['JsonConfig.MySettings'] = array(
  'pattern' => '/^MySettings$/', // Page name in Config namespace
);

Lo anterior habilita el espacio de nombres «Config» en el wiki local, pero no permite crear en ese espacio de nombres más que la página «Config:MySettings». Puedes almacenar en la página datos en forma de JSON bien formado.

Para leer los datos de MySettings en PHP, utiliza un objeto TitleValue para acceder a la página, y luego solicita su contenido: 

use JsonConfig\JCSingleton;
$tv = new TitleValue( NS_CONFIG, 'MySettings' ); // DB Key
$content = JCSingleton::GetContent( $tv );
if ( $content->isValid() ) {
    $data = $content->getData();
    ...
}

Implementar plantillas Wikimedia

Algunas plantillas de proyectos Wikimedia (p. ej., Template:TNT) requieren que JsonConfig tenga soporte para el espacio de nombres Data en Commons para mw.ext.data.get. Puedes usar la siguiente configuración para implementar ese caso de uso. 

wfLoadExtension( 'JsonConfig' );

$wgJsonConfigEnableLuaSupport = true; // required to use JsonConfig in Lua
$wgJsonConfigModels['Tabular.JsonConfig'] = 'JsonConfig\JCTabularContent';
$wgJsonConfigs['Tabular.JsonConfig'] = [ 
        'namespace' => 486, 
        'nsName' => 'Data',
        // page name must end in ".tab", and contain at least one symbol
        'pattern' => '/.\.tab$/',
        'license' => 'CC0-1.0',
        'isLocal' => false,
];

$wgJsonConfigModels['Map.JsonConfig'] = 'JsonConfig\JCMapDataContent';
$wgJsonConfigs['Map.JsonConfig'] = [ 
        'namespace' => 486,
        'nsName' => 'Data',
        // page name must end in ".map", and contain at least one symbol
        'pattern' => '/.\.map$/',
        'license' => 'CC0-1.0',
        'isLocal' => false,
];
$wgJsonConfigInterwikiPrefix = "commons";

$wgJsonConfigs['Tabular.JsonConfig']['remote'] = [ 
        'url' => 'https://commons.wikimedia.org/w/api.php'
];
$wgJsonConfigs['Map.JsonConfig']['remote'] = [
        'url' => 'https://commons.wikimedia.org/w/api.php'
];

Configuraciones múltiples compartidas en una agrupación (clúster)

Digamos que decidimor almacenar las direcciones IP de los proxies de confianza como páginas «Config:Proxy:Ejemplo» en Meta-Wiki y compartir estos datos con la agrupación. 

// All wikis must have this configuration:
$wgJsonConfigs['JsonConfig.Proxy'] = [
  'pattern' => '/^Proxy\:./', // require at least one letter after the ':'
  'isLocal' => false,
];

// The LocalSettings.php for all wikis except Meta-Wiki will set this URL to Meta-Wiki's API endpoint:
$wgJsonConfigs['JsonConfig.Proxy']['remote'] = 'http://meta.wikimedia.org/w/api.php';

// LocalSettings.php for Meta-Wiki will indicate that the data should be stored there
$wgJsonConfigs['JsonConfig.Proxy']['store'] = true;

Si en vez de esto prefieres dedicar un espacio de nombres separado a los proxies, los parámetros cambiarán a: 

$wgJsonConfigs['JsonConfig.Proxy'] = [
  'namespace' => NNN, // NNN is the number you would reserve for Proxy namespace
  'nsName' => 'Proxy', // Canonical namespace name
];

Validación

La mayoría de las veces se desea también una clase de contenido personalizada con su propia validación. Las páginas JSON se manejan mediante las clases de contenido que derivan de JCContent. La clase de contenido es responsable de analizar y validar el texto en crudo. JCContent no hace ninguna validación más allá del análisis del JSON, pero puedes derivar de ella y redefinir JCContent::validate(). Aún mejor, puedes derivar la clase JCObjContent que proporciona una serie de primitivas de validación y redefinir solamente JCObjContent::validateContent(). 

// This should be done on all wikis, including Meta-Wiki
$wgJsonConfigModels['JsonConfig.Proxy'] = 'ProxyExt\ProxyContent';

Para el propósito de esta documentación, asumamos que la página de configuración del proxy que describe los servidores Opera Mini tiene esta formato: 

{
    "enabled": true,
    "comment": "See http://... for updates",
    "ips": [
        '37.228.104.0/21',
        ...
    ]
}

He aquí la clase de contenido para validar esos datos. 

use JsonConfig\JCObjContent;
use JsonConfig\JCValidators;

class ProxyContent extends JCObjContent {

    /**
     * Derived classes must implement this method to perform custom validation
     * using the check(...) calls
     */
    public function validateContent() {
        // 'enabled' must be a boolean, true by default.
        // JCValidators::* already handle localized error messages
        $this->testOptional( 'enabled', true, JCValidators::isBool() );
        // an optional field 'comment' of type string
        $this->testOptional( 'comment', '', JCValidators::isString() );
        // 'ips' must be a list of valid CIDR ranges
        // field is not optional when default value would not pass validation
        $this->test( 'ips', self::getIpValidator() );
    }

    private static function getIpValidator() {
        // JCValue $value is a value of the field being checked wrapped with the status information.
        //              $v->getValue() actual value being examined
        //              $v->isMissing() if the value is not present in the data
        //              $v->defaultUsed() if the value did not exist and a default was supplied
        // array $path the location of this field in the hierarchy - each value is either string or an int
        // JCObjContent $self - this object, useful to get access to other fields via $self->getField()
        // You may modify the value stored inside, set additional flags, or report an error
        // using the $v->error( $key, $path, ... ) function
        return function ( JCValue $value, array $path, JCObjContent $self ) {
            $isErr = false;
            $v = $value->getValue();
            if ( is_string( $v ) ) {
                // user supplied a single string, treat as an non-assoc array
                $v = array( $v );
            } else {
                // ensure that $v is an non-assoc array, and all of its values are strings
                $isErr = !JCUtils::isList( $v ) || !JCUtils::allValuesAreStrings( $v );
            }
            if ( !$isErr ) {
                // @todo: do the rest of the IP validation and set $isErr to true on failure
            }
            // Error message might be in this form:
            // "Parameter \"$1\" must be an array of valid non-restricted (no private networks) CIDR IP blocks"
            if ( $isErr ) {
                $value->error( 'my-proxyconfig-err-ips', $path );
            } else {
                $value->setValue( $v );
            }
        };
    }
}

Personalizar el comportamiento en el wiki de almacenamiento

Puede que también desees personalizar la visualización y creación de páginas en el wiki de almacenamiento (Meta-Wiki en el ejemplo anterior). Hay dos formas de hacerlo: dentro de tu clase derivada de JCContent o mediante una clase separada de «vista» derivada de JCContentView. El segundo enfoque es preferible, ya que separa claramente la arquitectura y la clase de vista solo tiene necesidad de existir en el wiki de almacenamiento (p. ej. Meta-Wiki) y no en todos los wikis que usan los datos.

Para redefinir el valor por defecto en una clase derivada de JCContent, redefine el constructor y establece el valor de $text con el nuevo valor por defecto si se inicializó con el valor NULL antes de pasarlo al constructor del padre. Para redefinir la generación del HTML, redefine JCContent::getHtml().

Al seguir el método recomendado, crea una clase de vista que derive de JCContentView o una clase JCDefaultContentView con más funcionalidades. En el caso de JCContentView, deberás implementar valueToHtml() y getDefault(). Por defecto, la vista está implementada por la clase JCDefaultContentView, que también se puede utilizar como una base personalizable si solamente necesitas realizar ajustes menores en lo que se refiere a su apariencia. 

// Los cambios en la definición del modelo según lo anterior deben hacerse en todos los wikis, incluido META
$wgJsonConfigModels['JsonConfig.Proxy'] = [ 'class' => 'ProxyExt\ProxyContent' ];

// Añade la clase de la vista - se debe hacer sólo en el wiki de almacenamiento (p. ej. META)
$wgJsonConfigModels['JsonConfig.Proxy']['view'] = 'ProxyExt\ProxyView';

class ProxyView extends JsonConfig\JCDefaultObjContentView {
    public function getDefault( $modelId ) {
        return <<<JSON
{
    "comment": "See http://... for updates",
    "ips": [
        "N.N.N.N/NN",...
    ]
}
JSON;
    }
}


Buenas prácticas

  • Las extensiones que utilicen JsonConfig deberían añadir sus configuraciones a $wgJsonConfigs y $wgJsonConfigModels en el archivo principal de extensión.
  • Si compartes datos de configuración entre varios wikis, documenta el nombre de la clave utilizada en $wgJsonConfigs[] e inicializa la sección 'store'/'remote' en LocalSettings.php. Esto es mejor que introducir una serie de variables globales que duplican la funcionalidad de la configuración. Véase por ejemplo la configuración de Wikimedia de la extensión Graph entre múltiples wikis (aunque esto utiliza una configuración multiwiki compleja en lugar de simples variables de configuración).

Estado

Funcionalidades implementadas

  • El análisis sintáctico JSON convierte el texto JSON en una matriz o un objeto
  • La visualización muestra el JSON en forma de tabla intuitiva en lugar de en forma de código, con algunos resaltados suplementarios. Por ejemplo, si no se proporciona un valor sino que se utiliza el valor por defecto, se muestra en gris, y cuando el valor coincide con el valor por defecto, se muestra en morado. Por ejemplo, véase esto y esto.
  • El editor de código simplifica la edición de JSON
  • La validación personalizada realiza comprobaciones complejas tales como verificar que el valor se encuentra en el formato adecuado o que un identificador de usuario existe.
  • El almacenamiento en caché MemCached almacena blobs JSON en MemCached (caché de memoria) con claves y políticas de expiración personalizadas, y las resetea al guardar.
  • El soporte de revisiones marcadas permite que se marquen las configuraciones como «revisadas» antes de entrar en producción
  • La localización de los elementos de interfaz más básicos se ha llevado a cabo en muchos idiomas, y reduciría el trabajo de traducción si la mayoría de los mensajes comunes se gestionara una sola vez en un sitio.

Funcionalidades aún sin implementar, pero bienvenidas

Estas funcionalidades serían deseables para más de un tipo de configuración:

  • Validador de esquemas - valida el JSON Schema, teniendo en cuenta que la mayoría de las extensiones no necesitan reglas de complejas de validación, con la posibilidad de combinar el esquema con una validación suplementaria.
  • Editor personalizado - el equipo cero ha estado pensando en implementar un editor más complejo, posiblemente basado en el esquema JSON.
  • Soporte de consultas a la API - permite que se devuelvan páginas de configuración como resultados regulares de la API en todos los formatos - json/xml/... en lugar de como blobs de texto:
    api.php ? action=query & titles=Config:Proxy:Opera & prop=jsonconfig
  • Localización - sería deseable poder mostrar descripciones localizadas para cada clave de configuración

Acceso externo

Los datos de configuración almacenados a menudo pueden ser requeridos por algún agente externo como JavaScript, un bot u otros programas. JavaScript podría utilizar JSONP para acceder a los datos requeridos mediante una llamada estándar a la API action=query&rvprop=content, o bien podríamos desarrollar un servicio de reenvío si CORS no está disponible. Los autores de extensiones pueden optar por añadir sus propios módulos de API para proporcionar información específica del dominio. Por último, el parámetro rvprop=jcddata de consulta de la API podría devolver datos JSON como parte del resultado de la API en lugar del blob de texto que rvprop=content devolvería normalmente. 

// ¡NO IMPLEMENTADO! Usa la API regular action=query hasta que decidamos cómo hacerlo bien
var req = {
    format: 'json', action: 'query',
    titles: 'Proxy:Opera',
    prop: 'revisions', rvprop: 'jcdcontent', indexpageids: '',
};
$.ajax({
    url: '//meta.wikipedia.org/w/api.php',
    data: req, cache: true, dataType: 'jsonp',
    success: function(result) { /* maneja errores y advertencias, procesa el contenido */ }
});

Véase también

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:JsonConfig/es&oldid=6822510"