Page: Dicas de Plone 6 e Volto

Atendimento

Desenvolvimento do Portal Modelo 4

Dicas de Plone 6 e Volto

Estrutura do Portal Modelo 4

Portal modelo

Primeiros passos

Tecnologia

HTTP

17 Dicas de Plone 6 e Volto

Rodrigo Carvalho Benevides edited this page 1 month ago

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/<nome-projeto>	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-<nome-projeto>	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

pipx run cookieplone project
make install

Docs - Install Plone with cookieplone Training - Plone Deployment

Backend

O backend é o verdadeiro plone. Escrito em python, tem como base o conjunto de bibliotecas zope.

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 <include>.

Algumas diretivas usadas:

<include>	Indica outro arquivo zcml a ser lido
<genericsetup:registerProfile>	Define um conjunto de zcml que vai ser executado quando o addon for instalado ou desinstalado
<configlet>	Cria um item de painel de controle.
<browser:page>	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 <configlet>
<records>	Cria dados no registry do Plone. Por exemplo, dados referentes a um item customizado de painel de controle.
<plone:service>	Define um endpoint de api

Permissões

Em algumas das diretivas, é necessário especificar a permissão que o item sendo definido terá. As permissões mais comuns são:

Permissão	Descrição
zope2.View	Visualizar conteúdo. Não precisa estar logado no site. Comum em chamadas de API.
cmf.ManagePortal	Gerenciar portal. Comum em itens de painel de controle.
cmf.ModifyPortalContent	Gerenciar conteúdo. Permite criar e alterar páginas, etc.

Documentação na versão 5 do plone

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

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.

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:

   defaunt_context:
       zcml_package_includes: project_title, interlegis.barra-acessibilidade-backend
   

3. Configure o arquivo backend/mx.ini:

   [interlegis.barra-acessibilidade-backend]
   url = https://github.com/collective/example.contenttype.git
   pushurl = git@github.com:collective/example.contenttype.git
   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

Instalar Addon

1. Adicionar uma linha em backend/requirements.txt para o addon

2. Acrescentar o addon em backend/instance.yaml, no item zcml_package_includes:

   default_context:
       zcml_package_includes: project_title, <addon name>
   

3. make backend-build (no diretório raiz)

4. Vá no painel de controle, addons e adicione o addon

Não sei se é possível adicionar o addon de maneira programática, de forma que o site suba já com o addon adicionado

Documentação

Criando item de painel de controle

Frequentemente é necessário também criar um endpoint para acessar o que foi configurado no painel de controle.

Há duas formas de definir algo no painel de controle:

1. Definir interface detalhando os dados do painel de controle

   Não consegui achar um projeto com exemplo desta forma, mas é a forma que está explicada na documentação e nos treinamentos.

   Checklist típica (os arquivos não precisam ser exatamente esses, é só uma sugestão):

   • Criar um schema no arquivo interfaces.py, detalhando os campos desejados.
   • Incluir uma tag <configlet> nos profiles de instalação e desinstalação do item de painel de controle, arquivo controlpanel.xml. O atributo appId deve coincidir nos dois arquivos.
   • Criar um registro no Registry para a configuração, nos profiles de instalação e desinstalação. Arquivo registry.xml ou registry/main.xml. Usa-se a tag <records>.
   • Criar uma página pra responder o item, arquivo controlpanel/configure.zcml (tag browser:page) e controlpanel/controlpanel.py.
   • Criar um adapter pro Volto conseguir ver o item. Crie a tag <adapter>, em geral no arquivo restapi/configure.zcml.

   Documentação, Control Panels Training "Mastering Plone", add custom control panel Documentação dos tipos

2. Definir interface apenas com uma string, de forma que os dados sejam guardados como json. Neste caso, define-se um widget no frontend para editar este json. Esta forma é mais comum nos addons do "Awesome Volto".

   Checklist típica (os arquivos não precisam ser exatamente esses, é só uma sugestão):

   • Criar um schema no arquivo interfaces.py. Neste caso, o schema só contém um item, so tipo SourceText.
   • Incluir uma tag <configlet> nos profiles de instalação e desinstalação do item de painel de controle, arquivo controlpanel.xml. O atributo appId deve coincidir nos dois arquivos.
   • Criar um registro no Registry para a configuração, nos profiles de instalação e desinstalação. Arquivo registry.xml ou registry/main.xml. Usa-se a tag <records>.
   • Criar uma página pra responder o item, arquivo controlpanel/configure.zcml (tag browser:page) e controlpanel/controlpanel.py.
   • Criar um adapter pro Volto conseguir ver o item. Crie a tag <adapter>, em geral no arquivo restapi/configure.zcml.

   Projetos de exemplo:

   • eea.banner (usado pelo addon de frontend volto-banner)
   • collective.volto.subfooter
   • Redturtle Editable Footer

Mastering Plone 6 Training

Docs, Control Panels (bem limitado)

Troubleshooting

• Item aparece no plone clássico e não aparece no Volto.

  O Volto exige os atributos action_id e appId da tag <configlet>. Além disso, não se esqueça do <adapter>.

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 <include> 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 <plone:service> 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 (usado pelo volto-banner)
• collective.volto.cookieconsent

Frontend (Volto)

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.

Passos:

1. Configure o arquivo frontend/package.json:

   {
      "name": "my-volto-project",
      "addons": [
        "name-of-add-on"
      ]
    }
   

   ``

2. Configure o arquivo frontend/mrs.developer.json:

   {
     ... outros ...,
   
     "meu-addon": {
   	"output": "./packages/barra-acessibilidade",
   	"package": "<nome do package, exemplo '@interlegis/barra-acessibilidade'",
   	"url": "git@github.com:interlegis/barra-acessibilidade.git",
   	"https": "https://github.com/interlegis/barra-acessibilidade.git",
   	"tag": "<versão, exemplo '1.0'>"
     }
   }
   ´´´
   
   

3. make install no diretório frontend.

Docs, Install an add-on in development mode in Volto 18

Instalar Addon

1. Acrescente o addon em frontend/package.json.

   "dependencies": {
      "@plone/volto": "workspace:*",
      "@plone/registry": "workspace:*",
      "volto-ploneconf": "workspace:*",
      "<nome do addon>": "*"
    },
   

2. Acrescente o addon em frontend/volto.config.js.

   const addons = ['<nome do addon>', 'volto-ploneconf'];
   

   Aparentemente, pode também ser feito no frontend/package.json, num item addons. Não sei qual a maneira mais recomendada

3. No diretório do frontend, use make install.

Documentação no treinamento "Mastering Plone"

Utilizando uma API definida no backend

O Volto utiliza react-redux para acessar o backend.

Passos (usando o projeto volto-banner como exemplos:

1. Crie um novo reducer.

2. Acrescente o novo reducer na configuração do addon.

3. Crie uma nova action.

4. Use a action no seu addon (com useEffect).

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.

O componente é incluído no final da página, por default (acho). Se quiser posicionar em outro lugar, use react-portal, como no exemplo.

Docs, appextras

Exemplo: addon volto-banner:

• Acrescentando o componente no appExtras
• Usando react-portal para posicionar

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.

Uma outra opção é definir no backend a interface como uma string (contendo um json) e definir no frontend um widget para editar este json. Esta opção possibilita layouts mais complexos.

Exemplos:

• Addon dropdownmenu
• Addon subfooter
• Redturtle Editable Footer