Modelos do Url Composer

Componente de tema
1

Componente bem especializado para o meu site, mas vou compartilhar aqui, pois pode ser útil. Ele adiciona um modelo (template) ao composer com base em uma string na URL.

Houve muitas discussões sobre ter modelos de composer para tags. Isso não funcionou no meu caso de uso, então construí isto em vez disso. Pode ser usado em uma emergência ou modificado ligeiramente para funcionar também para tags.

Github: GitHub - focallocal/url-composer-templates: Reads url strings and adds template text to the composer if a match is found

Modelos de Composer de URL (URL Composer Templates)

Um componente de tema do Discourse que preenche previamente o composer com texto de modelo baseado em parâmetros de URL. Projetado para funcionar perfeitamente com o Docuss para fornecer modelos específicos de contexto para diferentes tipos de interações.

Funcionalidades

  • Suporte a Parâmetros de URL: Detecta automaticamente ?composer_template=X em URLs e aplica o modelo correspondente
  • Múltiplos Tipos de Modelo: Configure até 6 modelos diferentes para diferentes propósitos (relatório, presença, convite, modelos personalizados)
  • Abrir Composer Automaticamente: Opcionalmente, abre o composer automaticamente ao visitar um link do Docuss sem tópicos existentes
  • Aplicação Flexível: Modelos podem ser aplicados apenas à primeira postagem, a todas as respostas ou a ambos
  • Persistência de Sessão: Usa sessionStorage para manter a seleção do modelo entre as navegações de página
  • Modo de Depuração (Debug Mode): Ativa o registro detalhado no console para solucionar a aplicação do modelo

Instalação

  1. Instale o componente de tema no Discourse:

    • Vá para Admin → Personalizar (Customize) → Temas (Themes)
    • Clique em “Instalar” (Install) → “De um repositório Git” (From a Git repository)
    • Insira: https://github.com/focallocal/url-composer-templates
    • Adicione o componente ao seu tema ativo

  2. Nenhuma reconstrução de plugin necessária! O suporte ao parâmetro composer_template já existe no dcs-discourse-plugin e no dcs-client.

  3. Implante seu aplicativo React (fl-maps) com os componentes DCSLink atualizados que passam a propriedade composerTemplate.

  4. Configure os modelos nas configurações do componente (Admin → Personalizar → Temas → seu tema → url-composer-templates → Configurações).

Configuração

Configurações de Modelo (Template Settings)

Cada modelo tem três opções de configuração:

Modelo 1 (Relatório)

  • template_1_id: report - O valor do parâmetro de URL para acionar este modelo
  • template_1_text: O texto para preenchimento prévio no composer
  • template_1_use_for: first_post - Aplicar somente ao criar novos tópicos

Modelo 2 (Presença)

  • template_2_id: going - Para interações do tipo “Eu vou”
  • template_2_text: Texto preenchido previamente para confirmações de presença
  • template_2_use_for: all_replies - Aplicar a todas as respostas (não à primeira postagem)

Modelo 3 (Convite)

  • template_3_id: invite - Para interações de convite
  • template_3_text: Texto preenchido previamente para convites
  • template_3_use_for: all_replies - Aplicar a todas as respostas

Modelos 4-6 (Personalizados)

  • Desativados por padrão
  • Podem ser ativados e personalizados para casos de uso específicos
  • Configure ID, texto e escopo de aplicação conforme necessário

Configurações de Abertura Automática (Auto-Open Settings)

  • enable_auto_open_composer: true - Quando ativado, abre automaticamente o composer se:
    • Um link do Docuss for clicado (URL contém ?composer_template=X)
    • Nenhum tópico existir ainda para aquela combinação de tags
    • Ajuda os usuários a iniciar discussões imediatamente

Modo de Depuração (Debug Mode)

  • debug_mode: false - Ative para ver logs detalhados no console com prefixos de emoji:
    • :artist_palette: Logs de aplicação de modelo
    • :rocket: Logs de abertura automática do composer

Integração Docuss

Integração Automática

O componente url-composer-templates é projetado para funcionar automaticamente com o Docuss. Quando você tem ambos:

  • Este componente instalado na sua instância do Discourse
  • O cliente e plugin Docuss atualizados (com suporte a composer_template)

Os modelos serão aplicados automaticamente com base em:

  1. Modo de Interação (Interact Mode):
    • Modo DISCUSS → Usa dicas de triggerId (presença, convite) ou o padrão report
    • Modo COMMENT → Usa o modelo report

Modelos Personalizados via Atributos HTML

Para um controle mais preciso, você pode especificar modelos diretamente no seu HTML usando o atributo data-dcs-composer-template:

<!-- Exemplo: Botão de Relatório -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="issue-report"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="report">
  Relatar um Problema
</div>

<!-- Exemplo: Botão de Presença -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="event-rsvp"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="going">
  Eu Vou!
</div>

<!-- Exemplo: Botão de Convite -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="invite-friends"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="invite">
  Convidar Amigos
</div>

<!-- Exemplo: Modelo Personalizado -->
<div class="dcs-trigger" 
     data-dcs-trigger-id="feedback"
     data-dcs-interact-mode="DISCUSS"
     data-dcs-composer-template="custom1">
  Dar Feedback
</div>

Correspondência de ID de Modelo (Template ID Matching)

O componente corresponde aos IDs de modelo do parâmetro de URL com os IDs de modelo configurados:

Parâmetro de URL Configuração do Modelo Propósito Padrão
?composer_template=report template_1_id Relatórios de bugs, problemas
?composer_template=going template_2_id Confirmações de presença em eventos
?composer_template=invite template_3_id Convites
?composer_template=custom1 template_4_id Uso personalizado
?composer_template=custom2 template_5_id Uso personalizado
?composer_template=custom3 template_6_id Uso personalizado

Como Funciona

Fluxo de Aplicação do Modelo

  1. Detecção de URL: Quando um usuário navega para uma URL com ?composer_template=X, o componente armazena o ID do modelo no sessionStorage
  2. Intercepção do Composer: Quando o composer abre, o componente verifica se há um ID de modelo armazenado
  3. Correspondência de Modelo: Encontra o modelo correspondente com base no ID
  4. Validação de Escopo: Verifica se o modelo deve ser aplicado (primeira postagem, resposta ou ambos)
  5. Inserção de Texto: Preenche previamente o composer com o texto do modelo
  6. Limpeza: Marca o modelo como aplicado para evitar reaplicação

Fluxo de Abertura Automática

  1. Detecção de Parâmetro: Verifica se a URL contém ?composer_template=X e se a abertura automática está ativada
  2. Busca de Tópico: Procura por tópicos existentes com a combinação de tags atual
  3. Abertura do Composer: Se nenhum tópico for encontrado, abre o composer automaticamente
  4. Aplicação do Modelo: O modelo é então aplicado através do fluxo normal acima

Casos de Uso de Exemplo

Site de Evento

# settings.yml
template_2_id: "going"
template_2_text: "Estou planejando comparecer! 🎉\n\nAnsioso para ver todos lá."
template_2_use_for: "all_replies"

template_3_id: "invite"
template_3_text: "Gostaria de convidar amigos para este evento.\n\nQuem estou convidando:\n- \n\nPor que eles deveriam vir:\n"
template_3_use_for: "first_post"

Rastreamento de Problemas

template_1_id: "bug"
template_1_text: "**Descrição do Bug:**\n\n**Passos para Reproduzir:**\n1. \n2. \n3. \n\n**Comportamento Esperado:**\n\n**Comportamento Atual:**\n"
template_1_use_for: "first_post"

template_4_enabled: true
template_4_id: "feature"
template_4_text: "**Solicitação de Recurso:**\n\n**Caso de Uso:**\n\n**Solução Proposta:**\n"
template_4_use_for: "first_post"

Engajamento Comunitário

template_1_id: "question"
template_1_text: "**Minha Pergunta:**\n\n**O que eu Tentei:**\n\n**Contexto Adicional:**\n"
template_1_use_for: "first_post"

template_2_id: "answer"
template_2_text: "Isto foi o que funcionou para mim:\n\n**Solução:**\n\n**Por que funciona:**\n"
template_2_use_for: "all_replies"

Solução de Problemas (Troubleshooting)

Modelos Não Estão Sendo Aplicados

  1. Verifique o Parâmetro de URL: Certifique-se de que a URL contenha ?composer_template=X, onde X corresponde a um ID de modelo
  2. Ative o Modo de Depuração: Ligue o debug_mode nas configurações para ver os logs do console
  3. Verifique o Escopo do Modelo: Verifique se a configuração use_for corresponde à sua ação (criação de tópico vs resposta)
  4. Limpe o SessionStorage: Abra o console do navegador e execute: sessionStorage.clear()

Abertura Automática Não Está Funcionando

  1. Verifique a Configuração: Certifique-se de que enable_auto_open_composer esteja definido como true
  2. Verifique a URL: A abertura automática só funciona quando a URL contém ?composer_template=X
  3. Verifique Tópicos Existentes: A abertura automática só é acionada quando NÃO existem tópicos com a combinação de tags
  4. Ative o Modo de Depuração: Procure por logs com o emoji :rocket: no console

Modelo Errado Sendo Aplicado

  1. Verifique os IDs de Modelo: Certifique-se de que seu parâmetro de URL corresponda exatamente ao ID do modelo (sensível a maiúsculas e minúsculas)
  2. Verifique a Prioridade: Se vários modelos puderem corresponder, o primeiro modelo correspondente é usado
  3. Limpe a Sessão: O SessionStorage pode conter valores antigos: sessionStorage.clear()

Problemas de Integração Docuss

  1. Atualize o Docuss: Certifique-se de ter as versões mais recentes de:
    • dcs-client (com suporte a composerTemplate em HtmlBased.js)
    • dcs-discourse-plugin (com geração de parâmetros de URL em DcsIFrame.js.es6)
  2. Verifique os Atributos HTML: Verifique se data-dcs-composer-template está definido corretamente nos acionadores (triggers)
  3. Inspecione a Rede: Verifique a aba Rede (Network) das Ferramentas do Desenvolvedor do navegador para ver se os parâmetros de URL estão sendo adicionados

Histórico de Versões

v1.0.0 (Atual)

  • Lançamento inicial
  • Suporte para 6 modelos configuráveis
  • Seleção de modelo baseada em parâmetro de URL
  • Abertura automática do composer para links Docuss
  • Persistência de SessionStorage
  • Modo de depuração para solução de problemas

Contribuição

Encontrou um bug ou tem uma solicitação de recurso? Por favor, abra uma issue no repositório do GitHub.

Licença

Este componente é de código aberto e está disponível sob a Licença MIT.

Créditos

Desenvolvido por Andy@Focallocal para uso com Docuss - um sistema para incorporar discussões do Discourse em qualquer site.