Modules

A Diem project is made of modules.

Modules explanation by the example

The current example is taken from the diem-project website. It describes the doc module ( Reference page ) and the the docElem module ( this page, Modules ).

See the full diem-project source code
This website source code is shared. You can download it in the open source projects page.

Example data model

The schema.yml file looks like this:

Doc:  
  columns:  
    name:             { type: string(255), notnull: true }  
    body:             { type: clob, extra: markdown }  

DocElem:  
  columns:  
    doc_id:           { type: integer, notnull: true }  
    name:             { type: string(255), notnull: true }  
    body:             { type: clob, extra: markdown }  
  relations:  
    Doc:  
      foreignAlias:   Elems  

Modules declaration

Modules are declared in config/dm/modules.yml

Project:  

  Documentation:  

    doc:  
      model:                  Doc  
      page:                   true  
      name:                   Documentation  
      actions:  
        list:  
        listByVersion:  
          filters:            [ version ]  
        show:  

    docElem:  
      parent:                 doc  
      page:                   true  
      name:                   Documentation page  
      actions:  
        listByDoc:  
          filters:            [ doc ]  
        show:  

Note that the modules start with an underscore letter, and that words are separated by an uppercase letter. This is a mandatory convention name "modulized".

With these two files, Diem is able to build a fully functional project.

The doc module

This is the same modules.yml file, commented:

Project:                  # declare modules for the project   

  Documentation:          # namespace, mainly used to structure the admin menu  
                          # this has no meaning for Diem and follows no convention  
                          # so we can use whatever name we want to  

    doc:                  # declare the doc module  

      model: Doc          # declare that the doc module uses the Doc model  
                          # in this case this is not required,  
                          # because module and model have the same name  

      page: true          # declare that each Doc record  
                          # has a dedicated page on the front application  

      name: Documentation # human name shown in admin and front menus  

      actions:            # declare the module actions and components  

        list:             # the name starts with the "list" keyword  
                          # so Diem assumes it is used  
                          # to display a list of Doc records  

        show:             # the name starts with the "show" keyword  
                          # so Diem assumes it is used  
                          # to display a single Doc record  

The doc module:

• is linked to the Doc model. An administration interface will be generated to manipulate the Doc table.
• has a page. Each time a Doc record is created, a page is added to display it.
• has two actions: list and show. The components and templates will be created in the front application, with sensible default contents.

The docElem module

    docElem:               # declare the docElem module  
                           # in the same "Documentation" namespace  

      page:        true    # declare that each DocElem record  
                           # has a dedicated page on the front app  

      parent:      doc     # declare that a docElem is child of a doc  

      actions:             # declare the module actions and components  

        listByDoc:         # the name starts with the "list" keyword  
                           # so Diem assumes it is used  
                           # to display a list of DocElem records  

          filters: [ doc ] # declare that this list is filtered by a doc:  
                           # it will display all the DocElem records  
                           # for a given Doc Record  

        show:              # the name starts with the "show" keyword  
                           # so Diem assumes it is used  
                           # to display a single DocElem record  

The docElem module:

• is implicitly linked to the DocElem model. We didn't declare it but they have the same name
• has a page. Each time a DocElem record is created, a page is added to display it
• has a parent module: doc. Each docElem page will be inserted as a child of the matching doc page
• has two actions: listByDoc and show. The components and templates will be created in the front application.

Performances

The modules declaration is compiled, dumped to php, and stored in the cache directory.
You can see the dumped php code in cache/front/dev/config/config_dm_modules.yml.php

Full example

Here is an example that uses most possibilities:

docElem:                                    # module key  

  parent:                 doc               # module parent's key  

  model:                  DocElem           # linked to the DocElem model  

  page:                   true              # each DocElem record has a page in front app  

  name:                   Elem | Elems      # singular name | plural name  

  admin:                  on                # visible in admin app  

  actions:                                  # actions and components  

    listByDoc:                              # action key  

      filters:            [ doc, version ]  # front list filters  

      cache:              true              # the _listByDoc.php front template is cachable  
                                            # but varies on each page ( recommended )  
    show:  

      cache:              static            # the _show.php front template is cachable,  
                                            # and never varies