Estendendo o Rebase

Visão Geral

O Rebase oferece cerca de uma dúzia de mecanismos de extensão — plugins, slots, substituições de componentes, visualizações de entidade, ações, campos personalizados e muito mais. Cada um visa um escopo diferente (em nível de app, por coleção, por entidade, por propriedade) e uma parte diferente da interface do usuário.

Este guia ajuda você a escolher o mecanismo certo para o seu caso de uso e, em seguida, direciona para a referência detalhada de cada um.

Tudo aqui se refere ao painel administrativo. Para o servidor — limitar uma leitura, adicionar uma rota, incorporar o driver em seu próprio processo, rebase eject — consulte O Rebase não faz X, que traz uma tabela semelhante para o backend.

Tabela de Decisão

Eu quero…	Mecanismo	Escopo	Referência
Substituir a barra do app	components (Shell.AppBar)	app	Substituições de Componentes
Substituir a página de login	components (Auth.LoginView)	app	Substituições de Componentes
Substituir a página inicial	components (HomePage)	app	Substituições de Componentes
Mudar completamente a aparência do formulário de uma coleção	formView	coleção	abaixo
Trocar um componente dentro de uma coleção	collection.components	coleção	Substituições de Componentes
Definir substituições de componentes padrão para todas as coleções	components (nomes com escopo de coleção)	app	Substituições de Componentes
Adicionar um botão à barra de ferramentas da coleção	Actions da coleção	coleção	Ações de Entidade
Injetar interface em um slot da barra de ferramentas da coleção	slot collection.actions	app/plugin	Slots
Adicionar uma coluna computada a uma tabela	additionalFields	coleção	Colunas Adicionais
Adicionar um widget de campo personalizado para um tipo de propriedade	propertyConfigs	tipo de propriedade	Campos Personalizados
Adicionar uma aba à entidade	entityViews	entidade	Visualizações de Entidade
Renderizar as linhas de uma coleção de uma maneira diferente	admin.customViews	coleção	abaixo
Adicionar uma ação de linha/contexto ou botão de entidade	entityActions	entidade	Ações de Entidade
Inserir um número/indicador no card da página inicial de uma coleção	slot home.card.widget	app/plugin	Slots
Injetar interface em um local específico do chrome	slots	app/plugin	Slots
Distribuir várias extensões como uma única unidade instalável	plugins	app	Plugins
Estilizar o que acabei de construir	@rebasepro/ui + tokens do tema	qualquer	Estilizando UI Personalizada

Independentemente do que escolher, construa a partir do kit

Cada mecanismo abaixo fornece um componente React e não impõe como preenchê-lo. Use os componentes @rebasepro/ui e os tokens de cor do tema em vez de CSS manual — uma visualização personalizada ainda é uma visualização do admin, e uma cor fixa no código fica invisível em um dos dois temas. Consulte Estilizando UI Personalizada.

Mecanismos em Detalhes

Plugins

Escopo: app.

Um plugin agrupa coleções, visualizações, substituições de componentes, contribuições de slots, autenticação, fontes de dados, providers, hooks e callbacks de ciclo de vida em uma única unidade instalável. Todos os outros mecanismos listados aqui podem ser fornecidos por meio da interface de um plugin.

→ Referência de Plugins

Slots

Escopo: app (fornecido por slot).

Slots são pontos de extensão nomeados da interface de usuário distribuídos pelo chrome do CMS. Você registra um componente React direcionado a um nome de slot, e ele é renderizado naquele local. Existem 27 slots cobrindo a página inicial, navegação, visualizações de coleção, formulários, linhas de entidade, campos de formulário e a barra do app — e cada um deles é renderizado.

→ Referência de Slots

Substituições de Componentes (Swizzling)

Escopo: padrões em nível de aplicativo ou por coleção.

Dois modos: Eject (substituição completa) ou Wrap (estender o original).

19 nomes de componentes substituíveis divididos em dois níveis:

Exclusivos do App (7):

• Shell.AppBar
• Shell.Drawer
• Shell.DrawerNavigationItem
• Shell.DrawerNavigationGroup
• HomePage
• HomePage.CollectionCard
• Auth.LoginView

Com escopo de Coleção (12):

• Collection.View
• Collection.Table
• Collection.Card
• Collection.EmptyState
• Collection.Actions
• Collection.FilterField
• Entity.Form
• EditView.FormActions
• DetailView
• Entity.SidePanel
• EntityPreview
• Entity.MissingReference

Precedência: components em nível de coleção substituem os padrões em nível de app para o mesmo nome de componente (spread simples de objeto — os valores da coleção sobrescrevem os valores globais). Nomes de componentes exclusivos do app (Shell.*, HomePage, Auth.*) só podem ser substituídos no nível de <Rebase>.

→ Substituições de Componentes

Visualizações de Entidade

Escopo: entidade (adiciona abas).

Visualizações personalizadas que aparecem como abas na página de detalhes da entidade. Podem ser definidas globalmente em <Rebase> ou por coleção.

→ Visualizações de Entidade

Ações de Entidade

Escopo: entidade.

Botões de ação personalizados em entidades individuais (publicar, arquivar, clonar, etc.). Podem ser definidos globalmente ou por coleção.

→ Ações de Entidade

Actions de Coleção

Escopo: coleção.

Componentes React em nível de barra de ferramentas que recebem CollectionActionsProps (entidades selecionadas, controlador de tabela, contexto da coleção). Renderizados na barra de ferramentas da coleção juntamente com as ações integradas.

Relação com o slot collection.actions: Ambos são cumulativos — os componentes de Actions são renderizados primeiro na barra de ferramentas, seguidos pelas contribuições de slots de collection.actions. Eles não substituem um ao outro.

→ Ações de Entidade — Ações de Coleção

Modos de visualização personalizados

Escopo: coleção (adiciona um modo de visualização).

Um mapa, um calendário, uma galeria, uma linha do tempo — outra renderização das mesmas linhas, oferecida no seletor de visualizações da coleção ao lado de Lista, Tabela, Cards e Quadro.

// collection config
admin: {
    customViews: [
        { key: "map", name: "Map", icon: "Map", Builder: MapView }
    ],
    enabledViews: ["table", "map"],
    defaultViewMode: "map"
}

Ou registre o componente uma vez e o identifique pela chave, o que também o torna selecionável a partir do editor de coleções:

<RebaseCMS
    collections={collections}
    collectionViews={[{ key: "map", name: "Map", icon: "Map", Builder: MapView }]}
/>

admin: { customViews: ["map"] }

O Builder recebe o tableController ativo, portanto a visualização herda os filtros da coleção, a caixa de busca, a ordenação, a paginação, as verificações de permissão e o painel lateral da entidade — essa é a razão principal para declarar um em vez de construir uma AppView:

function MapView({ tableController, onEntityClick }: CollectionCustomViewParams) {
    return <MapCanvas
        markers={tableController.data.map(e => e.values.location)}
        onMarkerClick={i => onEntityClick?.(tableController.data[i])}
    />;
}

Selecionar a visualização atualiza ?__view=, sobrevive a um recarregamento e persiste por usuário. Declarar uma já é suficiente para oferecê-la — enabledViews só precisa ser configurado quando você deseja remover as opções integradas. Com apenas uma entrada, o seletor fica oculto.

Esta não é uma maneira de construir uma visualização que abranja várias coleções. Um modo de visualização é outra renderização da consulta de uma única coleção. Se o seu componente ignora o tableController e busca dados de quatro tabelas próprias, ele deveria ser uma AppView — a barra de ferramentas acima dele, com sua caixa de busca e contagem de registros, estaria descrevendo uma consulta que ele não renderiza.

formView

Escopo: coleção.

Substitui todo o formulário de entidade padrão por um componente personalizado. Definido na configuração de uma coleção:

const collection = {
    slug: "products",
    admin: {
        formView: {
            Builder: MyCustomProductForm,
            includeActions: true  // Save and Discard in the bar (default: true)
        }
    }
};

Use quando precisar de um layout totalmente personalizado para a experiência de edição de entidades de uma coleção. Para ajustes menores, prefira collection.components com a substituição de Entity.Form.

O Builder é renderizado dentro do formulário do registro e recebe seu formContext ativo: grave com formContext.setFieldValue, e o botão Salvar da barra armazenará o registro. Onde o registro não puder ser editado — na visualização de detalhes somente leitura, ou para um usuário sem permissão de edição —, formContext.disabled será true e as tentativas de escrita lançarão erro. Defina includeActions: false se o seu Builder salvar por conta própria através de formContext.submit().

additionalFields

Escopo: coleção.

Colunas computadas/virtuais exibidas na tabela da coleção. Elas não correspondem a propriedades armazenadas — são calculadas no momento da renderização.

→ Colunas Adicionais

propertyConfigs

Escopo: tipo de propriedade.

Widgets de campos personalizados para tipos de propriedade específicos, fornecendo campos de formulário e componentes de pré-visualização personalizados.

→ Campos Personalizados

Fora do painel administrativo

Se o que você deseja alterar é o comportamento do servidor, em vez do que o painel exibe, esta não é a página correta. O servidor tem sua própria estrutura em camadas:

Eu quero…	Degrau	Referência
Limitar quais linhas uma leitura retorna	callback beforeQuery	Estendendo o servidor
Ocultar/redigir um valor na saída	callback afterRead	Callbacks
Adicionar um endpoint próprio	função personalizada	Funções Personalizadas
Fazer a busca encontrar substrings e ignorar acentos	search.mode: "hybrid"	Busca
Assumir o controle do processo do servidor	servidor personalizado, depois rebase eject	Estendendo o servidor

→ O Rebase não faz X

Resumo de Precedência

• collection.components se aplica sobre os components globais dentro dessa coleção. Uma substituição (replace) da coleção substitui ambos; Desde 0.25 uma substituição da coleção com wrap: true envolve a substituição global quando há uma (na 0.24 ela envolve o componente integrado, e a substituição global é ignorada). Veja Substituições de Componentes.
• Actions de coleção e o slot collection.actions são cumulativos — Actions são renderizados primeiro, seguidos pelas contribuições de slots.
• entityActions e entityViews em nível de coleção estendem (não substituem) os globais.
• Os plugins se aplicam na ordem do array plugins, não pela key. As contribuições de slots são renderizadas pelo seu order (o menor primeiro, 50 por padrão), e os empates mantêm essa ordem. Desde 0.25 Os wrappers de campo de vários plugins se compõem nessa ordem, com o do primeiro plugin por dentro; na 0.24 apenas o último wrapper era renderizado. Veja Plugins.