System - WhatsApp Button

Get System - WhatsApp Button (v3.0.0)

Introduction

Chat, Editor Buttons

Lightweight, professional and fully configurable WhatsApp floating button plugin for Joomla 4, 5 and 6.

plgsystembtnwhatsapp — Floating WhatsApp Button Plugin for Joomla

plgsystembtnwhatsapp is a System type Joomla plugin that automatically injects a floating WhatsApp button into the frontend of any Joomla website. It enables direct and instant communication between visitors and the site owner without modifying the template structure or adding any manual code.

Built with a clean, modular and modern architecture, the plugin is fully compatible with Joomla 4, 5 and 6, requires PHP 8.3+ and has zero external dependencies.

Architecture Overview

Plugin type: System
Event interception: onBeforeCompileHead() + onAfterRender()
Frontend-only execution with context verification
Assets loaded via Joomla WebAssetManager
HTML injected before tag
CSS Variables for per-instance customization
data-attributes decoupling PHP config from JS behavior
Service Provider with dependency injection (Joomla 4+ standard)
FileLayout separating business logic from presentation
Template-independent structure

How It Works

Plugin loads as a System plugin
onBeforeCompileHead registers and enqueues CSS and JS via WebAssetManager
onAfterRender runs all validation rules before injecting the button:
- Context: frontend only (isClient site)
- Device: filters by desktop, mobile or both via HTTPUSERAGENT
- Page: checks active menu item against configured list
- Schedule: calculates if current time is within business hours by configured timezone
- Phone: sanitizes input, digits only
- Message: replaces dynamic variables {url}, {title}, {sitename}
- Link: generates wa.me URL for mobile or api.whatsapp.com for desktop
Layout default.php receives all data via displayData, resolves icon, builds inline CSS variables and data-attributes
JavaScript reads data-attributes after DOMContentLoaded and handles entrance animation and tooltip behavior

Key Features

WhatsApp
- Phone number with country code
- Pre-filled message with dynamic variables: {url}, {title}, {sitename}
- Button position: right or left with LTR/RTL support

Display
- Show on all pages, only selected or hide on selected
- Menu item filter with multiple selection
- Device filter: all, desktop only or mobile only

Layout
- Button modes: icon only / text only / icon + text
- Customizable icon by priority: CSS Class → SVG (sanitized) → Image via Joomla Media Manager → default WhatsApp icon
- Shapes: circle, pill, rounded, square
- Sizes: small, medium, large

Design
- Background, text and border colors for normal and hover states
- Shadow toggle
- Bottom and side offset in px
- Z-index control

Behaviour
- Entrance animations: slide, bounce, fade or none with configurable delay
- Auto tooltip with text, delay and colors
- Tooltip re-shown on hover and focus for accessibility

Business Hours
- Per weekday control with open and close time
- Configurable timezone
- Offline state: grey button without link with custom message

Security

SVG sanitization: automatically removes on* attributes, script tags and javascript: occurrences before saving
Media field type="media" for native Joomla Media Manager integration
Frontend-only execution, zero backend interference

Technical Decisions

| Decision | Justification |
|---|---|
| System plugin type | Global frontend injection without template dependency |
| onBeforeCompileHead + onAfterRender | Assets via WebAssetManager + HTML injected before |
| Inline CSS Variables | Per-instance customization without overriding stylesheets |
| data-attributes on wrapper | Decouples PHP configuration from JS behavior |
| Service Provider DI | Modern Joomla 4+ standard for plugin instantiation |
| SVG sanitization in PHP | Security: removes on*, script and javascript: before rendering |
| type="media" for image field | Native integration with Joomla Media Manager |
| Separate FileLayout | Separates business logic from presentation layer |

Requirements

Joomla 4.x / 5.x / 6.x
PHP 8.3+

Planned Roadmap

Multiple attendants / phone numbers support
WhatsApp Business API integration
Automatic dark mode
Per menu item color configuration
Pre-chat widget with name and subject fields

Author

Hirlei Carlos Pereira de Araújo
Senior Web Developer | PHP & Joomla | Corporate Systems | Government & Education

LinkedIn: https://linkedin.com/in/hirleicarlos
GitHub: https://github.com/hirleicarlos
Website: https://hirleicarlos.github.io

plgsystembtnwhatsapp — Plugin de Botão Flutuante WhatsApp para Joomla

Plugin leve, profissional e totalmente configurável de botão flutuante WhatsApp para Joomla 4, 5 e 6.

plgsystembtnwhatsapp é um plugin do tipo System para Joomla que injeta automaticamente um botão flutuante de WhatsApp no frontend do site. Permite comunicação direta e instantânea entre visitantes e o administrador do site sem necessidade de modificar o template ou inserir qualquer código manual.

Construído com arquitetura limpa, modular e moderna, o plugin é totalmente compatível com Joomla 4, 5 e 6, requer PHP 8.3+ e não possui dependências externas.

Visão Geral da Arquitetura

Tipo de plugin: System
Interceptação de eventos: onBeforeCompileHead() + onAfterRender()
Execução exclusiva no frontend com verificação de contexto
Assets carregados via WebAssetManager do Joomla
HTML injetado antes da tag
CSS Variables para personalização por instância
data-attributes desacoplando configuração PHP do comportamento JS
Service Provider com injeção de dependência (padrão Joomla 4+)
FileLayout separando lógica de negócio da apresentação
Estrutura independente do template

Como Funciona

Plugin carregado como plugin do tipo System
onBeforeCompileHead registra e enfileira CSS e JS via WebAssetManager
onAfterRender executa todas as validações antes de injetar o botão:
- Contexto: somente frontend (isClient site)
- Dispositivo: filtra por desktop, mobile ou ambos via HTTPUSERAGENT
- Página: verifica item de menu ativo contra a lista configurada
- Horário: calcula se está dentro do horário de atendimento pelo fuso configurado
- Telefone: sanitiza a entrada, aceita somente dígitos
- Mensagem: substitui variáveis dinâmicas {url}, {title}, {sitename}
- Link: gera URL wa.me para mobile ou api.whatsapp.com para desktop
Layout default.php recebe todos os dados via displayData, resolve o ícone, monta CSS variables inline e data-attributes
JavaScript lê os data-attributes após DOMContentLoaded e gerencia animação de entrada e comportamento do tooltip

Principais Recursos

WhatsApp
- Número de telefone com DDI
- Mensagem pré-preenchida com variáveis dinâmicas: {url}, {title}, {sitename}
- Posição do botão: direita ou esquerda com suporte a LTR/RTL

Exibição
- Exibir em todas as páginas, apenas nas selecionadas ou ocultar nas selecionadas
- Filtro por item de menu com seleção múltipla
- Filtro por dispositivo: todos, somente desktop ou somente mobile

Layout
- Modos do botão: somente ícone / somente texto / ícone + texto
- Ícone personalizável por prioridade: Classe CSS → SVG (sanitizado) → Imagem via Gerenciador de Mídia do Joomla → ícone padrão WhatsApp
- Formas: círculo, pílula, arredondado, quadrado
- Tamanhos: pequeno, médio, grande

Design
- Cores de fundo, texto e borda para os estados normal e hover
- Sombra ativável
- Distância do rodapé e lateral em px
- Controle de z-index

Comportamento
- Animações de entrada: slide, bounce, fade ou nenhuma com delay configurável
- Tooltip automático com texto, delay e cores configuráveis
- Tooltip re-exibido no hover e focus para acessibilidade

Horário de Atendimento
- Controle por dia da semana com horário de abertura e fechamento
- Fuso horário configurável
- Estado offline: botão cinza sem link com mensagem personalizada

Segurança

Sanitização de SVG: remove automaticamente atributos on*, tags script e ocorrências de javascript: antes de salvar
Campo de imagem type="media" para integração nativa com o Gerenciador de Mídia do Joomla
Execução exclusiva no frontend, zero interferência no backend

Decisões Técnicas

| Decisão | Justificativa |
|---|---|
| Plugin tipo System | Injeção global no frontend sem depender de template |
| onBeforeCompileHead + onAfterRender | Assets via WebAssetManager + HTML injetado antes do |
| CSS Variables inline | Personalização por instância sem sobrescrever folhas de estilo |
| data-attributes no wrapper | Desacopla configuração PHP do comportamento JS |
| Service Provider com DI | Padrão moderno Joomla 4+ para instanciação de plugins |
| Sanitização de SVG no PHP | Segurança: remove on*, script e javascript: antes de renderizar |
| Campo type="media" para imagem | Integração nativa com o Gerenciador de Mídia do Joomla |
| FileLayout separado | Separa lógica de negócio da camada de apresentação |

Requisitos

Joomla 4.x / 5.x / 6.x
PHP 8.3+

Roadmap Planejado

Suporte a múltiplos atendentes / números
Integração com WhatsApp Business API
Modo escuro automático
Configuração de cor por item de menu
Widget de pré-chat com nome e assunto

Autor

Hirlei Carlos Pereira de Araújo
Desenvolvedor Web Sênior | PHP & Joomla | Sistemas Corporativos | Governo e Educação

LinkedIn: https://linkedin.com/in/hirleicarlos
GitHub: https://github.com/hirleicarlos
Site: https://hirleicarlos.github.io