Modules are the most advanced kind of extension. If can hold libraries of different kinds like javascripts, python modules, css and pages. It can be complete applications ready for you to extend. All code libraries are copied each time you deploy, but pages and the likes are only copied the first time to make you able to do your changes without loosing them. Not all modules have forms, but the ones that do, will copy them into a folder with the same name as the module it self.

Format of the config file

The config file is a dict in a special format and stored in a file that must be named module.conf and lie in the root of the extension directory.

"""
This is telling what the module is and is also the info showing up in documentation if you do not supply a special help file.
"""

version = '1.0.0'

title = 'Module heading in the documentation'

dependencies = {
    'python' : ['modulename',],
    'javascript' : [],
    'css' : [],
    'modules' : [],
    'snippets' : [],
    'actions' : [],
}

libraries = {
    'python' : { 
        'modulename' : {
            'sortorder' : 200,
            'module' : 'pythonfilenamewithoutextention',
        },
    },
    'assets' : {
        'assetname' : {
            'sortorder' : 105,
            'filedirectory' : 'modules:assetdirectory/',
        },  
    },
    'js' : {},
    'css' : {},
}

definitions = {
    'alwaysinclude' : True,
    'settingsdef' : 'module:ModuleSettings',
    'settings' : {
        'DEFAULT_FROM_EMAIL' : '@settings.emailfrom',
        'EMAIL_HOST' : '@settings.emailsmtpserver',
        'EMAIL_PORT': '@settings.emailsmtpport',
        'EMAIL_HOST_USER': '@settings.emailsmtpuser',
        'EMAIL_HOST_PASSWORD' : '@settings.emailsmtppassword',
        'EMAIL_USE_TLS': '@settings.emailsmtpusetls',
    },
}

defaultsettings = {
    'emailtype' : 'send', #'read' 'both'
    'emailfrom' : 'yourname@example.com',
    'emailsmtpserver' : 'mail.example.com',
    'emailsmtpport' : 25,
    'emailsmtpuser' : 'yourmailuser',
    'emailsmtppassword' : 'secretpassword',
    'emailsmtpusetls' : False,
}

Each section is another dict that holds definition in a specific format.

Format of the setting form

The settings form is like any other form in DG3, it contain a comment of what it is, a title and a form element.

"""
Config form for mailhandling
"""

title = 'Mail handling config'

form = {
    'type' : 'page',
    'title' : 'Configuration',
    'stretch' : True,
    'elements' : [
        {
        'type' : 'label',
        'html' : '<b>Settings for mailhandling</b>',
        },
        {
         'type' : 'page',
         'layout' : 'lineform',
         'elements' : [
          {
           'type' : 'field',
           'label' : 'EMail from',
           'input' : {'type' : 'lineedit',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'losefocus',
            'toupdate' : '@emailfrom',
           },
          },
          {
           'type' : 'field',
           'label' : 'SMTP server',
           'input' : {'type' : 'lineedit',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'losefocus',
            'toupdate' : '@emailsmtpserver',
           },
          },
          {
           'type' : 'field',
           'label' : 'SMTP port',
           'input' : {'type' : 'lineedit',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'losefocus',
            'datatype' : 'int',
            'toupdate' : '@emailsmtpport',
           },
          },
          {
           'type' : 'field',
           'label' : 'SMTP user',
           'input' : {'type' : 'lineedit',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'losefocus',
            'toupdate' : '@emailsmtpuser',
           },
          },
          {
           'type' : 'field',
           'label' : 'SMTP password',
           'input' : {'type' : 'lineedit',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'losefocus',
            'toupdate' : '@emailsmtppassword',
           },
          },
          {
           'type' : 'field',
           'label' : 'SMTP use TLS',
           'input' : {'type' : 'checkbox',},
           'datamap' : {
            'type' : 'direct',
            'readon' : 'load',
            'writeon' : 'changed',
            'datatype' : 'bool',
            'toupdate' : '@emailsmtpusetls',
           },
          },
         ],
        },
    ],
}

The example in this document are taken from the mailhandling module.

The names for the fields in the settings document are the same as the one you find in definition and in default settings. The default settings are set as default values when the module is activated by the user.  All setting is then added as settings to the Django settings module with the name corresponding to name given in setting:

'EMAIL_HOST' : '@settings.emailsmtpserver' can be found in the Django settings as EMAIL_HOST = "mail.example.com" in this case.