Actions

No Nerdify, o método action permite declarar as ações que um modelo pode executar ou sofrer, criando a base para a geração automática de rotas, elementos do frontend, componentes visuais, e lógicas no controlador.

Cada action se conecta ao sistema inteiro do Nerdify: gera rotas RESTful ou personalizadas, aparece automaticamente nos templates como botões e ações interativas, e pode ter sua visibilidade controlada via condições inteligentes.

📦 As definições de actions são feitas diretamente no modelo, fora de blocos, apenas com chamadas a action :nome, opções....

---

🧠 O que acontece ao declarar uma action

Ao declarar uma action, o Nerdify automaticamente:

• Cria a rota correspondente (RESTful ou personalizada)
• Gera a action nos controladores (por meio dos controladores dinâmicos)
• Disponibiliza a ação para os templates, que podem interpretá-la para montar botões, menus e interações
• Permite acessar a definição via Model.nerdify.actions (como array de OpenStruct) para lógica condicional ou inspeção

Essas ações são utilizadas pelos templates em botões e menus com condicionais como:

• backend_if: → executado no backend com model, object, current_user, current_ability, etc.
• render_if: → condição avaliada no frontend. Se falsa, o botão nem é renderizado.
• show_if: → também é avaliada no frontend, mas apenas esconde o botão com hidden, mantendo o DOM.

🔗 Enquanto backend_if utiliza uma string que representa código ruby e tem acesso a recursos que existem no controlador, como object, model, params, entre outros, o render_if e show_if geram código na sintaxe javascript para o frontend usando dados que estão presentes na resposta json que monta a página com placeholeders, por exemplo, resource.id == page.resources.current_user.id

---

✍️ Exemplo

action :edit, only: %w[show], backend_if: "can?(:edit, object)", position: :header

action :create, on: :collection, layout: :default, click: {
  redirect_to: "/customers/new",
  params: { origem: "cadastro_interno" }
},
submit: {
  post: "/api/v1/customers",
  data: { customer: ":resource" },
  success: {
    toast: :success,
    update: "resources",
    close: :dialog
  },
  error: {
    toast: :error
  }
}
action :index, lists: %w[table kanban calendar], default_list: :table

Você pode acessar as actions em tempo de execução:

Customer.nerdify.actions.first.name
#=> "create"
Customer.nerdify.actions.first.on
#=> :collection
Customer.nerdify.actions.first.click.redirect_to
#=> "/customers/new"

💡 Você pode passar qualquer parâmetro extra na action e acessar posteriormente via Customer.nerdify.actions.

---

🛠️ Parâmetros da action

Parâmetro	Tipo	Descrição
on	:member ou :collection	Determina se a ação se refere a um item ou à coleção geral
only	Array<String>	Define em quais actions do template a ação deve aparecer (ex: %w[show index])
backend_if	String, Symbol	Condição avaliada no backend (can?(:edit, object), etc.)
render_if	String, Symbol	Condição avaliada no frontend. Se falsa, não renderiza
show_if	String, Symbol	Alias de render_if, mas apenas oculta com hidden
position	Symbol, String	Local onde a action será exibida no template (ex: :header, :footer, :inline ou :dropdown). As opções inline e dropdown fazem a action aparecer dentro de um item da listagem
layout	Symbol, String	Layout da página gerada pela action (:default, :modal, :embed)
click	Hash	Define o comportamento ao clicar (detalhado abaixo)
submit	Hash	Define o comportamento ao submeter um formulário (detalhado abaixo)
lists	Array<String>	Define quais listas (visualizações) essa action exibe quando usada
default_list	Symbol, String	Define a visualização padrão da lista
styles	Hash	Define estilos visuais como cores, bordas etc. Veja mais detalhes na documentação de componentes

---

🖱️ Parâmetros de click e submit

Tanto click quanto submit suportam os mesmos parâmetros. A diferença é que click ocorre no clique do botão, enquanto submit é executado no envio de um formulário. Por exemplo, em uma action new o click será executado quando clicar em um botão ou link que manda para a tela de cadastro, enquanto submit vai ser executado já na tela de cadastro quando o formulário for enviado. Você pode inclusive em uma action que fica dentro do formulário mas não é a padrão, usar click: { submit: "id_form" } para forçar um clique a disparar um submit manualmente.

Chave	Tipo	Descrição
get	String, Symbol	Rota para requisição GET. Pode conter placeholders :resource, :page, :resources, etc.
post	String, Symbol	Rota para POST. Pode conter placeholders :resource, :page, :resources, etc.
put	String, Symbol	Rota para PUT. Pode conter placeholders :resource, :page, :resources, etc.
delete	String, Symbol	Rota para DELETE. Pode conter placeholders :resource, :page, :resources, etc.
redirect_to	String, Symbol	Redirecionamento no frontend após o clique. Pode conter placeholders :resource, :page, :resources, etc.
open_in	Symbol, String	Onde abrir a resposta (:default, :dialog, :embed)
params	Hash	Parâmetros a serem enviados na rota. Pode conter placeholders como ":page.options.controller", ":resource.id"
data	Hash	Corpo enviado no post/put/delete. Pode conter placeholders como ":page.options.controller", ":resource.id". Ex: { customer: ":resource" }
submit	String, Symbol	ID do formulário que será submetido
confirm	Boolean	Exige confirmação antes de executar
success	Hash	Ações em caso de sucesso (detalhado abaixo)
error	Hash	Ações em caso de erro (detalhado abaixo)

✅ Ações em success e error

Chave	Tipo	Descrição
toast	Symbol, String	Mostra notificação (ex: :success, :error)
close	Symbol, String	Fecha interface (ex: :dialog)
update	String	Dispara evento(s) separados por vírgula. Ex: "resources,refresh". Pode combinar com path: para atualização específica
path	String	Usado para determinar onde o evento update deve ser executado. É um valor opcional para ser usado quando tem embeds e modais em conjunto com a página, para diferencia em qual o evento deve ser chamado.

---

🔄 Eventos possíveis em update

Evento	Descrição
closeDialog	Fecha o modal/dialogo aberto
detectChanges	Força o frontend a reprocessar mudanças de estado
refresh	Recarrega o backend completo para atualizar a página inteira
resource	Atualiza um resource específico a partir da resposta json
resources	Atualiza todos os resources da página a partir da resposta json
filters	Atualiza os filtros a partir da resposta json
sort	Atualiza a ordenação
paginate	Atualiza a página (com base em params[:page])
components	Atualiza os componentes da página a partir da resposta json

Você pode atualizar a página atual ou um embed/modal específico adicionando o parâmetro path: junto ao evento no update. Exemplo:

update: "resources", path: "/customers/:resources.current_user.id"

---

📎 Consultando as actions

Você pode consultar todas as actions definidas em tempo de execução com:

Customer.nerdify.actions

Isso retorna um array de OpenStruct com todos os parâmetros da action:

action = Customer.nerdify.actions.first

puts action.name                  # => "edit"
puts action.options[:on]          # => :member
puts action.options[:click]       # => { redirect_to: ..., params: ... }

As actions são o elo entre modelo, template, controlador e frontend — definindo comportamento, acesso e estrutura de forma automatizada e elegante no Nerdify. ✅