Criando campos personalizados em componentes nativos com um plugin

From Joomla! Documentation

This page is a translated version of the page Adding custom fields to core components using a plugin and the translation is 57% complete.

Outdated translations are marked like this.
Other languages:
বাংলা • ‎català • ‎Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎हिन्दी • ‎Nederlands • ‎português do Brasil • ‎русский

Você já quis que houvesse um campo extra no com_contact para mais um telefone ou no com_contact para os artigos? Joomla! oferece um jeito simples de integrar novos campos com componentes nativos como esses. Tudo que é necessário é um plugin de conteúdo e uma sobreposição de layout no seu template.

Esse artigo mostra como adicionar campos extras a um componente nativo tomando como exemplo criar mais um campo para e-mail no com_contact.

Adicionando um Campo Personalizado

Recomenda-se ler primeiro Criando um plugin para Joomla! para mais detalhes em como criar e instalar um plugin.

Para adicionar um campo a um componente do sistema, é necessário criar um plugin de conteúdo que pega o evento onContentPrepareForm e insere seus próprios campos dentro do JForm especificado. O código a seguir é para Joomla 3.1 e posterior. Para Joomla 2.5, é necessário carregar os arquivos de idioma no constructor (veja J2.5:Criando um Plugin para Joomla).

<?php
// no direct access
defined ('_JEXEC') or die;
class plgContentExample extends JPlugin
{
	/**
	 * Load the language file on instantiation.
	 * Note this is only available in Joomla 3.1 and higher.
	 * If you want to support 3.0 series you must override the constructor
	 *
	 * @var boolean
	 * @since <your version>
	 */
	protected $autoloadLanguage = true;

	/**
	 * Prepare form and add my field.
	 *
	 * @param   JForm  $form  The form to be altered.
	 * @param   mixed  $data  The associated data for the form.
	 *
	 * @return  boolean
	 *
	 * @since   <your version>
	 */
	function onContentPrepareForm($form, $data)
	{
		$app    = JFactory::getApplication();
		$option = $app->input->get('option');

		switch($option)
		{
			case 'com_contact' :
				if ($app->isClient('administrator'))
				{
					JForm::addFormPath(__DIR__ . '/forms');
					$form->loadFile('contact', false);
				}

				return true;
		}

		return true;
	}
}
?>

Enabling Front End Editing of Custom Fields

Enabling Frontend editing for your new custom fields is pretty easy. To add the fields to the frontend content edit form, simply add this block of code:

case 'com_contact':
	if ($app->isClient('site'))
	{
		JForm::addFormPath(__DIR__ . '/forms');
		$form->loadFile('contact', false);
	}
	return true;

Add that immediately below the existing instance of it.

Once you've got that done, create a template override for the content form edit.php file. If you're creating a set of custom fields for com_contact, you would copy /components/com_contact/views/form/tmpl/edit.php to /templates/your-template-name/html/com_contact/form/edit.php

Inside your layout override, add your new fields in the form where you want them to appear (e.g., below the title, below the description), making sure that the field names match the XML file from your plugin (you'll create this next).

<?php // Checking if this is an existing item or not ?>
<?php if ($this->item->id) : ?>
  <?php // If it is an existing item, get the attribs part of the existing record ?>
  <?php $attribs = json_decode($this->item->attribs); ?>
  <?php // Set the value of the custom field to what is already saved. ?>
  <?php // Duplicate for the number of fields you need, changing the field_name as needed. ?>
  <?php echo $this->form->setValue('field_name', 'attribs', $attribs->field_name); ?>
<?php endif; ?>
<?php // This line needs added to the file right where you want to display it. So, if you want it to show right after the description field, find the description field and place this right after it. Duplicate for the number of fields you need, changing the field_name as needed. ?>
<?php // Now we display the field. If we are editing an existing item, the previously saved data will be populated already ?>
<?php echo $this->form->renderField('field_name', 'attribs'); ?>

With that done, your fields will now appear and be stored via frontend editing.

Os campos adicionais são carregados do arquivo forms/contact.xml no diretório do plugin. É importante que esses campos estejam em um elemento de campos com a propriedade do nome definida como "params". Se não configurar essa propriedade do nome, os campos aparecerão no Admin mas os valores não serão salvos.

Nesse caso vamos adicionar um campo e um descritivo (label) para um campo de email no site e um segundo campo para o valor do endereço de email.

<?xml version="1.0" encoding="UTF-8"?>
<form>
	<fields name="params">
		<fieldset name="params" label="PLG_CONTENT_EXAMPLE_FIELDSET_LABEL">
			<field
				name="contact_emaillabel2"
				type="text"
				label="PLG_CONTENT_EXAMPLE_CONTACT_EMAILLABEL2"
			/>
			<field
				name="contact_email2"
				type="text"
				label="PLG_CONTENT_EXAMPLE_CONTACT_EMAIL2"
				filter="email"
			/>
		</fieldset>
	</fields>
</form>

Finalmente precisamos de um arquivo de idioma para que os parâmetros sejam apresentados corretamente no admin e sejam traduzíveis para outras línguas. Esse arquivo precisa ser nomeado en-GB.plg_content_example.ini.

PLG_CONTENT_EXAMPLE_FIELDSET_LABEL="Additional Information"
PLG_CONTENT_EXAMPLE_CONTACT_EMAIL2="Additional email address"
PLG_CONTENT_EXAMPLE_CONTACT_EMAILLABEL2="Additional email label"

Assim se adicionar o campo ao com_contact. Se instalar esse plugin, terá uma guia adicional o formulário de edição do contato chamada "Informação Adicional"com os campos novos incluídos. Ao preencher o novo campo para um contato, você verá que com_contact guardará e exibirá a informação para você.

O mesmo plugin pode ser usado para adicionar mais campos para componentes diferentes; basta incluir o código específico na função onContentPrepareForm e criar os arquivos XML de formulário apropriados.

Exibindo o Campo Personalizado

Para exibir o campo personalizado será necessário criar uma sobreposição de layout para o componente no seu template. Para mais detalhes para criar templates, leia Criando um template Joomla básico. Para mais detalhes sobre sobreposições de layout, leia Entendendo Sobreposições.

Copie o arquivo <Joomla>/components/com_contact/views/contact/tmpl/default.php para <template>/html/com_contact/contact/default.php, criando os diretórios conforme necessário. Vamos editar esse arquivo para incluir a informação adicional. O componente com_contact carregará automaticamente os campos adicionais e dentro da variável chamada $this->params. Tudo que se precisa fazer é conferir se os dados estão configurados e, feito isso, exibí-los.

Para exibir o campo, encontre o local em <template>/html/com_contact/contact/default.php que corresponde aonde você gostaria que o endereço de email adicional seja exibido e inclua o código a seguir:

<?php if ($this->params->get('contact_emaillabel2', false)) : ?>
	<div>
		<span class="contact-additionalemail"><?php echo $this->params->get('contact_emaillabel2'); ?>:&emsp;<a href="mailto:<?php echo $this->params->get('contact_email2'); ?>"><?php echo $this->params->get('contact_email2'); ?></a><br/></span>
	</div>
<?php endif; ?>

Incluindo esse código e instalando seu template, agora verá o campo personalizado no seu site.