Tu primer módulo

Información general

Este capítulo te guiará para que crees tu primer módulo de Odoo y lo despliegues en tu proyecto de Odoo.sh.

Este tutorial asume que ya creaste un proyecto en Odoo.sh y que conoces la URL de tu repositorio en GitHub.

También te explicaremos el uso básico de Git y GitHub.

Supondremos lo siguiente:

• ~/src es la carpeta donde están los repositorios de Git de tus proyectos de Odoo.

• odoo es el usuario de GitHub.

• odoo-addons es el repositorio de GitHub.

• feature-1 es el nombre de una rama de desarrollo.

• master es el nombre de la rama de producción.

• my_module es el nombre del módulo.

Puedes cambiar estos valores por los tuyos.

Crea la rama de desarrollo

Desde Odoo.sh

En la vista de ramas:

• Haz clic en el botón + junto a la etapa de desarrollo.

• Elige la rama master en la selección de bifurcación.

• Escribe feature-1 en el campo To (o A).

  

Una vez creada la compilación, puedes acceder al editor e ir a la carpeta ~/src/user para ver el código de tu rama de desarrollo.

Desde tu computadora

Clona tu repositorio de GitHub en tu computadora:

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

Crea una nueva rama:

$ git checkout -b feature-1 master

Crea la estructura del módulo

Estructura del módulo

No es necesario que uses una herramienta adicional, pero te ahorrará trabajo al crear la estructura básica de los módulos de Odoo. Puede usar el ejecutable odoo-bin para crear la estructura del nuevo módulo.

Desde el editor de Odoo.sh, en una terminal:

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

O desde tu computadora si tienes Odoo instalado de forma local:

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

Si no quieres instalar Odoo en tu computadora puedes descargar esta plantilla de estructura de módulo y reemplazar cada ocurrencia de my_module con el nombre que tú quieras.

Se generará esta estructura:

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

Advertencia

No uses caracteres especiales en el nombre de tu módulo, ni siquiera guiones (-). Solo puedes utilizar el guion bajo (_). Este nombre se usa para las clases de Python del módulo y este lenguaje no permite caracteres especiales en los nombres de clase, salvo el guion bajo.

Descomenta el contenido de los archivos:

• models/models.py, que es un ejemplo de modelo con sus campos.

• views/views.xml, que incluye una vista de árbol y de formulario, junto con los menús que las abren.

• demo/demo.xml, que son los registros de demostración para el modelo de ejemplo.

• controllers/controllers.py, que es un controlador de ejemplo que implementa algunas rutas.

• views/templates.xml, que son dos vistas QWeb de ejemplo usadas por las rutas del controlador.

• __manifest__.py, que es el archivo de manifiesto de tu módulo. Puede incluir su título, descripción y los archivos de datos a cargar. Solo debes descomentar el archivo de datos de la lista de control de acceso:

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

Manual

Si quieres crear la estructura de tu módulo de forma manual puedes seguir el tutorial Server framework 101 para entender la estructura de un módulo y el contenido de cada archivo.

Sube la rama de desarrollo

Prepara los cambios para hacer tu commit.

$ git add my_module

Confirma los cambios.

$ git commit -m "My first module"

Sube tus cambios a tu repositorio remoto.

Usa el siguiente comando en una terminal del editor de Odoo.sh:

$ git push https HEAD:feature-1

En la sección Confirmar y enviar cambios del capítulo Editor en línea encontrarás la explicación del comando anterior. Esa sección también te ayudará a entender porqué necesitas escribir tu usuario y contraseña, y lo que debes hacer si usas la autenticación de dos factores.

O desde la terminal de tu computadora:

$ git push -u origin feature-1

Solo necesitas especificar -u origin feature-1 en el primer push. Después, para enviar los próximos cambios desde tu computadora, puedes utilizar el siguiente comando:

$ git push

Prueba tu módulo

Tu rama debería aparecer en las ramas de desarrollo de tu proyecto.

En la vista de ramas de tu proyecto, puedes hacer clic en el nombre de tu rama en el panel de navegación izquierdo para acceder a su historial.

Ahí podrás ver los cambios que acabas de subir, incluyendo el comentario que escribiste. Una vez que la base de datos esté lista, podrás acceder a ella si haces clic en el botón Conectar.

Si tu proyecto de Odoo.sh está configurado para instalar tu módulo de forma automática, lo verás directamente entre las aplicaciones de la base de datos. De lo contrario, estará disponible en las aplicaciones a instalar.

Después podrás probar tu módulo, crear nuevos registros y verificar que tus funciones y botones funcionen.

Prueba con los datos de producción

Para este paso necesitas tener una base de datos de producción. Puedes crearla si aún no la tienes.

Una vez que hayas probado tu módulo en una compilación de desarrollo con los datos de demostración y consideres que está listo, puedes probarlo con los datos de producción usando una rama de prueba.

Puedes hacer lo siguiente:

• Convertir tu rama de desarrollo en una rama de prueba, arrastrándola y soltándola en el título de la sección de prueba.

  

• Fusionarla con una rama de prueba existente, arrastrándola y soltándola en dicha rama.

  

También puedes usar el comando git merge para fusionar tus ramas.

Esto creará una nueva compilación de prueba que duplicará la base de datos de producción y la ejecutará en un servidor con los últimos cambios de tu rama.

Una vez que la base de datos esté lista, puedes acceder a ella con el botón Conectar.

Instala tu módulo

Tu módulo no se instalará de manera automática, tendrás que instalarlo desde el menú de aplicaciones, pues el propósito de la compilación de prueba es revisar el comportamiento de tus cambios para conocer cómo funcionarían en producción. En producción no querrías que tu módulo se instalara automáticamente, sino que lo instalarías cuando fuera necesario.

Es posible que tu módulo tampoco aparezca en las aplicaciones a instalar de inmediato, así que primero necesitas actualizar tu lista de aplicaciones:

• Activa el modo de desarrollador

• Haz clic en el botón Actualizar lista de aplicaciones en el menú de aplicaciones.

• Aparecerá un cuadro de diálogo, haz clic en el botón Actualizar.

  

Tu módulo aparecerá en la lista de aplicaciones disponibles.

Despliegue en producción

Una vez que hayas probado tu módulo en una rama de prueba con los datos de producción, y creas que está listo para pasar a producción, puedes fusionar tu rama con la rama de producción.

Arrastra y suelta tu rama de prueba en la rama de producción.

También puedes usar el comando git merge para fusionar tus ramas.

Esta acción fusionará los cambios más recientes de tu rama de prueba en la rama de producción y actualizará tu servidor de producción con estos cambios.

Una vez que la base de datos esté lista, puedes acceder a ella con el botón Conectar.

Instala tu módulo

Como explicamos en la sección anterior sobre la instalación de los módulos en bases de datos de prueba, tu módulo no quedará instalado de forma automática, sino que tendrás que instalarlo por tu cuenta.

Agregar un cambio

Esta sección te explica cómo agregar un cambio a tu módulo añadiendo un nuevo campo en un modelo y desplegarlo.

Desde el editor de Odoo.sh:

• Ve a la carpeta de tu módulo ~/src/user/my_module.

• Abre el archivo models/models.py.

O desde tu computadora:

• Usa el explorador de archivos que prefieras para ir a la carpeta de tu módulo ~/src/odoo-addons/my_module.

• después abre el archivo models/models.py con el editor que quieras, como Atom, Sublime Text, PyCharm, vim, etc.

Luego, después del campo de descripción:

description = fields.Text()

Agrega un campo de fecha y hora:

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

Después, abre el archivo views/views.xml.

Después de

<field name="value2"/>

Agrega

<field name="start_datetime"/>

Estos cambios alteran la estructura de la base de datos al agregar una columna en una tabla y modifican una vista almacenada en la base de datos.

Para aplicar los cambios a las bases de datos existentes, como la base de producción, tendrás que actualizar el módulo.

Si quieres que la plataforma de Odoo.sh actualice tu módulo en automático cuando envíes tus cambios, aumenta la versión del módulo en el archivo manifest.

Abre el módulo manifest __manifest__.py.

Reemplaza

'version': '0.1',

con

'version': '0.2',

La plataforma detectará el cambio de versión y activará la actualización del módulo después del despliegue de la nueva revisión.

Ve a tu carpeta de Git.

Luego, desde una terminal de Odoo.sh:

$ cd ~/src/user/

O desde la terminal de tu computadora:

$ cd ~/src/odoo-addons/

Prepara los cambios a confirmar.

$ git add my_module

Confirma los cambios.

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

Envía tus cambios:

Desde una terminal de Odoo.sh:

$ git push https HEAD:feature-1

O desde la terminal de tu computadora:

$ git push

La plataforma creará una nueva compilación para la rama feature-1.

Una vez que hayas probado tus cambios, puedes fusionarlos con la rama de producción, por ejemplo, al arrastrar y soltar la rama sobre la rama de producción en la interfaz de Odoo.sh. Como aumentaste la versión del módulo en el archivo manifest, la plataforma actualizará el módulo de manera automática y tu nuevo campo estará disponible de inmediato. También puedes actualizar el módulo de forma manual desde la lista de aplicaciones.

Usar una biblioteca externa de Python

Si quieres usar una biblioteca externa de Python que no está instalada de forma predeterminada puedes definir un archivo requirements.txt con la lista de bibliotecas externas de las que depende tu módulo.

Nota

• No es posible instalar ni actualizar paquetes del sistema en una base de datos de Odoo.sh (por ejemplo, herramientas avanzadas de empaquetado APT). Sin embargo, bajo ciertas condiciones, se puede considerar la instalación de algunos paquetes. Esto también aplica a los módulos de Python que requieren paquetes de sistema para compilarse y a módulos externos de Odoo.

• Odoo.sh no es compatible con las extensiones de PostgreSQL.

• Consulta nuestras preguntas frecuentes para obtener más información.

La plataforma usará este archivo para instalar las bibliotecas de Python que tu proyecto necesita de manera automática.

Esta función se explica en esta sección usando la biblioteca Unidecode en tu módulo.

Crea un archivo requirements.txt en la carpeta principal de tu repositorio.

Desde el editor de Odoo.sh, crea y abre el archivo ~/src/user/requirements.txt.

O, desde tu computadora, crea y abre el archivo ~/src/odoo-addons/requirements.txt.

Agrega

unidecode

Luego usa la biblioteca en tu módulo. Por ejemplo, puedes eliminar acentos de los caracteres en el campo de nombre de tu modelo.

Abre el archivo models/models.py.

Antes

from odoo import models, fields, api

Agrega

from unidecode import unidecode

Después de

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

Agrega

@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)

Agregar una dependencia de Python requiere aumentar la versión del módulo para que la plataforma pueda instalarla.

Edita el módulo manifest __manifest__.py.

Reemplaza

'version': '0.2',

con

'version': '0.3',

Prepara y confirma tus cambios:

$ 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"

Luego, sube tus cambios con un push:

En una terminal de Odoo.sh:

$ git push https HEAD:feature-1

En la terminal de tu computadora:

$ git push