From 71058c7bf2bc76dc9e01eee52076f15afb064846 Mon Sep 17 00:00:00 2001 From: Rodrigo Carvalho Benevides Date: Wed, 18 Dec 2024 01:05:40 +0000 Subject: [PATCH] Atualizar 'Dicas de Plone 6 e Volto' --- Dicas-de-Plone-6-e-Volto.md | 125 +++++++++++++++++++++++++++++------- 1 file changed, 102 insertions(+), 23 deletions(-) diff --git a/Dicas-de-Plone-6-e-Volto.md b/Dicas-de-Plone-6-e-Volto.md index aaae99e..97cd726 100644 --- a/Dicas-de-Plone-6-e-Volto.md +++ b/Dicas-de-Plone-6-e-Volto.md @@ -1,9 +1,40 @@ + # Dicas para Uso de Plone 6/Volto Algumas anotações enquanto estudava Plone 6 e Volto. Não pretende ser 100% completa, mas indicar onde conseguir mais ajuda sobre alguns tópicos. ## Projeto +A instalação do Plone cria um projeto *"monorepo"*, contendo backend, frontend e devops. + +Vários comandos `make` podem ser disparados da raiz do projeto ou de dentro do diretório correspondente. Por exemplo, para iniciar o backend: + +``` +# da raiz +~/projeto$ make backend-start +# do diretório backend +~/projeto/backend$ make start +``` + +### Addons + +A filosofia do desenvolvimento Plone é que todo o desenvolvimento deve feito dentro de *addons*. + +O *monorepo* é criado seguindo esta filosofia, conforme a tabela abaixo: + +||| +|---|---| +|`/backend`|Configuração para subir o backend: porta, dependências, addons externos, etc| +|`/backend/src`|Addons internos ao repositório| +|`/backend/src/`|Addon principal, criado na instalação| +|`/frontend`|Configuração para subir o frontend: dependências, addons externos, etc| +|`/frontend/packages`|Addons internos ao repositório| +|`/frontend/packages/volto-`|Addon principal, criado na instalação| + +Addons de backend normalmente (via de regra?) são instalados na interface web do site para fazer seus efeitos. + +> Uma dúvida minha é se isto é estritamente necessário ou apenas recomendado + ### Criando um novo projeto ``` @@ -15,11 +46,39 @@ make install [Training - Plone Deployment](https://training.plone.org/plone-deployment/project-new.html) +## Backend +O backend é o *verdadeiro* plone. Escrito em python, tem como base o conjunto de bibliotecas `zope`. -## Backend +A documentação é sofrida e espalhada entre os sites do `plone` e as várias bibliotecas `zope`. Be afraid. + +### ZCML + +Boa parte da configuração do backend é através de arquivos *XML* com extensão *zcml*. + +O arquivo `configure.zcml` do diretório base de cada addon é lido automaticamente. Outros arquivos `.zcml` do addon deve ser incluídos a partir deste, usando a diretiva ``. + +Algumas diretivas usadas: +||| +|---|---| +|``|Indica outro arquivo *zcml* a ser lido| +|``|Define um conjunto de *zcml* que vai ser executado quando o addon for instalado ou desinstalado| +|``|Cria um item de painel de controle.| +|``|Define uma *"página"*. Até o momento, só sei que se usa para indicar o conteúdo de um item de painel de controle criado com ``| +|``|Cria dados no *registry* do Plone. Por exemplo, dados referentes a um item customizado de painel de controle.| +|``|Define um endpoint de api| + +### Arquivos De Interesse + +||| +|---|---| +|`instance.yaml`|Use para gerenciar addons| +|`mx.ini`|Use para incluir repositórios git externos ao monorepo na estrutura de diretórios| -### Apontando para repositório externo + +### Receitas + +#### Apontando para repositório externo Ao desenvolver um addon reutilizável, o próprio costuma ter um repositório git separado. Para isto, usa-se o [mxdev](https://github.com/mxstack/mxdev). @@ -28,7 +87,7 @@ Passos: 1. Configure o arquivo `backend/requirements.txt`, colocando o nome do add-on: ```interlegis.barra-acessibilidade-backend``` - + 2. Configure o arquivo `backend/instance.yaml`: ``` @@ -45,13 +104,13 @@ Passos: extras = test branch = feature-7 ´´´ - + 4. `make backend-build` na raiz do projeto para baixar o conteúdo do git. [docs, install an add-on from source](https://6.docs.plone.org/admin-guide/add-ons.html#install-an-add-on-from-source) -### Instalar Addon +#### Instalar Addon 1. Adicionar uma linha em `backend/requirements.txt` para o addon @@ -70,7 +129,7 @@ Passos: [Documentação](https://6.docs.plone.org/admin-guide/add-ons.html#install-an-add-on) -### Criando item de painel de controle +#### Criando item de painel de controle Há duas formas de definir algo no painel de controle. @@ -83,25 +142,45 @@ Há duas formas de definir algo no painel de controle. Projetos de exemplo: - [eea.banner](https://github.com/eea/eea.banner) (usado pelo addon de frontend `volto-banner`) - [collective.volto.subfooter](https://github.com/collective/collective.volto.subfooter) - - + - [Mastering Plone 6 Training](https://training.plone.org/mastering-plone/registry.html#add-a-custom-control-panel) [Docs, Control Panels (bem limitado)](https://6.docs.plone.org/backend/control-panels.html) -### Criando um endpoint para ser usado no frontend +#### Criando um endpoint para ser usado no frontend + +Passos, grosso modo. Veja os exemplos para ter uma ideia melhor. -???? +1. Se já não existir, crie um diretório `restapi` dentro da raiz do backend. O nome não importa, mas `restapi` segue o padrão dos projetos que vi. +2. Use `` no `configure.zcml` da raiz para incluir o diretório recém-criado. + +3. Crie um arquivo `configure.zcml` dentro do diretório. Use a diretiva `` para criar o endpoint. + +4. Crie um arquivo python, exemplo `get.py`, dentro do diretório. Lá deve ser implementada uma classe para devolver os dados desejados. + +5. No caso de dados guardados em como string e que se deseja servir como json, pode ser necessário um serializer/deserializer. Ainda não sei como funcionam.... Projetos de exemplo: - [eea.banner](https://github.com/eea/eea.banner) (usado pelo volto-banner) - +- [collective.volto.cookieconsent](https://github.com/collective/collective.volto.cookieconsent) ## Frontend (Volto) -### Apontando para repositório externo +O frontend é chamado de Volto. Escrito em react/javascript, é feito para substituir o antigo frontend do plone (feito em python, direto no backend). + +### Arquivos De Interesse + +||| +|---|---| +|`package.json`|Use para gerenciar addons| +|`volto.config.js`|Também usado para gerenciar addons| + +### Receitas + +#### Apontando para repositório externo Ao desenvolver um addon reutilizável, o próprio costuma ter um repositório git separado. Para isto, usa-se o [mrs developer](https://github.com/collective/mrs-developer). @@ -117,13 +196,13 @@ Passos: ] } ``` - + 2. Configure o arquivo `frontend/mrs.developer.json`: ``` { ... outros ..., - + "meu-addon": { "output": "./packages/barra-acessibilidade", "package": "": "*" }, ``` - -2. Acrescente o addon em `volto.config.js`. + +2. Acrescente o addon em `frontend/volto.config.js`. ``` const addons = ['', 'volto-ploneconf']; ``` - + 3. No diretório do frontend, use `make install`. [Documentação no treinamento "Mastering Plone"](https://training.plone.org/mastering-plone/volto_addon.html#install-an-add-on) -### Utilizando uma API definida no backend +#### Utilizando uma API definida no backend O Volto utiliza `react-redux` para acessar o backend. Passos (usando o projeto [`volto-banner`](https://github.com/eea/volto-banner) como exemplos: 1. [Crie um novo reducer](https://github.com/eea/volto-banner/blob/master/src/reducers/banner.js). - + 2. [Acrescente o novo reducer na configuração do addon](https://github.com/eea/volto-banner/blob/master/src/index.js). 3. [Crie uma nova action](https://github.com/eea/volto-banner/blob/master/src/actions.js). @@ -179,7 +258,7 @@ Passos (usando o projeto [`volto-banner`](https://github.com/eea/volto-banner) c -### Colocando um componente em todas as páginas +#### Colocando um componente em todas as páginas Use a opção `appExtras` ao configurar o add-on. Veja no exemplo do addon `volto-banner` abaixo. @@ -191,7 +270,7 @@ Exemplo: [addon ´volto-banner´](https://github.com/eea/volto-banner): - [Acrescentando o componente no `appExtras`](https://github.com/eea/volto-banner/blob/master/src/index.js) - [Usando `react-portal` para posicionar](https://github.com/eea/volto-banner/blob/master/src/StagingBanner.jsx) -### Definindo interface de painel de control no frontend +### Definindo interface de painel de controle no frontend A criação de painel de controle normalmente é através de interface no backend e o Volto monta os controles necessários para a edição dos itens desta interface. @@ -199,4 +278,4 @@ Uma outra opção é definir no backend a interface como uma string (contendo um Exemplos: - [Addon dropdownmenu](https://github.com/collective/volto-dropdownmenu) -- [Addon subfooter](https://github.com/collective/volto-subfooter) \ No newline at end of file +- [Addon subfooter](https://github.com/collective/volto-subfooter)