Welcome to Portal Developer’s documentation

This guide serves to describe how to develop with and for Cantemo Portal. Is it part of three guides for Cantemo Portal:

  • User’s Documentation.

  • Installation and Administrator’s Documentation.

  • Developer’s Documentation. (this document).

It is expected that you have read and have knowledge of Portal before you start to develop.

How to use this documentation

This documentation is used for theming, creating Portal Apps and creating new integration to you services with Cantemo products:

  1. Please read the section on installing for development first.

  2. Play with the Portal and get used its capabilities.

  3. Read the User and Administrator guides to get a greater understanding of the system.

  4. Understand how to stop/start the system and how to read the logs.

  5. Read the example source code for Applications to get an idea of how to write Apps.

  6. Start reading the documentation, read about themes and have a look at the theme files.

  7. If in doubt start a conversation on the Cantemo or your local reseller.

We are constantly in the process of improving the documentation, any suggestions are very welcome.

Portal 4.0 comes with a bunch of upgrades to vital components in Portal. If you have made plugins or components that are bound to the previous version §you may need to make changes.

News for Portal 5.1

Django USE_TZ setting is now always enabled. This helps prevent certain timezone related bugs.

Third party plugins that have DateTimeField in their database models and e.g. compare these to datetime.now() need to be updated to use timezone.now() from django.utils.timezone. Please see Django documentation and code migration guide at https://docs.djangoproject.com/en/3.2/topics/i18n/timezones/#concepts for all the details.

This only affects plugins that use datetime values from database models.

News for Portal 5

For developers there are essentially no new changes. Although lots more APIs has been added and we are aiming for more and more React development and will remove the old Plugins in the future.

Portal 4.3 API Deprecation

All APIs under /API/v1 and specifically GET /API/v2/search were deprecated in Portal 4.3.0 and removed in Portal 5.0.0.

Use of deprecated APIs will log a WARNING, which can be seen for example by using the following command:

$  tail -F /var/log/cantemo/portal/portal.log | grep "WARNING - Deprecated"
...
2020-06-03 ... - WARNING - Deprecated GET /API/v2/search/: This end-point is planned to be
                           removed in Portal 5.0.0. Please use PUT /API/v2/search/ instead.

In future versions of Portal any deprecation will be marked at least one minor release before any APIs are removed, giving partners and third parties enough time to update their code.

For example any APIs removed in Portal 5.1.0 would be marked as deprecated latest in Portal 5.0.0.

News for Portal 4

Celery Upgrade

Celery has been upgraded to Celery 4.1. The command for setting up queues manage.py celery is backwards compatible.

Django Upgrade

Django has been upgraded to Django 1.11. The main changes that you may change your code with are:

URL patterns

The syntax of the urls.py files have changed in Django 1.8 and later. If you are regestering urls in your plugin you will have to update the syntax. For more information, see Django’s release notes at https://docs.djangoproject.com/en/1.8/releases/1.8/#django-conf-urls-patterns

Database migrations Use manage.py makemigrations <app name> instead of the south migrations. When merging code with new database migrations to Portal4.0, the migrations need to be redone on new Django and additionally extra code added to prevent these from failing on upgrades.

DJANGO REST Framework The serializer is different. See https://www.django-rest-framework.org/api-guide/serializers/ for an explanation

Python upgrade

Python has been upgraded from version 2.7 to version 3.6. After you have done the Django upgrade you should be able to convert your code to Python 3. There are tools on Internet that can help you with the convert. See for example https://docs.python.org/3/library/2to3.html

React upgrade

React has been upgraded to version 16, but the upgrade should not break your React plugins, you should be able to run which React version you want, but we suggest you to upgrade to at least version 16.

Plugins on Collection page that contain React code may be affected.

Rules Engine Python Scripts

Python 2 scripts in Rules Engine 3 needs to be converted to Python 3

Other Topics

Development Setup

Information on how to setup Portal for development.

App Development

Apps and plugins API information. Building Apps in Portal greatly extends the functionality available to your users, and this section details the capabilities of the Apps and what can be built from the plugin infrastructure.

Testing

Testing and Debugging information for developing Apps.

Theming and templating

How to theme and style Portal.

Translation:

How to translate Portal and support new languages.

Portal REST interface

Integration support for models and objects stored within Portal via REST, or with systems that we interface with and provide support around. Further documentation can be found in the help menu in Portal under the headline REST API Reference.

Indices and tables

If you require more information than contained in these documents please contact Cantemo for assistance.