12 Ampliando o SAP Lumira com gráficos personalizados
12.1 Sobre gráficos de amostra criados de extensões CVOM
12.1.4 Compreendendo o fluxo de trabalho da criação de extensão
As seções a seguir fornecem detalhes sobre o fluxo de trabalho da criação de extensão.
12.1.4.1 Compreendendo os feeds de gráfico
Definição de feed
Um Feed é uma definição que descreve a relação entre os dados e a visualização. Os Feeds permitem juntar os dados a uma determinada visualização sem que fiquem incorporados a ela.
Uma Definição de feed pode ser para um Feed simples ou um grupo de Feeds. A execução de feed - ligação de dados a feeds - ocorrerá automática ou manualmente na criação de uma visualização.
Conteúdo de uma definição de feed
Uma Definição de feed contém os seguintes elementos:
● Descrição semântica de um recipiente de dados (índice de eixo de análise ou índice de grupo de valores de medida).
● Tipo de recipiente de dados aceito (dimensão ou medida).
● Restrição de feed (contagem mínima ou máxima do recipiente de dados). ● ID do feed.
96
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
● Nome do feed. ● Outros.
Amostra de definição de feed de gráfico de barras
Um gráfico de barras tem quatro Feeds: dois Feeds que aceitam uma dimensão e dois Feeds que aceitam uma medida.
FeedId FeedName FeedType Mín Máx AAIndex MGIndex AcceptMND
RegionColor Cor da região Dimensão 0 2 2 Indefinido 1 AxisLabels Etiquetas de eixo Dimensão 1 2 1 Indefinido 0 PrimaryValu es Valores primários
Medida 1 Infinidade Indefinido 1 Indefinido
SecondaryV alues
Valores secundários
Medida 0 Infinidade Indefinido 2 Indefinido
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
Usando Feeds e dimensões Nome de medida [page 98]
12.1.4.1.1 Usando Feeds e dimensões Nome de medida
Esta página o ajuda a entender como executar as seguintes tarefas: ● Obter a Definição de feed de uma visualização.
● Decidir a aparência da visualização. ● Vincular os dados ao Feed
98
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
Obter a definição do Feed
Você pode obter a definição do Feed de uma visualização por uma API pública. A definição de feed retornada conterá uma descrição completa de um conjunto de Feeds. MeasureNamesDimension é uma dimensão que consiste em todos os nomes das medidas. Ela só pode ser alimentada em um Feed que aceita
MeasureNamesDimension.
Decidir a aparência da visualização
Um conjunto de dados pode gerar diferentes resultados de visualizações.
Exemplo de Feeds e MeasureNameDimension
Observe os conjuntos de dados de tabela de referência cruzada a seguir. Atenas (2004):
País Ouro Prata Bronze
EUA 35 39 29
China 32 17 14
Rússia 27 27 38
Pequim (2008):
País Ouro Prata Bronze
EUA 36 38 36
China 51 21 28
Rússia 23 21 29
Queremos mostrar os dados como um gráfico de barras. Temos a definição de Feed do gráfico de barras:
FeedId FeedName FeedType Mín Máx AAIndex MGIndex AcceptMND
RegionColor Cor da região Dimensão 0 2 2 Indefinido 1 AxisLabels Etiquetas de eixo Dimensão 1 2 1 Indefinido 0
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
FeedId FeedName FeedType Mín Máx AAIndex MGIndex AcceptMND
PrimaryValu es
Valores primários
Medida 1 Infinidade Indefinido 1 Indefinido
SecondaryV alues
Valores secundários
Medida 0 Infinidade Indefinido 2 Indefinido
Execute o feed da MeasureNamesDimension no Feed AxisLabels:
var dataFeeding = [
{ "feedId" : "AxisLabels",
"binding" : [{"type": "analysisAxis", "index" : 1},{"type" : "measureNamesDimension"}]
},
{ "feedId" : "RegionColor",
"binding" : [{"type": "analysisAxis", "index" : 2}] },
{
"feedId" : "PrimaryValues",
"binding" : [{"type": "measureValuesGroup", "index" : 1}] },
];
O seguinte gráfico é o resultado do Feed:
100
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
Você também pode alterar a posição de MeasureNamesDimension:
var dataFeeding = [
{ "feedId" : "AxisLabels",
"binding" : [{"type": "measureNamesDimesion"},{"type": "analysisAxis", "index" : 1}]
},
{ "feedId" : "RegionColor",
"binding" : [{"type": "analysisAxis", "index" : 2}] },
{
"feedId" : "PrimaryValues",
"binding" : [{"type": "measureValuesGroup", "index" : 1}] },
];
O gráfico resultante terá então a MeasureNamesDimension em um local diferente do que o gráfico anterior:
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
12.1.4.2 Compreendendo o modelo de dados
Modelo de dados de tabela de referência cruzada
Utilizamos o seguinte código de amostra para explicar o que é um modelo de dados de tabela de referência cruzada. { "analysisAxis": [{ "index": 1, "data": [{ "type": "Dimension", "name": "Product",
"values": ["Car", "Truck", "Motorcycle", "Bicycle"] }] }, { "index": 2, "data": [{ "type": "Dimension", "name": "Country",
"values": ["China", "USA"] }, { "type": "Dimension", "name": "Year", "values": ["2001", "2001"] }] }], "measureValuesGroup": [{ "index": 1, "data": [{ "type": "Measure", "name": "Profit", "values": [ [25, 136, 23, 116], [58, 128, 43, 73] ] }, { "type": "Measure", "name": "Revenue", "values": [ [50, 236, 43, 126], [158, 228, 143, 183] ] }] }] }
As seguintes tabelas de dados mostram outra visão dos dados:
Um modelo de dados de tabela de referência cruzada é um modelo de dados semântico composto dos seguintes elementos:
102
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
● Dimensão: um dimensão tem um nome, uma matriz e uma etiqueta de valores de dimensão. Neste conjunto de dados de amostra, há 3 dimensões:
○ País ["China", "EUA"] ○ Ano ["2001", "2001"]
○ Produto ["Carro","Caminhão","Moto","Bicicleta"]
● Eixo de análise: o eixo de análise é composto de uma ou mais dimensões.
Há dois eixos de análise em uma modelo de tabela de referência cruzada que são chamados eixo de análise 1(aa1) e eixo de análise 2(aa2). Esses dois eixos podem ser considerados os cabeçalhos de linha e coluna da tabela de referência cruzada.
● Medida: a medida contém o valor de dados da tabela de referência cruzada.
Cada medida contém um nome de medida e uma matriz de valores de medida. Cada valor de medida é uma matriz bidimensional de número de aa2 * número de aa1.
● Grupo de valores de medida: cada conjunto de dados da tabela de referência cruzada pode conter um ou mais grupos de valores de medida.
Cada grupo de valor de medida é composto por uma ou mais medidas em um matriz.
Ligação de feed de dados
Os feeds de dados definem como ligar o eixo de análise e o grupo de valores de medida a uma visualização específica.
Por exemplo, uma visualização de tabela que tem os seguintes Feeds aceita os seguintes valores de dados: ● Coluna - aceita dados de dimensão
● Linha - aceita dados de dimensão ● Valor - aceita dados de medida
O processo do Feed determina como o conjunto de dados da tabela de referência cruzada se liga a esses Feeds. Por exemplo, se ligarmos aa1 à Coluna, aa2 à Linha e a medida Lucro ao Valor, teremos a seguinte visualização de tabela:
Multiplicador
Em alguns casos, pode ser útil separar a visualização em várias instância para fazer uma comparação. O Feed Multiplicador define como separar o conjunto de dados em várias instâncias.
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
Quando ligamos o feed aa1 à Coluna, aa2 à Linha, e a dimensão Nome da medida ao Multiplicador, obtemos a seguinte visualização de tabela.
Dimensão Nome da medida
A dimensão Nome da medida (MND) é diferente de outras dimensões. Nesta amostra, a dimensão Nome da medida tem um valor de ["Lucro", "Receita"] que é o nome das medidas.
Quando esta dimensão é ligada a feeds diferentes, a visualização pode gerar diferentes visões de análise: ● Coluna: aa1
Linha: aa2, MND
● Coluna: aa1 Linha: aa2, MND
104
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
● Coluna: MND Linha: aa2 Multiplicador: aa1
Dos dados da tabela para os dados da tabela de referência cruzada
Se os dados originais são dados da tabela, e não dados da tabela de referência cruzada, então você precisa executar uma conversão extra nos dados.
Consulte o HTML5 Visualization HANA Data Service para converter os dados da tabela em dados da tabela de referência cruzada de acordo com a configuração do feed.
12.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
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
//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:
Elemento Definição
id A identidade exclusiva de um módulo.
type O tipo do módulo.
name Nome do módulo.
base 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.
abstract Se um módulo pode ou não ser usado diretamente. Esta propriedade é opcional e é definida como falsa por padrão.
properties Propriedades personalizadas.
feeds Feeds utilizados por este módulo. Se o módulo for um módulo complementar, esta propriedade será opcional.
submodulekeys Definir chaves para fazer referência a submódulos em um recipiente.
datastructure Reservado para atualização futura.
events Eventos suportados pelo módulo.
css Classes CSS utilizadas pelo módulo.
fn Função do módulo.
Note
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.
106
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
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
Você deve valer-se de sap.riv.viz.shared.dispatch para implementar seus eventos.
Note
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.
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
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.
108
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
Tipo de módulo Descrição
Recipiente Utilizado para fazer layout de módulos.
Gráfico Utilizado como módulo de plotagem de um gráfico.
Complementar Utilizado para fornecer partes auxiliares, por exemplo, título, legenda etc.
Controlador Utilizado para controlar interações entre o usuário e o gráfico.
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);
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
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
110
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
* } */
'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);
12.1.4.4 Compreendendo a composição dos módulos
Definição de gráfico
As duas principais partes da definição de gráfico são módulos e dependências. Uma definição de gráfico típica parece com o seguinte bloco de código:
id : 'partner/samplebar', name : 'Sample Bar Chart', modules : { layout : { id : 'sap.viz.modules.layout.dock' }, title : { id : 'sap.viz.modules.title', configure : { propertyCategory : 'title' } }, legends:{ id:'sap.viz.modules.legend', configure:{ propertyCategory:'legendContainer', properties:{ layout:{ position:'right', priority:1 } } },
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
modules:{ legend:{ id:'sap.viz.modules.legend.common', data:{ aa:[ 2 ] }, configure:{ propertyCategory:'legend', properties:{ layout:{ order:0 } } } }, layout:{ id:'sap.viz.modules.layout.stack' } } }, main : { id : 'sap.viz.modules.xycontainer', modules : { plot : { id : 'partner.modules.samplebar' } } } }, dependencies : { attributes : [ { targetModule : 'legend', target : 'colorPalette', sourceModule : 'main.plot', source : 'colorPalette' } ], events : [] }
Módulos
As propriedades de módulo definem quais módulos o gráfico contém: Geralmente há vários módulos complementares além de um módulo recipiente ou gráfico.
Módulo complementar Descrição
Título Utilizado para gerar o título.
Legenda Utilizado para gerar a legenda.
Principal Gera a área principal. Neste exemplo nos referimos a um módulo recipiente em que colocamos um módulo gráfico.
112
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
reservados.
Guia do Usuário do SAP Lumira
Dependências
Pode haver dependências entre os módulos de um gráfico quando são adicionados à definição de gráfico. Há dois tipos de dependências: dependências de atributo e dependências de evento.
Atributos
As dependências de atributo são dependências de módulo entre atributos. Por exemplo, o módulo legenda deve usar a mesma paleta de cores que os módulos gráfico e o eixo X em um gráfico de colunas deve usar a mesma escala ordinal que um módulo barra.
Neste exemplo, colorPalette está sendo compartilhada entre o módulo plotagem e o módulo legenda, então é necessário definir o compartilhamento dentro das dependências:
'attributes' : [{ 'targetModule' : 'legend', 'target' : 'colorPalette', 'sourceModule' : 'plot', 'source' : 'colorPalette' }]
O atributo é fornecido pelo sourceModule e consumido pelo targetModule. A colorPalette é fornecida pelo módulo plotagem e pelo módulo legenda.
O sourceModule e o targetModule são os nomes de suas configurações de módulo dentro da configuração do gráfico. Para módulos que estão contidos dentro de outros módulos, o nome deve conter o caminho completo. A origem e o destino devem ser funções get/set públicas válidas em sourceModule e targetModule. O HTML VIZController é responsável por resolver as dependências em todas as atualizações de dados, propriedade ou tamanho.
Eventos
Um módulo pode obedecer o evento de outro módulo com um manipulador específico. Por exemplo, um módulo dica pode obedecer um evento showTooltip de um módulo barra e manipulá-lo com a função tooltipHandler e um módulo barra pode obedecer um evento hideSeries de um módulo legenda e manipulá-lo com a função showHideSeries:
/**
* Define event dependencies between modules.
* Target module can listen to source module’s event and handle it with a handler. */ 'events' : [{ 'targetModule' : 'tooltip', 'handler' : 'tooltipHandler', 'sourceModule' : 'main.plot', 'event' : 'showTooltip' }, { 'targetModule' : 'tooltip', 'handler' : 'tooltipHandler',
Guia do Usuário do SAP Lumira
Ampliando o SAP Lumira com gráficos personalizados
© 2013 SAP AG ou empresa afiliada da SAP. Todos os direitos
'sourceModule' : 'main.plot', 'event' : 'hideTooltip' }]
12.1.4.5 Registrando um novo tipo de gráfico
Depois de concluir a definição de um tipo de gráfico, você precisa usar o seguinte código para registrar o gráfico para que você e outros usuários possam utilizá-lo:
sap.viz.manifest.viz.register(chart);
Depois desta etapa, você pode utilizar o novo gráfico especificando o ID do gráfico.
Convenção de nomenclatura
Para evitar conflitos com tipos de gráficos pré-fornecidos, uma convenção é colocar seu arquivo JavaScript em