Configurar uma funcionalidade do seu site, ou um plugin

Formulário de configuração

Suponha que você tem uma funcionalidade "coisa" para configurar.

1. crie um formulário CVT cujo nome comece por «configurer_ », com apenas o ficheiro HTML e sem o PHP (e sem definir as funções charger, verifier e traiter) [1].
2. crie uma página configurer_coisa.html em prive/squelettes/contenu/ (para o SPIP 3) ou em prive/exec/ (para o SPIP 2), no interior do seu plugin ou do seu diretório squelettes. Dentro dele, chame o formulário com #FORMULAIRE_CONFIGURER_COISA

Pronto!

Configuração de um plugin

Quando um plugin dispõe de uma página de configuração, uma opção "Configurar" levando a esta página é exibida automaticamente na linha relativa ao plugin, na página de administração dos plugins.

Esta página é definida pelo template prive/squelettes/contenu/configurer_prefixoplugin.html e faz, normalmente, a chamada a um formulário de configuração.

Exemplo: Para o plugin ’mediabox’, o ficheiro prive/squelettes/contenu/configurer_mediabox.html contém:

[(#AUTORISER{configurer,mediabox}|oui)
	<h1><:mediabox:titre_page_configurer_box:></h1>
	<div class="ajax">
		#FORMULAIRE_CONFIGURER_MEDIABOX
	</div>
]

Se quiser que uma entrada apareça igualmente nos menus da área restrita, para dar um acesso mais direto a esta página de configuração, inclua uma entrada <menu> no ficheiro paquet.xml.

Exemplo:

<menu nom="coisa" titre="prefixeplugin:itemdelangue_coisa" parent="bando_configuration" icone="images/coisa-16.png" />

Para inicializar o valor de uma configuração (parâmetro "destaque", por exemplo) na criação ou atualização do plugin, incluir no pipeline meuplugin_upgrade():

• na criação:

  $maj['create'] = array(
  	array('ecrire_config','meuplugin/destaque', '3'),
  );
  

• numa atualização:

  $maj['0.1'] = array(
  	array('ecrire_config','meuplugin/destaque', '3'),
  );
  

Para remover o valor ao desinstalar o plugin, incluir no pipeline meuplugin_vider_tables():

effacer_config("meuplugin/destaque");

Aceder aos valores configurados

Num template, acede-se ao valor de uma configuração por meio da tag #CONFIG (por exemplo #CONFIG{meuplugin/destaque})

Em PHP os valores podem ser acedidos em leitura através da função lire_config com lire_config('meuplugin/destaque').

Em escrita, usa-se a função ecrire_config:
ecrire_config('meuplugin/destaque', 3)

Autorizações

Nenhum utilizador tem acesso à página de configuração. Por padrão, apenas os administradores o podem fazer, mas pode redefinir os direitos de acesso ao seu formulário de configuração. Para isso, use a API PHP autoriser, be como a tag #AUTORISER e o filtro sinon_interdire_acces para o seu template de formulário.

Exemplo: [(#AUTORISER{configurer,mediabox}|sinon_interdire_acces)]

Personalisar os processamentos

Às vezes, é preciso executar outros processamentos específicos quando valores de configuração são alterados. Nesse caso, é preciso incluir a função traiter() habitual da API CVT, e chamar a função comum que processa as configurações:

function formulaires_configurer_meuplugin_traiter_dist() {
	include_spip('inc/cvt_configurer');
	$retours = array();
	
	// Regista a nova configuração
	$trace = cvtconf_formulaires_configurer_enregistre('configurer_meuplugin', array());
	
	// Processamentos personalizados
	// …
	
	$retours['message_ok'] = _T('config_info_enregistree') . $trace;
	$retours['editable'] = true;
	
	return $retours;
}

Usa uma tabela diferente para armazenar os valores configurados

Por padrão, os valores configurados são armazenados na tabela spip_meta, e a totalidade dessa tabela é carregada em memória a cada hit. No entanto, pode-se usar uma tabela diferente para armazenar os valores configurados.

Por exemplo, para usar a tabela meta_meuplugin, é preciso incluir a linha a seguir no formulário de configuração:

<input type="hidden" name="_meta_table" value="meta_meuplugin" />

Para aceder aos valores registados nessa tabela, indique o nome da tabela antecedido por / no início do argumento lire_config:

ecrire_config('/meta_meuplugin/descricao', 'blah');
lire_config('/meta_meuplugin/argumento');

Além de _meta_table, o nome da tabela onde armazenar os valores configurados, existe três outras variáveis úteis para alterar o local ou o método de registo da configuração:

• _meta_casier: nome do "compartimento" onde serializar (por padrão, é xx de formulaire_configurer_xx)
• _meta_prefixe: prefixar os meta (alternativa ao compartimento) na tabela de meta (sem prefixo, por padrão)
• _meta_stockage: usar um método externo de armazenamento. Nenhum é fornecido pelo núcleo.