PHPReports LEIAME
escrito por TaQ (eustaquiorangel@yahoo.com)
Fevereiro 2003
Tópicos
1 - O que é o PHPReports ?
2 - O que eu preciso para usar o PHPReports ?
3 - Tem que pagar para usar ?
4 - Me conte como funciona
4.1 - Estrutura do relatório
5 - Um exemplo simples
5.1 - Layout do relatório
5.2 - Código PHP
5.3 - Arquivo de layout XML
6 - Arquivo DTD
6.1 - Elemento REPORT
6.2 - Elemento COL
6.3 - Elemento ROW
6.4 - Elemento HEADER
6.5 - Elemento FOOTER
6.6 - Elemento PAGE
6.7 - Elemento FIELD
6.8 - Elemento GROUP
6.9 - Elemento GROUPS
6.10- Elemento LINK
6.11- Elemento XHTML
7 - Validando seu documento
8 - Lista de arquivos
9 - Considerações finais
10 - Changelog
11 - Indíce das funções PHP mais comuns nas classes do PHPReports
12 - FAQ
1 - O que é o PHPReports ?
O PHPReports são algumas classes PHP, instruções XML e scripts
XSLT para transformar o arquivo XML em código PHP. O código PHP
gerado vai ser usado nas classes PHP pré-definidas.
Eu comecei com a idéia quando eu precisei fazer todas as coisas que
nós usavamos (na empresa que trabalho) em programas como Visual Basic
e FoxPro, mas no browser, e uma das coisas que eu não encontrei foi
como fazer e imprimir relatórios, usando uma consulta SQL, de um jeito
fácil (não tão fácil mas), usando o browser. Hoje em dia ele roda legal
onde eu trabalho, e espero que possa ser útil para vocês também.
2 - O que eu preciso para rodar o PHPReports ?
Você precisa de um servidor Apache com suporte PHP, compilado com
suporte XML/XSLT. Eu uso a lib Sablotron para isso
(http://www.gingerall.com/charlie/ga/xml/p_sab.xml), e todos os exemplos
são baseados nela.
3 - Tem que pagar para usar ?
Não, não, não. Está sob a GPL, e você não precisa pagar. Apenas siga
as regras da GPL e todo mundo fica feliz. Eu realmente estava precisando
de algum jeito de contribuir para a comunidade open source, e espero que
isso seja apenas o começo. Se você realmente gostou do PHPReports e quer
fazer algum tipo de doação ou coisa do tipo, você pode ver minha lista de
desejos (wish list) na http://www.amazon.com. Apenas procure por
Eustáquio Rangel lá. :-)
4 - Me conte como funciona
Eu ouvi uma vez um professor muito sábio dizer que "o propósito de uma
boa documentação é que você não precisa do autor grampeado nela, na sua
biblioteca". Eu vou tentar fazer o melhor que eu posso para fazer isso
valer, então vamos lá.
Um relatório, no PHPReports ou outro programa que mexe com isso, sempre
tem algumas divisões. Eu as chamo assim:
- a camada do documento
- a camada da página
- a camada de agrupamento
Tem apenas uma camada de documento, uma camada de página (você pode
ter um monte de páginas, mas apenas uma camada para configurar) e
algumas camadas de grupos.
Todas essas camadas coletam informação sobre os dados do seu relatório,
como o número de linhas, estatísticas sobre os campos e por aí vai.
A camada do documento armazena TODAS essas estatísticas, e armazena até
que o relatório acabe.
A camada da página armazena-as até que a página acabe, e as zera lá.
A camada do grupo armazena-as até o fim do grupo, deixe-me traduzir
grupo aqui como dados definidos por uma expressão de quebra, que pode
ser qualquer um dos campos contidos no seu conjunto de dados.
Cada camada tem seu próprio cabeçalho (header) e rodapé (footer). A
camada do grupo tem uma divisão a mais onde mostra os dados. Se você tem
mais que um grupo (mesmo se você tiver um relatório bem simples, você tem
que adicionar um grupo para tratar suas informações), o grupo mais interno
vai lhe mostrar os dados, o outro pode até lhe mostrar também, mas é sua
escolha. Deixe-me tentar desenhar a coisa toda aqui:
4.1 - Estrutura do relatório
+----------------------------------+
| DOCUMENT_LAYER |
+----------------------------------+
| HEADER |
| |
| +------------------------------+ |
| | PAGE_LAYER | |
| +------------------------------+ |
| | HEADER | |
| | | |
| | +--------------------------+ | |
| | | GROUP LAYER | | |
| | | break expression A | | |
| | +--------------------------+ | |
| | | HEADER | | |
| | | FIELDS | | |
| | | | | |
| | | +----------------------+ | | |
| | | | GROUP LAYER | | | |
| | | | break expression A,B | | | |
| | | +----------------------+ | | |
| | | | HEADER | | | |
| | | | FIELDS | | | |
| | | | FOOTER | | | |
| | | +----------------------+ | | |
| | | FOOTER | | |
| | | | | |
| | +--------------------------+ | |
| | | |
| | FOOTER | |
| +------------------------------+ |
| |
| FOOTER |
+----------------------------------+
Então, documento (document) contém a página (page), página contém grupos (groups), e um
grupo pode conter outro grupo.
Uma regra nesse caso é que a expressão de quebra do grupo interno tem que conter a expressão
de quebra do grupo acima. No exemplo, o primeiro grupo quebra quando A muda, e o segundo
grupo muda quando A e B mudam. Quando isso acontece, é disparado um evento que notifica que
o grupo precisa imprimir seu rodapé e cabeçalho, e todos os outros grupos relacionados são
notificados também, para fazer o que precisa ser feito.
5 - Um exemplo simples
Ok, vamos supor que você tem a seguinte tabela no seu banco de dados (não é um bom
desenho de tabela esse, mas é apenas para o exemplo):
SalesLog
ID NUMBER 5
NAME CHAR 50
CITY CHAR 50
PRODUCT CHAR 50
VALUE NUMBER 15,5
Se você fizer essa consulta:
select * from SalesLog order by ID
você tem:
1 - Eustaquio Rangel - Sao Jose do Rio Preto, SP - Book: Linux Programming Guide - 25.00
1 - Eustaquio Rangel - Sao Jose do Rio Preto, SP - Book: Design Patterns - 35.00
2 - Ana Carolina - Sao Jose do Rio Preto, SP - Book: Photoshop 7.0 - 22.50
3 - Andre Kada - Sao Paulo, SP - CD: Kreator - Violent Revolutions - 15.00
*** DICA ÚTIL ***
Para mais exemplos, inclusive um passo-a-passo, visite o website (http//phpreports.sourceforge.net)
com os arquivos incluídos aqui.
5.1 - Layout do relatório
Agora você precisa de um relatório agrupando seus dados por cidade (city), desse jeito:
+---------------------------------------+----+
| John Doe Enterprises |////+--- camada do documento
| Sales Report |////|
+------+--------------------------------+----+
| city | <city goes here> |\\\\|
+------+-+------+-------------+---------+\\\\|
| id | name | product | $ |\\\\|
+------+--------+-------------+---------+\\\\+--- camada do grupo
| <id> | <name> | <product> | <value> |\\\\|
+------+--------+-------------+---------+\\\\|
| total | <total> |\\\\|
+-----------------------------+---------+----+
| page total | <total> |////+--- camada da página
+-----------------------------+---------+----+
| report total | <total> |\\\\+--- camada do documento (de novo)
+-----------------------------+---------+----+
A primeira coisa que você precisa pensar é fazer seu layout de relatório como
se fosse uma tabela HTML (para ser honesto, É uma tabela HTML), então para o
relatório acima temos uma tabela com 4 colunas e 8 linhas.
5.2 - Código PHP
Agora vamos ver o código PHP para consultar no seu banco de dados seus dados e
fazer o relatório:
<?php
include 'PHPReportMaker.php';
$sql = "select ID,NAME,CITY,PRODUCT,VALUE from SalesLog order by ID";
$parm = Array();
makeReport( "sales.xml", "PHPReport.xsl", "scott", "tiger", "connection", "databaseinterface", $sql, $parm );
?>
A função makeReport é uma unica função PHP que você precisa trabalhar. Vamos dar uma
olhada nos parametros dela, acima:
1 - "sales.xml" - uma string com o arquivo de layout
2 - "PHPReports.xsl" - o arquivo XSLT usado para converter o XML em código PHP
3 - "scott" - uma string com o nome de usuário do banco de dados
4 - "tiger" - uma string com a senha do banco de dados
5 - "connection"- a conexão com o banco de dados
6 - "databaseinterface" - você precisa especificar qual banco de dados você está conectando,
por exemplo, "oracle".
7 - $sql - uma string com a query SQL
8 - $parm - um array de parametros - limitado a 5 parametros
Se você achar que tem muitos parametros na função makeReport (algumas vezes eu penso assim também),
tem uma classe que pode nos ajudar com isso. Seu nome é PHPReportMaker e usando-a no exemplo acima
ficaria assim:
<?php
include 'PHPReportMaker.php';
$sql = "select ID,NAME,CITY,PRODUCT,VALUE from SalesLog order by ID";
$oRpt = new PHPReportMaker();
$oRpt->setXML("sales.xml");
$oRpt->setUser("scott");
$oRpt->setPassword("tiger");
$oRpt->setConnection("connection");
$oRpt->setDatabaseInterface("databaseinterface");
$oRpt->setSQL($sql);
$oRpt->run();
?>
Você percebeu que não usamos o array de parametros e o XSLT? A classe tem alguns valores
default (para ser honesto, apenas o parametro é um Array() como default, o processador
XSLT é sempre "PHPReport.xsl" e o resto dos parametros são todos nulos e não vão funcionar
se você os deixar desse jeito ehehe) e - para parametros não obrigatórios - podemos rodar
desse jeito. Algumas vezes é bem mais fácil e legível usar essa classe do que a função.
Preste atenção especialmente no arquivo XSLT - se ele não está no diretório corrente,
não vai funcionar e você terá que mostrar onde ele está. Então você precisará de algo como
$oRpt->setXSLT(<meupathcompletodoarquivoXSLT>) também.
Os parametros da makeReports são:
1 - string com o path do arquivo de layout XML *OBRIGATÓRIO*
2 - string com o path do arquivo XSTL usado na transformação *OBRIGATÓRIO*
3 - string com o nome do usuário do banco de dados *OBRIGATÓRIO*
4 - string com a senha do banco de dados *OBRIGATÓRIO*
5 - string com o nome da conexão do banco de dados - por ex. no Oracle, um nome no
arquivo TNSNAMES.ORA *OBRIGATÓRIO*
6 - string com a interface do banco de dados (leia sobre isso abaixo) *OBRIGATÓRIO*
7 - string com sua query SQL *OBRIGATÓRIO*
8 - Array com parametros
9 - string com o nome do banco de dados que você deseja usar
10 - string com o arquivo de saída do código PHP - as classes geradas com XML -> XSLT
para rodar seu relatório
11 - string com o path do arquivo HTML resultante - quando esse parametro não é null,
o arquivo vai ser criado e nenhum output vai ser feito quando você rodar seu
relatório, mas isso é útil quando você quer fazer outro tratamento antes
de mostrar o relatório na tela - por ex. eu uso isso quando eu quero que os
usuários abram o relatório em uma nova página quando desejarem, então eu coloco
algum nome temporário aqui e faço um link dentro de um script Javascript para
abri-lo.
12 - boolean - se verdadeiro, PHPReports vai lhe dar uma breve descrição do seu
relatório, depois que o processar - aí você pode ver como o PHPReports está
"vendo" seu arquivo de layout XML.
*** AVISO DE SEGURANÇA ***
Se você especificar um arquivo PHP para ser criado com o parametro 10, você *DEVE*
apagá-lo depois do uso, por que ele mantém o usuário e senha do banco de dados
armazenados lá.
Se você apenas usa o parametro 10 como null, o arquivo vai ser automaticamente apagado
depois da saída do relatório. Use como não nulo para propósito de depuração.
A classe PHPReportMaker tem os seguintes métodos:
run() - usada quando todos os parametros estão ok - roda o relatório.
setXML(string)/getXML() - seta/retorna o path do arquivo XML
setXSLT(string)/getXSLT() - seta/retorna o path do arquivo XSLT
setUser(string)/getUser() - seta/retorna o usuário do banco de dados
setPassword(string)/getPassword() - seta/retorna a senha do banco de dados
setConnection(string)/getConnection() - seta/retorna o nome da conexão
setDatabaseInterface(string)/ - seta/retorna o nome da conexão com o banco de dados
getDatabaseInterface()
setSQL(string)/getSQL() - seta/retorna a string da consulta SQL
setParameters(array)/getParameters() - seta/retorna o array de parametros
setDatabase(string)/getDatabase() - seta/retorna o nome do banco de dados
setPHPOutput(string)/getPHPOutput() - seta/retorna o path de saída do código PHP
setOutput(string)/getOutput() - seta/retorna o path de saída HTML
setDebug(boolean)/getDebug() - ativa/desativa o recurso de debug
Apenas para dar uma explicação rápida antes de ir para uma mais extensa, as interfaces
do banco de dados são alguns arquivos com seus nomes começados com "db_". Por exemplo,
tem um db_oracle.php que eu estou trabalhando agora. Dentro dele tem algumas funções
que disponibilizam meios de abrir a conexão com o banco de dados, rodar a query SQL
e por aí vai. Desde um banco de dados usa funções diferentes (em PHP) um do outro,
você pode especificar um jeito que vai suportar essa funcionalidade. Os parametros de
usuário e a senha são usados para abrir a conexão especificada no parametro connection.
Estou usando a interface do Oracle agora, e vou colocar algumas outras interfaces no
projeto, se você fizer uma por favor me envie para ser incluida no projeto.
5.3 - Arquivo de layout XML
*** NOTA IMPORTANTE ***
Desde a versão 0.0.8 eu inclui alguns arquivos XML de exemplo com o pacote - verifique o
website para ver os exemplos.
Agora, o layout do relatório em XML. Isso é especificado pelo parametro sales.xml, mas o que
o sales.xml tem dentro? Se lembra da comparação com a tabela HTML: Então, precisamos de um
documento XML *bem-formado* como aquele, com linhas e colunas. Mas com as três camadas do
relatório definidas nele também !!! Vai se parecer com isso:
(P.S.: o arquivo sales.xml incluído no pacote não é igual a esse - esse está aí apenas para exemplo)
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<?xml-stylesheet type="text/xsl" href="PHPReport.xsl"?>
<!DOCTYPE REPORT SYSTEM "PHPReport.dtd">
<REPORT>
<TITLE>Sales Report</TITLE>
<PATH>phpreports/</PATH>
<BACKGROUND_COLOR>#FFFFFF</BACKGROUND_COLOR>
<CSS>johndoe.css</CSS>
<DOCUMENT>
<FOOTER>
<ROW>
<COL COLSPAN="3" TEXTCLASS="BOLD" ALIGN="RIGHT">report total</COL>
<COL TYPE="EXPRESSION" TEXTCLASS="BOLD" ALIGN="RIGHT">$this->getSum( "VALUE" )</COL>
</ROW>
</FOOTER>
</DOCUMENT>
<PAGE SIZE="30">
<HEADER>
<ROW>
<COL COLSPAN="4" TEXTCLASS="BOLD">John Doe Enterprises</COL>
</ROW>
<ROW>
<COL COLSPAN="4" TEXTCLASS="BOLD">Sales Report</COL>
</ROW>
</HEADER>
<FOOTER>
<ROW>
<COL COLSPAN="3" TEXTCLASS="BOLD" ALIGN="RIGHT">page total</COL>
<COL TYPE="EXPRESSION" TEXTCLASS="BOLD" ALIGN="RIGHT">$this->getSum( "VALUE" )</COL>
</ROW>
</FOOTER>
</PAGE>
<GROUPS>
<GROUP NAME="CityBreak" EXPRESSION="CITY">
<HEADER>
<ROW>
<COL ALIGN="RIGHT">city:</COL>
<COL TYPE="EXPRESSION" COLSPAN="3" TEXTCLASS="BOLD">$header->getValue( "CITY" )</COL>
</ROW>
<ROW>
<COL>id</COL>
<COL>name</COL>
<COL>product</COL>
<COL>$</COL>
</ROW>
</HEADER>
<FIELDS>
<ROW>
<COL>ID</COL>
<COL>NAME</COL>
<COL VISIBLE="FALSE">CITY</COL>
<COL>PRODUCT</COL>
<COL ALIGN="RIGHT" NUMBERFORMATEX="2">VALUE</COL>
</ROW>
</FIELDS>
<FOOTER>
<ROW>
<COL ALIGN="RIGHT">total</COL>
<COL TYPE="EXPRESSION" COLSPAN="3" TEXTCLASS="BOLD" ALIGN="RIGHT" NUMBERFORMATEX="2">$this->getSum( "VALUE" )</COL>
</ROW>
</FOOTER>
</GROUP>
</GROUPS>
</REPORT>
Vamos dar uma olhada nele. Primeiro, nós temos três linhas de instruções XML
sobre a versão, encoding e o arquivo DTD (vamos falar dele na próxima seção),
e nosso elemento raiz, sempre definido pela tag REPORT. REPORT tem alguns elementos
dentro dele, mas vamos ve-los mais tarde (nós temos elementos TITLE, PATH, BACKGROUND_COLOR
e CSS definidos lá). Depois a tag DOCUMENT (se lembra?) com o FOOTER definido. FOOTER e
HEADER e algumas outras tags, tem ROWs e COLs dentro delas.
Depois da tag REPORT, temos o tag PAGE e a tag GROUPS, com tags GROUPs dentro dela.
Você pode ter uma prévia de como seu relatório ficará, *sem* os dados,
usando o arquivo PHPReportPreview.php. Apenas aponte seu browser para o arquivo,
usando um parametro "xml" com o path completo do seu arquivo XML de layout, por ex:
http://localhost/phpreports/PHPReportPreview.php?xml=sales6.xml
Você realmente precisa especificar o path completo do arquivo XML e *deve* rodar o
PHPReportPreview no mesmo diretório onde está localizado o arquivo PHPReportPreview.xsl.
Claro que você pode mudar esse comportamento no código do PHPReportPreview.php, é realmente
bem fácil fazer isso. :-)
6 - Arquivo DTD
Vamos dar uma olhada mais de perto no arquivo PHPReports.dtd (se você não sabe o que diabos
é tags XML, um arquivo DTD e coisas do tipo, procure na web sobre algum tutorial fácil e
rápido, será melhor para entender como as coisas funcionam por aqui, http
http://www.w3schools.com/xml/ é uma boa escolha):
<?xml version="1.0" encoding="ISO-8859-1"?>
<!ELEMENT REPORT (TITLE?,PATH?,BACKGROUND_COLOR?,BACKGROUND_IMAGE?,CSS?,SQL?,DOCUMENT?,PAGE?,GROUPS?)>
<!ATTLIST REPORT MARGINWIDTH CDATA #IMPLIED>
<!ATTLIST REPORT MARGINHEIGHT CDATA #IMPLIED>
<!ELEMENT TITLE (#PCDATA)>
<!ELEMENT PATH (#PCDATA)>
<!ELEMENT BACKGROUND_COLOR (#PCDATA)>
<!ELEMENT BACKGROUND_IMAGE (#PCDATA)>
<!ELEMENT CSS (#PCDATA)>
<!ELEMENT SQL (#PCDATA)>
<!ELEMENT DOCUMENT (HEADER?,FOOTER?)>
<!ELEMENT HEADER (ROW*)>
<!ELEMENT FOOTER (ROW*)>
<!ELEMENT ROW (COL*)>
<!ELEMENT COL (LINK?)>
<!ATTLIST COL TYPE CDATA #IMPLIED>
<!ATTLIST COL NUMBERFORMAT CDATA #IMPLIED>
<!ATTLIST COL NUMBERFORMATEX CDATA #IMPLIED>
<!ATTLIST COL CELLCLASS CDATA #IMPLIED>
<!ATTLIST COL TEXTCLASS CDATA #IMPLIED>
<!ATTLIST COL ROWSPAN CDATA #IMPLIED>
<!ATTLIST COL COLSPAN CDATA #IMPLIED>
<!ATTLIST COL WIDTH CDATA #IMPLIED>
<!ATTLIST COL HEIGHT CDATA #IMPLIED>
<!ATTLIST COL ALIGN CDATA #IMPLIED>
<!ATTLIST COL VALIGN CDATA #IMPLIED>
<!ATTLIST COL VISIBLE CDATA #IMPLIED>
<!ATTLIST COL SUPPRESS CDATA #IMPLIED>
<!ELEMENT PAGE (HEADER?,FOOTER?)>
<!ATTLIST PAGE SIZE CDATA #IMPLIED>
<!ATTLIST PAGE WIDTH CDATA #IMPLIED>
<!ATTLIST PAGE HEIGHT CDATA #IMPLIED>
<!ATTLIST PAGE CELLPADDING CDATA #IMPLIED>
<!ATTLIST PAGE CELLSPACING CDATA #IMPLIED>
<!ATTLIST PAGE BORDER CDATA #IMPLIED>
<!ATTLIST PAGE ALIGN CDATA #IMPLIED>
<!ELEMENT GROUPS (GROUP+)>
<!ELEMENT GROUP (HEADER?,FIELDS?,FOOTER?,GROUP*)>
<!ATTLIST GROUP NAME CDATA #REQUIRED>
<!ATTLIST GROUP EXPRESSION CDATA #IMPLIED>
<!ATTLIST GROUP PAGEBREAK CDATA #IMPLIED>
<!ELEMENT FIELDS (ROW?)>
<!ELEMENT LINK (#PCDATA)>
<!ATTLIST LINK TYPE CDATA #REQUIRED>
<!ATTLIST LINK TARGET CDATA #IMPLIED>
<!ATTLIST LINK TITLE CDATA #IMPLIED>
<!ELEMENT XHTML (#PCDATA)>
6.1 - Elemento REPORT
Elementos internos:
TITLE - o título HTML que vai aparecer no título da janela.
PATH - o path onde as classes do PHPReports estão.
outra coisa que você deve usar é uma barra final (/)
no path (ex. phpreports/). é também uma boa idéia
colocar o conteúdo do pacote tar do PHPReports em um
diretório sem outras classes, apenas por questão de
organização. :-) você pode também alterar o include_path
no PHP para arrumar onde as classes do PHPReports estão
e não usar essa opção.
BACKGROUND_COLOR - cor de fundo do relatório
BACKGROUND_IMAGE - imagem de fundo do relatório
CSS - path do arquivo CSS que você quer usar no seu relatório
SQL - você pode escrever a query SQL aqui se assim desejar
DOCUMENT - a camada do documento
PAGE - a camada da página
GROUPS - o elemento GROUPS (não a camada do grupo!)
Atributos:
MARGINWIDTH - comprimento da margem, em pixeis
MARGINHEIGHT - altura da margem, em pixeis
6.2 - Elemento COL
Elementos internos:
LINK - Elemento LINK (veja 6.10)
Atributos:
TYPE - se você define como EXPRESSION, o PHPReports vai interpretar tudo que você por
no elemento COL como código PHP
NUMBERFORMAT - se é uma coluna numérica, você pode especificar aqui como a formatar, usando
a formatação standard da linguagem C (por examplo, "%10.2f")
NUMBERFORMATEX - formatação numérica extendida. use essa propriedade para formatar números com
casas decimais e separador de milhares. coloque o número de casas decimais
no valor da propriedade. se lembre de usar setLocale para o locale que você quiser.
CELLCLASS - especifique aqui a classe CSS que a célula vai usar
TEXTCLASS - especifique aqui a classe CSS que a coluna de texto vai usar
ROWSPAN - quantas linhas essa célula vai usar
COLSPAN - quantas colunas essa célula vai usar
WIDTH - a comprimento da célula
HEIGHT - a altura da célula
ALIGN - alinhamento horizontal da célula
VALIGN - alinhamento vertical da célula
VISIBLE - se FALSE, essa coluna não será visível quando estiver na camada do grupo
SUPPRESS - se TRUE, não mostra valores repetidos na camada do grupo
6.3 - Elemento ROW
Elementos internos:
COL - Elemento COL (veja 6.2)
6.4 - Elemento HEADER
Elementos internos:
ROW - Elemento ROW (veja 6.3)
6.5 - Elemento FOOTER
Elementos internos:
ROW - Elemento ROW (veja 6.3)
6.6 - Elemento PAGE
Elementos internos:
HEADER - Elemento HEADER (veja 6.4)
FOOTER - Elemento FOOTER (veja 6.5)
Atributos:
SIZE - o número de linhas que essa página vai ter
WIDTH - comprimento da página, em pixeis
HEIGHT - altura da página, em pixeis
CELLPADDING - padding interno da célula (o mesmo que HTML TABLE CELLPADDING)
CELLSPACING - espaçamento interno da célula (o mesmo que HTML TABLE CELLSPACING)
BORDER - a borda da página entre as linhas e colunas, você pode colocar ela maior
que 0 para ver como sua tabela está ficando
ALIGN - o alinhamento da página na janela do browser
6.7 - Elemento FIELD
Elementos internos:
ROW - Elemento ROW (veja 6.3)
6.8 - Elemento GROUP
Elementos internos:
HEADER - Elemento HEADER (veja 6.4)
FIELDS - Elemento FIELD (veja 6.7)
FOOTER - Elemento FOOTER (veja 6.5)
GROUP - Elemento GROUP (esse aqui! um grupo pode conter outro grupo)
Atributos:
NAME - nome do grupo, será usado para criar a classe com esse nome
EXPRESSION - o nome do campo onde a expressão de quebra do grupo será baseada,
quero dizer, quando esse campo mudar, vai ser disparado um evento de
quebra no grupo
PAGEBREAK - se YES, toda vez que o grupo quebrar vai gerar uma quebra também da
página
6.9 - Elemento GROUPS
Elementos internos:
GROUP - Elemento GROUP (veja 6.8)
6.10 - Elemento LINK
Atributos:
TYPE - STATIC para links estaticos, ou seja, que não mudam ou
DYNAMIC para links que mudam com os valores do campo da consulta SQL.
TARGET - frame onde o link vai abrir
TITLE - texto da tooltip do mouse over
6.11 - Elemento XHTML
Elementos internos:
Qualquer elemento XHTML que você queira.
7 - Validando seu documento
Você pode usar o RXP (http://www.cogsci.ed.ac.uk/~richard/rxp.html) para validar seu
arquivo XML, SEMPRE ANTES de usá-lo no browser (acredite, é uma boa idéia).
A sintaxe é assim:
rxp -V -o 0 <file.xml>
8 - Lista de arquivos
db_mysql.php - MySQL interface
db_oracle.php - Oracle interface
db_interbase.php - Interbase interface
db_mssql.php - Microsoft SQL Server interface
db_adodb.php - ADODB interface (obrigado Aztek!)
PHPRepoDoc.php - objeto da camada do documento
PHPRepoField.php - objeto do campo do banco de dados
PHPRepoGroup.php - objeto da camada do grupo
PHPRepoPage.php - objeto da camada da página
PHPRepoRow.php - objeto para linha do banco de dados
PHPReport.dtd - arquivo de validação XML
PHPReportMaker.php - a função/classe usada para fazer os relatórios
phpreports.css - arquivo de estilo
PHPReport.xsl - arquivo de transformação XSLT
PHPReportCol.xsl - arquivo de transformação XSLT
PHPReportDoc.xsl - arquivo de transformação XSLT
PHPReportField.xsl - arquivo de transformação XSLT
PHPReportGroup.xsl - arquivo de transformação XSLT
PHPReportPage.xsl - arquivo de transformação XSLT
PHPReportTable.xsl - arquivo de transformação XSLT
PHPReportXHTML.xsl - arquivo de transformação XSLT
sales.php - arquivo de exemplo PHP
sales7.php - arquivo de exemplo PHP
sales.xml - arquivo de exemplo XML
sales2.xml - arquivo de exemplo XML
sales3.xml - arquivo de exemplo XML
sales3b.xml - arquivo de exemplo XML
sales4.xml - arquivo de exemplo XML
sales5.xml - arquivo de exemplo XML
sales6.xml - arquivo de exemplo XML
sales7.xml - arquivo de exemplo XML
sales8.xml - arquivo de exemplo XML
PHPReportPreview.xsl - arquivo de transformaçao para previa
PHPReportPreview.php - codigo para usar o arquivo de previa XSLT
README - esse arquivo, porém em Inglês
LEIAME - esse arquivo
9 - Considerações finais
Sem considerações finais. :-) Teste as tags e atributos para ver qual
satisfaz suas necessidades, faça um monte de testes, eu acredito que
tudo deve rodar bem. Até mais !!!
10 - Changelog
11 de Agosto de 2002
--------------------
- reescrito código para manter as interfaces dos bancos de dados de um jeito fácil de lidar
- adicionado o arquivo de interface do MySQL
- mudanças feitas no arquivo XSLT
- adicionado o path do arquivo XSLT na função makeReport
- adicionado o parametro de banco de dados na função makeReport
31 de Agosto de 2002
--------------------
- adicionada a interface para o m$ SQL Server
- algumas correções feitas nesse documento
02 de Setembro de 2002
----------------------
- adicionada a propriedade NUMBERFORMATEX, para formatar números com
casas decimais e separador de milhares.
10 de Setembro de 2002
----------------------
- CORREÇÃO DE BUGÃO: os valores processados não estavam indo para a
camada do grupo, então você não poderia se referir a eles (sempre
nulo). agora funciona.
- adicionada uma referencia para os dados do header com a referencia
$header. agora você pode referenciar os dados do header usando
$oValue (argh!) ou $header (melhor). :-)
11 de Setembro de 2002
----------------------
- adicionada a função getRowNum(), para retornar o número da linha na
camada da página.
21 de Outubro de 2002
---------------------
- consertadas algumas coisas na documentação (agradecimentos à Remigijus Sajauka)
27 de Dezembro de 2002
----------------------
- consertadas algumas coisas aqui na documentação novamente.
23 de Janeiro de 2003
---------------------
- adicionado o parametro de saída HTML
- criada a classe PHPReportMaker
- adicionada a seção FAQ aqui no arquivo LEIAME
26 de Janeiro de 2003 (1 semana de férias! oba!)
- modificações nos parametros - agora você pode os referenciar com uma chave
do array (se tiver alguma) ou da forma numérica (ainda baseado em 1, não 0)
28 de Janeiro de 2003
---------------------
- BUGÃO! O MySQL retornava alguns campos numéricos como o sendo do tipo REAL,
e eu não havia percebido isso ainda. Agora está ok. Isso corrige o comportamento
de todas as funções de agrupamento (getSum(),getMax(),getMin()...) que verificam
o tipo do campo para processar o valor. minhas desculpas para o pessoal que está
usando o MySQL.
- para fixar o bug acima, nós precisamos de um jeito de ver como o PHPReports está
vendo os tipos de dados, então eu fiz a função debug() - verifique os parametros
da makeReport acima - para depurar como o PHPReports está "vendo" nosso arquivo
de layout XML e, nesse caso de bug, qual a string do tipo do campo que o banco de
dados está retornando, se lembre que apenas campos númericos são permitidos para
uso das funções de agrupamento.
29 de Janeiro de 2003
---------------------
- todo o dia gasto escrevendo o novo site ... um monte de documentação, putz, cara,
eu odeio fazer isso eheheh. :-)
- adicionados os arquivos de exemplos - XML, PHP e CSS. verifique no site
(http://phpreports.sourceforge.net) como usá-los.
- vou liberar a 0.0.8 hoje.
04 de Fevereiro de 2003
-----------------------
- criado o arquivo PHPReportPreview. você pode usá-lo para ter uma prévia de como
seu layout do relatório está ficando *antes* de rodar a query SQL no seu banco
de dados. isso pode salvar algum tempo e processamento de dados. apenas aponte
seu browser para o arquivo com o parametro "xml" com o path do seu arquivo XML
de layout. por ex:
http://localhost/phpreports/PHPReportPreview.php?xml=sales6.xml
você tem mesmo que especificar o caminho completo do arquivo XML e você *deve*
rodar o PHPReportPreview no mesmo diretório onde está localizado o arquivo
PHPReportPreview.xsl. claro que você pode mudar esse comportamento no código do
PHPReportPreview.php, é realmente muito fácil fazer isso. :-)
09 de Fevereiro de 2003
-----------------------
- traduzido o README para esse arquivo aqui, o LEIAME
10 de Fevereiro de 2003
-----------------------
- alterado o modo de impressão de valores - se não tem valor no campo,
imprime um espaço em branco, para fazer a célula da tabela HTML
ficar "correta" (agradecimentos para Kenneth N. Flaxman pelo meu
primeiro patch!)
- criados os parametros CELLCLASSEVEN e CELLCLASSODD - use os nos
fields para diferenciar linhas pares e ímpares (even=pares,odd=ímpares),
baseado no grupo corrente. você pode verificar o arquivo sales3b.xml para
um exemplo desse recurso.
15 de Fevereiro de 2003
-----------------------
- adicionada a interface para o Interbase (obrigado ao Andre "Biriba"
<andre@appsistemas.com.br> pela sua paciencia testando a interface -
eu não tenho um banco Interbase para testes ehehehe).
- adicionado o elemento LINK para inserir um link HTML A HREF dentro
do elemento COL.
22 de Fevereiro de 2003
-----------------------
- dividi o arquivo principal XSLT em arquivos menores - mais fácil de
gerenciar
- adicionada a interface ADODB - muito obrigado, Aztek!
para a usar, coloque setDatabaseInterface("adodb") e
setConnection para algo como setConnection("mysql:localhost");
- adicionado suporte para elementos XHTML no arquivo XML - atenção,
são arquivos XHTML e não HTML, tem muito poucas diferenças entre
eles (os arquivos XHTML tem que ser bem formados), aprenda mais
em http://www.w3.org
11 - Indíce das funções PHP mais comuns nas classes do PHPReports
Você pode usar algumas funções para retornar alguns valores dos
campos/grupos correntes:
getValue("campo") - retorna o valor corrente do campo
getMin("campo") - retorna o valor mínimo do campo no grupo corrente
getMax("campo") - retorna o valor máximo do campo no grupo corrente
getSum("campo") - retorna a soma dos valores do campo no grupo corrente
getAvg("campo") - retorna a média dos valores do campo no grupo corrente
getRowCount() - retorna a contagem de linhas do grupo corrente
getParameter(indice) - retorna o parametro na posição especificada (baseado em 1)
getParameter("chave")- retorna o parametro na chave especificada
Você deve usar essas funções com a referencia $this->. Por exemplo:
$this->getSum("TOTAL");
dentro do seu arquivo XML. A única exceção são os valores que você pega
do elemento HEADER. Você deve usar a referencia $oValue-> aqui, por exemplo:
$oValue->getValue("CITY");
Se você está usando uma versão igual ou maior que a 0.0.5, você pode usar
a referencia $header para fazer isso também (eu acho que desse jeito fica
mais vísivel e limpo):
$header->getValue("CITY");
*** IMPORTANTE ***
Eu explico por que. PHPReports apenas processa os valores dos campos quando
eles alcançam o elemento ROW no elemento GROUP. Quando estão no elemento
HEADER, os valores são passados lá para o objeto $header (antiga $oValue),
mas ainda não foram processados para serem referenciados para referencia
$this ainda.
Você precisa entender isso a respeito dos valores do header ...
Outra coisa que eu tenho que dizer que pode ser um pouco confusa é sobre
a getParameter(). Quando você coloca os valores dos parametros no array
que você usa na função makeReport, é baseado em 0. Mas quando você pega o
parametro no arquivo XML, é baseado em 1. Eu acho que é meio estranho você
falar "pegue o parametro 0" então eu deixei desse jeito. Não sei se foi uma
boa idéia, mas ao menos você pode dizer "pegue o primeiro parametro". :-)
Em Janeiro de 2003 eu mudei esse único modo de referenciar os parametros com
a possibilidade de referenciar usando as chaves do array também. Em minha
opinião é mais fácil de lidar assim ... por exemplo:
No modo de referencia numérico:
$parm = Array();
$parm[0] = "SAO PAULO";
$parm[1] = "RIO DE JANEIRO";
e no arquivo XML
getParameter(1); <- retorna SAO PAULO - se lembre, baseado em 1, não 0
getParameter(2); <- retorna RIO DE JANEIRO
No modo de referencia de chave:
$parm = Array();
$parm["from"] = "SAO PAULO";
$parm["to"] = "RIO DE JANEIRO";
e no arquivo XML
getParameter("from"); // retorna SAO PAULO
getParameter("to"); // retorna RIO DE JANEIRO
12 - FAQ
P: Como posso testar se a Sablotron está rodando legal?
R: Faça um pequeno teste com o arquivo sales6.xml e com o PHPReportPreview.xsl,
rodando o sabcmd desse jeito:
sabcmd PHPReportPreview.xsl sales6.xml test.html
Isso deve retornar uma saída válida de HTML no arquivo test.html. Abra-o em
seu browser para ver uma prévia do layout do seu relatório.
P: Tive um erro rodando o relatório e toda a instalação está ok ...
um negócio do tipo Fatal error: Call to a member function on a non-object in
blá blá blá ... o que está acontecendo?
R: Verifique as letras maiúsculas e minúsculas dos campos na consulta SQL
e no arquivo de layout XML - alguns bancos de dados precisam dos campos exatamente
iguais, maiúsculas e minúsculas.
P: Não tenho saída de linhas de dados no relatório, nenhuma. O que está acontecendo?
R: Verifique o parametro PAGE SIZE, se ele é muito curto você não verá seu relatório.
P: Estou tendo alguns problemas com as classes do PHPReports - me dizem que não estão
encontrando algumas classes para incluir.
R: Tem um parametro PATH no elemento REPORT. Se usando-o seu problema não acabar,
remova o parametro PATH e adicione o PATH das classes do PHPReports no seu código PHP
usando ini_set("<seu_diretório_do_phpreports>"). Eu acho que desse jeito é o melhor jeito. :-)
P: Não consigo ver valores no cabeçalho (header).
R: Use $header e não $this e verifique a explicação do elemento HEADER no arquivo LEIAME.
P: As funções de agrupamento (getSum(),getMin()) não funcionam! Só retornam 0 ou nulo quando
são chamadas.
R: Por favor useo método setDebug(true) e me envie o output por email -
PHPReports vai mostrar lá como ele está vendo os tipos dos campos, e
desde que ele apenas processa campos numéricos, pode ser que o jeito que seu
banco de dados está retornando o tipo do campo não seja um dos tipos que eu
coloquei como numéricos. Você não precisa me enviar o relatório completo, só
a descrição. Ah, e me conte também que banco de dados você está usando.<br>
|
Stumble It!
Bookmark in del.icio.us
Download
