Classe auxiliar para criação dinâmica de cards e charts (gráficos) para telas genéricas de dashboard, para ser utilizada em aplicativos angular POUI
Essa classe deve ser utilizada como herança da sua classe que terá os cards e charts
Essa classe por padrão herda a classe genérica de adapter FwAdapterBaseV2, portanto podem ser utilizados os métodos disponíveis na classe pai também.

classe disponível a partir da lib 20240115

Métodos disponíveis:

addCard()
addChart()
setOrderDefault()
card
chart

Métodos que devem ser implementados na classe que herdar esta

card_name()
chart_name()
card_nameQuery()
addFieldscard_name()

Exemplos

addCard

Descrição

Método para adicionar cards ao dashboard, deve ser utilizado no método new da classe

Parâmetros:

Nome	Tipo	Descrição
cName	Carácter	Nome único do card, não pode conter espaços nem caracteres especiais, os métodos deveram ter os nomes definidos aqui
cLabel	Carácter	Titulo a ser exibido no card

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} New
    Metodo construtor da classe
nesse metodo deve ser definido os cards e charts disponiveis no dashboard
@param verbo a ser executado, get, post, put...
@return object, self
@author Totvs
@since 08/12/2023
//-----------------------------------------------------------------*/
Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )

    // Cards disponiveis na home do dashboard de privilégio
    ::addCard("total_users", STR0001 ) //"Total de usuários"
    ::addCard("active_users", STR0002 ) //"Usuários ativos"

    // graficos disponiveis na home do dashboard de privilégio
    ::addChart("group_x_user", STR0008 ) //"Usuários com ou sem grupos"
    ::addChart("group_rules", STR0009  ) //"Regra de grupo do usuário"

Return self

addChart

Descrição

Método para adicionar charts (graficos) ao dashboard, deve ser utilizado no método new da classe

Parâmetros:

Nome	Tipo	Descrição
cName	Carácter	Nome único do chart, não pode conter espaços nem caracteres especiais, os métodos deveram ter os nomes definidos aqui
cLabel	Carácter	Titulo a ser exibido no chart

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} New
    Metodo construtor da classe
nesse metodo deve ser definido os cards e charts disponiveis no dashboard
@param verbo a ser executado, get, post, put...
@return object, self
@author Totvs
@since 08/12/2023
//-----------------------------------------------------------------*/
Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )

    // Cards disponiveis na home do dashboard de privilégio
    ::addCard("total_users", STR0001 ) //"Total de usuários"
    ::addCard("active_users", STR0002 ) //"Usuários ativos"

    // graficos disponiveis na home do dashboard de privilégio
    ::addChart("group_x_user", STR0008 ) //"Usuários com ou sem grupos"
    ::addChart("group_rules", STR0009  ) //"Regra de grupo do usuário"

Return self

setOrderDefault

Descrição

Método para definir qual será a ordenação padrão dos detalhes de um card ou chart, deve ser utilizado no método que adiciona os campos aos detalhes.

Parâmetros:

Nome	Tipo	Descrição
cOrderDefault	Carácter	Nome da propriedade default que será utilizada como ordem padrão dos detalhes de um card ou chart

Retorno nil

Exemplo

//-----------------------------------------------------------------------------
/*/{Protheus.doc} addFieldsActive_Users
    Função para geração do mapa de campos
@author Totvs
@since 11/12/2023
@version 1.0
/*/
//-----------------------------------------------------------------------------
Method addFieldsActive_Users() Class home
    ::addMapFields( 'user_id' , 'USR_ID'  , .T., .T., { 'USR_ID', 'C', 06, 0 },,.T. )
    ::addMapFields( 'user_code' , 'USR_CODIGO'  , .T., .T., { 'USR_CODIGO', 'C', 25, 0 },,.T. )
    ::addMapFields( 'name'    , 'USR_NOME'   , .T., .F., { 'USR_NOME', 'C', 30, 0 },,.T. )
    ::setOrderDefault('user_id')
Return

card_name

Descrição

Método que irá criar um card no dashboard, o nome desse método é dinâmico, deve ser de acordo com o card que foi criado no new da classe.

Parâmetros:

Nome	Tipo	Descrição
oCard	Objeto	Objeto do tipo totvs.framework.adapter.dashboard.card

Retorno nil

Exemplo

Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )
    // Cards disponiveis na home do dashboard de privilégio
    ::addCard("total_users", STR0001 ) //"Total de usuários"
Return self

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao card total_users
@param, oCard, objeto de card a ser criado.
@param, jResponse, json de retorno da api até o momento
@return objeto de card passado por parametro
@author totvs
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oCard as object, jResponse as json) as object Class home
    Local cSql as character

    cSql := ::total_UsersQuery("total")

    oCard:setDescription(STR0010) //"Total de usuários existente no protheus"
    oCard:setValue(FwExecCachedQuery():ExecScalar(cSql, "QTD", "30", "10"))
    oCard:addColumn("user_id", STR0011, "string", .T.) //"Id do usuário"
    oCard:addColumn("user_code", STR0012, "string", .T.) //"Código do usuário"
    oCard:addColumn("name", STR0013, "string", .T.) //"Nome do usuário"
    
Return(oCard)

chart_name

Descrição

Método que irá criar um chart (grafico) no dashboard, o nome desse método é dinâmico, deve ser de acordo com o chart que foi criado no new da classe.

Parâmetros:

Nome	Tipo	Descrição
oChart	Objeto	Objeto do tipo totvs.framework.adapter.dashboard.chart

Retorno nil

Exemplo

Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )

	// graficos disponiveis na home do dashboard de privilégio
    ::addChart("group_rules", STR0009  ) //"Regra de grupo do usuário"
Return self  

//-------------------------------------------------------------------
/*/{Protheus.doc} group_rules
    definições referente ao chart group_rules
@param, oCard, objeto de chart a ser criado.
@param, jResponse, json de retorno da api até o momento
@return objeto de chart passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method group_rules(oChart as object, jResponse as json) as object Class home
    Local cSql as character
    Local cAlias as character
    Local cAliasBk as character

    oChart:setDescription(STR0029) //"Total de usuários por regra de acesso do grupo (prioriza, desconsidera ou soma)"
    oChart:addColumn("user_id", STR0011, "string", .T.) //"Id do usuário"
    oChart:addColumn("user_code", STR0012, "string", .T.) //"Código do usuário"
    oChart:addColumn("name", STR0013, "string", .T.) //"Nome do usuário"
    oChart:addColumn("group_rule", STR0030, "string", .T.) //"Regra de acesso do grupo"

    // a api de detalhes desse grafico será a mesma referente a api de total de usuários,
    // apenas mostrando a coluna de regra de acesso do grupo a mais
    oChart:setApiDetail("/api/framework/dashboard/detail/totvs.framework.adapter.privileges.home/total_users")
    
    cAliasBk := Alias()
    
    cSql := ::group_RulesQuery("total")
    cAlias := FwExecCachedQuery():OpenQuery(cSql,,,,"30","10")

    oChart:addDataChart(STR0032, (cAlias)->PRIORIZA, STR0031, "color-03") //"Usuários que priorizam os acessos do grupo" //"Prioriza"
    oChart:addDataChart(STR0033, (cAlias)->DESCONSIDERA, STR0034, "color-05") //"Desconsidera" //"Usuários que desconsideram os acessos do grupo"
    oChart:addDataChart(STR0036, (cAlias)->soma, STR0035, "color-07") //"Usuários que somam os acessos do grupo" //"Soma"
    
    (cAlias)->(DbCloseArea())

    FWRestAlias(cAliasBk)

Return(oChart)

card_nameQuery

Descrição

Método para definir a query que será utilizada nos detalhes de uma card ou chart, o nome desse método é dinâmico, deve ser de acordo com que foi criado no new da classe.

Parâmetros:

Nome	Tipo	Descrição
		sem parâmetros

Retorno caractere

Exemplo

Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )
    // Cards disponiveis na home do dashboard de privilégio
    ::addCard("total_users", STR0001 ) //"Total de usuários"
Return self  

//-------------------------------------------------------------------
/*/{Protheus.doc} total_UsersQuery
    Retorna a query referente a quantidade total de usuarios
@param cType, tipo de query a ser retornado, podendo ser detail ou total
@return character, sql a ser utilizado
@author totvs
@since 08/12/2023
//-----------------------------------------------------------------*/
Method total_UsersQuery(cType as character) as character Class home
    Local cSql as character

    If cType == "total"
        cSql := " SELECT COUNT(*) QTD "
    ElseIf cType == "detail"
        cSql := " SELECT #QueryFields# "
        cSql += " FROM ( SELECT US.*, "
        cSql += " CASE USR_GRPRULE  "+CRLF
        cSql += " WHEN '1' THEN '"+STR0032+"' "+CRLF // 'Priorizar'
        cSql += " WHEN '2' THEN '"+STR0033+"' "+CRLF // 'Desconsiderar'
        cSql += " WHEN '3' THEN '"+STR0036+"' END group_rule "+CRLF // 'Somar'
    EndIf

	cSql += " FROM "+MPSysSqlName("MPUSR_USR")+" US "
	cSql += " WHERE US.D_E_L_E_T_=' ' "

    If cType == "detail"
        cSql += " ) TAB WHERE 1=1 #QueryWhere# "
    EndIf

Return(cSql)

addFieldscard_name

Descrição

Método para definir os campos que serão utilizados nos detalhes de uma card ou chart, o nome desse método é dinâmico, deve ser de acordo com que foi criado no new da classe.

Parâmetros:

Nome	Tipo	Descrição
		sem parâmetros

Retorno caractere

Exemplo

Method new(cVerb as character) as object Class home
    _Super:new( cVerb, .T. )
    // Cards disponiveis na home do dashboard de privilégio
    ::addCard("total_users", STR0001 ) //"Total de usuários"
Return self  

//-----------------------------------------------------------------------------
/*/{Protheus.doc} addFieldsTotal_Users
    Função para geração do mapa de campos
@author totvs
@since 11/12/2023
@version 1.0
/*/
//-----------------------------------------------------------------------------
Method addFieldsTotal_Users() Class home
    ::addMapFields( 'user_id' , 'USR_ID'  , .T., .T., { 'USR_ID', 'C', 06, 0 },,.T. )
    ::addMapFields( 'user_code' , 'USR_CODIGO'  , .T., .T., { 'USR_CODIGO', 'C', 25, 0 },,.T. )
    ::addMapFields( 'name'    , 'USR_NOME'   , .T., .F., { 'USR_NOME', 'C', 30, 0 },,.T. )
    ::addMapFields( 'group_rule'    , 'group_rule'   , .T., .F., { 'group_rule', 'C', 12, 0 },,.T. )
    ::setOrderDefault('user_id')
Return

setDescription

Descrição

Método para definir a descrição completa de um card ou chart, deve ser utilizado dentro do método dinâmico que recebe o nome da propriedade e recebe como parâmetro o mesmo

Parâmetros:

Nome	Tipo	Descrição
cDescription	Carácter	descrição a ser definida

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao card total_users
@param, oCard, objeto de card a ser criado.
@return objeto de card passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oCard as object) as object Class home

    oCard:setDescription(STR0010) //"Total de usuários existente no protheus"
    
Return(oCard)

setValue

Descrição

Método para definir o valor do card, deve ser utilizado dentro do método dinâmico que recebe o nome da propriedade e recebe como parâmetro o mesmo
Disponível apenas para o card

Parâmetros:

Nome	Tipo	Descrição
nValue	numerico	Valor a ser definido para o card

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao card total_users
@param, oCard, objeto de card a ser criado.
@return objeto de card passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oCard as object) as object Class home
	Local cSql as character
	Local nValue as numeric

    cSql := ::total_UsersQuery("total")
	nValue := FwExecCachedQuery():ExecScalar(cSql, "QTD", "30", "10")

    oCard:setValue(nValue)
    
Return(oCard)

setApiDetail

Descrição

Método para definir a api que será utilizada para os detalhes de um card ou chart
caso não seja definido será utilizado o default que é
/api/framework/dashboard/detail/:cDashClient/:cWich

caso seja definido uma api detail diferente não é necessário implementar os métodos addfields e query referente.

Parâmetros:

Nome	Tipo	Descrição
cApiDetail	Carácter	caminho para a api de detalhes de um card ou chart

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao card total_users
@param, oCard, objeto de card a ser criado.
@return objeto de card passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oCard as object) as object Class home

	// utilizo a api de detalhes já existente no dashboard de saneamento.
    oCard:setApiDetail("/api/framework/privileges/sanitation/usersWithoutPrivileges")
    
Return(oCard)

addColumn

Descrição

Adiciona uma coluna que será utilizada para a estrutura de detalhes do card/chart

Parâmetros:

Nome	Tipo	Descrição
cProperty	caractere	nome da coluna que virá na api de detalhes
cLabel	caractere	titulo da coluna
cType	caractere	tipo da coluna
lVisible	logico	indica se a coluna será visivel na grid de detalhes

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao card total_users
@param, oCard, objeto de card a ser criado.
@return objeto de card passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oCard as object) as object Class home

	oCard:addColumn("user_id", STR0011, "string", .T.) //"Id do usuário"
    oCard:addColumn("user_code", STR0012, "string", .T.) //"Código do usuário"
    oCard:addColumn("name", STR0013, "string", .T.) //"Nome do usuário"
    
Return(oCard)

addDataChart

Descrição

Adiciona uma nova dimensão no gráfico a ser construído
Método disponível apenas para objeto do tipo chart

Parâmetros:

Nome	Tipo	Descrição
cLabel	caractere	titulo da dimensão
nValue	numerico	valor da dimensão
cToolTip	caractere	Tooltip da dimensão, exibida no mousehover no grafico
cColor	caractere	cor da dimensão, para maiores informações consultar documentação de chart do POUI

Retorno nil

Exemplo

//-------------------------------------------------------------------
/*/{Protheus.doc} total_users
    definições referente ao chart total_users
@param, oChart, objeto de chart a ser criado.
@return objeto de chart passado por parametro
@author Caio Lima
@since 15/12/2023
//-----------------------------------------------------------------*/
Method total_users(oChart as object) as object Class home
    Local cSql as character
    Local cAlias as character
    Local cAliasBk as character

	cAliasBk := Alias()

    cSql := ::group_RulesQuery("total")
    cAlias := FwExecCachedQuery():OpenQuery(cSql,,,,"30","10")

    oChart:addDataChart(STR0032, (cAlias)->PRIORIZA, STR0031, "color-03") //"Usuários que priorizam os acessos do grupo" //"Prioriza"
    oChart:addDataChart(STR0033, (cAlias)->DESCONSIDERA, STR0034, "color-05") //"Desconsidera" //"Usuários que desconsideram os acessos do grupo"
    oChart:addDataChart(STR0036, (cAlias)->soma, STR0035, "color-07") //"Usuários que somam os acessos do grupo" //"Soma"
    
    (cAlias)->(DbCloseArea())

    FWRestAlias(cAliasBk)

Return(oCard)

Exemplo:

framework.adapter.privileges.home.tlpp

Páginas filhas

totvs.framework.adapter.dashboard - cards e charts

Exemplos

addCard

addChart

setOrderDefault

card_name

chart_name

card_nameQuery

addFieldscard_name

setDescription

setValue

setApiDetail

addColumn

addDataChart

Exemplo: