Cargo

De Support Wiki ES
Ir a la navegación Ir a la búsqueda

Para una guía completa sobre cargo, consulta Extension:Cargo en mediawiki.org. Esta página no busca repetir la información disponible ahí, y deberías de intentar aprovechar ambos recursos.

Cargo es una extensión que permite que las páginas se compartan información entre ellas. Imagina tener una hoja de cálculo (como un archivo de Excel o Google Sheets) con los datos de tu juego, todo distribuido entre varias páginas. Una de las hojas trata sobre objetos, otra sobre piezas de equipamiento, y una más que incluye las estadísticas de los jefes. Quizá incluso tienes un par más sobre los personajes no jugables y sus diálogos. Puede que ya te estés imaginando algunas de las columnas en estas hojas de cálculo: los objetos tienen precio de compra y venta, ingredientes, bonificaciones; los jefes tienen puntos de salud, defensa, debilidades, habilidades especiales; los personajes no jugables tienen un saludo, una despedida, una ocupación y quizá hasta una casa.

Con el ejemplo anterior, Cargo te permite crear "hojas de cálculo virtuales" a través de "tablas de Cargo" que contienen esta información, además de hacer que esté disponible para que cualquier página en la wiki pueda usar esa información.

Cuando creas páginas en una wiki usando infoboxes, ya estás pensando sobre los datos de esta manera. Puedes ver las similitudes en las siguientes preguntas:

Infoboxes Analogía de las hojas de cálculo Cargo
¿Qué tipos de infoboxes necesito? ¿Qué libros de Excel debería de hacer? ¿Qué tablas debería de declarar?
¿Qué filas debería de incluir la infobox? ¿Qué columnas debería de usar en la hoja de cálculo? ¿Qué campos debería de incluir en la declaración?
¿Qué valores debería de poner en esta infobox o cómo debería de darles formato? ¿Qué tipo de formato aplico a las celdas en una columna? (Fecha, número, porcentaje, etcétera) ¿Qué tipos debería de asignar a estos campos? (DateTime, Boolean, String, etcétera)

¿Por qué usar Cargo?

Cargo te permite reutilizar los mismos datos en varias páginas de tu wiki'. Específicamente, puedes:

  • Combinar, agrupar o reunir datos. Por ejemplo, si cada personaje tiene su propia página con una infobox, puedes crear una página central que muestre a todos los personajes.
  • Recombinar o reagrupar datos. Por ejemplo, si cada personaje puede usar distintas armas, y cada arma tiene su propia página, puedes mostrar automáticamente todos los personajes que pueden usar un arma dada, así como todas las armas que puede usar un personaje.

Terminología

Término Equivalente de las hojas de cálculo Definición
Tabla Hoja de cálculo
Hoja de Excel 		Una colección de objetos con datos de tipo similar y sus propiedades.
Declarar Crear un archivo nuevo Decirle a la wiki sobre la tabla que quieres hacer.
Escribir Guardar Guardar los datos en una tabla.
Leer Abrir Obtener datos de una tabla.
Condición "where" Filtrar una columna Una condición que debe de ser cumplida por todos los campos para ser incluidos en el resultado

¿Por dónde empiezo?

Ya que Cargo es una extensión que no está habilitada de forma predeterminada, el primer paso es conseguir Cargo en tu wiki, lo cual puedes conseguir hablando con el equipo de soporte. Si tienes experiencia de desarrollo, también te recomendamos usar la extensión de Scribunto para escribir módulos de Lua - pero si no quieres lidiar con nada en términos de código, ¡no hay ningún problema! Puedes usar Cargo sin tener que escribir una sola línea de código.

Paso 1: Declaración

En la analogía de la hoja de cálculo, esto es como crear un nuevo archivo, agregar algunas etiquetas para las columnas y quizá aplicar algun formato a las celdas de cada columna. Eso es todo. No hay datos guardados todavía, y tampoco datos para consultar. Solo estás diciéndole a la wiki qué campos debería de esperar cuando eventualmente empieces a almacenar datos.

Info.svg
Por convención, procura nombrar tanto tus tablas como sus campos en inglés o en español sin caracteres especiales (acentos, ñ, etcétera) y usando camel case o cualquier nomenclatura que no use espacios o guiones bajos, ya que esto puede ocasionar problemas.


Una declaración de Cargo para un conjunto de ciudades ficticias que no tienen ninguna relación con ciudades de algún videojuego popular puede verse sí: 

{{#cargo_declare:_table=Cities
|name=String
|population=Integer
|area=Float
|slogan=Text
|isCapital=Boolean
}}

Primero le estamos dando un nombre a nuestra tabla: "Cities". Posteriormente estamos diciendo que "los elementos en esta tabla tienen 5 piezas de información que necesitamos saber", y estas son:

  1. El nombre de la ciudad (name). Este va a ser el identificador principal de cada fila, y queremos que sea una cadena de texto (string).
    • String significa que son "varias letras o palabras". La diferencia entre String y Text no suele ser importante la mayor parte del tiempo, pero la explicaremos en otro apartado.
    • Si tienes wikitexto que quieres almacenar y que este se muestre de la manera que esperarías, puedes usar en su lugar el tipo de dato Wikitext string.
  2. La población de la ciudad (population). Se trata de un número, y ya que no puedes tener una fracción de una persona, lo tratamos como un tipo entero (integer).
    • Un entero (integer) es un número que no puede tener parte decimal.
  3. El área de la ciudad en alguna unidad de medida del juego (area). Este valor sí puede ser fraccional, por lo que usamos un flotante (float).
    • Un flotante (float) es un número que sí puede tener parte decimal.
  4. El eslogan de la ciudad (slogan). No esperamos que tengamos que buscar datos a partir de este valor, por lo que podemos mejorar un poco el rendimiento al almacenarlo como texto (Text). Sin embargo, también sería válido guardarlo como string; cuando tengas dudas, usa string.
    • Por lo general, un campo de tipo text es un conjunto grande de datos (varias palabras o incluso párrafos), mientras que un string es una pieza más pequeña de datos que identifica una característica de la entidad en cuestión.
  5. Determinar si la ciudad es la capital del país o no (isCapital). Esto puede ser "verdadero" (True o "falso" (False). Este tipo de dato representa valores verdaderos/falsos, y se les suele llamar booleanos (Boolean).
    • Un booleano (boolean) es una variable que solo tiene dos opciones: "verdadero" y "falso". "Falso" significa "no verdadero".
      • En Cargo, deberías de almacenar un valor booleano como Sí o No.[1]
      • Siempre deberías de consultar un valor booleano usando ="1" o ="0".

Después de declarar una tabla, necesitarás realizar un paso más para que esté lista para ser usada. Si eres administrador en la wiki, puedes hacer clic en el botón que dice "Crear tabla de datos" en la página de la plantilla después de haberla declarado y guardado. Si no lo eres, necesitarás pedírselo a un administrador o al soporte de la plataforma si no hubiera uno.

Info.svg
Cada vez que añadas o elimines un campo, o cambies el tipo de alguno de los campos, necesitarás recrear la tabla también. Esto se hace de la misma manera, excepto que el botón dirá "Recrear" en lugar de "Crear". Para informacioń adicional, consulta Recreando tablas.


Indexando

Info.svg
Esta sección explica porqué anteriormente mencionamos que evites usar Text y Wikitext en condiciones de filtrado (where) y unión (join).


Buscar datos en una tabla de Cargo es un proceso lento comparado con otras cosas que podrías hacer. Para poder hacer que encontrar las filas sea más rápido cuando provees de una condición where (para filtrar los resultados), algunos campos son "indexados". Sin embargo, indexar un campo hace que sea más lento para almacenar en primer lugar; por lo tanto, para acelerar un poco el proceso de almacenamiento, Cargo te da la opción de usar "texto" o "wikitexto" para campos extensos que no necesitarán ser indexados. No hay problema en consultar estos campos para mostrarlos en una página, pero nunca deberías de filtrar los resultados a partir de estos valores; ya que no están indexados, la consulta será extremadamente lenta.

¿Dónde declaro la tabla?

Tienes dos opciones:

  1. En una sección entre <noinclude></noinclude> de la plantilla de la cual estás almacenando datos.
  2. En una plantilla independiente que no es usada en ningún otro lado.

Es tu decisión, el único requisito es que tiene que estar en el espacio de nombres de plantilla.

Paso 2: Almacenando los datos

Acabas de crear una nueva hoja de cálculo y agregaste algunas etiquetas para las columnas junto con sus tipos, ¿qué sigue? Ciertamente, es bastante inútil tenerla ahí sin filas de datos en ella, por lo que eso es lo que sigue a continuación.

Info.svg
Normalmente, quieres almacenar datos desde una plantilla de infobox. En este caso, por mantener el ejemplo sencillo, no involucraremos una infobox como tal.


Esta es una plantilla de ejemplo para almacenar datos en nuestra tabla de ciudades: 

{{#cargo_store:_table=Cities
| name = {{{nombre|}}}
| population = {{{población|}}}
| area = {{{área|}}}
| slogan = {{{eslogan|}}}
| isCapital = {{{capital|}}}
}}

Recuerda que del lado izquierdo tienes el nombre del campo, mientras que del lado derecho estamos usando los parámetros que se usarán a través de la plantilla: 

{{Ciudad
| nombre = 
| población = 
| área = 
| eslogan = 
| capital = 
}}

Paso 3: Consultando datos

Finalmente tenemos nuestra hermosa hoja de cálculo con datos: tiene un nombre, un montón de columnas y varias filas que contienen información. Todo esto es genial, pero no hemos hecho nada con ella todavía.

"Hacer algo con ella" significa usar la función {{#cargo_query:}}. Intentemos hacer una tabla de ciudades cuya población sea de al menos 10,000 habitantes. Observa que, a diferencia de las funciones para declarar y almacenar, #cargo_query toma un argumento llamado table y no _table ({{#cargo_attach:}} acepta ambos). También puedes usar tables en lugar de table.

En los siguientes ejemplos, estamos usando CONCAT(slogan)=slogan en lugar de solo slogan para evitar un problema común que ocurre al intentar mostrar texto con apóstrofes. 

{{#cargo_query:table=Cities
| fields = name, population, area, CONCAT(slogan)=slogan, isCapital
| where = population > "10000"
}}
name population area slogan isCapital
Riften 17,119 40.6 Welcome to Summoner's - wait wrong Rift No
Windhelm 85,102 10.5 The actually windy city. No
Winterfell 10,285 18.3 No, we're not Winterhold. What do you think this is, Skyrim? No

Consultas avanzadas

Revisa personalizando tablas para más información sobre cómo añadir más formato a los resultados mostrados como tablas.

Quizá ya hayas notado que no tienes mucho control sobre cómo luce el resultado: todo lo que puedes ver es una tabla con todos los valores. ¿Qué tal si solo quisieras mostrar una lista de íconos de objetos para mostrar todos los objetos en los que se puede convertir un material? ¿y si quisieras hacer una cuadrícula con cada retrato de un héroe y un enlace a su página para mostrar en la página principal? Resulta que puedes hacer esto y más usando |format=template. El valor predeterminado es |format=table cuando no estableces un formato en la consulta.

Cuando usas el formato de plantilla, puedes crear una plantilla que controle el formato de cada "fila" en el resultado. Así, en lugar de hacer una tabla, puedes mostrar una lista o un montón de íconos según prefieras. Aquí hay algunas opciones de lo que podrías elegir hacer:

  • Tener una plantilla que muestre una fila de una wikitabla, pero con un estilo más sofisticado para cada fila. Esto requiere que definas tanto el encabezado como el pie de la tabla usando |intro= y |outro= o solo incluyendo los elementos adicionales alrededor de la consulta.
  • Hacer una plantilla que muestre una imagen de cada uno de los valores junto con su nombre para formar una cuadrícula de navegación.
  • Usar #vardefine y #expr para calcular totales y mostrarlos al final.

Conceptos más avanzados

  • Las tablas de Cargo pueden unirse unas con otras usando |join on= (o solo join = a través de Lua).
  • En Lua, hay una función dedicada mw.ext.cargo.query, pero si quieres hacer una declaración o almacenar datos desde Lua necesitas usar frame:callParserFunction.
  • Las tablas de Cargo están disponibles a través de la API de MediaWiki usando action=cargoquery.

Usando números

En ocasiones quieres que Cargo te diga el número de algo. Aquí hay algunos consejos.

Comandos de SQL

  • Puedes usar COUNT(*) para obtener el número total de registros que coincidieron con tu condición WHERE.
  • Puedes usar COUNT(DISTINCT campo) para obtener el número total de registros diferentes sobre un campo para los registros que coincidieron con tu condición WHERE.
  • Existen funciones como SUM, MAX y MIN. Consulta Usando funciones de SQL (en inglés) en la documentación principal de Cargo para más información.

Usando números desde Cargo

  • Un problema que muchas personas encuentran es que #cargo_query devuelve números con separadores en los millares. Usa TRIM() en el campo (por ejemplo, |fields=TIRM(Costo)=Costo) para eliminar los separadores si lo necesitas para usar en funciones como #expr.
  • Otro problema es que Cargo agrega HTML adicional a los resultados. Si quieres usar algo como {{#expr:{{#cargo_query:CONSULTA}} * 100}} para mostrar un porcentaje, necesitas añadir el parámetro |no html a la consulta; esto suprimirá el HTML alrededor del resultado y regresará solo el número para poder ser usado por #expr.

Otros problemas comunes

  • En ocasiones, |format=template no funciona o se muestra incorrectamente. Esto no ocurre si usas el módulo de CargoQuery (a través de una plantilla {{CargoQuery}}) con los mismos parámetros; no necesitas usar Lua por tu cuenta.
  • Cuando se usa HOLDS, los errores que se dan a través de Lua suelen ser completamente incorrectos para el problema real. En general, no uses HOLDS; si lo haces, ignora cualquier texto de error que pudieras recibir.
  • De forma similar al problema de los separadores de millares en números, puede que necesites usar TRIM sobre valores que se guardaron usando la palabra mágica {{PAGENAME}} (_pageName es un campo predeterminado, pero quizá usaste {{#titleparts:}} para alguno de los campos).
  • Cada plantilla solo puede escribir a 1 tabla. Si necesitas que una plantilla escriba a varias tablas, necesitarás crear plantillas "falsas" que hagan esa escritura y transcluirlas en tu plantilla principal.
    • De forma similar, una plantilla solo puede declarar 1 tabla.
    • Una plantilla puede hacer tanto una declaración como una escritura a la vez.
  • unique no funciona, por lo tanto no lo uses.

¡Ayuda! Mi tabla recreada no tiene datos

Si recreas tu tabla y no se cargan los datos, aquí hay algunas cosas que podrían ser el causante:

  1. La declaración o escritura son incorrectos. Asegúrate de que realmente estés llamando a las funciones correctamente.
  2. Tipos de datos equivocados.
    • ¿Todos tus campos de tipo entero son realmente enteros? No debe de haber wikitexto, letras, operaciones o puntos decimales.
    • ¿Todos tus campos de tipo flotante so números? No debe de haber wikitexto, letras u operaciones.
    • ¿Estás usando valores de texto muy largos? De forma predeterminada, un "string" puede contener un máximo de 300 caracteres. Puedes cambiar esto usando |NombreDelCampo=String(size=500) o cualquier tamaño que necesites, pero quizá también prefieras cambiar al tipo Text.
  3. Demasiadas columnas en la tabla. El número exacto de columnas que puedes tener depende de algunas configuraciones del wiki, pero en general, esta puede ser tu causa si tienes alrededor de 60 columnas o más.
  4. No ha pasado suficiente tiempo. Si ya has revisado todo lo anterior y estás seguro que ninguno de esos motivos es el problema, intenta esperar alrededor de 30 minutos para que los datos sean insertados.

Notas

  1. ↑ Un valor booleano se considera falso si es igual a No o 0; cualquier otro valor es tratado como verdadero.
Obtenido de «https://support.wiki.gg/es/index.php?title=Cargo&oldid=571»