Pie | A leaflet library

En este tutorial se explicarán las principales características de la librería. Estas no se activarán hasta que llegues a las secciones donde se describen.

The main features of this plugin will be explained in this tour. These features won't be active in the map until you scroll to related sections.

Pie usa una clase base L.Pie.Dataset. Esta es el contenedor de los datos y de sus modos de representación, contenidos en la clase L.Pie.Display. Un display es un conjunto de instrucciones de representación de datos —como los colores, etiquetas y tamaños—. Asíque para empezar tienes que hacer tres cosas:

Cargar los archivos del plugin —LeafletPie.min.js y LeafletPie.min.css.
Instanciar un dataset pasando un array con los datos que quieres representar.
Añadir al menos un display para representar esos datos (y activarlo).

Pie uses a base class named L.Pie.Dataset. This one is the container of the data to be rendered and the ways of representing it, encapsulated in the class L.Pie.Display. A display is a set of instructions to represent data—like colors, labels, sizes...—. So, to start you've to do three things:

Load plugin files as usual—LeafletPie.min.js and LeafletPie.min.css.
Instantiate a dataset, passing to it an array of the elements that compose the dataset.
At least add a display to the dataset and activate it.

El marcado generado para cada gráfica es un SVG, donde cada 'porción de la tarta' es un path. A cada path se le añade una clase que es el resultado de slugificar su etiqueta para facilitar operaciones JS/CSS. Por ejemplo una categoría con etiqueta «Número de socios» añadiráal path una clase cat--numero-de-socios. Los valores necesarios se añaden como atributos data al elemento para poder acceder a ellos mediante javascript, pudiendo accediendo al diccionario dataset del nodo. (Ver ejemplo Hover callbacks más abajo.) Las opciones min_size y compensation determinan los tamaños de estos elementos. La primera es el diámetro del elemento más pequeño del dataset, y la segunda establece si queremos aplicar el método de compensación de Flannery a la hora de calcular los tamaños relativos de los elementos. Este método hará los iconos más grandes pero compensará la comparación de tamaños relativos. Artículo sobre los métodos cognitivos en el diseño de mapas, con la fórmula de Flannery empleada aquí

The generated markup for each pie chart will be a DivIcon, with a SVG inside, wherein each 'slice' is rendered as a path. A class will be added to each of these 'slices', result of slugifying its data label, to ease JS/CSS operations. For instance an item labelled as 'number of members' will have a class 'cat--number-of-members' appended to it. Color, label and value will be appended as data attributes as well, allowing to retrieve them using javascript (see Hover callback example below). min_size and compensation options determine the size of pies. The first one will set the diameter of the smallest data item in the set and the second one will activate Flannery's compensation when calculing the rest of sizes. Compensation will yield bigger items but 'compensated', that's it, it will take into account the way in which our brain perceives circular areas, making comparations between elements more accurate. Article about cognitive map-design, including the Flannery's formula used here.

Puedes añadir tooltips como opción de configuración del display. Para ello tienes que pasar una opción default-hover al display con valor true. Puedes añadir clases CSS al contenedor del tooltip con la opción hover_classes. Las cantidades mostradas en el tooltip se sufijarán con la unidad que indiques en el parámetro units. La librería dispone de varias clases genéricas para dar estilo al tooltip, dentro del namespace lpie. En este ejemplo se usan lpie-light y lpie-shadow, para usar un tema base claro y poner una sombra al tooltip. Actualmente los tooltips se resuelven exclusivamente con CSS, de manera que pueden quedar parcialmente ocultos bajo otros marcadores.

You can configure the display to show tooltips by default when hovering a pie, passing to it a default-hover option set to true. To customise it you can add HTML classes to the tooltip container, passed as a String value to hover_classes display's option (for example "class-a class-b class-c"). The tooltip will show a complete breakdown of pie's values, suffixed by the unit passed in the argument units. The plugin has a few generic classes to set default styles, prefixed by the namespace 'lpie', as 'lpie-light', lpie-dark' and 'lpie-shadow'.
Disclaimer: To keep things simple, tooltip effect is solved with CSS right now, so it can be partially hidden under leaflet markers.

El marcado del tooltip sigue la estructura:

Tooltip's markup follows this structure:

Otra necesidad común es la de generar un cuadro explicativo para el dataset. Siguiendo un principio DRY la librería dispone de un control de Leaflet para generarlo automáticamente a partir de un display. Al instanciar la leyenda se le ha de pasar este, que usará para crear automáticamente la lista de categorías y colores asociados. Del mismo modo que con los tooltips puedes añadir clases CSS al contenedor en el valor de la opción legend_classes.

To have an explicative legend is a common need for this kind of displays. Following a DRY convention, the plugin has a Leaflet control to render it automatically from a given display and a set of arguments (title, description, source). The display will be used to fetch label and color per each category and append a category list to the legend. As with tooltips you can pass a legend_classes argument to customise the look of the legend through CSS.

El marcado de la leyenda sigue la estructura:

Legend's markup follow this structure:

Puedes pasar al display el nombre de una función que será la que retorne el HTML del popup de leaflet. Esta función tendrá acceso —en el ejemplo la variable item— a campos del elemento correspondiente dentro del dataset.

Markers can have regular leaflet popups attached to them. To set the markup of the popup you can pass to the display the name of a function that will have access to item data in the dataset and that will return the markup to be rendered.

Puedes pasarle una función al display para que se ejecute cuando la usuaria haga hover sobre los marcadores del mapa. Abre la consola para ver los resultados de este callback.

You can set a custom callback when the user hovers the pie to trigger custom events or to create different kinds of tooltips. To set a custom callback pass the name of the function to the display. Notice how in the previous case you passed the function whilst here you pass the function name

Pie tiene licencia GPL v.3. Si detectas bugs o tienes features que sugerir abre un issue en Github. Y si la usas en algún proyecto interesante, ponte en contacto con nosotras en info(en)tejido.io

Pie, 2017. Pie is licensed under a free software license GPL v.3. If you detect a bug or have features to suggest open an issue in Github. And if you use this plugin in an interesting project let us know at info(at)tejido.io