Loading...
 

The field dependency mapping arrived in coreBOS at the end of 2018. It’s a very demanded feature. It’s a rather complex business map because it is very powerful and very complex to configure. Hopefully, in the future, we will have a map editor for this map.

At the moment if follows the same philosophy that all of the other business maps have in coreBOS where you have to manually create the XML and get it.

The idea is that when you edit a record in coreBOS, for example when I change a picklist another picklist changes(this is a picklist dependency, where the values of a certain picklist are dependent on the value of a previous picklist ).

That was about all you could do in coreBOS until now, but now with this Field Dependency Mapping what we can do is that any field can condition any other field and operation on the module.

So for example, if we changed the Industry to Banking, we could hide the Custom Information block or unhide a field or make some other field read-only and that kind of logic. That is exactly what the field dependency mapping is for.

You can define very complex conditions. It always depends on the change event, one field changes and when that field changes we have to modify other fields. The change in that field can be conditioned, so you can say if it is equal to or not equal to this.

The list of operations:

  • e: Igual | equal | “=”

  • n: distinto | not equal | “<>”

  • s: empieza con | begins with | “LIKE” (“$value%”)

  • Ns: | does not begin with | “LIKE” !(“$value%”)

  • ew: termina con | ends with | “LIKE” (“%$value”)

  • New: | does not end with | “LIKE” !(“$value%”)

  • c: contiene | like | “LIKE” (“click="javascript:toggle_dynamic_var("$value");" title="Click to edit dynamic variable: $value">No value assigned”)

  • k: no contiene | not like | “NOT LIKE” (“%$value”)

  • l: menor que | less than | “<”

  • b: menor que | less than | “<”

  • g: mayor que | greater than | “>”

  • a: mayor que | greater than | “>”

  • m: menor o igual | less or equal | “⇐”

  • h: mayor o igual | greater or equal | “>=”

These conditions can be grouped and constructed into very complex things so you could say if this field changes and this other field has this value and another field is different from some other value than we have to hide this block. That kind of logic you can define how the form has to change depending on a whole bunch of conditions. The actions you can take once you have defined and captured a change and you decided that the conditions fulfill your requirement, your necessity, then what happens, what can you do once you detect that change. All the actions supported are:

The list of actions

  • change: will assign a value or set of values to another field

  • setoptions: will add selectable options in a picklist

  • deloptions: will eliminate selectable options from a picklist

  • hide: hide a field and its’ label

  • show: show a field and its’ label

  • collapse: will collapse a block

  • open: will open a block

  • disappear: will hide a block

  • appear: will show a block

  • readonly: will make a field read-only

  • editable: will make a field not read-only

  • enable: will enable a field

  • disable: will disable a field

  • function: will call the given function with the parameters:

    • change_field, action_field, new_value, old_value, any additional parameters in XML

“Function” leaves the door open to all sorts of options, giving total control to the programmer. We will provide a set of common functions to be used:

  • fieldDep_AssignNewValue: return new value in the action_field

  • fieldDep_AddDays: add the given number of days to new_value and return the result

  • fieldDep_SubDays: subtract the given number of days from new_value and return the result

  • fieldDep_OnlyNumbers: return all numbers in new_value

  • fieldDep_OnlyLetters: return all letters in new_value

  • fieldDep_GetField: use getFieldValuesFromRecord to retrieve the value of the given field

  • NOT IMPLEMENTED YET

  • fieldDep_ChangeLabel: will permit changing the label of a field

  • fieldDep_Format: return sprintf formatting of new_value (use sprintf javascript library: https://github.com/alexei/sprintf.js)

The format of the Map is similar to other Mappings where we have the module that we are going to affect, that it has to apply to. And then we have a whole bunch of dependencies. The dependency is applied to a field, in this case, the campaign name; When this field changes and this set of conditions are met then you have to do a set of actions. In this case, we have to change the sponsor field to the value “Sponzori” and the campaignname to the value “232332”, hide the field targetaudience and make the field campaingname read-only.

<map>
  <originmodule>
    <originname>SalesOrder</originname>
  </originmodule>
<dependencies>
<dependency>
    <field>campaignname</field>
    <condition>[{...}]</condition>
    <actions>
        <change>
            <field>sponsor</field>
            <value>Sponzori</value>
        </change>
        <change>
            <field>campaignname</field>
            <value>2323232</value>
        </change>
        <hide>
            <field>targetaudience</field>
        </hide>
        <readonly>
            <field>campaignname</field>
        </readonly>
        <collapse>
        <block>sponsor</block>
        </collapse>
    </actions>
</dependency>
<dependency>
…
</dependency>
</dependencies>
</map>

 

The map is rather simple.

Another example: On the payment module; When the amount changes and that amount is less or equal than 0 then the payment category picklist has to be set to Infrastructure. So basically, when the amount field is negative then automatically the payment category will be set to Infrastructure.

Let’s try it out!

Firstly, go to the Business Mapping Module and create a new Business Mapping with the following details.

Map Name: CobroPago_FieldDependency
Map Type: Field Dependency
Target Module: Payment Module

 

 

image

On the Content section paste this code:

<map>
  <originmodule>
    <originname>CobroPago</originname>
  </originmodule>
<dependencies>
<dependency>
    <field>amount</field>
    <condition>[{"groupid":"",
	 "columnname":"vtiger_cobropago:amount:amount:CobroPago_Amount:N",
	 "comparator":"m",
	 "value":"0",
	 "columncondition":""}]
    </condition>
    <actions>
        <change>
            <field>paymentcategory</field>
            <value>Infrastructure</value>
        </change>
    </actions>
</dependency>
</dependencies>
</map>

 

Click Save.

On the other hand, create a new Payment record and set the amount to -10, You can see that the Payment Category changes to infrastructure. The action takes place when you leave the field; when you click outside the field, it is when the browser detects that the field has changed and launches condition.

Notes

  • This functionality totally overlaps with the native Picklist dependency, so we have moved that functionality to the map and eliminated the code that manages picklist dependency in javascript. The graphical editor in settings is still valid.

  • When we manually assign a value to a field we have to launch the change event against that field so the dependencies get calculated again, but we have to make sure that we don’t enter an infinite loop by not launching the event against the same field we just modified.

  • The mappings will be named modulename_FieldDependency (to follow the logic of all the others)

  • In EditView script we will search and load a mapping called $current_module.’_FieldDependency’. This will be done using GlobalVariable (like the others)

  • If more than one is found we will load the first one found with no special preference. There should be only one.

  • The mapping interface will have a method called getJSON (or similar). This method will return the conditions, fields and any other information the browser needs to implement the dependencies. We will load one or more variables into Smarty and modify the templates to load those values in javascript variables

  • We will add a javascript library to process the mapping on the onchange events

  • In MassEdit we have to do the same as in EditView

  • In DetailView we will load the mapping and use another method called getFieldsWithDependency (or similar) to modify those fields in the detail view so they are not editable (as we do now with picklist fields that have dependencies). This is because we can’t guarantee their dependencies when editing one field individually. Note: it is very possible that this can be done directly in the getBlocks function.

  • It is very possible that we have to modify the fields edit templates to add the onchange events. I would like that to be generic. I mean, we call a generic onchange event and add some hooks so anyone can add their own functionality. We use this hook to add the Field Dependency functionality.

You can use the following examples to work out with this mapping.

 

Page actions
PDF Print
⌅
Admin Manual
Developer Manual