Packages Sankhya HTML5/JSP dashboards and gadgets: snk:query row iteration, URL-parameter hardening, openLevel drill-down, TGFCAB/TGFITE SQL, and BI zip layout. Trigger on Sankhya dashboard, gadget, or boas práticas do Sankhya. Not for generic React SPAs or non-Sankhya BI tools. Do not use for native ERP Java screens outside the JSP/HTML5 gadget path.
Instrucciones de origen · Vista previa de solo lectura
name
sankhya-dashboard-html-jsp-custom-best-pratices
description
Packages Sankhya HTML5/JSP dashboards and gadgets: snk:query row iteration, URL-parameter hardening, openLevel drill-down, TGFCAB/TGFITE SQL, and BI zip layout. Trigger on Sankhya dashboard, gadget, or boas práticas do Sankhya. Not for generic React SPAs or non-Sankhya BI tools. Do not use for native ERP Java screens outside the JSP/HTML5 gadget path.
Sankhya Dashboard — HTML/JSP/Java/SQL Best Practices
Overview
Consolidated guide of patterns and best practices for creating and maintaining dashboards, SQL queries, BI parameterization, and UI/UX within the Sankhya ecosystem (JSP/HTML/Java). Covers code generation, visual consistency, database exploration, and BI construction flow.
Table and field names below are representative and may vary per instance implementation. Always verify against the target instance's data dictionary.
When to Use
Use this skill when:
The user asks about "boas práticas do Sankhya" or "Sankhya best practices".
The user mentions "dashboard Sankhya" or is working on a Sankhya BI dashboard.
The user asks for anything related to the word "Sankhya".
The user wants to create or modify code files (JSP, HTML, JS, SQL) for Sankhya dashboards or gadgets.
The user needs patterns for snk:query, openLevel, drill-down, or BI HTML5 component packaging.
Prerequisites
Access to a Sankhya instance (application server + Oracle/SQL Server backend).
DBExplorer available for table/field inspection.
Familiarity with JSP/JSTL, HTML5, JavaScript, and SQL.
Windows host (PowerShell) is the primary development environment.
Procedure
1. Code Best Practices (JSP/JSTL)
Apply JSP/JSTL patterns and server-side organization to reduce compilation errors, rendering failures, and regressions.
Implementation guidelines:
Declare JSP directives and mandatory taglibs at the top of the file.
Force isELIgnored="false" to enable ${...} at render time.
Prefer core_rt for JSTL core in the Sankhya ecosystem.
Avoid Java scriptlets in JSP; use JSTL (c:if, c:choose, c:forEach).
Modularize business logic (layers/services); avoid single-file coupling.
Never hardcode credentials, sensitive URLs, or tokens.
Model global UI state (data, filters, sorting, active tab) and reset state before new load.
Persist view preferences in localStorage (column order and sorting).
Implement lazy-load for heavy tabs/modals to reduce initial load time.
Parameter hardening: Always define a fallback default for URL parameters via c:set to avoid HTTP 500 on the Sankhya Java server.
Layer separation (JSP vs JS): Do not inject JSP tags directly inside <script> blocks. Use hidden HTML containers to pass data to JavaScript, preserving IDE linting health.
In versioned TOP, relate CODTIPOPER + alteration date (DHTIPOPER/DHALTER).
For optional filters, use pattern (... = :P_PARAM OR :P_PARAM IS NULL).
Always parameterize (avoid user literals).
SELECT
CAB.NUNOTA,
CAB.CODPARC,
CAB.DTNEG,
ITE.SEQUENCIA,
ITE.CODPROD,
(ITE.VLRTOT - ITE.VLRDESC) AS VLR_LIQUIDO
FROM TGFCAB CAB
JOIN TGFITE ITE
ON ITE.NUNOTA = CAB.NUNOTA
JOIN TGFTOP TOP
ON TOP.CODTIPOPER = CAB.CODTIPOPER
AND TOP.DHALTER = CAB.DHTIPOPER
WHERE (CAB.CODPARC = :P_CODPARC OR :P_CODPARC ISNULL)
AND (CAB.CODVEND = :P_CODVEND OR :P_CODVEND ISNULL)
User access map query:
SELECT
U.CODUSU,
U.NOMEUSU,
G.NOMEGRUPO,
A.CODREL,
I.NOME AS DESCRICAO_RECURSO,
A.CONS,
A.ALTERA
FROM TSIUSU U
JOIN TSIGRU G ON G.CODGRUPO = U.CODGRUPO
JOIN TSIACI A ON A.CODGRUPO = U.CODGRUPO
JOIN TSIIMP I ON I.CODREL = A.CODREL
WHERE U.CODUSU = :P_CODUSU
ORDERBY I.NOME
4. BI Builder Guide
Apply HTML5 component development flow in BI to ensure rendering, reactivity, and navigation between levels.
Structure and publication:
Package component in .zip with index.html as main entry.
Organize static resources in assets/ (CSS, JS, libs, images).
Use XML/design as needed; consider entry JSP when server-side preprocessing is required.
Data flow and parameters:
Define SQL or BeanShell variables per complexity.
Use parameter translation prefixes:
: for standard bind.
:# for literal substitution (use with caution and validation).
:@ for text literal in scenarios like LIKE.
For extensive multi-list parameters, use /*inCollection*/.
SELECT
C.CODCID,
C.NOMECID,
C.UF
FROM AD_TABELA_EXEMPLO C
WHERE/*inCollection*/ C.CODCID IN :P_CODCID /*inCollection*/
Reactivity and lifecycle:
Program re-render when global filters change.
Avoid exclusive dependency on DOMContentLoaded for injected content.
Apply async initialization to ensure elements are available.
<script>functionrenderizarComponente(dados) {
// Update DOM, charts, and KPIs with received data
}
functioniniciar() {
const dadosIniciais = window.snkBIData || [];
renderizarComponente(dadosIniciais);
}
setTimeout(iniciar, 300);
</script>
Drill-down and events:
Model independent levels (macro → micro) with explicit arguments.
Avoid empty container in subsequent levels.
Use context inheritance between levels to preserve filters and navigation.
Implement click actions to update details and open native screens with context key.
Multi-level navigation (openLevel and context contract):
Define level constants in configuration (NIVEL_RESUMO, NIVEL_DETALHE, NIVEL_ITEM) to avoid loose-string coupling.
Encapsulate openLevel in dedicated functions per navigation route.
Pass context parameters between levels with explicit contract (ARG_* for keys, P_* for filters/period).
Validate openLevel availability and mandatory parameters before navigating.
Apply error fallback in console/UI when context does not allow level opening.
Restrict any level query by user-meta/scope relationship before aggregating data.
Centralize security predicate in a WHERE builder function for reuse across KPIs, grids, and charts.
Prefer session variables (CODUSU_LOG or equivalent logged-user function) to avoid user parameter spoofing.
Block load when critical parameters are missing (e.g., period, meta, drill-down entity).
SELECT
M.CODMETA,
M.CODENTIDADE,
SUM(M.VLRPREV) AS VLR_PREV,
SUM(M.VLRREAL) AS VLR_REAL
FROM AD_DADOS_META M
WHERE M.CODMETA = :P_CODMETA
AND M.DTREF BETWEEN TO_DATE(:P_PERIODO_INI, 'DD/MM/YYYY')
AND TO_DATE(:P_PERIODO_FIN, 'DD/MM/YYYY')
ANDEXISTS (
SELECT1FROM AD_META_USUARIO_LIB L
WHERE L.CODMETA = M.CODMETA
AND L.CODUSU = STP_GET_CODUSULOGADO
)
GROUPBY M.CODMETA, M.CODENTIDADE
Hierarchical grid with expand/collapse:
Structure filhosPorPai map and nosExpandidos state for incremental tree rendering.
Initialize non-analytical top-level nodes as expanded for better initial reading.
In collapsed nodes, display descendant aggregates to maintain context without opening full tree.
Provide "Expand all" and "Collapse all" quick actions in header.
In text filters, include ancestors of found nodes to preserve hierarchical traceability.
var filhosPorPai = {};
var nosExpandidos = {};
functionalternarNo(codNo) {
var id = String(codNo);
nosExpandidos[id] = !nosExpandidos[id];
renderizarGrid();
}
functionobterVisiveis(raiz) {
var lista = [];
functionvisitar(pai) {
(filhosPorPai[pai] || []).forEach(function (no) {
lista.push(no);
if (nosExpandidos[String(no.CODNO)]) visitar(String(no.CODNO));
});
}
visitar(String(raiz || ""));
return lista;
}
Load resilience:
Separate main load from complementary load (e.g., monthly actuals); do not block primary view on secondary failure.
Handle per-component data absence (vazio) without dropping entire layout.
Destroy chart instances before recreating to avoid leakage and visual overlap.
Load secondary panels only when opening corresponding tab/view (on-demand).
Intra-level navigation (single JSP):
Treat single JSP as navigation shell: main table + detail modal + internal tabs + auxiliary modals.
Display explicit loading, empty, and error states in each panel.
On update actions, disable confirm button until executeQuery returns.
After success, reload data and restore previous context (product and active tab).
Internal security variables:
Leverage session variables for row-level security (CODUSU_LOG, CODGRU_LOG, CODVEN_LOG).
Restrict data by user context before building visualizations.
Pitfalls
Missing parameter fallback → HTTP 500: Always use c:set with a default value for URL parameters before passing to snk:query. Missing parameters cause server-side null errors.
JSP tags inside <script> blocks: Breaks IDE linting and can cause rendering issues. Use hidden HTML containers to pass server-side data to JavaScript.
Iterating root query object instead of .rows: snk:query returns an object with a rows property. Iterating the root object yields nothing or errors.
SELECT * on BLOB/CLOB tables: Causes excessive memory consumption in DBExplorer and dashboards. Always select explicit columns.
Loose-string level names in openLevel: Hardcoded level strings break when configuration changes. Use constants from DASH_CONFIG.
Chart recreation without destroying: Causes visual overlap and memory leaks. Always destroy previous chart instance before re-creating.
User parameter spoofing: Never trust P_CODUSU from URL for security. Use session variable CODUSU_LOG or STP_GET_CODUSULOGADO.
Blocking primary view on secondary load failure: Complementary data failure should not prevent main dashboard rendering. Separate load paths.
DOMContentLoaded only for injected content: Content injected after DOM ready will not trigger it. Use setTimeout or MutationObserver.
Relative paths in openLevel secondary levels: Break asset resolution. Use absolute paths with contextPath + BASE_FOLDER.
Verification
JSP compiles without errors: Deploy the JSP file and access it via browser. Confirm no HTTP 500 or compilation error in server logs.
Parameter hardening check: Access the dashboard URL without expected parameters (e.g., omit P_CODUSU). Verify fallback value is used and no 500 error occurs.
Empty query handling: Run snk:query against a condition that returns zero rows. Confirm the c:when test="${empty qDados.rows}" branch renders the "Sem resultados" message.
Layer separation: Open the JSP in an IDE with JS linting. Confirm no JSP tags appear inside <script> blocks and JS reads from hidden containers.
DBExplorer query: Run exploration SQL in DBExplorer. Confirm it respects DBEXPMAXROW and returns expected columns without BLOB/CLOB overflow.
openLevel navigation: Click a drill-down element. Confirm the next level opens with correct ARG_* and P_* context parameters.
Security predicate: Run the security query with a user who has no meta assignment. Confirm zero rows returned (access blocked).
Chart destroy/recreate: Trigger a re-render of a chart panel. Confirm no visual overlap or canvas duplication.
Lazy-load tabs: Open the dashboard and confirm secondary tabs do not fire queries until clicked. Check network tab or server logs.
Sticky header: Scroll a wide table vertically and horizontally. Confirm header stays pinned and fixed columns remain visible.
Limitations
Use this skill only when the task clearly matches the Sankhya dashboard/JSP/BI scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Table and field names are representative; always verify against the target instance's data dictionary (TDDTAB, TDDCAM).
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
