Manhas do JFactory e jimport

Quando comecei a fazer meus módulos e componentes para o Joomla 1.5.x encontrei alguma dificuldade em lidar com a extensão de classes. É que me faltava o conhecimento básico de como utilizar a função jimport ou de como usar instâncias de classes que o JFactory nos oferece de bandeja. É claro que, quem não tem a base, vai bater cabeça e perder um tempão.

Se este também é o seu caso, então este pequeno tutorial talvez ajude.

O que é jimport?

O framework do Joomla fica em /libraries/joomla/. Lá podemos encontrar todas as classes com um caminhão de métodos (funções) responsáveis pelo funcionamento deste gerenciador de conteúdo. Antes de escrever qualquer função nova, é bom dar uma espiada no framework para ver se já não existe a função que precisamos (pronta ou faltando muito pouco para atender nossas necessidades) - é a lei do mínimo esforço e uma grande oportunidade para ir descobrindo os segredos do Joomla.

A princípio, procurar o que se precisa parece uma tarefa impossível, mas não é bem assim. Os arquivos que compõem o framework do Joomla estão muito bem arrumadinhos, guardados em diretórios que indicam sua função. Com o tempo, você vai encontrar o que procura de bate-pronto.

Porque esta agora de ficar garimpando classes e métodos existentes? Porque podemos usar as classes para substituir métodos existentes ou adicionar novos e fazer com que dancem de acordo com a nossa música. Para obter uma classe "domesticada" (tecnicamente chamada de classe estendida) é preciso carregá-la. Ao invés de encher o código com uma porção de require_once ou include_once, podemos usar a função jimport.

A função jimport( ) usa a sintaxe com pontos: para carregar /libraries/joomla/utilities/utility.php você escreve jimport('joomla.utilities.utility'); Depois desta chamada, a classe JUtility estará disponível no seu código, prontinha para ser acionada.

jimport( 'joomla.utilities.utility' );
echo JUtility::dump( $minhaVariavel );
// joga na tela o valor de $minhaVariavel

O mesmo vale para arquivos que estão em diretórios mais profundamente aninhados, por exemplo, /libraries/joomla/application/component/view.php:

jimport('joomla.application.component.view');
class MeucomponenteViewItems extends JView {
...
}

Com o PHP5, ao invés de carregar o arquivo imediatamente, o nome do arquivo e o nome da classe são apenas registrados e o carregamento da classe só ocorre quando a primeira de uma de suas funções for chamada. No exemplo dado acima, a coisa fica assim:

jimport( 'joomla.utilities.utility' );
// neste ponto, utility.php ainda não foi carregado
...
echo JUtility::dump( $minhaVariavel );
// aqui o arquivo é carregado

(pode parecer que é muita firula, mas este processo faz muita diferença numa porção de situações... principalmente quando incluímos algumas classes que depois não são usadas e esquecemos de tirar as respectivas linhas de código).

Qual é o mecanismo do jimport? Bem, a função pega a última parte do caminho que indicamos ('joomla.utilities.utility'), adiciona um prefixo 'J' e registra 'JUtility' como o nome da classe para utility.php. Depois disto, quando usamos JUtility::dump ou MinhaClasse extends JUtility, ou class_exists('JUtility'), o arquivo utility.php é carregado.

O problema

Se você quiser derivar a classe JSessionStorageDatabase, localizada em /libraries/joomla/session/storage/database.php, esta história de sintaxe com pontos não vai dar certo. De acordo com a regra teríamos que usar jimport('joomla.session.storage.database'), o que faz com que o jimport registre a classe JDatabase... que não existe. Usar esta classe vai resultar em erro porque o arquivo que a contém não será carregado. Na verdade, nós não precisamos nos preocupar em carregar classes como a JSessionStorageDatabase no nosso código. O Joomla possui fábricas (factories) para isto.

O JFactory

Você não precisa se preocupar em instanciar certos objetos. Os mais específicos são manipulados pelo JFactory e uma porção de métodos getInstance. Por exemplo, JFactory::getDBO( ) pode prover um objeto JDatabaseMySQL, JDatabaseMySQLi ou até mesmo um JDatabasePostgresSQL. Já JFactory::getSession( ) fornece um objeto JSession. Este objeto contém um objeto JSessionStorage, que pode ser JSessionStorageDatabase (aquele que estávamos procurando), JSessionStorageApc ou outros. O X da questão é: você não precisa se preocupar com isto porque JFactory (e JSession::getInstance( ), JDatabse::getInstance( ), etc) cuidam de tudo.

As únicas classes que precisam de jimport são as com nomes simples como JNome, não classes como JNomeCompridoComplicado.Importante: antes de usar o jimport, confira o que o JFatory oferece:

* getApplication( $id = null, $config = array() )
* getConfig( $file = null, $type = 'PHP' )
* getSession( $options = array() )
* getLanguage( )
* getDocument( )
* getUser( $id = null )
* getCache( $group = '', $handler = 'callback', $storage = null )
* getACL( )
* getTemplate( )
* getDBO( )
* getMailer( )
* getXMLParser( $type = 'DOM', $options = array() )
* getEditor( $editor = null )
* getURI( $uri = 'SERVER' )

Mato sem cachorro

Se o que você precisa é de uma classe que não tenha um nome simples ou uma classe cujo nome não seja o mesmo do arquivo e que, além disto, não esteja contemplada no JFactory, então não tem outra saída a não ser fazer um require ou include. Por exemplo, a classe JHTMLGrid está no arquivo /libraries/joomla/html/html/grid.php. A esta altura do campeonato você já sabe que a classe registrada pelo jimport será JGrid, ou seja, o jimport não poderá ser utilizado. Para nosso azar, o JFactory também não oferece suporte a esta classe. Neste caso, não nos resta outra alternativa a não ser usar a chamada clássica:

$queroClasse = JPATH_SITE.DS.'joomla'.DS.'html'.DS.'html'.DS.'grid.php';
require_once( $queroClasse );

class novoJHTMLGrid extends JHTMLGrid {
...
}

Finalmentes

Encontrei a maior parte destas explicações no blog do Mathias Verraes. Coloquei mais alguma coisinha que aprendi fazendo meus componentes e módulos. Espero que este tutorial ajude a esclarecer alguns pontos ainda meio obscuros porque a versão 1.5.x do Joomla é relativamente nova e tem pouca coisa espalhada pela net.

Fonte: Numa Boa.