Learn how to define GenDoc Virtual Relations to support multiple relation fields in the same module among other relations.

Some weeks ago I received a question from one of our users who is learning to customize their installation using GenDoc document generator. The question goes more or less like this:

I have a module where I have added custom fields and have two relation fields related to the same module. Using GenDoc I can reference the module but it always returns fields from the first related field. How can I tell GenDoc that I want to use values from the second related field?

I know that GenDoc will search for the first related field and work with that one so it will never use the second one. I also know that GenDoc has a way of specifying this case but I didn't remember how that worked.

Since we have a module with this configuration I decided to do some testing with that one. The module is Product Component. That module defines the dependency relation between products, so it contains a "From" and "To" product by using two relation fields to Products. Exactly what I need for testing.

I create this document which has this section:

Name: {Products.productname}
Code: {Products.productcode}
Serial: {Products.serial_no}

This works only with the first related field, the "Product From" field.

Once I verify the error I go to the code and find that GenDoc has two arrays that define virtual modules to establish special relations between modules. By defining the module that requires the additional definitions, the virtual name you want to use, and the fields that hold the relation you can access both related field records.

The code change I need to do looks like this:

diff --git a/modules/evvtgendoc/compile.php b/modules/evvtgendoc/compile.php
index 946886c84..df3783523 100644
--- a/modules/evvtgendoc/compile.php
+++ b/modules/evvtgendoc/compile.php
@@ -103,6 +103,10 @@ $related_module = array(
        'Organization' => array(
                'Accounts' => 'accid'
        ),
+       'ProductComponent' => array(
+               'ProductFrom' => 'frompdo',
+               'ProductTo' => 'topdo',
+       ),
);

//Array de mapeig de moduls especials, p.e. el presciptors son comptes
@@ -127,6 +131,8 @@ $special_modules = array(
        ),
        'HDRelatedTo' => array('Accounts','Contacts'),
        'HDProducts' => array('Products','Services'),
+       'ProductFrom' => 'Products',
+       'ProductTo' => 'Products',
);

$image_modules = array(

We have to add the virtual modules ProductFrom and ProductTo to the $related_modules array and then again to the $special_modules array.

With that change, I can now use these directives inside my GenDoc template:

Name: {ProductFrom.productname}
Code: {ProductFrom.productcode}
Serial: {ProductFrom.serial_no}

and

Name: {ProductTo.productname}
Code: {ProductTo.productcode}
Serial: {ProductTo.serial_no}

and get the values I expect.

Note how ProductFrom and ProductTo are "virtual" modules, they don't exist in the application but GenDoc understands how to use them. Fantastic piece of software!

That was rather easy, I didn't have to modify any of the logic of GenDoc, just a couple of entries in two configuration arrays, but one of our goals is to not have to modify the code for configurations so I have a look at our collection of business maps and decide to use the Information Map to permit implementors to define these virtual relations.

I created a business map named GenDocRelations with this structure:

<map>
  <information>
    <infotype>GendDoc Relations</infotype>
    <value>
       <module>ProductComponent</module>
       <virtualmodules>
          <virtualmodule>
            <name>ProductFrom</name>
            <field>frompdo</field>
            <module>Products</module>
          </virtualmodule>
          <virtualmodule>
            <name>ProductTo</name>
            <field>topdo</field>
            <module>Products</module>
          </virtualmodule>
       </virtualmodules> 
    </value>
  </information>
</map>

With this exact business map, there is no need to modify the code to get the GenDoc template working. It supports as many modules > virtual modules as needed with no need to modify the code anymore.

All that said, I did leave the ProductFrom and ProductTo virtual modules hardcoded as that makes a lot of sense

Enjoy the power and flexibility of EvolutivoFW!

Image by rawpixel.com on Freepik