How to install

Import the tuneMultiCheckBox_1_0_0_x_managed.zip solution (find the current one in the Download section).

Important:
The checkbox on the images below should be checked when you import the solution

if you use 2013:
EnableSDKMessages.JPG

if you use 2011:
EnableSDKMessages2011.JPG

If you would like to start with demo examples first, please read the "How to install Demo Examples" section further down.

How to configure

In order to understand how to configure the multicheckbox set on a form let's consider the following example.
Let's assume:
  • we have some simple custom Category entity and it has the following structure:
    • Entity logical name: "new_category"
    • The entity contains the following fields:
      • new_name (Category Name)
      • new_order (Order number of Category)
      • other out-of-box fields

We would like to categorize our account records using the list of categories in the Category entity.
We want each an account could be associated with multiple categories.
In order to do that we create a new N:N (many-to-many) relationship between Account and Category entity. Let's call it "new_new_category_account":
AccountCategoryRelationship.jpg

Now we would like to have a multicheckox section section on the Account form to be able to select required categories quickly.

Let's start configuring that.

The first step we have to do is to create a "fake" text field on Account entity for our mulicheckbox set (the reason is described below):
fakefieldexample.jpg

The reason of this "strange step" above is that it's only a possible "way" to make our multicheckbox functionality to work for "Create" form mode case.
(For those who are interested in how it works "behind the scene": the system stores the list of checked/unchecked checkboxes in this "fake" field so that appropriate plug-in functionality be able to perform corresponding association/disassociation for the related records. In fact no data is stored in this field (plug-in cleans the field up after reading the value passed)).

Next step is making changes in the configuration file:

Open the the tuneMultiCheckBox solution:

ListOfSolutions2.jpg

select the "Configuration" section, and press the link marked below:

tuneMultiCheckBoxSolutionConfigLink.JPG

the webresource window below is open:

configxmlwebresource.JPG

We need to edit this xml file the way you can see below:

configxmdetails01.jpg

We need to add <crmEntity> node inside <crmEntities> node for each an entity where we want to have multicheckbox functionality on form.
In our current case it's Account entity only.
So, we add the following node: <crmEntity logicalName="account">
Then we need to add <checkboxSet> node inside <crmEntity> node for each a multicheckbox set we want to have on the entity forms.
In our current case we want to have a checkbox set related to categories.
Let's consider attributes used for <checkboxSet> node on the image above.
  • name="accountcategories". This attribute defines a name of the checkbox set. We will use it later when referring to the checkbox set from the form.
  • description="Provides a set of categories to associate with an account". This is just a description of the checkbox set (in order to not to forget the purpose of the set in case we have multiple checkbox sets for a single entity)
  • fakeSavingField="new_checkboxset_new_new_category_account". This is the name of the "fake" field we created and considered on the previous step above.
  • relationshipName="new_new_category_account". This is the many-to-many relationship name we use for the checkbox set
  • labelFieldName="new_name". This is the name of a field from the FetchXml defined below. The values of this field will be used as a label for the checkboxes.

For each a <checkboxSet> node we need to have a child <fetchXml> node that in turn contains the text of Fetch Xml we want to use to get the list of available options for the checkbox set.
In our current case we have a fetch xml that "give" us a list of all Active Categories sorted by custom Order field.

Note: We can define multiple <checkboxSet> nodes inside <crmEntity> node. We only need to have separate fake fields in question for each a checkbox set.

Please publish the edit xml webresource after you complete the changes

The last step is to configure entity form itself.
In the current case we configure the Account form as follow:

AccountFormConfig1.jpg
  • we insert a new "one column" section to the form

insertSection.JPG
  • we add our "fake" field to the section (new_checkboxset_new_new_category_account) and make it invisible by default

invisibleFakeField.JPG
  • we insert a new Web Resource to the section insertWebresource.JPG

and configure it the following way:

webresourceConfig1.jpg

On the Web Resource Properties dialog above we need to specify the following things:
  • Custom Parameter(data): we write here: checkboxSetName=accountcategories (where "accountcategories" is the name of the checkbox set we defined in the xml configuration on the previous step above)
  • The checkbox "Pass record object-type code and unique identifier as parameters." should be checked
  • Web resource lookup field on the top of the dialog should contain a reference to a template file you would like to use for the checkbox set. (In the current case on the image above we select "tunecrm_TuneCrmTools/html/tuneMultiCheckBox/templates/template01.html" template. This template represent the list of checkboxes in 3 columns and uses CRM 2011 background \ view)

In general you can select one of the 4 templates predefined:

templateLookup.JPG
  • default2011.html: one column checkbox list with CRM 2011 background \ view
  • default2013.html: one column checkbox list with CRM 2013 background \ view
  • template01.html: three column checkbox list with CRM 2011 background \ view
  • template02.html: three column checkbox list with CRM 2013 background \ view

In case you would like to have e.g. a list of checkbox in two column list you can open template01.html webresource file and make the appropriate changes here (var columnCount = 2;)

templateEdit1.JPG

You can also make other your own changes in the templates layout and appropriate css files as needed.

Now, publish the form changes and you can start using the multicheckbox set on the account form:

AccountFormExample.jpg

Note: we will work on a convenient configuration wizard in the next versions in order to simplify defining configuration settings




How to install Demo Examples

You need to import one of the example managed solutions below to get the demo examples.
Note: the main tuneMultiCheckBox_1_0_0_x_managed.zip solution should be imported before the example solution.
  • Import the tuneMultiCheckBoxExampleOfUseForCRM2011_1_0_0_x_managed.zip example solution if you use CRM 2011
  • Import the tuneMultiCheckBoxExampleOfUseForCRM2013_1_0_0_x_managed.zip example solution if you use CRM 2013

(find the current example solution files in the Download section).

Please note that the example solution makes changes to your data structure and adds some test data.
Please consider using it on some test environment only just in case.

The example solution makes the following changes:
- Creates a new test entity (Category)
- Updates Account and Contact entities (adjusting their forms and adding new test N:N relationships).
- Adds a new test N:N relationship to Campaign entity
- Adjusts tuneMultiCheckBox configuration webresource file (tunecrm_TuneCrmTools/xml/TuneMultiCheckBox/config.xml)

After the example solution is imported, please add some test data:
Open the example solution:
ListOfSolutions1.jpg

Select the "Configuration" section and press the "Add Test Records" button:
AddTestDataForExamples.jpg

Wait for a couple of seconds.
After the records are added you can see the following message:
AddTestDataForExamples2.jpg

Just in case, here are the records added (to the Campaign entity and to the new Category entity):
AddTestCampaigns.jpgAddTestCategories.jpg

In order to try the example please open either some Account or Contact. You will see the multicheckbox sections on them.
AccountExample.jpg
ContactExample.jpg

Note for CRM 2013: please select "Information" form to see the multicheckbox sections on the form:
AccountInformationFormSwitch.jpg

Last edited Mar 29, 2014 at 6:49 PM by tunecrm, version 40