Seu primeiro módulo

Visão Geral

Este capítulo instrui a criação do seu primeiro módulo no Odoo e da implementação dele em seu projeto no Odoo.sh.

Este tutorial requer que você tenha criado um projeto no Odoo.sh e saiba o URL do seu repositório do Github.

O uso básico do Git e do Github é explicado.

São feitas as seguintes suposições:

• ~/src é o diretório onde estão localizados os repositórios Git relacionados aos seus projetos Odoo,

• odoo é o usuário do Github,

• odoo-addons é o repositório do Github,

• feature-1 é o nome da ramificação de desenvolvimento,

• master é o nome da ramificação de produção,

• my_module é o nome do módulo.

Substitua esses valores pelos valores de sua escolha.

Criar a ramificação de desenvolvimento

Pelo Odoo.sh

Na visualização das ramificações:

• pressione o botão + ao lado do estágio de desenvolvimento,

• escolha a ramificação master na seleção Bifurcação,

• digite feature-1 na entrada Para.

  

Depois que a compilação for criada, você poderá acessar o editor e navegar até a pasta ~/src/user para acessar o código da sua ramificação de desenvolvimento.

Pelo seu computador

Clone seu repositório do Github no computador:

$ mkdir ~/src
$ cd ~/src
$ git clone https://github.com/odoo/odoo-addons.git
$ cd ~/src/odoo-addons

Crie uma nova ramificação:

$ git checkout -b feature-1 master

Criar a estrutura do módulo

Estruturação do módulo

Embora não seja necessário, a estruturação evita o tédio de definir a base do módulo Odoo. Você pode criar um novo módulo usando o odoo-bin executável.

Pelo editor do Odoo.sh, em um terminal:

$ odoo-bin scaffold my_module ~/src/user/

Ou, em seu computador, se você tiver uma instalação do Odoo:

$ ./odoo-bin scaffold my_module ~/src/odoo-addons/

Se não quiser se dar ao trabalho de instalar o Odoo em seu computador, você também pode baixar esse modelo de estrutura de módulo, no qual você substituirá todas as ocorrências de my_module pelo nome de sua escolha.

A estrutura abaixo será gerada:

my_module
├── __init__.py
├── __manifest__.py
├── controllers
│   ├── __init__.py
│   └── controllers.py
├── demo
│   └── demo.xml
├── models
│   ├── __init__.py
│   └── models.py
├── security
│   └── ir.model.access.csv
└── views
    ├── templates.xml
    └── views.xml

Aviso

Não use outros caracteres especiais além do sublinhado ( _ ) no nome do módulo, nem mesmo um hífen ( - ). Esse nome é usado para as classes Python do seu módulo, e ter nomes de classes com caracteres especiais que não sejam o sublinhado não é válido no Python.

Descomente o conteúdo dos arquivos:

• models/models.py, um exemplo de modelo com seus campos,

• views/views.xml, uma árvore e uma visualização de formulário, com os menus que as abrem,

• demo/demo.xml, registros de demonstração para o modelo de exemplo acima,

• controllers/controllers.py, um exemplo de controlador que implementa algumas rotas,

• views/templates.xml, dois exemplos de visualizações do qweb usadas pelas rotas do controlador acima,

• __manifest__.py, o manifesto do seu módulo, incluindo, por exemplo, o título, a descrição e os arquivos de dados a serem carregados. Você só precisa descomentar o arquivo de dados da lista de controle de acesso:

  # 'security/ir.model.access.csv',
  

Manualmente

Se quiser criar a estrutura do módulo manualmente, você pode seguir o tutorial Getting started para entender a estrutura de um módulo e o conteúdo de cada arquivo.

Enviar a ramificação de desenvolvimento

Preparar as alterações para o commit

$ git add my_module

Fazer commit das suas alterações

$ git commit -m "My first module"

Envie suas alterações para seu repositório remoto

Em um terminal do editor do Odoo.sh:

$ git push https HEAD:feature-1

O comando acima é explicado na seção Fazer commit e Enviar suas alterações do capítulo Editor online. Isso inclui a explicação sobre a solicitação para que você digite seu nome de usuário e senha e sobre o que fazer se usar a autenticação de dois fatores.

Ou, no terminal de seu computador:

$ git push -u origin feature-1

Você precisa especificar -u origin feature-1 apenas para o primeiro envio. A partir desse ponto, para enviar as alterações futuras do seu computador, basta usar

$ git push

Testar seu módulo

Sua ramificação deve aparecer nas ramificações de desenvolvimento do seu projeto.

Na visualização de ramificações do seu projeto, você pode clicar no nome da ramificação no painel de navegação esquerdo para acessar o histórico dela.

Você pode ver aqui as alterações que acabou de enviar, inclusive o comentário que definiu. Quando a base de dados estiver pronta, você poderá acessá-la clicando no botão Conectar.

Se o seu projeto Odoo.sh estiver configurado para instalar seu módulo automaticamente, você logo o verá entre os aplicativos da base de dados. Caso contrário, ele estará disponível nos aplicativos para instalar.

Em seguida, você pode brincar com seu módulo, criar novos registros e testar seus recursos e botões.

Testar com os dados de produção

Você precisa ter uma base de dados de produção para esta etapa. Você pode criá-la se ainda não tiver.

Depois de testar seu módulo com os dados de demonstração em uma compilação de desenvolvimento e achar que está pronto, você poderá testá-lo com os dados de produção usando uma ramificação de teste.

Você pode:

• Transforme sua ramificação de desenvolvimento em uma ramificação de teste, arrastando e soltando-a no título da seção teste.

  

• Mescle-a com uma ramificação de teste existente arrastando e soltando-a na ramificação de teste em questão.

  

Você também pode usar o comando git merge para mesclar suas ramificações.

Isso criará uma nova compilação de teste, que duplicará a base de dados de produção e a executará usando um servidor atualizado com as alterações mais recentes da sua ramificação.

Quando a base de dados estiver pronta, você poderá acessá-la usando o botão Conectar.

Instalar seu módulo

Seu módulo não será instalado automaticamente, você terá que instalá-lo no menu de aplicativos. De fato, o objetivo da compilação de teste é testar o comportamento de suas alterações como seria na sua produção, e na produção você não gostaria que seu módulo fosse instalado automaticamente, mas sob demanda.

Seu módulo também pode não aparecer diretamente nos aplicativos a serem instalados; primeiro, você precisa atualizar sua lista de aplicativos:

• Ative o modo de desenvolvedor

• No menu de aplicativos, clique no botão Atualizar lista de aplicativos,

• Na caixa de diálogo exibida, clique no botão Atualizar.

  

Seu módulo aparecerá na lista de aplicativos disponíveis.

Implementar em produção

Depois de testar seu módulo em uma ramificação de teste com os dados de produção e acreditar que está pronto para produção, você pode mesclar sua ramificação na de produção.

Arraste e solte a ramificação de teste na ramificação de produção.

Você também pode usar o comando git merge para mesclar suas ramificações.

Isso mesclará as alterações mais recentes de sua ramificação de teste na ramificação de produção e atualizará seu servidor de produção com essas alterações.

Quando a base de dados estiver pronta, você poderá acessá-la usando o botão Conectar.

Instalar seu módulo

Seu módulo não será instalado automaticamente, você deverá instalá-lo manualmente, conforme explicado na seção acima sobre a instalação do seu módulo em bases de dados de teste.

Adicionar uma alteração

Esta seção explica como adicionar uma alteração em seu módulo, adicionando um novo campo em um modelo e implementando-o.

No editor do Odoo.sh,

• navegue até a pasta do módulo ~/src/user/my_module,

• em seguida, abra o arquivo models/models.py.

Ou, em seu computador,

• use o navegador de arquivos de sua preferência para navegar até a pasta do módulo ~/src/odoo-addons/my_module,

• Em seguida, abra o arquivo models/models.py usando o editor de sua preferência, como Atom, Sublime Text, PyCharm, vim etc.

Em seguida, após o campo de descrição

description = fields.Text()

Adicione um campo de data e hora

start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())

Em seguida, abra o arquivo views/views.xml.

Depois

<field name="value2"/>

Adicionar

<field name="start_datetime"/>

Essas alterações modificam a estrutura da base de dados, adicionando uma coluna em uma tabela e modificando uma visualização armazenada na base de dados.

Para que sejam aplicadas em bases de dados existentes, como a base de dados de produção, essas alterações exigem que o módulo seja atualizado.

Se quiser que a atualização seja realizada automaticamente pela plataforma Odoo.sh quando você enviar suas alterações, aumente a versão do módulo em seu manifesto.

Abra o manifesto do módulo __manifest__.py.

Trocar

'version': '0.1',

com

'version': '0.2',

A plataforma detectará a mudança de versão e acionará a atualização do módulo após a implementação da nova revisão.

Navegue até sua pasta Git.

Em seguida, em um terminal do Odoo.sh:

$ cd ~/src/user/

Ou, no terminal de seu computador:

$ cd ~/src/odoo-addons/

Em seguida, prepare suas alterações para serem confirmadas

$ git add my_module

Fazer commit das suas alterações

$ git commit -m "[ADD] my_module: add the start_datetime field to the model my_module.my_module"

Envie suas alterações:

Em um terminal Odoo.sh:

$ git push https HEAD:feature-1

Ou, no terminal de seu computador:

$ git push

Em seguida, a plataforma criará uma nova compilação para a ramificação feature-1.

Depois de testar suas alterações, você pode mesclar suas alterações na ramificação de produção, por exemplo, arrastando e soltando a ramificação na de produção pela interface do Odoo.sh. À medida que você aumentar a versão do módulo no manifesto, a plataforma atualizará o módulo automaticamente e seu novo campo logo estará disponível. Caso contrário, você pode atualizar manualmente o módulo na lista de aplicativos.

Usar uma biblioteca Python externa

Se quiser usar uma biblioteca Python externa que não esteja instalada por padrão, você poderá definir um arquivo requirements.txt listando as bibliotecas externas das quais seus módulos dependem.

Nota

• Não é possível instalar ou atualizar pacotes do sistema em uma base de dados do Odoo.sh (por exemplo, pacotes apt). No entanto, sob condições específicas, os pacotes podem ser considerados para instalação. Isso também se aplica a módulos Python que exigem pacotes do sistema para sua compilação e módulos Odoo de terceiros.

• As extensões PostgreSQL não são compatíveis com o Odoo.sh.

• Para obter mais informações, consulte nosso FAQ.

A plataforma usará esse arquivo para instalar automaticamente as bibliotecas Python de que seu projeto precisa.

O recurso é explicado nesta seção usando a Biblioteca Unidecode em seu módulo.

Crie um arquivo requirements.txt na pasta raiz do seu repositório

No editor do Odoo.sh, crie e abra o arquivo ~/src/user/requirements.txt.

Ou, em seu computador, crie e abra o arquivo ~/src/odoo-addons/requirements.txt.

Adicionar

unidecode

Em seguida, use a biblioteca em seu módulo, por exemplo, para remover acentos dos caracteres no campo de nome de seu modelo.

Abra o arquivo models/models.py.

Antes

from odoo import models, fields, api

Adicionar

from unidecode import unidecode

Depois

start_datetime = fields.Datetime('Start time', default=lambda self: fields.Datetime.now())

Adicionar

@api.model
def create(self, values):
    if 'name' in values:
        values['name'] = unidecode(values['name'])
    return super(my_module, self).create(values)

def write(self, values):
    if 'name' in values:
        values['name'] = unidecode(values['name'])
    return super(my_module, self).write(values)

A adição de uma dependência do Python requer um aumento da versão do módulo para que a plataforma o instale.

Edite o manifesto do módulo __manifest__.py

Trocar

'version': '0.2',

com

'version': '0.3',

Prepare e faça commit das suas alterações:

$ git add requirements.txt
$ git add my_module
$ git commit -m "[IMP] my_module: automatically remove special chars in my_module.my_module name field"

Em seguida, envie as alterações:

Em um terminal do Odoo.sh:

$ git push https HEAD:feature-1

No terminal do seu computador:

$ git push