Guia do usuário do MultiDatePick

1. Os três componentes: quando usar cada um

O MultiDatePick traz três Lightning Web Components sobre uma mesma base. Escolha o que combina com os seus dados.

Comparação de recursos

Os recursos se somam. Tudo o que o Date tem, o Date Time e o Booking também têm. O Date Time acrescenta horários. O Booking acrescenta recursos e capacidade.

2. Formatos de registro: quando usar cada um

O formato de registro define como uma seleção vira registros. Ele sai de três escolhas independentes, e todas as combinações funcionam.

O Assistente de Configuração dá nome a seis formatos: um registro por data, um por intervalo de datas, um por bloco de horário, pai mais sub-blocos, recurso único e vários recursos.

Exemplos práticos: responda às 3 perguntas

Responda a três perguntas por cenário e você chega ao formato. O Assistente de Configuração faz as mesmas três.

A grade: todas as combinações

Escolha a linha conforme a sua necessidade de horário e recurso. A coluna depende de o End Date Field API Name estar definido ou não. Todas as células são configurações válidas.

Resumindo: qualquer combinação das três escolhas funciona. Se o seu cenário não tem nome na lista, defina cada escolha separadamente e o componente faz o resto.

3. Passo a passo do Assistente de Configuração

O Assistente de Configuração salva uma configuração uma única vez. Digite o nome dela no Config Name de qualquer página ou tela de fluxo e pronto: aquele local passa a usá-la. Altere a configuração e todos os locais acompanham.

1. 1 Nome & Tipo
2. 2 Objeto & Campos
3. 3 Campos de Tempo
4. 4 Status & Exibição
5. 5 Revisar & Salvar

Escolha por onde começar

A aba Criar Nova oferece dois caminhos. Me guie pelo processo faz três perguntas e escolhe o componente e o formato. Configurar todas as propriedades abre todas as opções. Ao lado há mais duas abas: Configurações Existentes, para editar uma configuração salva, e Importar, para colar uma da Config Library.

Etapa 1: Nome & Tipo

Escolha o componente (Date, Date Time ou Booking) e dê um nome à configuração. É esse nome que você digita depois no Config Name. Esta etapa também define as visualizações: a padrão, quais o seletor oferece e as opções de Linha do tempo e Agenda.

Etapa 2: Objeto & Campos

A etapa principal. Escolha o objeto que guarda os registros, o campo de data dele e o campo de relacionamento com o registro pai. Campos opcionais acrescentam intervalos, recursos, capacidade, sub-blocos e datas bloqueadas. Nas configurações de Booking, o objeto de recurso, o campo de capacidade e o horário comercial também ficam aqui.

Etapa 3: Campos de Tempo

Só Date Time e Booking. Mapeie os campos de hora inicial e final e depois defina o Intervalo de Horário (qualquer intervalo funciona; 15, 30 ou 60 minutos são os mais comuns), a hora mais cedo e a mais tarde, o modo de exibição e o que acontece em caso de conflito.

Etapa 4: Status & Exibição

Campo de status e cores, status a ocultar, status que os usuários podem escolher, campos ao passar o mouse, modo de edição, nome dos registros, rótulos dos botões, tamanho do calendário e limites como Max Dates Allowed (Máximo de Seleções).

Etapa 5: Revisar & Salvar

Confira o resumo, teste a visualização ao vivo e clique em Salvar Configuração. O assistente implanta a configuração para você em 30 a 60 segundos. No fim, se quiser, adicione uma descrição.

Configurações Existentes e Importar

As configurações salvas aparecem em Configurações Existentes: clique em uma para editar ou exportar. A aba Importar aceita o JSON de qualquer cartão da Config Library ou uma exportação de outra organização.

4. Conjuntos de permissões e acesso

O pacote traz quatro conjuntos de permissões. Atribua-os em Configuração, Conjuntos de permissões.

Os componentes rodam com as permissões de cada usuário, então os usuários também precisam de acesso aos seus objetos e campos:

• Objetos: Ler e Criar no objeto em que os registros são salvos, mais Ler em qualquer objeto de recurso, fechamento ou filho que o calendário lê.
• Campos, leitura: todo campo que o calendário mostra (data, status, campos ao passar o mouse).
• Campos, edição: todo campo que ele grava (data, horários, status, segunda lista de opções, campo de nome, o lookup para o registro pai). Um campo que o usuário não pode editar faz o salvamento falhar, mesmo que a leitura funcione.
• Registros referenciados: pelo menos Ler no registro pai e no recurso para os quais o novo registro aponta.

Cada mensagem de erro e sua causa estão em Solução de problemas: erros de acesso. Sites para convidados precisam de alguns passos extras: veja Páginas públicas para convidados.

5. Salvar com clique vs. salvar pelo fluxo

Há duas formas de salvar. Escolha a que combina com o local de uso.

Salvar com clique: as quatro configurações

O Assistente de Configuração preenche estas. Quando as quatro têm valor, o botão Salvar aparece.

Qual registro pai uma página usa, e quando é melhor escolhê-lo em um fluxo, está explicado em Páginas de aplicativo, iniciais e do Experience Cloud.

Salvar pelo fluxo: as saídas

Deixe as quatro configurações em branco. O botão Salvar some e a seleção sai por estas saídas do fluxo:

Passe o JSON para Parse Date Entries from JSON. Ela retorna uma lista que você pode percorrer em um Loop, com data inicial, data final, hora inicial, hora final e Id do recurso em cada item. Passo a passo: Receitas de fluxo.

Salvar só adiciona

O salvamento por clique só cria registros novos. Desmarcar uma data nunca exclui um registro salvo, então um clique errado não apaga dados. Para alterar ou remover registros, use o modo de edição ou a lista relacionada.

6. Cores de status e modo de edição

Cores de status e filtros

Dê cor aos registros com base em qualquer lista de opções do seu objeto, oculte alguns valores e limite o que os usuários finais podem escolher.

Modo de edição

Ative Enable Edit Mode (Ativar Modo de Edição) e aparece o botão Editar. No modo de edição, os usuários podem:

• Ver os registros existentes como cartões com data e status
• Clicar em datas para incluir os registros delas na edição
• Alterar data, horários, recurso ou status, e o registro é atualizado
• Excluir com confirmação em dois cliques, para nada sumir por acidente

7. Visualizações: cinco layouts, um componente

Todo componente desenha cinco layouts. Eles leem os mesmos registros pelos mesmos mapeamentos de campos, seguem as mesmas regras de conflito, datas bloqueadas e horário comercial, e salvam do mesmo jeito. Trocar de visualização muda a aparência dos registros, nunca o que eles significam.

As cinco, e a pergunta que cada uma responde

Configurações

Uma visualização diferente por página

A visualização é uma configuração de cada local de uso, então os mesmos registros podem aparecer de jeitos diferentes em cada lugar. Uma instalação, um conjunto de mapeamentos de campos.

O modo de edição funciona em todas as visualizações

Com Enable Edit Mode ativado, o botão de edição aparece em todas as visualizações. Clique em um registro na Linha do tempo, na Semana ou na Agenda para incluí-lo na edição, como faria com uma data no calendário mensal. Uma alteração de status em massa pela Linha do tempo funciona igual à feita pelo calendário.

Linha do tempo: linhas recolhidas

Quando um recurso tem reservas sobrepostas, a linha dele se recolhe em uma única faixa com um selo N ao mesmo tempo. Um botão de expandir abre uma faixa por reserva. Linhas recolhidas continuam aceitando arrastar, passar o mouse e clicar.

Linha do tempo: arraste para reagendar

Com Enable Edit Mode ativado, as barras da Linha do tempo podem ser arrastadas. Pegue pelo meio para mover uma reserva para outros dias. Pegue por uma borda para mudar o início ou o fim. A barra mostra onde vai cair e salva quando você solta. No zoom Dia, os mesmos gestos mudam os horários.

Agende pessoas, não só salas

Resource Object API Name (Objeto de Recurso) aceita qualquer objeto. Defina como User e a Linha do tempo vira uma escala de equipe, a Semana uma grade de turnos e a Ocupação um painel de capacidade da equipe.

• O User não tem campo de capacidade padrão. Crie um personalizado (por exemplo Daily Capacity) para ver a Ocupação em porcentagens.
• Mapeie Business Hours Start Field (Campo de Início do Horário Comercial) e Business Hours End Field (Campo de Fim do Horário Comercial) para campos do User e a grade da Semana segue o horário de cada pessoa.

A Config Library tem dois exemplos prontos: Planejamento de Capacidade da Equipe e Escala de Turnos da Equipe.

8. Reserva de recursos e capacidade (componente Booking)

Recurso único

Os usuários escolhem um recurso em uma lista suspensa. A grade de horários carrega as reservas e a capacidade desse recurso.

Vários recursos

Ative Allow Multiple Resources (Permitir Vários Recursos) e a lista suspensa vira caixas de seleção. A grade mostra só os horários livres em todos os recursos marcados, e o Salvar reserva todos de uma vez.

Capacidade

Permita que várias reservas dividam um horário, com selos 3/5 ao vivo. Um horário lotado para de aceitar reservas.

Conflitos

Conflict Behavior (Comportamento de Conflito) define o que acontece quando um horário escolhido já está ocupado. Conflict Look-Ahead Days (Dias de Antecedência para Conflitos) define até quantos dias à frente verificar (padrão 360).

Um fechamento sempre prevalece. Nada é salvo em um horário bloqueado, nem com Permitir.

9. Limitar o que os usuários selecionam

Limite quanto uma pessoa pode escolher, por datas ou por horários.

10. Bloquear datas, horários e recursos (fechamentos)

Qualquer calendário pode ler fechamentos de outro objeto e deixar em cinza as datas, horários ou recursos que eles cobrem, para que os usuários só reservem quando você está aberto. Aponte algumas configurações para o objeto de fechamentos e o componente faz o resto. Bloqueios de dia inteiro funcionam nos três componentes. Bloqueios de horário e de recurso precisam da grade de horários do Date Time ou do Booking.

Bloquear vs. ocultar: qual é a diferença?

Parecem iguais, mas fazem o oposto. Bloquear tira disponibilidade: o horário aparece, mas não pode ser reservado. Ocultar tira registros da tela, o que libera os horários deles.

As configurações de datas bloqueadas

Três níveis de bloqueio

1. Dia inteiro: um fechamento sem horários deixa a data inteira em cinza. Nos três componentes. Uma data fechada continua fechada mesmo que já tenha reservas.
2. Parte do dia: um fechamento com hora inicial e final bloqueia só aqueles horários. O resto do dia continua disponível. Os horários bloqueados aparecem quando uma data é selecionada.
3. Um recurso: um fechamento que aponta para um recurso fecha só esse recurso. Na visualização de um recurso, o horário aparece riscado. Na visualização combinada, ganha uma pequena marca no canto e continua disponível nos recursos abertos.

Usa a grade de horários? Então você quer bloqueios de parte do dia. Bloqueios de dia inteiro combinam com seletores só de data.

Dois modelos para o objeto de fechamentos

• O mesmo objeto, marcado por status: aponte o Blocked Dates Object para o seu objeto de reservas e filtre Status = Cancelled, assim as reservas canceladas também funcionam como fechamentos. É o mais simples, mas todos os calendários desse objeto os compartilham. Veja a configuração Agendamento de Atendimentos com Feriados na Config Library.
• Um objeto só para fechamentos: um objeto Office Closure com data, hora inicial e final opcionais, um campo Region e um lookup opcional para recurso. Cada calendário filtra pela sua região, e um fechamento pode valer para um único recurso. Veja a configuração Fechamentos de Recursos por Horário.

Para que as pessoas bloqueiem o próprio horário (um responsável bloqueando uma manhã, por exemplo), coloque um componente Date Time que salva no objeto de fechamentos em uma página ou site interno.

Como os horários bloqueados se comportam

• Aparência: um horário totalmente fechado aparece riscado e em cinza. Um horário fechado só para alguns dos recursos escolhidos ganha uma marca no canto.
• Seleção: um horário totalmente fechado não aceita clique nem arrasto.
• Salvar: nada é salvo em um recurso, data e horário fechados. Com vários recursos, só o fechado fica de fora; os abertos são reservados normalmente.

Uma tabela de fechamentos, vários calendários

Dê ao objeto de fechamentos um campo de etiqueta (Region, Location, Building) e coloque o mesmo campo nos seus recursos. Cada calendário então usa Resource Filter Field / Value para mostrar os próprios recursos e Blocked Dates Filter Field / Value para ler os próprios fechamentos.

11. Páginas públicas para convidados (Experience Cloud)

Coloque um componente em um site do Experience Cloud e qualquer pessoa pode reservar sem fazer login. Conclua os cinco passos antes de testar como convidado.

1. Permissões de objeto. Dê ao usuário convidado do site Ler, mais Criar se os convidados enviam dados, em cada objeto. O Salesforce nunca deixa convidados editarem ou excluírem registros, então mantenha as páginas de edição, cancelamento e exclusão para usuários logados.
2. Segurança em nível de campo em todo campo que o componente usa, inclusive os campos de horário comercial do recurso e os campos de hora dos fechamentos. Um único campo faltando derruba a consulta de recursos ou de fechamentos.
3. Uma regra de compartilhamento para convidados (Ler) para que o convidado veja os registros. O padrão externo para toda a organização do objeto precisa ser Privado para a regra valer. Uma regra implantada como metadados precisa de um clique em Recalcular em Configuração, Configurações de compartilhamento.
4. O conjunto de permissões MultiDatePick - Guest no usuário convidado do site. Ele dá o acesso às classes Apex pelas quais o componente carrega os dados.
5. Ative o site. Publicar e ativar são passos separados.

• Qual registro os convidados veem: uma página pública usa o Static Parent Record Id, então todos os convidados reservam no mesmo registro pai (um escritório, local ou recurso). Para um registro por visitante, use um fluxo com um parâmetro de URL. Calendários realmente individuais exigem usuários logados.
• Contatos e contas: o Salesforce restringe muito o acesso de convidados a eles. Faça as reservas de convidados em um objeto personalizado ou use um site autenticado.
• Vários componentes na mesma página: eles não se sincronizam em tempo real. Inclua um aviso para atualizar entre eles, para que um bloqueio feito em um apareça no seguinte.

Os passos para colocar o componente estão em Páginas de aplicativo, iniciais e do Experience Cloud. Um site completo de exemplo está em Reservas no Experience Cloud.

12. Armadilhas comuns (perguntas frequentes)

Apareceu um aviso, sumiu o botão Salvar ou o calendário está vazio? A Solução de problemas mostra cada mensagem com uma captura de tela e a correção.

As cores de status não estão sendo aplicadas

Verifique três coisas. (a) O Status Field (Campo de Status) é exatamente o nome de API da lista de opções? Ele diferencia maiúsculas de minúsculas. (b) O Status Colors (Cores de Status de Reserva) usa o formato Value:#hex, Value:#hex, sem aspas? 'Confirmed':'#22C55E' quebra tudo sem aviso. (c) Os registros têm mesmo um valor nessa lista de opções?

Os registros são salvos com nomes inesperados

Verifique o Record Name Field (Campo de Nome do Registro): se o campo é curto, nomes longos são cortados. Verifique o Append Date to Record Name (Anexar DateTime ao Nome): quando ativado, a data e o horário selecionados são acrescentados a todos os nomes.

Como oculto registros Cancelled da grade de capacidade?

Defina Ignored Statuses como Cancelled, ou uma lista como Cancelled,Rejected. Eles saem do calendário e da contagem de capacidade.

Qual é a diferença entre bloquear e ocultar?

Bloquear (fechamentos) mantém uma data, horário ou recurso visível, mas sem permitir reserva: feriados, manutenção, uma sala fechada. Ocultar tira registros como os Cancelled do calendário e da capacidade, o que libera o horário. Veja Bloquear vs. ocultar.

O botão de edição não aparece

Ative Enable Edit Mode. É o único requisito, nos três componentes. O Status Field é opcional; ele só acrescenta uma lista de status no editor. Se o botão continuar sumido, a página ou a configuração está com Enable Edit Mode desativado.

Quero só alguns recursos (salas, não equipamentos)

Use Resource Filter Field (Campo de Filtro de Recurso) e Resource Filter Value (Valor do Filtro de Recurso). Um valor: campo Active__c, valor true. Vários valores (OU): North,South. Vários campos (E): campo Type__c;Active__c, valor Conference Room;true.

O Date Time insiste em mostrar um único seletor de horário compartilhado

A configuração certa é o Time Display Mode (Modo de Exibição de Horário): Grade ou Dropdown. No modo Grade, todas as datas compartilham a grade. Para um horário diferente por data, escolha Dropdown e ative Allow Different Times Per Date (Permitir Horários Diferentes).

Como passo do salvamento pelo fluxo para o salvamento com clique?

Preencha Parent Record Id, Child Object API Name, Date Field API Name e Relationship Field API Name. Remova a ação Parse Date Entries from JSON e o loop que criava os registros. Agora o próprio botão Salvar do componente os grava.

Aparece uma notificação de erro sem detalhes

Abra o console de desenvolvedor do navegador e procure linhas que começam com [MDP:ERROR]. O erro completo sempre fica registrado lá, mesmo quando a notificação é curta.

13. Receitas de fluxo

Tudo aqui é feito no Flow Builder. Sem Apex.

Percorrer as datas selecionadas em um loop

1. Adicione uma Tela com o componente Date Time. Deixe em branco as configurações do salvamento com clique.
2. Depois da tela, adicione a ação Parse Date Entries from JSON. Passe para ela o Dates With Times JSON (Output).
3. Percorra em um loop a lista da ação. Cada item tem data inicial, data final, hora inicial e hora final.
4. Dentro do loop, atribua os valores a uma variável de registro e adicione-a a uma coleção. Crie os registros uma única vez, depois do loop.

Levar a primeira e a última data para o registro pai

Quer que o registro pai mostre a data mais antiga e a mais recente dos filhos? Escolha o caminho sem código que combina com os seus dados.

Mais modelos de fluxo: Guia de fluxo de tela.

14. Mapeamento de objetos e campos

Cada página de componente tem um diagrama completo de mapeamento de objetos e campos:

• Date: mapeamento de objetos
• Date Time: mapeamento de objetos
• Booking: mapeamento de objetos

Os componentes funcionam com qualquer objeto. Os objetos de exemplo do pacote (Schedule, Event, Resource, Sub Block) são só o padrão. Aponte as configurações para os seus próprios objetos, personalizados ou padrão, com os campos certos.

15. Referência de todas as propriedades

Todas as configurações dos três componentes, pelo rótulo que você vê no Lightning App Builder, no Experience Builder e no Flow Builder. O nome de API fica embaixo de cada rótulo.

16. Segurança e acessibilidade

• Aprovado no Security Review do Salesforce AppExchange.
• 100% nativo. Seus dados ficam na sua organização Salesforce. Sem servidores externos, sem callouts. Veja Confiança e segurança.
• Sempre com as suas permissões. Cada leitura e cada salvamento rodam com o acesso do próprio usuário, então permissões de objeto, segurança em nível de campo e compartilhamento valem em cada registro.
• Acessível. WCAG 2.1 AA, testado com axe-core. VPAT 2.5 completo.
• 9 idiomas: inglês, espanhol, francês, alemão, japonês, hindi, português (Brasil), italiano e chinês (simplificado).

17. Dúvidas ou bugs?

Encontrou uma lacuna neste guia ou algo quebrado? Escreva para support@multidatepick.com.