Welcome to Cantemo Developer’s documentation

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

  1. User’s Documentation.

  2. Installation and Administrator’s Documentation.

  3. Developer’s Documentation. (this document).

It is expected that you have read and have knowledge of Cantemo before you start development.

How to use this documentation

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

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

  2. Play with Cantemo 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.

Cantemo 6.0 comes with many upgrades to essential components in Cantemo. If you have made plugins or components that are bound to the previous version you may need to make changes.

News for Cantemo 6

There are some small backwards incompatible changes for plugins in Cantemo 6. The example plugin https://github.com/Cantemo/SearchPageExportExample has been updated to work on Cantemo 6, and serves as a practical example.

User Interface

Cantemo User Interface now uses Accurate.Player UI components. All plugins that render menu items should now return menu items in a <ap-menu-list-item> HTML tag instead of <li>, for example:

<ap-menu-list-item>
    <a href="/myplugin/">My Plugin home</a>
</ap-menu-list-item>

Django 4 Changes

  • django.conf.urls.url is removed, django.urls.re_path is a drop-in replacement

  • All timezone logic in Python now use the stdlib zoneinfo objects, not the deprecated pytz module. localize() and normalize() use should be replaced, for example:

    date_with_tz = settings.TIME_ZONE_TZINFO.normalize(date_without_tz)

  ->

date_with_tz = date_without_tz.astimezone(settings.TIME_ZONE_TZINFO)

  • Cantemo templatetag date_back from datetimeformatting was removed

  • request.is_ajax() is removed

  • Some template tags like ifnotequal are not available anymore

  • providing_args argument for Django Signal is not available anymore

  • https://docs.djangoproject.com/en/dev/internals/deprecation/#deprecation-removed-in-4-1 has detailed documentation about the changes, and suggested replacements. Cantemo 5.4 uses Django 3.2.

Celery Upgrade

  • The management command manage.py celery has been removed, use the command /opt/cantemo/python/bin/celery directly

  • /opt/cantemo/python/bin/celery now requires the argument -A portal before the action, for example /opt/cantemo/python/bin/celery -A portal worker ...

  • Instead of from celery.task import task use from celery import shared_task, @shared_task has same arguments as previous @task

Settings and database model changes

Page size for administrative pages like Jobs List, Archive Job List, Share List, etc. is now chosen in the view and selected value is kept on page reloads. Due to this:

  • The fields paginate_by and paginate_by_jobs_page have been removed from UserProfile-model.

  • The portal.conf settings DEFAULT_RESULTS_CHOICES, DEFAULT_RESULTS_SHOWN, and MAX_RESULT_CHOICE have been removed.

News for Cantemo 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 Cantemo 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.

Cantemo 4.3 API Deprecation

All APIs under /API/v1 and specifically GET /API/v2/search were deprecated in Cantemo 4.3.0 and removed in Cantemo 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 Cantemo 5.0.0. Please use PUT /API/v2/search/ instead.

In future versions of Cantemo 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 Cantemo 5.1.0 would be marked as deprecated latest in Cantemo 5.0.0.

News for Cantemo 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 Cantemo 4.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 Cantemo for development.

App Development

Apps and plugins API information. Building Apps in Cantemo 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 Cantemo.

Translation:

How to translate Cantemo and support new languages.

Cantemo REST interface

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

Indices and tables

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