Configuration Settings
In order to understand how to configure the settings and finally get a multi-select control on a form, let's consider an example.
Let's assume we have an "Interest" entity, which has attributes like in the screenshot below:
The "Interest" entity has a N:N relationship to the "Account" entity - "pavelkh_pavelkh_interest_account" .
What we would like to achieve is to have a set of checkboxes on an Account entity form, and each of the checkboxes in that set would represent a record from "Interest" entity where Interest "Type" equals to "Renewable Energy Sources" value. In other word, we would like to get this on the account form:
To achieve this, we first need to define a so-called "Item Set Configuration".
Navigate to the "AdvancedMultiSelect Item Set Configuration":
We can see the list of Item Set Configurations:
Here we need to create a new "AdvancedMultiSelect Item Set Configuration" record to describe our new "set of items" (actually a set of Interest entity records) we want to have on Account forms. Once you define it, you then are able to specify on which particular forms (you might have muiltiple forms for account entity) you would like to embed the "item set". So, let's start creating a new item set configuration:
Now at this stage, we need to specify several parameters describing the new item set. At first, we need to select a base entity (forms of this entity will contain the control in question). In our case we select "account" as the entity. Note that, in the autocomplete combobox you can see a list of entities (with both Logical and Display names). (You also will meet such an autocomplete feature in several fields on).
Then name the item set. Let's set name to "Account Renewable Energy Interests" in the "Item Set Name" field. Now we need to select N:N relationship in the "Relationship (schema name)" field (you can see relationship name and the name of the related entity in the autocomple list). In our case we select "pavelkh_pavelkh_interest_account" relationship:
On the next step, we need to set so-called "Dummy Saving Attribute". It will be a hidden text field. The reason of this "strange step" is that it's only a possible way to make our multiselect functionality to work for "Create" form mode (e.g. when a new account record is being created). For those who are interested in how it works "behind the scene": the system stores the list of selected options in this "dummy" field (actually it stores a list of IDs/Guids of selected related records) so that appropriate plug-in functionality be able to perform corresponding association/disassociation for the related records. However, in fact, no data is stored eventually in this field (plug-in cleans up the field just after reading the value passed)). By default, the system suggests to "Create New Dummy Saving Attribute" and suggests default schema name and display name for the field. It make sense to leave the field length = 4000 (it gives an ability to pass info about 100 selected options). The new field will be created for the entity just after you save the current "Item Set Configuration" record. Note: the new dummy field will be hidden in the Advanced Find.
If you would like to utilize some existing text field for this purpose you can click on "Create New Dummy Saving Attribute" switcher to change the mode and specify an existing field:
The next field is "Save Action (unique name)".
In most cases (when you selected a custom N:N relationship) you should leave it empty. The only case when you need specify it is when you select an out-of-box relationship which implies a special API to associate/disassociate related records in an N:N relationship. For instance, it concerns out-of-box relations between Marketing List and Account or Contact entity. If you really use such a relation between Marketing List and Account or Contact entity, please select "pavelkh_ProcessChangesForMarketingListItemSet" as Save Action. In case you need to use any other out-of-box N:N relationship (which is extremely unlikely), you can create a special Save Action for it - similar to the way it is implemented for the "pavelkh_ProcessChangesForMarketingListItemSet" action. Just look at the source code of the AdvancedMultiSelect.Plugins.ItemSet.SaveProcessorExtensions.MarketingListProcessor class.
The next field is read-only "Item Set Entity" field and it's set automatically.
Now you can select attributes for the option/checkbox label and its tooltip. You can see attribute logical names and display names in the autocomplete comboboxes:
The next settings are "Auto-process Item Status" and "Item Status Attribute". General recomendation is to check this checkbox.
If the "Auto-process Item Status" above is checked it means that system will "automatically handle" inactive/obsolete items in the set. It means, for instance, if you had these records (in the picture below) to show in the control, and one of the records had "Inactive" status
then the system would not show "Wave Power" item/option in the set on the form unless it had already been associated with the current Account record before the "Wave Power" Interest record was deactivated. "Item Status Attribute" field determines which attribute to use to identify if the record is inactive or obsolete. In most cases, you will specify "statecode" attribute for "Item Status Attribute", however you can also select any "Boolean" attribute for this purpose as needed.
The next field to specify is "Handle Security Privileges". General recommendation is to check this checkbox. Once it's checked, the system will automatically follow security permission regarding the related entities and make the control read-only on the form if a user, for example, does not have permissions like "Append To" for a related entity, and so forth. The only case when you might consider keeping this setting "unchecked" is the when you do not have special restrictions regarding related entity for all users (the restrictions which could limit possibilities of relating the records). In such a case it might make sense to "uncheck" it in order to the system would not perform additional requests to check permissions.
On the next step, we need specify "Item Set Entity Query". This query will determine a base query to select items to show in the item set on a form. In our case we need to define a query to select records from the "Interest" entity. By default, the system builds a default FetchXml itself once you selected "Item Set Label Attribute" and "Tooltip Attribute" earlier. Also, by default, you are in "Fetch Xml" edit mode and can simply start adjusting the Fetch Xml Query directly as needed.
If you like you can also use a "query bulder" to build the query, just change "Edit Mode" to the "Query Builder" value. Make changes of the query conditions in the builder and press "Update Fetch Xml" button to update the Fetch Xml Query field:
and now have your Fetch Xml Query updated:
Regarding sorting: as for now, you can specify sorting directly inside Fetch Xml query. For instance, you can sort by special "Sort Order" attribute of the Interest entity.
If required, you can specify a description for the Item Set Configuration:
Now that you specified all the field, save the record:
Once the configuration is saved, you can start adding the control itself on the forms you need. Click the "ADD CONTROL WIZARD" button in the ribbon:
and the system will switch to another "Wizard. Add AdvancedMultiSelect On A Form" form where you can specify a template of the multi-select control, some additional parameters along with an exact place you would like to add it to.
First, you need to specify which form you are going to add the control to:
Second, you need to select Tab where it should be placed:
The new control (actually it will be an special web resource embeded) will be places inside a new dedicated Section. Thus, you need to give a name for the new Section inside the Tab you selected on the previous step. Please give the section name, specify a text for the label, specify if you want to show the label and the line under the label:
Now specify exact place of the new section. In the "New Section Location" field, you can select one of the following options:
and then specify a neighboring section in the "Section Name" field:
Now please select a template which will determines how the items be presented inside the control. You can select one of the five existing templates or create you own as needed. Five existing templates can present items in 1, 2, 3, and 4 columns (see template names). Also there is a template which shows the items in 1 column but with additional description field which actually takes data from the attribute you specified for a tooltip.
You can create your own template as needed, just follow the way how it works for the existing templates. Note: if you create your own template, the Display Name of you custom template must contain MultiSelectTemplate word in order to the template appears in the list of templates to select.
NOTE: if you want to use Selectize.js control, please select "pavelkh_/html/templates/selectize_01.html" template.
Finally, specify how many rows the control should occupy:
Now you are ready to add the control. Please note that the current "wizard form" is not intended to be "saved". In order to add the control with the parameters you specified, just click "ADD ON THE FORM" button in the ribbon:
Wait a bit for the operation to complete:
Now the control has been added on the form, and you can continue adding the control to other forms as needed here. Now you can already open an Account record, select the form you need and you are able to see the contol there
If you need to return to the Main form, just click on the "RETURN TO MAIN FORM" button in the ribbon.
If you need to transfer setting from "Instance A" to "Instance B":
- On "Instance A", create a solution which includes
- Forms where you embedded the multi-select controls
- "Dummy Saving attributes" you specified in the Item Set Configurations
-
Export the solution and Import it into "Instance B"
-
Export required Item Set Configurations from "Instance A" into a file. To do this, select the Item Set Configuration records you want to export and click "EXPORT CONFIGURATIONS" button in the ribbon:
You will be prompted to save the exported file. Save it somewhere.
- Import the Item Set Configurations on "Instance B" from the file. To do this, navigate to Item Set Configurations on "Instance B" and click "IMPORT CONFIGURATION" button in the ribbon:
In the new window select the file for import and click "Import" button:
Wait a bit:
In case there is any error during the import, the system inform will you how many "Item Set Configuration" records have been imported successfully and how many were not imported providing error details:
In case all records are imported successfully you get this message:
