Bernado Nguyen-Hoan's Blog – Coding Stories from an IT Mercenary

In CRM Portal, different web form steps of a web form can operate on different entities. Imagine you have an Enrolment web form that allows students to enrol in courses. The first step of this form might capture student details (Student entity). The second step might capture the enrolment details (Course Enrolment entity). The Student entity would have a lookup to the Course Enrolment entity in this particular example.

Each web form step of the web form must have a Mode specified, which can be Insert, Edit or ReadOnly. If you want to allow users to be able to edit the form (e.g. save and resume), then you would typically need (at a minimum) a web form where all the steps are set to Edit mode.

As the 2nd step operates on a related record, and not the main record that the user clicked on to launch the form however, there is no OOTB way to configure this as an Edit step.

This is because for Edit mode, we need to provide the step with the source record. OOTB however, the available options are:

1. Query String
2. Current Portal User
3. Result From Previous Step
4. Record Associated to Current Portal User

Since our record is not related to the current Portal User, option 2 and 4 above are no good. Since the record that our 2nd step operates on is different to that of the 1st step, option 3 is also no good. The only viable option for us is the first option, Query String.

The problem here is that CRM Portal does not include the ID of the related record (the one our 2nd step operates on) in the URL when the user navigates to the 2nd step of the form.

So how do we workaround this?

The workaround…

The workaround, at a high level, is to use JavaScript to manipulate the URL to pass the ID of the related record in the query string to our 2nd step. This JavaScript will run on load of the 1st step, and update the action property of the form HTML element. This effectively changes the URL that is used to navigate to the 2nd step.

Perform the following:

• Add the lookup field to the related entity (e.g. new_courseenrolmentid) to the backing CRM form of the 1st step. This enables our JavaScript on the web form step to read this value.
• Make the lookup field above read-only on the backing CRM form so that users cannot update this field on the Portal.
• Configure the following JavaScript for the 1st web form step. This script passes the ID of the related record to the 2nd web form step using the ‘relatedid‘ query string parameter. Please review the in line comment.

function appendRelatedEntityIdToQueryString() {
	//Append the ID of the related record to the form's post URL using the 'relatedid' query string parameter.
	//If this query string param already exists in the URL then it is updated. Else, it is appended to the end of the URL.

	var relatedEntityId = $("#new_courseenrolmentid").val();

	var $form = $("form");
	var formActionUrl = $form.prop("action");

	if (formActionUrl.indexOf("&relatedid=") == -1) {
		//The URL does not contain our param so just add it.
		formActionUrl += "&relatedid=" + relatedEntityId;
		$form.prop("action", formActionUrl);
		return;
	}

	//Find the existing param in the URL and replace its value.
	var queryStringStartIndex = formActionUrl.indexOf("?") + 1;
	var queryString = queryStringStartIndex == 0 || queryStringStartIndex == formActionUrl.length
		? ""
		: formActionUrl.substring(queryStringStartIndex);

	var queryPairs = queryString.split("&");

	var newQueryString = "";

	for (var i = 0; i < queryPairs.length; i++) {
		/*Find the relatedid and replace it.*/

		if (queryPairs[i].indexOf("relatedid=") == 0) {
			queryPairs[i] = "relatedid=" + relatedEntityId;
		}

		if (newQueryString == "") {
			newQueryString = queryPairs[i];
		} else {
			newQueryString += "&" + queryPairs[i];
		}
	}

	formActionUrl = formActionUrl.substring(0, queryStringStartIndex) + newQueryString;
	$form.prop("action", formActionUrl);
}

$(function () {
	appendRelatedEntityIdToQueryString();
});

• Configure the 2nd web form step as follow:
  • Set Target Entity Logical Name to the related entity (e.g. Course Enrolment)
  • Set Mode to Edit
  • For Record Source:
    • Set Source Type to Query String
    • Set Primary Key Query String Parameter Name to relatedid
    • Set Primary Key Attribute Logical Name to the lookup field (e.g. new_courseenrolmentid) on the primary entity

That’s it!

Now you should be able to edit the related entity on your 2nd web form step.

By the way…

Do a lot of JavaScript, CSS, HTML and Liquid coding with CRM Portal? Want to source-control these artefacts and work together with your team without overwriting each other’s code? Then check out my Visual Studio extension CRMQuickDeploy! This simple extension allows you to work with these artefacts in Visual Studio and quickly deploy them to CRM!

This has been tested on xRM Portal CE only.

There may be times where you need to load and display an entity form by JavaScript in CRM Portal. For example, you may have a content page with a link that when clicked, should display an entity form in a modal dialog. You want the modal dialog to display the entity form without any of the site’s branding, navigation, footer, etc.

You can achieve this by leveraging an OOTB service that renders the entity form. This is the same service that is used by the OOTB entity lists and sub-grids.

The service…

The URL for this service is:

[rootWebSite]/_portal/modal-form-template-path/[portalId]?id=[recordId]&entityformid=[entityFormId]

• portalId: The service seems to be happy with any GUID. We used an empty GUID (00000000-0000-0000-0000-000000000000) and it was fine.
• recordId: Guid of the record you want to display
• entityFormId: Guid of the entity form record you want to use

This service returns an HTML document containing the specified entity form loaded with the specified record. The site’s branding, navigation, footer, etc. are excluded, which means the HTML document is ready to be used in a modal dialog via an iframe.

The modal dialog…

CRM Portal uses Bootstrap, so we will use Bootstrap’s modal to load an iframe that invokes the service above and displays the entity form. Again, this is the same approach used by the OOTB entity lists and sub-grids.

Below is the HTML that should be added to the page. The first part (the div) is the normal page content. The second part (the section) is the modal dialog that stays hidden until the user clicks the link in our content. The code for this second part was adapted from the modal element used by the OOTB entity list. Please review the inline comments below.

<!--This is our main content-->

<div>
	Hello world. <a href="javascript:loadEntityFormAsModal();">Click me!</a>
</div>


<!--Code adapted from modal element of entity list. The ID of the section element is used in the JavaScript below.-->

<section id="myModalDialog" aria-hidden="true" aria-label="<span class='fa fa-info-circle' aria-hidden='true'></span> My Modal Title" class="modal fade modal-form modal-form-details" data-backdrop="static" role="dialog" tabindex="-1" style="display: none;">
	<div class="modal-lg modal-dialog">
		<div class="modal-content">
			<div class="modal-header">
				<button aria-label="Close" class="close" data-dismiss="modal" tabindex="0" title="Close" type="button">
					<span aria-hidden="true">×</span><span class="sr-only">Close</span>
				</button>
				<h1 class="modal-title h4" title="My Modal Title">My Modal Title</h1>
			</div>
			<div class="modal-body">
				<div class="form-loading" style="display: none;">
					<span class="fa fa-spinner fa-spin fa-4x" aria-hidden="true"></span>
				</div>

				<iframe src=""></iframe>
			</div>
		</div>
	</div>
</section>

Next we need to add the below JavaScript to the page. If embedded on the same page, then should be wrapped in <script> tags. This script was adapted from the OOTB entity-grid.js script. Please review the inline comments below.

function loadEntityFormAsModal() {
	//Code adapted from entityGrid.prototype.addDetailsActionLinkClickEventHandlers in \js\entity-grid.js.

	//Setup the record and entity form you want to display
	var portalId = "00000000-0000-0000-0000-000000000000";
	var recordId = "B3FEC1EB-7F68-E811-859D-B86B23AC9F7C";
	var entityFormId = "396293DD-9D46-E811-8551-B86B23AC9F7C";

	//Form the URL to the service
	var url = "/_portal/modal-form-template-path/" + portalId + "?id=" + recordId + "&entityformid=" + entityFormId;

	//This ID needs to match the ID of the modal section element.
	var $modal = $("#myModalDialog");

	//Retrieve the iframe of the modal and set it load the service
	var $iFrame = $modal.find("iframe");

	$iFrame.attr("src", url);

	//Hook in handler to hide loader image when done loading
	$iFrame.on("load", function () {
		$modal.find(".form-loading").hide();
		$modal.find("iframe").contents().find("#EntityFormControl").show();
	});

	//Show the loader image at start
	$modal.find(".form-loading").show();
	$modal.find("iframe").contents().find("#EntityFormControl").hide();

	$modal.on('show.bs.modal', function () {
		$modal.attr("aria-hidden", "false");
	});

	$modal.off("hidden.bs.modal.entitygrid").on("hidden.bs.modal.entitygrid", function () {
		$modal.attr("aria-hidden", "true");
	});

	$modal.modal();
}

That’s it!

And there you have it, you can now dynamically launch an entity form in JavaScript. Leveraging the OOTB service means that any entity permissions you may have setup will be honoured, and any JavaScript attached to the entity form itself will also be executed.

By the way…

Do a lot of HTLM, JavaScript, CSS and Liquid coding in CRM Portal? You should check out my Visual Studio extension CRMQuickDeploy. This allows you to work with HTML, JavaScript, CSS and Liquid in Visual Studio and quickly deploy them to CRM Portal. Not only this improves your productivity, but also allows you to source control these artefacts and facilitates scenarios where multiple developers work on the same code base.