Plugin WhatsApp Floating Button

Plugin para Mapas Culturais que adiciona um botão flutuante do WhatsApp fixado no lado direito inferior da tela em todo o sistema. O plugin permite configuração fácil do número e mensagem através de variáveis de ambiente.

Características

• 🎯 Botão flutuante fixo - Sempre visível no canto inferior direito
• 📱 Responsivo - Adapta-se automaticamente a dispositivos móveis e desktop
• 🎨 Visual atrativo - Design moderno com efeito de pulso e animações
• ⚙️ Configurável - Número e mensagem configuráveis via variáveis de ambiente
• 🌐 Acessível - Suporte a navegação por teclado e leitores de tela
• 🌍 Internacionalizado - Suporte a múltiplos idiomas (pt_BR, es_ES, es_AR, en_US)
• 📊 Analytics - Integração opcional com Google Analytics e Google Tag Manager
• 🔧 Plug and play - Fácil instalação e configuração

Instalação

1. Configuração do Plugin

Adicione o plugin ao arquivo de configuração do seu projeto Mapas Culturais:

<?php
// Em config.d/plugins.php ou config.d/0.main.php

return [
    'plugins' => [
        // ... outros plugins
        
        'WhatsAppFloating' => [
            'namespace' => 'WhatsAppFloating',
            'config' => []
        ],
    ]
];

2. Configuração das Variáveis de Ambiente

Adicione as seguintes variáveis ao seu arquivo .env:

# Habilita ou desabilita o plugin
WHATSAPP_ENABLED=true

# Número do WhatsApp (com código do país)
# Exemplo para Brasil: 5511999999999 (55 = Brasil, 11 = DDD, 999999999 = número)
WHATSAPP_NUMBER=5511999999999

# Mensagem padrão que será enviada
WHATSAPP_MESSAGE=Olá! Gostaria de falar com vocês. 👋\n\nObrigado!

Internacionalização

O plugin suporta múltiplos idiomas automaticamente baseado na configuração do Mapas Culturais:

Idiomas Suportados

• pt_BR - Português (Brasil) - Padrão
• es_ES - Espanhol (Espanha)
• es_AR - Espanhol (Argentina)
• en_US - Inglês (Estados Unidos)

Adicionando Novos Idiomas

1. Copie o arquivo translations/whatsapp-floating.pot
2. Renomeie para translations/[codigo_idioma].po
3. Traduza as strings no arquivo
4. Faça um pull request com a nova tradução

Strings Traduzíveis

• Mensagem padrão do WhatsApp
• Título do botão (tooltip)
• Texto do tooltip

Consulte translations/README.md para detalhes sobre como contribuir com traduções.

### 3. Restart da Aplicação

Após a configuração, reinicie a aplicação para que as alterações tenham efeito.

## Configuração Detalhada

### Variáveis de Ambiente

| Variável | Tipo | Padrão | Descrição |
|----------|------|---------|-----------|
| `WHATSAPP_ENABLED` | boolean | `true` | Habilita/desabilita o plugin |
| `WHATSAPP_NUMBER` | string | - | Número do WhatsApp com código do país |
| `WHATSAPP_MESSAGE` | string | "Olá! Gostaria de falar com vocês." | Mensagem padrão |

#### Formato do Número

O número deve seguir o formato internacional sem símbolos:

- ✅ Correto: `5511999999999` (Brasil: 55 + DDD: 11 + Número: 999999999)
- ❌ Incorreto: `+55 (11) 99999-9999`
- ❌ Incorreto: `11 99999-9999`

#### Exemplos de Números por País

```env
# Brasil
WHATSAPP_NUMBER=5511999999999

# Argentina
WHATSAPP_NUMBER=5491199999999

# Estados Unidos
WHATSAPP_NUMBER=15551234567

# Portugal
WHATSAPP_NUMBER=351999999999

Personalização da Mensagem

A mensagem pode incluir:

• Emojis: 👋 😊 📞
• Quebras de linha: Use \n no .env
• Caracteres especiais: Serão automaticamente codificados

# Exemplo com quebra de linha
WHATSAPP_MESSAGE=Olá! 👋\n\nGostaria de falar com vocês sobre o Mapas Culturais.\n\nObrigado!

Funcionalidades

Comportamento Responsivo

• Desktop: Abre WhatsApp Web (web.whatsapp.com)
• Mobile: Abre o aplicativo nativo do WhatsApp
• Tooltip: Exibido apenas em desktop (escondido em mobile)

Acessibilidade

• Navegação por teclado (Tab + Enter/Espaço)
• Atributos ARIA apropriados
• Contraste adequado seguindo WCAG

Analytics (Opcional)

O plugin está preparado para integração com:

Google Analytics 4

gtag('event', 'click', {
    'event_category': 'WhatsApp',
    'event_label': 'Floating Button'
});

Google Tag Manager

dataLayer.push({
    'event': 'whatsapp_click',
    'event_category': 'engagement',
    'event_action': 'click',
    'event_label': 'whatsapp_floating_button'
});

Estrutura do Plugin

plugins/WhatsAppFloating/
├── Plugin.php                          # Classe principal do plugin
├── README.md                           # Esta documentação
├── .env.example                        # Exemplo de configuração
├── assets/
│   ├── css/
│   │   └── whatsapp-floating.css      # Estilos do botão
│   └── js/
│       └── whatsapp-floating.js       # Funcionalidades JavaScript
├── layouts/
│   └── parts/
│       └── whatsapp-floating-button.php # Template do botão
├── translations/                       # Arquivos de tradução
│   ├── README.md                      # Documentação das traduções
│   ├── whatsapp-floating.pot          # Template de tradução
│   ├── pt_BR.po                       # Português (Brasil)
│   ├── es_ES.po                       # Espanhol (Espanha)
│   ├── es_AR.po                       # Espanhol (Argentina)
│   └── en_US.po                       # Inglês (Estados Unidos)
└── components/
    └── whatsapp-floating/              # Componente (reservado para futuro)

Customização

Modificando o Visual

Para personalizar o visual do botão, edite o arquivo assets/css/whatsapp-floating.css:

/* Mudar cor do botão */
.whatsapp-floating__button {
    background-color: #075e54; /* Verde mais escuro */
}

/* Mudar posição */
.whatsapp-floating {
    bottom: 30px; /* Mais distante da borda */
    left: 20px;   /* Lado esquerdo ao invés do direito */
}

/* Mudar tamanho */
.whatsapp-floating__button {
    width: 70px;
    height: 70px;
}

Modificando o Comportamento

Para alterar funcionalidades, edite assets/js/whatsapp-floating.js:

// Exemplo: esconder botão durante scroll
function handleScrollBehavior() {
    // Descomentar a chamada no final do arquivo
}

Solução de Problemas

O botão não aparece

1. Verifique se WHATSAPP_ENABLED=true
2. Confirme se WHATSAPP_NUMBER está configurado
3. Reinicie a aplicação após alterar as variáveis
4. Verifique o console do navegador por erros JavaScript

O WhatsApp não abre

1. Confirme o formato do número (apenas dígitos com código do país)
2. Teste o número em outro serviço WhatsApp
3. Verifique se o navegador permite pop-ups

Conflito com outros plugins

1. Verifique o z-index do CSS (padrão: 9999)
2. Analise conflitos de JavaScript no console
3. Teste desabilitando outros plugins temporariamente

Compatibilidade

• Mapas Culturais: v6.0+
• PHP: 7.4+
• Navegadores: Chrome, Firefox, Safari, Edge (últimas 2 versões)
• Dispositivos: Desktop, Tablet, Mobile

Contribuição

Para contribuir com o plugin:

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

Licença

Este plugin é distribuído sob a licença do projeto Mapas Culturais.

Suporte

Para suporte e dúvidas:

1. Abra uma issue no repositório do projeto
2. Consulte a documentação do Mapas Culturais
3. Entre em contato com a equipe de desenvolvimento

---

Desenvolvido para Mapas Culturais 🗺️