Ampliando o SAP Lumira com gráficos personalizados
8.1 Sobre gráficos de amostra criados de extensões CVOM
8.1.4 Compreendendo o fluxo de trabalho da criação de extensão
8.1.4.3 Compreendendo os módulos de gráfico
Os módulos são os componentes principais de um gráfico. É necessário que vários módulos trabalhem juntos para construir um gráfico. Um módulo consiste em uma definição de módulo e uma função de módulo.
Definição de módulo
Uma definição de módulo é um objeto JSON:
'id': 'UNIQ_ID',
'type': 'CONTAINER|CHART|SUPPLEMENTARY|CONTROLLER', 'name' : 'bar',
'base' : 'xy', //optional
'abstract' : true|false, //optional
'properties' : PROPERTIES SPEC,
'feeds' : FEED CONFIGURATION, //feeds is optional for supplementary modules
//define keys to reference sub modules in a container, see container module special 'submodulekeys' : CONTAINER MODULE SPECIAL SPEC,
'datastructure' : DATA STRUCTURE DOC, //reserved for future detail doc, can be ignored for now 'events' : EVENT DOC,
'css' : CSS DOC,
'fn' : fn //your module function
Os elementos de uma definição de módulo estão definidos na tabela abaixo:
Definição Elemento
A identidade exclusiva de um módulo. id
O tipo do módulo. type
Nome do módulo. name
O supermódulo. Um módulo pode ser herdeiro de outro módulo, o módulo que dá a herança é chamado de supermódulo. Esta propriedade é opcional.
Definição Elemento
Se um módulo pode ou não ser usado direta- mente. Esta propriedade é opcional e é definida como falsa por padrão.
abstract
Propriedades personalizadas. properties
Feeds utilizados por este módulo. Se o módulo for um módulo complementar, esta propriedade será opcional.
feeds
Definir chaves para fazer referência a submódulos em um recipiente.
submodulekeys
Reservado para atualização futura. datastructure
Eventos suportados pelo módulo. events
Classes CSS utilizadas pelo módulo. css
Função do módulo. fn
Observação:
As definições de properties, feeds, submodulekeys, data structure, events e css são descritivas; o módulo deve seguir essas definições, mas a implementação do módulo tem permissão para violá-las.
Documento de evento
Cada módulo pode definir seus próprios eventos expostos em manifest.js.
'events': {
'EVENT_NAME' : 'EVENT_DESCRIPTION' }
Em uma descrição de evento, você deve descrever claramente quando o evento é acionado e o que pode ser esperado nos dados do evento. Uma estrutura de dados de evento típica deve parecer com o seguinte exemplo:
'name' : EVENT_NAME, 'data' : EVENT_DATA
Observação:
A base d3.dispatch é um pacote interno sujeito a alteração sem garantia de compatibilidade com versões anteriores.
Função de módulo
Um módulo gráfico é um componente de gráfico reutilizável que deve ser encapsulado em uma função configurável.
Coloque sua lógica de desenho na função passada em selection.each().
function module() { var width = 720,
height = 80;
function my(selection) {
selection.each(function(d, i) {
// put drawing logic here, generate chart here; `d` is the data and `i` is the element });
return my; }
my.width = function(value) {
if (!arguments.length) return width; width = value;
return my; };
my.height = function(value) {
if (!arguments.length) return height; height = value;
return my; };
return my; }
No código acima, my suporta duas interfaces: width e height. Para um módulo, entretanto, mais interfaces devem ser suportadas.
Todos os módulos devem suportar as seguintes interfaces:
/** * set/get width */ 'width' : function(value){ if (!arguments.length){ return width; } width = value; return my; } /** * set/get height */ 'height' : function(value); /** * set/get size
* @param {Object} {'width':Num, 'height':Num} */
'size' : function(_);
/**
* set/get data, for some modules like Title, it doesn't need data */ 'data' : function(data); /** * set/get properties */ 'properties' : function(props);
/**
* get/set your color palette if you support color palette */
'colorPalette' : function(_);
/**
* get/set your shape palette if you support shape palette */
'shapePalette' : function(_);
/**
* get/set your event dispatch if you support event */
'dispatch' : function(_);
/**
* get/set your parent g element, currently we don't use set, usually you just * return the selection passed to you when call you
*/
'parent' : function(_)
Um tipo de módulo específico pode suportar interfaces adicionais, conforme descrito nas seguintes seções.
Tipo de módulo
Há quatro tipos de módulos.
Descrição Tipo de módulo
Utilizado para fazer layout de módulos. Recipiente
Utilizado como módulo de plotagem de um gráfi- co.
Gráfico
Utilizado para fornecer partes auxiliares, por ex- emplo, título, legenda etc.
Complementar
Utilizado para controlar interações entre o usuário e o gráfico.
Controlador
Módulo recipiente
Um módulo recipiente pode ter tudo que um módulo comum tem, como propriedades, “Feeds”, eventos, CSS etc. Entretanto, geralmente ele não tem “Feeds” ou CSS. Além disso, um módulo recipiente deve definir suas estruturas de submódulo em submodulekeys.
'submodulekeys':[{ 'key': KEY_NAME,
'description': DESCRIPTION }]
Um recipiente simples pode suportar 5 chaves:
'submodulekeys' : [{ 'key': 'xaxis',
'description': 'Define horizontal axis module in the bottom' },{
'key': 'x1axis',
'description': 'Define horizontal axis module in the top' },{
'key': 'yaxis',
'description': 'Define vertical axis module in the left' },{
'key': 'y1axis',
'description': 'Define vertical axis module in the right' },{
'key': 'plot',
'description': 'Define the plot module in the center' }]
Um módulo recipiente também deve suportar configuração, como as interfaces:
/**
* set/get configuration
* Required for container modules */
'config' : function(config);
Módulo gráfico
O módulo gráfico precisa suportar os seguintes recursos:
/**
* Get/set all of your scales. The name does not need to be the same across all modules, but should be well documented.
* Like for bar modules, there are three scales: the category scale, the primary value scale and the second value scale.
* Functions can be: */
'categoryScale' : function(_); 'primaryScale' : function(_); 'secondScale' : function(_);
/**
* Get size calculation function.
* Required for modules that support size legend. * @return {
* 'width': function(w){
* //biggest size function against width, currently we only support linear equation
* return a*w + c;
* },
* 'height': function(h){
× //biggest size function against height, currently we only support linear equation
* return a*h + c;
* }
*/
'getSizeCalculationFunction' : function();
Se você quer usar um módulo gráfico em vários gráficos, as seguintes interfaces também devem ser suportadas:
/**
* Get/set data range of all of your value scales. As in the multi-chart case, × we need to sync domain values of scales in each sub chart module.
* The chart module has to provide corresponding get/set functions for the data range. * Functions can be:
*/
'primaryDataRange' : function(_); 'secondDataRange' : function(_);
Módulo complementar
O módulo complementar é utilizado para criar partes auxiliares para um gráfico. Por exemplo, o módulo título para mostrar um título ou o módulo legenda para mostrar uma legenda. CVOM entrega vários módulos complementares, que você pode usar normalmente diretamente. Se eles não atenderem às suas necessidades, você poderá criar seus próprios módulos.
As seguintes interfaces devem ser suportadas:
/**
* Get preferred size.
* Required for Supplementary modules only. * @return { * 'width': NUMBER, * 'height' : NUMBER * } */ 'getPreferredSize' : function(); /**
* Get/set scale which is needed by you, for example, a size Legend may need/want to export a size scale * A value axis may need a value scale. the name can be determined by modules but should be well documented. * like for value axis, we can have a function like:
*/
'scale' : function(_);
Módulo controlador
O módulo controlador é utilizado para controlar interações entre o usuário e o gráfico. Se seu gráfico precisa suportar interações como essas, você precisa adicionar o módulo controlador à sua definição de gráfico.
Diferentemente de outros módulos, os módulos controladores somente precisam de uma interface pública:
/**
* Get/set properties: */
'properties' : function(props);