Criar Módulo para Magento – Parcelas no Produto Configurável

Estrutura de Módulos no Magento: Fundamentos e Organização

Basicamente, um módulo para Magento é constituído por um conjunto de arquivos cujo propósito é estender, modificar ou sobrescrever o comportamento padrão do sistema. Essa arquitetura modular é um dos atributos que tornam o Magento uma das principais plataformas de e-commerce no Brasil e no mundo. Por meio dos módulos, desenvolvedores conseguem implementar funcionalidades personalizadas, integrar sistemas externos e adaptar o funcionamento da loja virtual às necessidades específicas de cada operação de ecommerce.

Vale lembrar que grande parte do sistema de vendas online denominado Magento E-commerce é formado por módulos nativos, que já vêm integrados à instalação padrão do sistema. Esses módulos estão localizados (organizados) dentro do diretório app/code/core/Mage, onde cada pasta representa uma funcionalidade específica. Essa estrutura facilita a manutenção e a evolução do sistema, permitindo que novas funcionalidades sejam adicionadas sem comprometer o núcleo da aplicação.

Na criação de lojas virtuais premium, o uso estratégico de módulos é essencial para garantir uma experiência diferenciada ao usuário final. Seja por meio de melhorias na performance, personalizações no layout, ou integrações com sistemas de pagamento e logística, os módulos desempenham um papel central na construção de soluções de alto nível. Além disso, o Magento permite a criação de módulos personalizados, que podem ser desenvolvidos sob medida para atender demandas específicas de cada projeto.

A modularidade do Magento também contribui para a escalabilidade da plataforma. À medida que o negócio cresce, novos módulos podem ser adicionados para suportar funcionalidades avançadas, como programas de fidelidade, marketplaces, vendas omnichannel e muito mais. Essa capacidade de expansão é um dos motivos pelos quais o Magento é amplamente adotado por empresas que buscam plataformas de e-commerce robustas e preparadas para operações consideráveis.

Em resumo, entender a estrutura e o funcionamento dos módulos no Magento é fundamental para qualquer desenvolvedor ou empresa que deseje explorar todo o potencial da plataforma. Seja para pequenas customizações ou para projetos complexos de criação de lojas virtuais premium, os módulos são a chave para transformar ideias em soluções digitais eficientes e escaláveis.

Produtos Configuráveis: Dinamismo e Compatibilidade com Módulos Personalizados

No Magento, os produtos configuráveis representam uma solução versátil para oferecer variações específicas de um item, permitindo que o consumidor selecione atributos como sabores, cores, tamanhos, modelos e outras opções relevantes. Cada variação pode possuir um preço adicional, refletindo com precisão o valor de cada escolha feita durante a navegação.

Como uma das “principais plataformas para criar loja virtual“, o Magento realiza a atualização do preço dos produtos configuráveis de forma dinâmica, sem a necessidade de recarregar a página. Essa funcionalidade é essencial para garantir uma experiência de compra moderna e fluida, especialmente em projetos voltados para a “criação de lojas virtuais premium”, onde a performance e a interatividade são prioridades.

Dessa forma, ao desenvolver um módulo de parcelamento compatível com produtos configuráveis, é fundamental seguir esse mesmo padrão de atualização dinâmica. Isso assegura que o cálculo das parcelas reflita corretamente o valor da variação selecionada, mantendo a consistência da interface e a confiabilidade das informações exibidas ao cliente.

Definindo os Diretórios do Módulo Magento

A partir deste ponto, é fundamental que você preste atenção à diferenciação entre letras maiúsculas e minúsculas. O Magento é sensível a essa distinção, e qualquer alteração incorreta pode impedir o funcionamento do módulo.

Acesse o diretório app/code/local, caso a pasta local não exista em seu sistema, será necessário criá-la, pois é nessa área que vamos estruturar os novos diretórios e inserir os arquivos ao longo deste artigo.

Utilizaremos Newer7 como Namespace e o nome do módulo será Parcelamento. Com isso, a estrutura de diretórios que você deverá criar será a seguinte:

app/code/local/Newer7/Parcelamento/controllers
app/code/local/Newer7/Parcelamento/etc
app/code/local/Newer7/Parcelamento/Helper

1) Após a criação dos diretórios, crie um arquivo chamado config.xml e coloque-o no diretório etc (app/code/local/Newer7/Parcelamento/etc/config.xml). Esse arquivo deverá conter o seguinte conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<config>
	<modules>
		<Newer7_Parcelamento>
			<version>0.1.0</version>
		</Newer7_Parcelamento>
	</modules>
	<frontend>
		<routers>
			<parcelamento>
				<use>standard</use>
					<args>
						<module>Newer7_Parcelamento</module>
						<frontName>parcelamento</frontName>
					</args>
			</parcelamento>
		</routers>
		<layout>
    		<updates>
        		<parcelamento>
            		<file>newer7_parcelamento.xml</file>
            	</parcelamento>
			</updates>
		</layout>
	</frontend>
	<global>
		<helpers>
    		<parcelamento>
        		<class>Newer7_Parcelamento_Helper</class>
        	</parcelamento>
		</helpers>
	</global>
    <adminhtml>
        <acl>
            <resources>
                <admin>
                    <children>
                        <system>
                            <children>
                                <config>
                                    <children>
                                        <parcelamento>
                                            <title>Newer7 Parcelamento</title>
											<sort_order>70</sort_order>
                                        </parcelamento>
                                    </children>
                                </config>
                            </children>
                        </system>
                    </children>
                </admin>
            </resources>
        </acl>
    </adminhtml>
        <default>
            <parcelamento>
                <parcelamento_general>
                    <enabled>0</enabled>
                    <parcelamento_jquery>1</parcelamento_jquery>
					<parcelamento_xparcelas>0</parcelamento_xparcelas>
					<parcelamento_desconto>0</parcelamento_desconto>                                       
                </parcelamento_general>
            </parcelamento>
        </default>
</config>

Linha 5: <version>0.1.0</version> Versão do módulo.

Linha 8: <frontend> Refere-se à área frontal da loja virtual — a parte acessível aos clientes.

Linha 9: <routers> Inclui informações de configuração sobre os roteadores e os objetos responsáveis pelo encaminhamento das requisições.

Linha 11: <use>standard</use> Indica ao sistema que essa rota será utilizada no frontend.

Linha 13: <module>Newer7_Parcelamento</module> Nome completo do módulo, incluindo seu package/namespace. O Magento utiliza esse valor para localizar os arquivos do controlador.

Linha 14: <frontName>parcelamento</frontName> Valor definido para informar ao Magento qual rota será usada na URL.

Linha 21: <file>newer7_parcelamento.xml</file> Define o arquivo de atualização de layout do módulo (que será criado e inserido no sistema em breve).

Linha 34: <acl> Define a entrada ACL (Access Control List).

Linha 43: <title>Newer7 Parcelamento</title> Título exibido na seção de permissões de usuários (lista de recursos ACL) dentro do painel administrativo do Magento.

Linha 57: <parcelamento_general> Nome do grupo de configurações.

Linhas 58, 59, 60 e 61: São campos que serão criados no arquivo system.xml, recebendo seus valores iniciais através do arquivo config.xml. Neste caso, os valores definidos são: 0, 1, 0 e 0.

2) Crie um arquivo chamado system.xml e coloque no diretório etc (app/code/local/Newer7/Parcelamento/etc/system.xml).
O arquivo deverá conter o seguinte conteúdo:

<?xml version="1.0"?>
<config>
    <tabs>
        <parcelamento translate="label" module="parcelamento">
            <label>Newer7</label>
            <sort_order>110</sort_order>
        </parcelamento>
    </tabs>
    <sections>
        <parcelamento translate="label" module="parcelamento">
            <class>separator-top</class>
            <label>Parcelamento</label>
            <tab>parcelamento</tab>
            <sort_order>100</sort_order>
            <show_in_default>1</show_in_default>
            <show_in_website>1</show_in_website>
            <show_in_store>1</show_in_store>
            <groups>
                <parcelamento_general translate="label">
                    <label>Configurações</label>
                    <frontend_type>text</frontend_type>
                    <sort_order>10</sort_order>
                    <show_in_default>1</show_in_default>
                    <show_in_website>1</show_in_website>
                    <show_in_store>1</show_in_store>
                    <fields>
                    	<enabled translate="label">
                        <label>Ativar</label>
                        <frontend_type>select</frontend_type>
                        <source_model>adminhtml/system_config_source_yesno</source_model>
                        <sort_order>1</sort_order>
                        <show_in_default>1</show_in_default>
                        <show_in_website>1</show_in_website>
						<show_in_store>1</show_in_store>
						<comment>Selecione para ativar/desativar o módulo.</comment>
						</enabled>
					    <parcelamento_jquery translate="label">
                        <label>Habilitar jQuery</label>
                        <frontend_type>select</frontend_type>
                        <source_model>adminhtml/system_config_source_enabledisable</source_model>
                        <sort_order>2</sort_order>
                        <show_in_default>1</show_in_default>
                        <show_in_website>1</show_in_website>
                        <show_in_store>1</show_in_store>
                        <comment>Desabilite se estiver sendo carregado por outro módulo.</comment>
                        </parcelamento_jquery>
                        <parcelamento_xparcelas translate="label">
                        <label>Quantidade de parcelas</label>
                        <frontend_type>text</frontend_type>
                        <sort_order>3</sort_order>
                        <show_in_default>1</show_in_default>
                        <show_in_website>1</show_in_website>
                        <show_in_store>1</show_in_store>
				        <comment>Digite a quantidade máxima de parcelas.</comment>
                        </parcelamento_xparcelas>
			            <parcelamento_desconto translate="label">
                        <label>Desconto à vista</label>
                        <frontend_type>text</frontend_type>
                        <sort_order>4</sort_order>
                        <show_in_default>1</show_in_default>
                        <show_in_website>1</show_in_website>
                        <show_in_store>1</show_in_store>
						<comment>Digite o valor para o desconto à vista.</comment>
                        </parcelamento_desconto>
                    </fields>
                </parcelamento_general>
            </groups>
        </parcelamento>
    </sections>
</config>

Linha 5: <label>Newer7</label> Rótulo que será utilizado para exibição na guia do menu lateral.

Linha 6: <sort_order>110</sort_order> Indica o posicionamento em relação as outras guias.

Linha 12: <label>Parcelamento</label> Rótulo da seção exibido na guia do menu lateral e no lado direito como título da página.

Linha 13: <tab>parcelamento</tab> Nome da posição na lista de seções.

Linha 14: <sort_order>100</sort_order> Indica o posicionamento em relação as outras seções.

Linhas 23, 24 e 25: <show_in_default>, <show_in_website>, <show_in_store> Valores 1 ou 0 (exibir ou ocultar), destina-se aos diferentes escopos selecionáveis no painel administrativo do Magento. Se for omitido receberá o valor padrão 0 (ocultar).

Linha 57: <label>Desconto à vista</label> Nome do campo.

Linha 58: <frontend_type>text</frontend_type> Determina o tipo de campo que será usado para coletar o valor da configuração. Neste caso “text”.

Linha 59: <sort_order>4</sort_order> Indica o posicionamento em relação aos outros campos.

Linha 63: <comment>Digite o valor para o desconto à vista.</comment> Comentário referente ao campo.

3) Chegou a hora de avisar ao Magento que o nosso módulo existe e está ativo, para isso crie um arquivo chamado, Newer7_Parcelamento.xml e coloque dentro do diretório de módulos do sistema app/etc/modules. O arquivo deverá ser composto pelo seguinte conteúdo:

<?xml version="1.0" encoding="UTF-8"?>
<config>
	<modules>
		<Newer7_Parcelamento>
			<active>true</active>
			<codePool>local</codePool>
		</Newer7_Parcelamento>
	</modules>
</config>

Linha 5: <active>true</active> Informamos que o módulo está ativo.

Linha 6: <codePool>local</codePool> Informamos o diretório que o módulo se encontra.

4) Crie um arquivo chamado Data.php e coloque no diretório Helper (app/code/local/Newer7/Parcelamento/Helper/Data.php). O arquivo deverá ser composto pelo seguinte conteúdo:

<?php

class Newer7_Parcelamento_Helper_Data extends Mage_Core_Helper_Abstract
{

}

5) Crie um arquivo chamado IndexController.php e coloque no diretório controllers (app/code/local/Newer7/Parcelamento/controllers/IndexController.php).
O arquivo deverá ser composto pelo seguinte conteúdo:

<?php

class Newer7_Parcelamento_IndexController extends Mage_Core_Controller_Front_Action {

public function indexAction() {

$preco_inicial = $this->getRequest()->get('preco');
$preco = str_replace('R$', '', $preco_inicial);
$preco = str_replace('.', '', $preco);
$preco = str_replace(',', '.', $preco);

$quantidade_parcelas = Mage::getStoreConfig('parcelamento/parcelamento_general/parcelamento_xparcelas');
$desconto = Mage::getStoreConfig('parcelamento/parcelamento_general/parcelamento_desconto');
$valor_parcela = number_format($preco/$quantidade_parcelas,2,',','.');
$preco_avista = ($preco/100)*(100-$desconto);

echo 'R$ '.number_format($preco,2,',','.').' em até '.$quantidade_parcelas.'x de R$ '.$valor_parcela.' no cartão <br/>R$ '.number_format($preco_avista,2,',','.').' à vista com '.$desconto.'% de desconto';

		}
	}
?>

Esse arquivo é responsável por receber, tratar e devolver os valores para a página do produto configurável (enviado via post quando uma opção do select for selecionada). Basicamente o que ele faz é receber o preço, resgatar os valores dos campos Quantidade de parcelas e Desconto à vista, efetuar os cálculos necessários, formatar os valores e devolver para a página do produto configurável.

Aviso: Os campos Quantidade de parcelas e Desconto à vista devem ser preenchidos na área administrativa do módulo.

6) Acesse app/design/frontend/base/default/template/ e crie um diretório chamado newer7_parcelamento. Crie também um arquivo chamado valores.phtml e coloque dentro do diretório newer7_parcelamento
(app/design/frontend/base/default/template/newer7_parcelamento/valores.phtml).
O arquivo valores.phtml deverá ser composto pelo seguinte conteúdo:

<?php
$_product = $this->getProduct();
$preco = $_product->getPrice();
$quantidade_parcelas = Mage::getStoreConfig('parcelamento/parcelamento_general/parcelamento_xparcelas');
$desconto = Mage::getStoreConfig('parcelamento/parcelamento_general/parcelamento_desconto');
$valor_parcela = number_format($preco/$quantidade_parcelas,2,',','.');
$preco_avista = ($preco/100)*(100-$desconto);
echo '<div id="parcelamento">R$ '.number_format($preco,2,',','.').' em até '.$quantidade_parcelas.'x de R$ '.$valor_parcela.' no cartão <br/>R$ '.number_format($preco_avista,2,',','.').' à vista com '.$desconto.'% de desconto</div>';
?>

<script type="text/javascript">
//<![CDATA[
var $j = jQuery.noConflict();
$j(document).ready(function(){
$j(".input-box select").change(function(){
$j('#parcelamento').html('<img src="<?php echo $this->getSkinUrl('images/newer7_parcelamento/ajax-loader.gif'); ?>"> Carregando');
$j.ajax({
url: '<?php echo $this->getUrl("parcelamento")?>',
type:"POST",
data:({"preco": $j('.price-box span span.price').html()}),
success: function(data) {
$j('#parcelamento').html(data);
}
})
})
})
//]]>
</script>

Se você está acompanhando este artigo desde o início já deve ter percebido que a biblioteca jQuery será necessária para o funcionamento do módulo, e por isso vamos inseri-la.
Acesse: js e crie um diretório chamado newer7_parcelamento. Após efetuar o download, renomeie o arquivo para jquery-newer7.js e coloque dentro do diretório newer7_parcelamento.

baixar jQuery

Lembre-se de inserir jQuery.noConflict(); no final de sua biblioteca.

Aviso: Se você fizer exatamente como foi explicado não precisará se preocupar com conflitos entre Prototype / jQuery e, caso seu tema ou módulo(s) já estiverem utilizando jQuery, lembre-se que em system.xml criamos um campo exclusivo para habilitar ou desabilitar a biblioteca do módulo.

Sobre o arquivo valores.phtml:

Será chamado na página de visão do produto e é responsável pelas seguintes tarefas.

• Calcular e exibir o parcelamento quando a página for carregada.
• Iniciar a requisição AJAX quando alguma das opções do select for selecionada.
• Exibir uma imagem giratória juntamente com a mensagem Carregando (esse efeito ocorrerá entre o início e o fim da requisição AJAX).
• Assim que houver sucesso na requisição, o valor do produto, a quantidade de parcelas, o valor da parcela e o desconto à vista serão atualizados.

A imagem abaixo ilustra o funcionamento das tarefas mencionadas, no entanto, para fazer o módulo funcionar ainda precisamos criar o arquivo de layout e chamar nosso bloco valores.phtml no template (faremos isso nos próximos passos deste artigo).

Para finalizar este passo vamos inserir a imagem animada.

Após efetuar o download da imagem acesse: skin/frontend/base/default/images e crie um diretório chamado newer7_parcelamento. Coloque a imagem ajax-loader.gif dentro do diretório newer7_parcelamento (skin/frontend/base/default/images/newer7_parcelamento/ajax-loader.gif).

7) Crie um arquivo chamado newer7_parcelamento.xml e coloque em app/design/frontend/base/default/layout.
(app/design/frontend/base/default/layout/newer7_parcelamento.xml). Segue abaixo o conteúdo para o arquivo:

<?xml version="1.0"?>
<layout version="0.1.0">
<default>
    <reference name="head">
		<action method="addItem" ifconfig="parcelamento/parcelamento_general/parcelamento_jquery"><type>js</type><name>newer7_parcelamento/jquery-newer7.js</name></action>
	</reference>
</default>
<catalog_product_view>
	<reference name="product.info">
    	<block type="catalog/product_view" name="valores" as="valores" template="newer7_parcelamento/valores.phtml" />
	</reference>
</catalog_product_view>
</layout>

Este é o arquivo de layout do módulo que estamos criando. Observe que na linha 5 existe um método que nos permite adicionar um arquivo js adicional para a seção head, e neste caso, o arquivo que está sendo adicionado é jquery-newer7.js. O ifconfig (também na linha 5) verifica se o campo Habilitar jQuery está habilitado no admin antes de adicionar o arquivo.

Na linha 10 acrescentamos o bloco valores.phtml para ser exibido na página de visualização do produto.

8) Esta é a parte onde vamos chamar o bloco responsável pela exibição do parcelamento em nosso template. O local para inserção do código ficará a critério de cada um, eu apenas vou dar um exemplo de como fazer com o tema padrão do magento, pois, devido a diversidade de temas disponíveis no mercado seria impossível dizer um local exato. Sem falar que cada usuário tem seu próprio gosto, ou seja, enquanto um usuário prefere inserir o parcelamento abaixo da imagem do produto, outros poderiam inserir acima da breve descrição, enfim, as opções são muitas.

Abra o arquivo view.phtml do seu tema (app/design/frontend/default/seu-tema/template/catalog/product/view.phtml).

Próximo a linha 100 insira o código abaixo:

<style type="text/css">
#parcelamento{clear:both;padding-top:8px;}
</style>

<?php if($_product->getTypeId() == 'configurable' && Mage::getStoreConfig('parcelamento/parcelamento_general/enabled')): ?>
<?php echo $this->getChildHtml("valores"); ?>
<?php endif; ?>

Na linha 2 foi inserido um pequeno trecho de código para posicionar corretamente a div com id “parcelamento” no tema padrão do Magento. É recomendável que vocês apliquem seus próprios estilos de acordo com o local de inserção. Se possível, coloque em uma folha externa.

A linha 5 verifica se o produto é do tipo configurável e se o módulo está ativado na administração. Se as duas condições forem satisfeitas a linha 6 irá inserir o bloco na pagina.

Dica: Antes de acessar as configurações do módulo no painel administrativo do magento, limpe o cache, faça log out / log in.

E assim chegamos ao final deste artigo. Se alguma dúvida surgir, utilize os comentários.

Piero Luiz

Full Stack & Performance Expert

+13 anos transformando café e lógica em ecossistemas digitais de alta performance. Especialista em “domar o caos” no desenvolvimento de sites, apps e sistemas complexos, Piero une a precisão da engenharia de software com estratégias de SEO e marketing digital que colocam marcas no topo. Entre um riff de guitarra e uma linha de código, ele constrói arquiteturas robustas e interfaces que convertem.

Sistemas & Aplicativos: APIs, ERP/CRM, softwares e integrações sob medida.
E-commerce & CMS: Lojas virtuais, blogs e módulos de alta conversão.
Growth & UX: SEO de precisão e design focado na experiência do usuário.
Infra: Suporte, manutenção e hospedagem web de alta disponibilidade.

Localização: Brasil | Atendimento Global.