CIWEMB-56: Add batch owner organisation field and use it for transactions filtration

[omarabuhussein]

Overview

Adding the batch owner organisation entity and field to the batch creation/update form, and use it to filter the transactions on batch transactions screen.

Before

The batch creation looks like this:

After

The batch add/update screen now has a new organisation auto-complete/search field called "Owner Organisation(s) :

that accepts multiple organisations.

and once the user goes to the batch transactions page, only the transactions that belong to these organisations will appear:

which happen because we pass the batch owner organisations to the contribution owner organization filter:

Technical Details

In this PR: #2 I've added a custom field on the contribution called "owner organisation", which is set automatically when a contribution is created based on the Income account for the first line item, the idea of that field is to allow filtering contributions based on which organisation owns them, allowing for multi legal entities (companies) setup.

The work here is a continuation of that, where it allows for filtering the transactions on the batch transactions screen, based on the value of that field, it also allows the user to decide during the batch creation to select which owner organisations should show in the available transactions list for the batch. The batch owner organisations are stored as new entity called BatchOwnerOrganisation entity which is added on the first commit of this PR, the reasons for creating new entity instead of using custom group/fields are:

1- CiviCRM does not support custom groups for batches, and while we can add the batch entity to cg_extend_objects option group, we still need to write code in the extension using hooks to make it appear in the batch screen.

2- And even if we do the above, the relationship between the batch and owner orgnisation is one to many, where a single batch can have transactions from various orgnisations. The problem is that CiviCRM custom fields implementation stores relationships like that in single field in serialized format, which make it hard and more expensive to use the field, and also make it harcoded to filter batches based on the owner orgnisation value (something I am going to implement in another PR later).

The second step after creating the new entity, is to inject it in the create/update batch form, and to save it in the database in the entity table during the form submission, this was accomplished in the 2nd commit using buildForm and postProcess hooks.

The last step was to make sure the batch owner orgnisations will be used in filtering the transactions in the batch transactions screen, which is basically taking the value of this field from batch entity, and sending it to the owner organization custom field on the contribution entity, which is already available on the batch transactions page, because it was added in the previous PR as a contribution custom field, this was accomplished in the 3rd commit with the help of buildForm hook and using setDefaults() method. Though there was a problem where CiviCRM does not enforce these search filters by default when you open the batch transactions page, mainly to improve performance given using filters require a more complex query, thus CiviCRM just assumes if users want to use filters they can just do it manually, but because now we allow users to select the value of one of these filers (the owner organisation custom field) during the batch creation (and before entering the batch transactions page), I had to enforce CiviCRM to use any set filter automatically, this was accomplished by using the alterContent hook, and changing this line in batch transactions page:

https://github.com/civicrm/civicrm-core/blob/5.39.1/templates/CRM/Financial/Form/BatchTransaction.tpl#L94

to buildTransactionSelectorAssign( true ) to enforce using the search filters from the beginning.

Here is a quick graph to help understand how the above work:

Also worth noting, that the custom fields on the batch screen will not work without this Core PR :
civicrm/civicrm-core#20556

Which is already part of CiviCRM >= 5.41.0 , and I've patched to our 5.39.1 fork here: compucorp/civicrm-core#93