El lenguaje de plantillas de calibre

El lenguaje de plantillas de calibre se usa en varios lugares. Se usa para controlar la estructura de carpetas y el nombre del archivo cuando se guardan archivos de la biblioteca de calibre en el disco o en un lector. También se usa para definir columnas «virtuales» que contienen datos de otras columnas, etcétera.

El lenguaje de plantillas básico es simple pero también tiene potentes características avanzadas. Una plantilla consiste en texto y nombres entre llaves que se sustituyen por los metadatos correspondientes del libro que está siendo procesado. Por ejemplo, la plantilla predeterminada usada para guardar libros en un dispositivo en calibre es:

{author_sort}/{title}/{title} - {authors}

Para el libro «La Fundación» de «Isaac Asimov» da lugar a:

Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov

Las barras son texto que se ponen en la plantilla donde van a aparecer. Por ejemplo, si la plantilla es:

{author_sort} Some Important Text {title}/{title} - {authors}

Para el libro «La Fundación» de «Isaac Asimov» da lugar a:

Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov

Puede usar los campos de metadatos disponibles en calibre en una plantilla, incluidas las columnas personalizadas que haya creado, usando su «nombre de búsqueda». Para obtener el nombre de búsqueda de una columna (campo), pase el cursor sobre el encabezado de la columna. Los nombre para las columnas personalizadas (columnas que haya creado usted) siempre empiezan por #. Para columnas personalizadas de tipo serie, siempre hay un campo adicional llamado #nombredeserie_index que es el índice de serie para dicha serie. Así, si tiene un campo personalizado de serie llamado #miserie, también habrá un campo llamado #miserie_index.

Además de los campos basados en columnas, también puede usar:

{formats} - A list of formats available in the calibre library for a book
{identifiers:select(isbn)} - The ISBN of the book

Si un libro no tiene un determinado metadato, el campo se se sustituye por un texto vacío en la plantilla para este libro. Considere, por ejemplo:

{author_sort}/{series}/{title} {series_index}

Si un libro tiene una serie, la plantilla producirá:

Asimov, Isaac/Foundation/Second Foundation 3

y si un libro no pertenece a una serie:

Asimov, Isaac/Second Foundation

(calibre elimina automáticamente barras múltiples y espacios iniciales o finales).

Formato avanzado

Puede hacerse más que simples sustituciones con las plantillas. Se puede incluir texto de manera condicional y controlar el formato de los datos sustituidos.

Primero, incluir texto condicionalmente. Hay casos en los que puede querer que aparezca un texto en la salida sólo si un campo no está vacío. Un caso común es series y series_index, para los que puede querer o nada o ambos valores con un guión entre ellos. calibre tiene en cuenta este caso usando una sintaxis de campo especial.

Por ejemplo, supongamos que desea usar la plantilla:

{series} - {series_index} - {title}

Si el libro no tiene serie, la respuesta será - - title. La mayoría preferiría que el resultado fuera simplemente title, sin los guiones. Para conseguir esto, use la sintaxis extendida {campo:|prefijo|sufijo}. Cuando usa esta sintaxis, si el campo tiene el valor SERIE el resultado será prefijoSERIEsufijo. Si el campo no tiene ningún valor, el resultado será un texto vacío (nada); el prefijo y el sufijo se descartan. El prefijo y el sufijo pueden contener espacios. No use subplantillas (`{ … }`) ni funciones (ver más adelante) como prefijo o sufijo.

Usando esta sintaxis, podemos resolver el problema anterior de las series con esta plantilla:

{series}{series_index:| - | - }{title}

Los guiones se incluirán solamente si el libro tiene índice de serie, que sólo tendrá si tiene una serie.

Notas: debe incluir el carácter : si quiere usar un prefijo o un sufijo. Debe usar ambos caracteres | o ninguno; usar sólo no, como en {campo:| - }, no está permitido. Es posible especificar un texto vacío en uno u otro lugar, como en {series:|| - }. Usar {title:||} es lo mismo que usar {title}.

Segundo: formato. Supongamos que queremos asegurarnos de que series_index siempre tenga tres dígitos, con ceros a la izquierda. Se conseguiría de esta manera:

{series_index:0>3s} - Three digits with leading zeros

Si en lugar de ceros a la izquierda desea espacios, utilice:

{series_index:>3s} - Three digits with leading spaces

Para obtener ceros a la derecha use:

{series_index:0<3s} - Three digits with trailing zeros

Si usa índices de serie con subvalores (por ejemplo 1,1), puede querer asegurarse de que los decimales quedan alineados. Por ejemplo, puede que los índices 1 y 2,5 aparezcan como 01,00 y 02,50 para que se ordenen correctamente. Para ello, use:

{series_index:0>5.2f} - Five characters, consisting of two digits with leading zeros, a decimal point, then 2 digits after the decimal point

Si quiere sólo las dos primeras letras de los datos, use:

{author_sort:.2} - Only the first two letter of the author sort name

The calibre template language comes from Python and for more details on the syntax of these advanced formatting operations, look at the Python documentation <https://docs.python.org/library/string.html#format-string-syntax>.

Usar plantillas en columnas personalizadas

A veces querrá mostrar metadatos en la lista de libros que calibre no muestra normalmente, o mostrarlos de una manera diferente. Por ejemplo, puede querer mostrar el ISBN, un campo que calibre no muestra. Puede usar columnas personalizadas para esto creando una columna de tipo «columna generada a partir de otras columnas» (en lo sucesivo llamadas columnas compuestas), e introduciendo una plantilla. calibre mostrará una columna con el resultado de evaluar la plantilla. Para mostrar el ISBN, cree la columna e introduzca {identifiers:select(isbn)} en el cuadro de plantilla. Para mostrar una columna que contenga los valores de dos campos personalizados de serie separados por una coma, use {#serie1:||,}{#serie2}.

Las columnas compuestas pueden utilizar cualquier opción de plantilla, incluidas las de formato.

No puede modificar los datos mostrados en una columna compuesta. Si modifica una columna compuesta, por ejemplo pulsando dos veces sobre ella, se abrirá la plantilla para modificarla, no los datos resultantes. Modificar la plantilla en la interfaz gráfica es una manera rápida de probar y modificar columnas compuestas.

Usar funciones en plantillas: modo de función única

Supongamos que desea mostrar el valor de un campo en mayúsculas, aunque normalmente el valor del campo tiene sólo las iniciales en mayúscula. Puede conseguir esto (y muchas otras cosas) usando las funciones disponibles para plantillas. Por ejemplo, para mostrar el título en mayúsculas use {title:uppercase()}. Para mostrarlo con las iniciales en mayúscula use {title:titlecase()}.

Las funciones aparecen en la parte del formato, después de : y antes del primer | o del } de cierre. Si tiene tanto un formato como una referencia de función, la función después de otro :. Las funciones siempre deben acabar con (). Algunas funciones toman valores adicionales (argumentos), y éstos van dentro de los ().

Las funciones siempre se aplican antes de las especificaciones de formato. Véase más abajo un ejemplo de cómo usar un formato y una función, donde se demuestra este orden.

La sintaxis para usar funciones es {campo:función(argumentos)} o {campo:función(argumentos)|prefijo|sufijo}. Los argumentos van separados por comas. Las comas dentro de los argumentos deben ir precedidas por una barra invertida ( \\ ). El último (o único) argumento no puede contener un paréntesis de cierre ( ) ). Las funciones devuelven el valor del campo usado en la plantilla, convenientemente modificado.

Importante: Si tiene experiencia en programación, tenga en cuenta que la sintaxis de este modo (de función única) no es la que podría esperarse. Los textos van sin comillas. Los espacios son importantes. Todos los argumentos deben ser constantes; no hay evaluación interna. No use subplantillas (``{…}``) como argumentos de función. En lugar de ello, use el modo de programación de plantilla y el modo de programación general.

Muchas funciones usan expresiones regulares. En todos los casos, la expresión regular no distingue entre mayúsculas y minúsculas.

Las funciones disponibles se enumeran a continuación. Tenga en cuenta que la documentación definitiva para las funciones está disponibles en la sección Referencia de funciones:

  • lowercase() – devuelve el valor del campo en minúsculas.

  • uppercase() – devuelve el valor del campo en mayúsculas.

  • titlecase() – devuelve el valor del campo con las iniciales en mayúscula.

  • capitalize() – devuelve el valor con la primera letra mayúscula y el resto en minúsculas.

  • contains(patrón, texto_si_coincide, texto_si_no_coincide) – comprueba si el campo contiene coincidencias para la expresión regular patrón. Devuelve texto_si_coincide si se encuentran coincidencias, en caso contrario devuelve texto_si_no_coincide.

  • count(separador) – interpreta el valor como una lista de elementos separados por ­separador y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero «authors» usa un ampersand («&»). Ejemplos: {tags:count(,)}, {authors,count(&)}

  • format_number(plantilla) – interpreta el campo como un número y le da formato usando una plantilla de formato de Python como «{0:5.2f}» o «{0:,d}» o «${0:5,.2f}». El nombre del campo dentro de la plantilla debe ser un 0 (cero) (el «{0:» en los ejemplos anteriores). Si la plantilla contiene sólo un formato, puede omitir el «{0:» inicial y el «}» final. Véase la documentación del lenguaje de plantillas y de Python para más ejemplos. Devuelve un texto vacío si el formato falla.

  • human_readable() – espera que el valor sea un número y devuelve un texto que representa ese número en KB, MB, GB, etc.

  • ifempty(texto) – si el campo no está vacío, devuelve el valor del campo. En caso contrario devuelve texto.

  • in_list(separador, patrón, encontrado, ..., no_encontrado) – interpreta el campo como una lista de elementos separados por separador y evalúa patrón con cada valor de la lista. Si patrón coincide con alguno de los elementos de la lista, devuelve encontrado, en caso contrario devuelve no_encontrado. Los argumentos patrón y encontrado pueden repetirse tantas veces como se desee, lo que permite devolver diferentes valores según la búsqueda. Los patrones se evalúan en orden. Se devuelve la primera coincidencia.

  • language_codes(nombres) – devuelve los códigos de idioma correspondientes a «nombres». Los nombres deben estar en el idioma actual. El argumento «nombres» es una lista separada por comas.

  • language_strings(códigos, localizar) – devuelve los nombres de los idiomas identificados por códigos. Si localizar es cero, devuelve los nombres en inglés. Si localizar no es cero, devuelve los nombres en el idioma actual. El argumento códigos es una lista separada por comas.

  • list_item(índice, separador) – interpreta el campo como una lista de elementos separados por «separador» y devuelve el elemento número «índice». El primer elemento es el número cero. El último elemento puede obtenerse con list_item(-1, separador). Si el elemento no está en la lista devuelve un valor vacío. El separador tiene el mismo significado que en la función «count».

  • lookup(patrón, campo, patrón, campo, ..., otro_campo) – como switch, pero los argumentos son nombres de campo (metadatos), no texto. Se usará el valor del campo apropiado. Tenga en cuenta que puesto que las columnas compuestas son campos, puede usar esta función en un campo compuesto para usar el valor de otro campo compuesto. Esto es muy útil para construir rutas de guardado variables (más sobre esto más adelante).

  • rating_to_stars(usar_media_estrella) – Devuelve la calificación como caracteres de estrella. El valor de origen debe ser un número entre 0 y 5. Ponga usar_media_estrella a 1 si quiere caracteres de media estrella para columnas personalizadas de calificación que no sean enteros, por ejemplo 2.5.

  • re(patrón, sustitución) – devuelve el campo después de aplicar la expresión regular. Todas las veces que aparezca patrón se sustituirá por sustitución. Como en todo calibre, se trata de expresiones regulares compatibles con Python.

  • select(clave) – interpreta el campo como una lista de elementos separados por comas, con los elementos de la forma «id:valor». Encuentra la pareja con «id» igual a «clave» y devuelve el valor correspondiente. Esta función es particularmente útil para extraer un valor tal como el ISBN del conjunto de identificadores de un libro.

  • shorten(car_izq, texto_medio, car_der) – devuelve una versión abreviada del campo, consistente en un número car_izq de caracteres del principio del campo, seguidos de texto_medio, seguido de un número car_der de caracteres del final del campo. car_izq y car_der deben ser números enteros. Por ejemplo, supongamos que el título del libro es «Novísima recopilación de las leyes de España» y que quiere que quepa en un espacio de 15 caracteres a lo sumo. Si usa {title:shorten(9,-,5)}, el resultado será «Novísima -spaña». Si la longitud del campo es menor que car_izq + car_der + la longitud de texto_medio, se usará el campo intacto. Por ejemplo, el título «La colmena» no se cambiará.

  • str_in_list(separador, texto, encontrado, ..., no_encontrado) – interpreta el campo como una lista de elementos separados por separador, y compara texto con cada valor de la lista. Si texto coincide con alguno de los valores (sin distinción de mayúsculas y minúsculas), devuelve encontrado, en caso contrario devuelve no_encontrado. Si el texto contiene separadores, también se considera como una lista y se comprueba cada elemento. Los argumentos patrón y encontrado pueden repetirse tantas veces como se desee, lo que permite devolver diferentes valores según la búsqueda. Los patrones se evalúan en orden. Se devuelve la primera coincidencia.

  • subitems(índice_inicio, índice_fin) – Esta función se usa para separar listas de elementos jerárquicos de tipo etiqueta, tales como los géneros. Interpreta el campo como una lista de elementos separados por comas, donde cada elemento es a su vez una lista de elementos separados por puntos. Devuelve una nueva lista formada tomando, de cada lista de elementos separados por puntos, los elementos situados entre las posiciones índice_inicio e índice_fin y combinando los resultados. El primer elemento de cada lista separada por puntos ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si índice_fin es cero, se considera que es el final de la lista. Ejemplos:

    Assuming a #genre column containing "A.B.C":
        {#genre:subitems(0,1)} returns "A"
        {#genre:subitems(0,2)} returns "A.B"
        {#genre:subitems(1,0)} returns "B.C"
    Assuming a #genre column containing "A.B.C, D.E":
        {#genre:subitems(0,1)} returns "A, D"
        {#genre:subitems(0,2)} returns "A.B, D.E"
    
  • sublist(índice_inicio, índice_fin, separador) – interpreta el campo como una lista de elementos separados por separador y devuelve una nueva lista con los elementos comprendidos entre la posición índice_inicio e índice_fin. El primer elemento ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si índice_fin es cero, se considera que es el final de la lista. Ejemplos suponiendo que la columna de etiquetas (definida como valores separados por comas) contiene «A, B, C»:

    {tags:sublist(0,1,\,)} returns "A"
    {tags:sublist(-1,0,\,)} returns "C"
    {tags:sublist(0,-1,\,)} returns "A, B"
    
  • swap_around_articles(separador) – devuelve el valor con los artículos puestos al final. El valor puede ser una lista, en cuyo caso se procesará cada elemento de la lista. Si el valor es una lista, debe proporcionar el separador de los elementos de la lista. Si no se proporciona ningún separador, la lista se trata como un único valor, no una lista.

  • swap_around_comma() – dado un campo con un valor de la forma B, A, devuelve A B. Esto es útil para convertir nombres en formato APELLIDO, NOMBRE a NOMBRE APELLIDO. Si no hay ninguna coma, la función devuelve «val» sin cambios.

  • switch(patrón, valor, patrón, valor, ..., otro_valor) – para cada pareja patrón, valor, comprueba si el campo contiene coincidencias para la expresión regular patrón y, en tal caso, devuelve ese valor. Si no coincide ningún patrón, devuelve otro_valor. Pueden emplearse tantas parejas patrón, valor como se desee.

  • test(texto_si_no_vacío, texto_si_vacío) – devuelve texto_si_no_vacío si el campo no está vacío, devuelve texto_si_vacío en caso contrario.

  • transliterate() – Devuelve un texto en el alfabeto latino formado por aproximación del sonido de las palabras en el campo de origen. Por ejemplo, si el campo de origen es «Фёдор Миха́йлович Достоевский» la función devuelve «Fiodor Mikhailovich Dostoievskii».

Now, what about using functions and formatting in the same field? Suppose you have an integer custom column called #myint that you want to see with leading zeros, as in 003. To do this, you would use a format of 0>3s. However, by default, if a number (integer or float) equals zero then the field produces the empty value, so zero values will produce nothing, not 000. If you really want to see 000 values, then you use both the format string and the ifempty function to change the empty value back to a zero. The field reference would be:

{#myint:0>3s:ifempty(0)}

Tenga en cuenta que puede usar también prefijo y sufijo. Si desea que el número aparezca como [003] o [000], use el campo:

{#myint:0>3s:ifempty(0)|[|]}

Funciones más complejas en plantillas: modo de programación de plantillas

El modo de programación de plantillas se diferencia del modo de función única en que permite escribir expresiones de plantilla que se refieren a otros campos de metadatos, usan plantillas anidadas, modifican valores y realizan operaciones aritméticas. Es un lenguaje de programación razonablemente completo.

Puede usar las funciones documentadas anteriormente en modo de programación de plantillas. Véase más adelante para más detalles.

Para empezar con un ejemplo, supongamos que quiere una plantilla que muestre la serie de un libro si la tiene, y en caso contrario muestre el valor del campo personalizado «#genre». Esto no se puede hacer en el modo de función única, porque no se puede hacer referencia a otro campo en la expresión de la plantilla. En el modo de programación de plantillas sí se puede. La siguiente expresión funciona:

{#series:'ifempty($, field('#genre'))'}

El ejemplo muestra varias cosas:

  • el modo de programación de plantillas se usa si la expresión empieza por :' y termina por '. Cualquier otra cosa se supone que es una sola función.

  • la variable $ representa el campo sobre el que opera la expresión, #series en este caso.

  • las funciones deben llevar todos sus argumentos. No hay valores predeterminados. Por ejemplo, las funciones estándar predefinidas deben tener un parámetro inicial que indique el campo de origen, lo que es una diferencia importante con respecto al modo de función única.

  • los espacios en blanco se ignoran y se pueden utilizar en cualquier lugar dentro de la expresión.

  • los textos constantes se encierran en comillas del mismo tipo, ya sea ' o ".

La sintaxis del lenguaje se muestra con la siguiente gramática. En el modo de programación general puede ver una discusión de «compare», «if_expression» y «template_call»::

program         ::= expression_list
expression_list ::= expression [ ';' expression ]*
expression      ::= identifier | constant | function | assignment | compare | if_expression
function        ::= identifier '(' expression [ ',' expression ]* ')'
compare         ::= expression compare_op expression
compare_op      ::= '==' | '!=' | '>=' | '>' | '<=' | '<' | '==#' | '!=#' | '>=#' | '>#' | '<=#' | '<#'
if_expression   ::= 'if' expression 'then' expression_list [elif_expression] ['else' expression_list] 'fi'
elif_expression ::= 'elif' expression 'then' expression_list elif_expression | ''
assignment      ::= identifier '=' expression
constant        ::= " string " | ' string ' | number
identifier      ::= sequence of letters or ``_`` characters

Los comentarios son líneas que empiezan por un carácter «#».

Una expression sin errores siempre tiene un valor. El valor de una expression_list es el valor de la última expresión de la secuencia. Así, el valor del siguiente programa (expression_list):

1; 2; 'foobar'; 3

es 3.

Otro ejemplo de un programa complejo pero más bien tonto podría ayudar a aclarar las cosas:

{series_index:'
    substr(
        strcat($, '->',
            cmp(divide($, 2), 1,
                assign(c, 1); substr('lt123', c, 0),
                'eq', 'gt')),
        0, 6)
   '| prefix | suffix}

Este programa hace lo siguiente:

  • especifica que el campo que se examina es series_index. El valor del campo se asigna a la variable $.

  • ejecuta la función substr, que toma 3 argumentos (texto, inicio, fin). Devuelve un texto formado extrayendo los caracteres entre inicio y fin de texto (el primer carácter es el número cero). En este caso, el texto se calcula mediante la función strcat, inicio es 0 y fin es 6. En este caso, devolverá los primeros 6 caracteres del texto devuelto por strcat, que debe evaluarse antes de que substr pueda finalizar.

  • ejecuta la función strcat (concatenación de textos). strcat acepta 1 o más argumentos, y devuelve un texto formado por la concatenación de todos los valores. En este caso hay tres argumentos. El primer argumento es el valor en $, que aquí es el valor de series_index. El segundo parámetro es el texto constante '->'. El tercer parámetro es el valor devuelto por la función cmp, que debe evaluarse completamente antes de que strcat pueda finalizar.

  • The cmp function takes 5 arguments (x, y, lt, eq, gt). It compares x and y and returns the third argument lt if x < y, the fourth argument eq if x == y, and the fifth argument gt if x > y. As with all functions, all of the parameters can be statements. In this case the first parameter (the value for x) is the result of dividing the series_index by 2. The second parameter y is the constant 1. The third parameter lt is a statement (more later). The fourth parameter eq is the constant string 'eq'. The fifth parameter is the constant string 'gt'.

  • The third parameter (the one for lt) is a statement, or a sequence of expressions. Remember that a statement (a sequence of semicolon-separated expressions) is also an expression, returning the value of the last expression in the list. In this case, the program first assigns the value 1 to a local variable c, then returns a substring made by extracting the c’th character to the end. Since c always contains the constant 1, the substring will return the second through end’th characters, or 't123'.

  • Una vez que se ejecuta la sentencia que proporciona un valor para el tercer parámetro, cmp puede devolver un valor. En este punto, strcat puede devolver un valor, y substr puede devolver un valor. Entonces el programa finaliza.

Para distintos valores de series_index, el programa devuelve:

  • series_index == undefined, resultado = prefix ->t123 suffix

  • series_index == 0.5, resultado = prefix 0.50-> suffix

  • series_index == 1, resultado = prefix 1->t12 suffix

  • series_index == 2, resultado = prefix 2->eq suffix

  • series_index == 3, resultado = prefix 3->gt suffix

Todas las funciones mostradas en el modo de función única puede usarse en el modo de programación. Para ello debe proporcionar el valor sobre el que actuará la función como primer parámetro, además de los parámetros documentados anteriormente. Por ejemplo, en el modo de programación los parámetros de la función test son test(x, texto_si_no_vacío, texto_si_vacío). El parámetro x, que es el valor que se comprueba, casi siempre será una variable o una llamada una función, a menudo field().

Las siguientes funciones están disponibles, además de las descritas en el modo de función única. Recuerde del ejemplo anterior que las funciones del modo de función única requieren un primer parámetro adicional que especifique el campo sobre el que se opera. Excepto el parámetro id de assign, todos los parámetros pueden ser sentencias (secuencias de expresiones). Tenga en cuenta que la documentación definitiva de las funciones está disponible en la sección Referencia de funciones:

  • and(valor, valor, ...) – devuelve el texto «1» si todos los valores son no vacíos, en caso contrario devuelve un texto vacío. Esta función opera bien con test o first_non_empty. Pueden usarse tantos valores como se desee.

  • add(x, y) – devuelve x + y. Da un error si x o y no son números.

  • assign(id, val) – asigna val a id y devuelve val. id debe ser un identificador, no una expresión

  • approximate_formats() – devuelve una lista separada por comas de formatos que en algún momento estuvieron asociados con el libro. No hay garantía de que esta lista sea correcta, aunque probablemente lo sea. Esta función puede usarse en el modo de programación de plantillas usando la plantilla {:'approximate_formats()'}. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB».

  • author_links(sep_val, sep_par) – devuelve un texto que contiene una lista de autores y enlaces de autores de la forma: autor1 sep_val enlace_autor1 sep_par autor2 sep_val enlace_autor2 etc. Cada autor está separado de su correspondiente enlace por el texto sep_val, sin espacios adicionales. Los pares autor:enlace_autor están separados por el texto sep_par, sin espacios adicionales. Es responsabilidad del usuario proporcionar separadores que no aparezcan en los nombres o enlaces de autor. El nombre de autor se incluye aunque su enlace esté vacío.

  • author_sorts(separador) – devuelve un texto que contiene la lista de valores de orden de autor para los autores del libro. El orden de autor es el que figura en los metadatos de autores (diferente del valor de orden de autor del libro). La lista devuelta es de la forma orden_de_autor_1 separador orden_de_autor_2 etc. Los valores de orden de autor en la lista están en el mismo orden que los autores del libro. Si quiere espacios alrededor de separador, inclúyalos en el valor.

  • booksize() – devuelve el valor del campo «tamaño» de calibre. Devuelve «» si no hay formatos.

  • check_yes_no(nombre_de_campo, no_definido, es_false, es_true) – comprueba si el valor del campo de tipo sí o no identificado por la clave de búsqueda nombre_de campo coincide con el valor especificado en los parámetros. Devuelve «yes» si coincide, y un texto vació en caso contrario. Establezca el parámetro no_definido, es_false o es_true a 1 (el número) para comprobar dicha condición, en caso contrario establézcalos a 0. Ejemplo:

    check_yes_no("#bool", 1, 0, 1)
    

    devuelve «yes» si el campo de tipo sí o no "#bool" es True o no está definido (no es ni True ni False). Más de uno de no_definido, es_false y es_true puede ser 1. Esta función se usa normalmente con las funciones test() o is_empty().

  • ceiling(x) – devuelve el menor entero que es mayor o igual a x. Da un error si x no es un número.

  • cmp(x, y, mn, ig, my) – compara x e y después de convertirlas en números. Devuelve mn si x < y. Devuelve ig si x == y. Devuelve my en otros casos.

  • connected_device_name(ubicación_de_almacenamiento) – si hay un dispositivo conectado, devuelve el nombre del dispositivo, en caso contrario devuelve un texto vacío. Cada ubicación de almacenamiento de un dispositivo puede tener un nombre diferente. Los nombres de ubicación son «main», «carda» y «cardb». Esta función sólo funciona en la interfaz gráfica.

  • connected_device_uuid(storage_location) – if a device is connected then return the device uuid (unique id), otherwise return the empty string. Each storage location on a device has a different uuid. The location names are 'main', 'carda' and 'cardb'. This function works only in the GUI.

  • current_library_name() – devuelve la última parte de la ruta a la biblioteca de calibre actual. Esta función puede usarse en el modo de programación de plantillas usando la plantilla {:'current_library_name()'}.

  • current_library_path() – devuelve la ruta a la biblioteca de calibre actual. Esta función puede usarse en el modo de programación de plantillas utilizando la plantilla {:'current_library_path()'}.

  • days_between(fecha1, fecha2) – devuelve el número de días entre fecha1 y fecha2. El número es positivo si fecha1 es posterior a fecha2, en caso contrario es negativo. Si fecha1 o fecha2 no son fechas, la función devuelve un texto vacío.

  • divide(x, y) – returns x / y. Throws an exception if either x or y are not numbers.

  • eval(texto) – evalúa texto como un programa, pasando las variables locales (las definidas con assign). Esto permite usar el procesador de plantillas para elaborar resultados complejos a partir de variables locales. Dado que los caracteres { y } tienen un uso especial, debe usarse [[ en lugar de { y ]] para }; se convertirán automáticamente. Tenga en cuenta que los prefijos y sufijos (la sintaxis |prefijo|sufijo|) no pueden usarse en el argumento de esta función en el modo de programación de plantillas.

  • field(nombre) – devuelve el campo de metadatos identificado por nombre.

  • finish_formatting(val, formato, prefijo, sufijo) – aplica el formato, prefijo y sufijo a un valor de la misma manera que se haría en una plantilla como {series_index:05.2f| - |- }. Esta función se proporciona para facilitar la conversión de plantillas complejas en modo de función única o de plantilla al modo de programación general (ver más adelante) y aprovechar la compilación de plantillas. Por ejemplo, el siguiente programa produce la misma salida que la plantilla anterior:

    program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
    

    Otro ejemplo: para la plantilla {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} use:

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • first_matching_cmp(val, cmp1, resultado1, cmp2, resultado2, ..., otro_resultado) – compara val < cmpN consecutivamente y devuelve resultadoN para la primera comparación que sea cierta. Devuelve otro_resultado si ninguna comparación es cierta. Ejemplo:

    first_matching_cmp(10,5,"small",10,"middle",15,"large","giant")
    

    devuelve «»large»». El mismo ejemplo con un primer valor de 16 devuelve «»giant»».

  • first_non_empty(valor, valor, ...) – devuelve el primer valor que no esté vacío. Si todos los valores están vacíos, se devuelve también un valor vacío. Puede incluir tantos valores como quiera.

  • floor(x) – devuelve el mayor entero que es menor o igual a x. Da un error si x no es un número.

  • format_date(val, formato_fecha) – da formato a un valor, que debe ser un campo de fecha, según formato_fecha y devuelve un texto. Los códigos de formato son:

    d    : the day as number without a leading zero (1 to 31)
    dd   : the day as number with a leading zero (01 to 31)
    ddd  : the abbreviated localized day name (e.g. "Mon" to "Sun").
    dddd : the long localized day name (e.g. "Monday" to "Sunday").
    M    : the month as number without a leading zero (1 to 12).
    MM   : the month as number with a leading zero (01 to 12)
    MMM  : the abbreviated localized month name (e.g. "Jan" to "Dec").
    MMMM : the long localized month name (e.g. "January" to "December").
    yy   : the year as two digit number (00 to 99).
    yyyy : the year as four digit number.
    h    : the hours without a leading 0 (0 to 11 or 0 to 23, depending on am/pm)
    hh   : the hours with a leading 0 (00 to 11 or 00 to 23, depending on am/pm)
    m    : the minutes without a leading 0 (0 to 59)
    mm   : the minutes with a leading 0 (00 to 59)
    s    : the seconds without a leading 0 (0 to 59)
    ss   : the seconds with a leading 0 (00 to 59)
    ap   : use a 12-hour clock instead of a 24-hour clock, with 'ap' replaced by the localized string for am or pm.
    AP   : use a 12-hour clock instead of a 24-hour clock, with 'AP' replaced by the localized string for AM or PM.
    iso  : the date with time and timezone. Must be the only format present.
    

    Puede obtener resultados inesperados si la fecha a la que se da formato contiene nombres de meses traducidos, lo que puede ocurrir si ha modificado los ajustes de formato para incluir MMMM. En este caso, en lugar de usar algo como {pubdate:format_date(yyyy)}, escriba la plantilla usando el modo de programación de plantillas, como en {:'format_date(raw_field('pubdate'),'yyyy')'}.

  • formats_modtimes(formato_fecha) – devuelve una lista de elementos (separados por dos puntos) separados por comas que representa las fechas de modificación para los formatos de un libro. El argumento formato_fecha especifica cómo se da formato a la fecha. Véase la función «format_date» para más detalles. Puede usar la función «select» para obtener la fecha de modificación de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB».

  • formats_paths() – devuelve una lista separada por comas de elementos separados por dos puntos que representan la ruta completa a los formatos de un libro. Puede usar la función «select» para obtener la ruta a un formato específico. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB».

  • formats_sizes() – devuelve una lista de elementos (separados por dos puntos) separados por comas que representa los tamaños en bytes de los formatos de un libro. Puede usar la función «select» para obtener el tamaño de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB».

  • fractional_part(x) – returns the value after the decimal point. For example, fractional_part(3.14) returns 0.14. Throws an exception if x is not a number.

  • has_cover() – return Yes if the book has a cover, otherwise return the empty string.

  • not(valor) – devuelve el texto «1» si el valor está vacío, en caso contrario, devuelve un texto vacío. Esta función opera bien con «test» o «first_non_empty».

  • list_difference(lista1, lista2, separador) – devuelve una lista construida eliminando de lista1 cualquier elemento que aparezca en lista2, sin distinguir mayúsculas y minúsculas. Los elementos de lista1 y lista2 están separados por separador, así como los de la lista resultante.

  • list_equals(lista1, sep1, lista2, sep2, val_sí, val_no) – devuelve val_sí si lista1 y lista2 contienen los mismos elementos, en caso contrario devuelve val_no. Los elementos se determinan dividiendo cada lista por el correspondiente carácter separador (sep1 o sep2). El orden de los elementos no es relevante. La comparación no diferencia mayúsculas y minúsculas.

  • list_intersection(lista1, lista2, separador) – devuelve una lista construida eliminando de lista1 cualquier elemento que no aparezca en lista2, sin distinguir mayúsculas y minúsculas. Los elementos de lista1 y lista2 están separados por separador, así como los de la lista resultante.

  • list_re(lista_orig, separador, incluir, sust_opc) – construye una lista separando primero lista_orig en elementos usando el carácter separador. Para cada elemento en la lista, comprueba si coincide con la expresión regular incluir. Si coincide, se añade a la lista final. Si sust_opc no es un texto vacío, se aplica la sustitución antes de añadir el elemento a la lista final.

  • list_re_group(lista_orig, separador, incluir, búsqueda, plantilla_grupo_1, plantilla_grupo_2, ...) – como list_re, pero las sustituciones no son opcionales. Usa re_group(elemento, búsqueda, plantilla_grupo_1, ...) para hacer sustituciones..

  • list_sort(list, direction, separator) – return list sorted using a case-insensitive sort. If direction is zero, list is sorted ascending, otherwise descending. The list items are separated by separator, as are the items in the returned list.

  • list_union(list1, list2, separator) – return a list made by merging the items in list1 and list2, removing duplicate items using a case-insensitive comparison. If items differ in case, the one in list1 is used. The items in list1 and list2 are separated by separator, as are the items in the returned list.

  • mod(x) – returns the remainder of x / y, where x, y, and the result are integers. Throws an exception if either x or y is not a number.

  • multiply(x, y)– devuelve x * y. Da una excepción si x o y no son números.

  • ondevice() – return the string «Yes» if ondevice is set, otherwise return the empty string

  • or(value, value, ...) – returns the string "1" if any value is not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want.

  • print(a, b, ...) – escribe los argumentos en la salida estándar. Sólo será visible si inicia calibre a partir de línea de órdenes (calibre-debug -g).

  • raw_field(name) – devuelve el campo de metadatos llamado nombre sin aplicar ningún formato.

  • raw_list(nombre, separador) – devuelve la lista de metadatos nombrada por nombre sin aplicar ningún formato u ordenación, con los elementos separados por separador.

  • re_group(val, pattern, template_for_group_1, for_group_2, ...) – return a string made by applying the regular expression pattern to the val and replacing each matched instance with the string computed by replacing each matched group by the value returned by the corresponding template. The original matched value for the group is available as $. In Template Program Mode, like for the template and the eval functions, you use [[ for { and ]] for }. The following example in Template Program Mode looks for series with more than one word and uppercases the first word:

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • round(x) – devuelve el entero más cercano a x. Da un error si x no es un número.

  • series_sort() – devuelve el valor de orden de serie.

  • split(lista, sep, prefijo_id) – divide la lista en valores separados por sep y asigna los valores a variables con nombre prefijo_id_N, donde N es la posición del valor en la lista. El primer elemento tiene posición 0 (cero). La función devuelve el último elemento de la lista. Ejemplo:

    split('one, two, foo', ',', 'var')
    

es equivalente a:

var_0 = 'one';
var_1 = 'two';
var_3 = 'foo
  • strcat(a, b, ...) – puede tomar cualquier número de argumentos. Devuelve texto formado por la concatenación de todos los argumentos.

  • strcat_max(max, string1, prefix2, string2, ...) – Returns a string formed by concatenating the arguments. The returned value is initialized to string1. prefix, string pairs are added to the end of the value as long as the resulting string length is less than max. Returns string1 even if string1 is longer than max. You can pass as many prefix, string pairs as you wish.

  • strcmp(x, y, lt, eq, gt) – does a case-insensitive comparison x and y as strings. Returns lt if x < y. Returns eq if x == y. Otherwise returns gt.

  • strlen(a) – Devuelve la longitud del texto pasado como argumento.

  • substr(texto, inicio, fin) – devuelve los caracteres entre la posición inicio y fin de texto. El primer carácter de texto está en la posición cero. Si fin es negativo, entonces indica la posición contando desde la derecha. Si fin es cero, indica el último carácter. Por ejemplo, substr('12345', 1, 0) devuelve 2345, y substr('12345', 1, -1) devuelve 234.

  • subtract(x, y) – returns x - y. Throws an exception if either x or y are not numbers.

  • today() – return a date string for today. This value is designed for use in format_date or days_between, but can be manipulated like any other string. The date is in ISO format.

  • template(x) – evaluates x as a template. The evaluation is done in its own context, meaning that variables are not shared between the caller and the template evaluation. Because the { and } characters are special, you must use [[ for the { character and ]] for the “}” character; they are converted automatically. For example, template('[[title_sort]]') will evaluate the template ``{title_sort} and return its value. Note also that prefixes and suffixes (the |prefix|suffix syntax) cannot be used in the argument to this function when using Template Program Mode.

Usar el modo de programación general

Para programas de plantilla más complicados, mucha veces es más sencillo evitar la sintaxis de plantillas (todos los caracteres «{» y «}») y escribir programas con aspecto más convencional. Puede hacer esto comenzando la plantilla con program:. El programa de plantilla se compila y ejecuta. No se realiza ningún procesado de plantillas (formato, prefijos, sufijos). El valor especial $ no se establece.

Una ventaja del modo program: es que las llaves dejan de ser especiales. Por ejemplo, no es necesario usar [[ y ]] al usar la función template(). Otra ventaja es la legibilidad.

El modo de programación de plantillas y el modo de programación general permiten usar los operadores de relación (comparación) tradicionales: ==, !=, <, <=, >=, >=. Los operadores devuelven «1» si son ciertos y en caso contrario, «». Los textos se comparan sin distinguir mayúsculas y minúsculas y en orden lexicográfico. Ejemplos:

  • program: field('series') == 'lala' devuelve «1» si la serie del libro es «lala».

  • program: if field('series') != 'lala' then 'nana' else 'blabla' fi devuelve «nana» si la serie del libro no es «lala», en caso contrario devuelve «blabla».

  • program: if or(field('series') == 'lala', field('series') == '1632') then 'sí' else 'no' fi devuelve «sí» si la serie es «lala» o «1632», en caso contrario devuelve «no».

  • program: if '11' > '2' then 'sí' else 'no' fi devuelve «no» porque realiza una comparación lexicográfica. Si quiere efectuar comparaciones numéricas en lugar de lexicográficas, use los operadores ==#, !=#, <#, <=#, >#, >=#. En este caso los valores a la izquierda y derecha se toman como cero si no están definidos o son un texto vacío. Si no son números, se genera un error.

Tanto el modo de programación general como el de plantillas permiten expresiones con ``if``, con la siguiente sintaxis:

if <<expression>> then
    <<expression_list>>
[elif <<expression>> then <<expression_list>>]*
[else <<expression_list>> ]
fi

The elif and else parts are optional. The words if, then, elif, else, and fi are reserved; you cannot use them as identifier names. You can put newlines and white space wherever they make sense. <<expression>> is one template language expression; semicolons are not allowed. <<expression_list>> is a semicolon-separated sequence of template language expressions, including nested ifs. Examples:

  • program: if field('series') then 'yes' else 'no' fi

  • program: if field('series') then a = 'yes'; b = 'no' else a = 'no'; b='yes' fi; strcat(a, '-', b)

  • Ejemplo de if anidado:

    program:
        if field('series')
        then
            if check_yes_no(field('#mybool'), '', '', '1')
            then
                'yes'
            else
                'no'
            fi
        else
            'no series'
        fi
    

Un if produce un valor como cualquier otra expresión. Esto significa que todas las siguientes expresiones son válidas:

  • program: if field('series') then 'foo' else 'bar' fi

  • program: if field('series') then a = 'foo' else a = 'bar' fi; a

  • program: a = if field('series') then 'foo' else 'bar' fi; a

  • program: a = field(if field('series') then 'series' else 'title' fi); a

El lenguaje de plantillas permite expresiones con ``for``, con la siguiente sintaxis:

for <<id>> in <<expression>>:
    <<expression_list>>
rof

La expresión debe arrojar una clave de consulta de un campo de metadatos, como tags o #genero, o una lista de valores separados por comas. Si el resultado es un nombre de consulta válido, se obtiene el valor del campo, en caso contrario la lista se divide en sus valores individuales. Cada valor de la lista se asigna a la variable id y después se evalúa expression_list.

Ejemplo: Esta plantilla elimina el primer nombre jerárquico para cada valor de Género (#genre`), construyendo una lista con los nuevos nombres.

program:
        new_tags = '';
        for i in '#genre':
                j = re(i, '^.*?\.(.*)$', '\1');
                new_tags = list_union(new_tags, j, ',')
        rof;
    new_tags

Si el Género original es Historia.Militar, Ciencia ficción.Historia alternativa, Léeme, la plantilla devolverá Militar, Historia alternativa, Léeme. Puede usar esta plantilla en Modificar metadatos en masa > Buscar y sustituir con Buscar establecido en plantilla para eliminar el primer nivel de la jerarquía y asignar el valor resultante a Género.

Nota: la última línea en la plantilla, new_tags, no es necesaria en este caso, porque for devuelve el valor de la última expresión en expression_list.

Plantillas guardadas de modo de programa general

El modo de programación general permite guardar plantillas e invocarlas desde otra plantilla. Puede guardar plantillas en Preferencias > Avanzado > Funciones de plantilla. Hay más información en el diálogo correspondiente. Puede invocar una plantilla de la misma manera que una función, pasando argumentos por posición si lo desea. Un argumento puede ser una expresión. Ejemplos para invocar una plantilla, suponiendo que la plantilla guardada se llame foo:

  • foo() – invoca la plantilla sin pasar argumentos.

  • foo(a, b) – invoca la plantilla pasando los valores de las variables a y b.

  • foo(if field('series') then field('series_index') else 0 fi) – if the book has a series then pass the series_index, otherwise pass the value 0.

En la plantilla guardada puede obtener el valor de los argumentos pasados en la invocación usando la función arguments. Esta función declara e inicializa las variables locales, parámetros en la práctica. Las variables son posicionales: obtienen el valor del argumento usado en la misma posición en la invocación. Si el argumento correspondiente no aparece en la invocación, arguments asigna a esa variable el valor predeterminado suministrado. Si no hay valor predeterminado, será un texto vacío. Por ejemplo, la siguiente función arguments declara dos variables: key y ``alternate`:

arguments(key, alternate='series')

Ejemplos, suponiendo de nuevo que la plantilla guardada se llame foo:

  • foo('#miserie') – la variable key tendrá el valor #miserie y la variable alternate tendrá el valor series.

  • foo('serie', '#genero') – la variable key tendrá el valor serie y la variable alternate tendrá el valor #genero.

  • foo() – la variable key será un texto vacío y la variable alternate tendrá el valor #genre#.

Una buena manera de probar las plantillas guardadas es usar el diálogo Prueba de plantillas. Asígnele un atajo de teclado en Preferencias > Avanzado > Atajos > Prueba de plantillas. Si le asigna un atajo de teclado podrá alternar rápidamente entre la prueba de plantillas y la modificación del código de programa de la plantilla.

Pasar información adicional a las plantillas

Un desarrollador puede decidir pasar información adicional al procesador de plantillas, como metadatos del libro específicos para una aplicación o información sobre lo que se quiere que haga el procesador. Una plantilla puede acceder a esta información y usarla durante la evaluación.

Desarrollador: cómo pasar información adicional

La información adicional es un diccionario Python que contiene pares nombre_de_variable: valor de variable donde los valores deben ser textos. La plantilla puede acceder al diccionario, creando variables locales con nombre nombre_de_variable y valor valor de variable. El usuario no puede cambiar el nombre, así que lo mejor es usar nombres que no entren en conflicto con otras variables locales, por ejemplo añadiendo un guión bajo al principio del nombre.

El diccionario se pasa al procesador de plantillas (el formatter) usando el argumento global_vars=diccionario. La forma completa del método es:

def safe_format(self, fmt, kwargs, error_value, book,

column_name=None, template_cache=None, strip_results=True, template_functions=None, global_vars={})

Creador de plantillas: cómo acceder a la información adicional

Puede acceder a la información adicional de una plantilla usando la función de plantilla globals(id[=expresión] [, id[=expresión]]*), donde id es cualquier nombre de variable permitido. Esta función comprueba si la información adicional prevista por el desarrollador contiene el nombre. Si es así, la función asigna el valor a una variable local con ese nombre. Si el nombre no está presente en la información adicional y se suministra una expresión, se evalua dicha expresión y el resultado se asigna a la variable local. Si no existe ni un valor ni una expresión, la función asigna el texto vacío ('') a la variable local.

Notas sobre las diferencias entre modos

Los tres modos de programación, el modo de funcíon única (MFU), el modo de programación de plantillas (MPP) y el modo de programación general (MPG) funcionan de distinta manera. MFU pretende ser «sencillo» y oculta muchos elementos del lenguaje de programación. Por ejemplo, el valor de la columna siempre se pasa como el primer argumento «invisible» a la función que se incluye en la plantilla. Además MFU no hace distinciones entre variables y textos: todas las variables son textos.

Ejemplo: La siguiente plantilla MFU devuelve el nombre de la serie o el texto «no series»:

{series:ifempty(no series)}

La plantilla equivalente en MPP es:

``{series:'ifempty($, 'no series')'}``

La plantilla equivalente en MPG es:

``program: ifempty(field('series'), 'no series')``

El primer argumento de ifempty es el valor del campo series. El segundo argumento es el texto no series. En MFU el primer argumento, el valor, se pasa automáticamente (es el argumento invisible).

Varias funciones de plantilla, como booksize() y current_library_name(), no admiten argumentos. Debido al «argumento invisible», no puede usar estas funciones en MFU.

Las funciones anidadas, en las que una función invoca a otra función para evaluar un argumento, no pueden usarse en MFU. Por ejemplo, esta plantilla, que pretende devolver los primeros cinco caracteres del valor de la serie convertidos en mayúsculas, no funcionará en MFU:

``{series:uppercase(substr(0,5))}``

MPP y MPG permiten usar funciones anidadas. La plantilla anterior en MPP sería:

``{series:'uppercase(substr($, 0,5))'}``

En MPG sería:

``program: uppercase(substr(field('series'), 0,5))``

Funciones de plantilla Python definidas por el usuario

Puede añadir funciones propias al procesador de plantillas. Dichas funciones pueden usarse en cualquiera de los tres modos de programación de plantillas. Las funciones se añaden en Preferencias > Avanzado > Funciones de plantilla. Las instrucciones se muestran en el correspondiente cuadro de diálogo.

Notas especiales para plantillas de guardado o envío

Cuando una plantilla se usa como plantilla de «guardado a disco» o de «envío a dispositivo», ocurre un procesado especial. Los valores de los campos se sanean, eliminando caracteres especiales para los sistemas operativos por guiones bajos, incluyendo barras. Esto significa que el texto de los campos no puede usarse para crear carpetas. Sin embargo, las barras no se modifican en los textos de prefijo o sufijo, por lo que las barras en estos textos harán que se creen carpetas. Gracias a esto, es posible crear estructuras de carpetas de profundidad variable.

Por ejemplo, supongamos que quiere una estructura de carpetas serie/índice de serie - título, con la salvedad de que si la serie no existe el título debe estar en la carpeta superior. La plantilla para conseguir esto es:

{series:||/}{series_index:|| - }{title}

La barra y el guión sólo aparecen si la serie no está vacía.

La función lookup() nos permite realizar un procesado aún más complejo. Por ejemplo, supongamos que si un libro tiene una serie, entonces queremos una estructura de carpetas serie/índice de serie - título. Si el libro no tiene una serie, entonces queremos la estructura género/orden de autor/título. Si el libro no tiene género, queremos que use «Desconocido». Queremos seguir dos caminos completamente distintos según el valor de la serie.

Para lograr esto:
  1. Creamos un campo compuesto (démosle el nombre de consulta #AA) que contiene {series}/{series_index} - {title}. Si la serie no está vacía, esta plantilla produce serie/número_de_serie - título.

  2. Creamos un campo compuesto (démosle el nombre de consulta #BB) que contenga {#genre:ifempty(Desconocido)}/{author_sort}/{title}. Esta plantilla produce género/orden de autor/título, donde un género vacío se sustituye por Desconocido.

  3. Establecemos la plantilla de guardado en {series:lookup(.,#AA,#BB)}. Esta plantilla elige el campo compuesto #AA si la serie no está vacía y el campo compuesto #BB si la serie está vacía. Obtenemos por lo tanto dos rutas de guardado completamente diferentes según el campo series esté o no vacío.

Plantillas y controles de metadatos

Los paneles de conexiones se usan para cambiar los metadatos escritos en los libros durante las operaciones de guardado en disco y de envío a dispositivo. Un panel de conexiones le permite especificar una plantilla para suministrar los datos que se escribirán en los metadatos del libro. Puede usar los paneles de conexiones para modificar los siguientes campos: authors, author_sort, language, publisher, tags, title, title_sort. Esa función es útil para los que quieren usar metadatos diferentes en los libros de los dispositivos, para solucionar problemas de ordenación o de visualización.

When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are connected to their destination fields, hence the name plugboards. You can, of course, use composite columns in these templates.

Cuando un panel de conexiones pueda aplicarse (servidor de contenido, guardado en disco o envío a dispositivo), calibre busca los paneles definidos para elegir el correcto según el formato y dispositivo. Por ejemplo, para encontrar el panel de conexiones apropiado para enviar un libro EPUB a un dispositivo ANDROID, calibre busca en los paneles en el siguiente orden:

  • un panel de conexiones con una coincidencia exacta de formato y dispositivo, por ejemplo: EPUB y ANDROID

  • un panel de conexiones con una coincidencia exacta de formato y el dispositivo especial any device, por ejemplo EPUB y any device

  • un panel de conexiones con el formato especial any format y una coincidencia exacta de dispositivo, por ejemplo: any format y ANDROID

  • un panel de conexiones con any format y any device

Los campos etiquetas y autores tienen un trato especial, debido a que ambos pueden tener más de un elemento. Un libro puede poseer varias etiquetas y varios autores. Cuando indique que desea cambiar uno de estos campos, la plantilla se examina para comprobar si hay más de un elemento. Para las etiquetas, el resultado se divide dondequiera que calibre encuentre una coma. Por ejemplo, si la plantilla produce el valor Intriga, Terror, el resultado serán dos etiquetas: Intriga y Terror. No existe manera de poner una coma dentro de una etiqueta.

Lo mismo ocurre con los autores, pero usando un carácter diferente para el corte, un signo «&» en lugar de una coma. Por ejemplo, si la plantilla produce el valor Blogs, Joe&Posts, Susan, el libro acabará con dos autores, Blogs, Joe y Posts, Susan. Si la plantilla produce el valor Blogs, Joe;Posts, Susan, el libro tendrá un autor con un nombre peculiar.

Los paneles de conexiones afectan a los metadatos escritos en el libro cuando se guarda en disco o se escribe en un dispositivo. Los paneles de conexiones no afectan a los metadatos usados por las funciones Guardar en el disco Enviar al dispositivo para crear los nombres de archivo. En lugar de ello, los nombres de archivo se construyen usando las plantillas introducidas en la ventana de preferencias correspondiente.

Consejos

Puede encontrar útiles los siguientes consejos.

  • Use la prueba de plantillas para probar plantillas. Añada esta función al menú contextual para libros en lea biblioteca o asígnele un atajo de teclado.

  • Las plantillas pueden usar otras plantillas haciendo referencia a columnas compuestas construidas con la plantilla deseada. También puede usar plantillas guardadas.

  • En un panel de conexiones, puede establecer un campo como vacío (o lo que sea equivalente a vacío) utilizando la plantilla especial {}. Esta plantilla siempre producirá un texto vacío.

  • La técnica descrita anteriormente para mostrar los números incluso si son cero funciona con el campo estándar «series_index».

Referencia de funciones