novo alfa do Axe, documentação preliminar de plugins

[Augusto Campos]

Prezados:

Conforme prometido, segue versão preliminar da documentação para quem quiser começar a desenvolver plugins.

Ao longo da semana que inicia hoje deve sair nova versão alfa do Axe, com algumas correções e incluindo o suporte a plugins que modifiquem o conteúdo dos posts, e não apenas os templates - aí o Jânio vai poder incluir o suporte a MarkDown que ele queria ツ

Se tiverem sugestões para este segundo alfa, por favor enviem até a segunda-feira terminar.

Abraços

Augusto

Como fazer um plugin para o Axe

NEWS

tags:axe,devel,php

Os plugins para o Axe são armazenados no diretório <tt>axe/plugins</tt> e são chamados pelo Axe em vários momentos do processamento dos posts, índices e feeds. 

A interface de plugins do Axe ainda não chegou à sua especificação definitiva, portanto considere esta documentação como <b>preliminar e sujeita a mudanças</b>. Ela será ampliada e melhor detalhada quando a interface de plugins amadurecer.

De modo geral as interfaces já implementadas permitem que os seus plugins atuem como filtros de texto, recebendo um trecho de conteúdo ou do template que será usado para gerar uma página (por exemplo, <i>o tema do rodapé de um índice de tags</i>), aplicando a ele as modificações que desejar, e retornando ao Axe o texto original, com ou sem modificações.

No momento o Axe suporta plugins de templates nos seguintes contextos e subcontextos:

<ul>

<li>feed: <tt>header</tt>, <tt>item</tt> e <tt>footer</tt>

<li>index: <tt>header</tt>, <tt>post</tt> e <tt>footer</tt>

<li>post: <tt>header</tt>, <tt>body</tt>, <tt>coverpreview</tt> e <tt>footer</tt>

</ul>

A partir da próxima versão, serão agregados contextos de conteúdo para posts, e contextos de inicialização do Axe e encerramento de rebuild.

O plugin deve definir, para cada contexto em que deseja operar, uma função cujo nome é formado pela regra <i>nomedoplugin_nomedocontexto</i>. Exemplo: para um plugin chamado <tt>patrocinador.php</tt>, a função na qual ele deseja interferir no contexto <tt>post</tt> precisa se chamar <tt>patrocinador_post()</tt>.

No momento, essa e todas as demais funções de plugins precisam ser definidas com suporte a receber 5 parâmetros, mesmo que não usem a todos. A primeira delas sempre é o conteúdo a modificar (e <i>sempre</i> retornar, em versão modificada ou não), e as demais dependem do contexto – por exemplo, no contexto <tt>post</tt>, o segundo parâmetro indicará o subcontexto (ver lista acima), e o terceiro indica o número sequencial (e não o ID!) do post sendo processado.

Como a interface ainda não está madura, não vou documentar quais os elementos de chamada de cada contexto e de cada subcontexto, e por enquanto você precisará pesquisar no código-fonte, procurando as chamadas à função <tt>aplica_plugins</tt>, e sempre desprezando o primeiro parâmetro dela, que nunca é passado ao plugin. Mas saiba que eles ainda podem mudar, a implementação atual é apenas a título precário.

Esqueleto do plugin <tt>exemplo.php</tt>:

<pre>

&lt;?php

/*

TITULO: Exemplo de plugin para modificar rodapés de índices e de posts

© 2013 Augusto Campos http://augustocampos.net/ (1.06.2013)

Licensed under the Apache License, Version 2.0 (the "License"); 

you may not use this file except in compliance with the License. 

You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software 

distributed under the License is distributed on an "AS IS" BASIS, 

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

See the License for the specific language governing permissions and 

limitations under the License.

*/

function exemplo_index($trecho,$template,$p2='',$p3='',$p4='') {

if ($template=="footer") {

// aplica modificações desejadas ao $trecho (que é template, e não conteúdo)

}

return $trecho;

}

function otherfeeds_post($trecho,$template,$c_items=0,$p3='',$p4='') {

if (($template=="footer") && ($c_items < blogparm('NUMPOSTSCOVER'))) {

// aplica modificações desejadas ao $trecho (que é template, e não conteúdo)

}

return $trecho;

}

?&gt;

</pre>

-- 

Augusto Campos