You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.

In Blueriq 14 the old Vaadin based development tools are no longer available. If you are using a (recent version of) Material theme the new Angular based development toolbar is automatically integrated in your theme, this is however not the case when you are still using an MVC based theme. It is possible to integrate the new Angular based development toolbar manually in your MVC theme or other frontend technology. This page describes a partial example integration for the default MVC v2 theme that comes with Blueriq 12.13.26.

Preparation

  • The MVC v2 theme must be based on Blueriq 12.13.26 (or up) because the blueriq.onAfterApplicationStart hook was introduced in that version
  • The new (Angular based) development-tools must be active in the Blueriq Runtime
  • Add the @blueriq/devtools library to your package manager or download it manually from the Blueriq Artifactory. Don't forget the peer dependency (rxjs) when downloading manually.
  • If you don't use a package manager add the dependencies manually to your MVC theme .stg file

Steps to integrate

The documentation of the @blueriq/devtools library (see API Documentation) describes which steps you should take to (fully) integrate the Angular based development toolbar in your theme. Use the example script below as an inspiration, it should also be included in your MVC theme .stg file.

loadDevToolsExample.js
/*
 * This example script loads the Blueriq dev tools for a Blueriq application using the MVC v2 theme. It needs the 'rxjs' and 'blueriq-devtools' libraries to have been loaded.
 * Please note that this is NOT a full implementation and should only be used as an inspiration.
 */
(function (blueriq, ko) {

	/**
	 * Get the starting point in the DOM for a Blueriq application
	 *
	 * @returns Element | null
	 */
	function getBqContentDomElement() {
        // '#content' is for forms themes, 'form.form-horizontal' is for dashboard themes
        var bqContentSelector = '#content, body > form.form-horizontal';
		
		return document.querySelector(bqContentSelector);
    }

	/**
	 * Get the DOM element that matches with the supplied Blueriq element. Multiple DOM elements might match, the first one is returned
	 *
	 * @returns Element | null
	 */
	function getDomElementForBqElement(bqElement) {
		// Note: it might be possible to implement this in a more efficient way by wrapping the Knockout nativeTemplateEngine (see https://github.com/knockout/knockout/blob/2bec689a9a7fcaaed37e6abb9fdec648f86c4f81/src/templating/native/nativeTemplateEngine.js)
		var bqContent = getBqContentDomElement();
		if (bqContent) {
			var domElems = bqContent.getElementsByTagName('*');
			// Search through the DOM to find the correct DOM element matching the Blueriq element
			for (i=0; i < domElems.length; i++) {
				var viewModel = ko.dataFor(domElems[i]);
				if (viewModel && viewModel.model) {
					if (bqElement.elementKey === viewModel.model.key && bqElement.sessionId === viewModel.context.session.id) {
						return domElems[i];
					}
				}
			}
		}

		return null;
	}

	/**
	 * Load the Blueriq dev tools
	 *
	 * @returns Promise<DevtoolsHost>
	 */
	function loadBqDevTools() {
		// This environment implementation assumes The Blueriq Runtime and the dev tools are deployed on the same server or reverse proxied to appear that way
		var environment = {
			devtoolsUrl: '/server/devtools/index.html',
			runtimeUrl: '/server',
			targetOrigin: '*',
			get: function (path) {
				return fetch(path);
			},
			getElementInfo: function (domElement) {
				var viewModel = ko.dataFor(domElement)
				if (viewModel === undefined || viewModel.model === undefined) {
					return null;
				}
			
				return {
					elementKey: viewModel.model.key,
					sessionId: viewModel.context.session.id,
					elementName: viewModel.model.name
				};
			},
			locateElement: function (element) {
				return getDomElementForBqElement(element);
			}
		};

		return blueriq.devtools.initializeDevtools(environment);
	}

	/**
	 * After the Blueriq application is started, the Blueriq dev tools should be loaded. the 'onAfterApplicationStart' hook was added in Blueriq 12.13.26
	 */
	blueriq.onAfterApplicationStart = function() {	
		// The Blueriq dev tools are always loaded in this example, regardless of whether the 'devtools' query parameter is passed
		var devToolsHost = loadBqDevTools();

		devToolsHost.then(function (devToolsHost) {
			devToolsHost.activate();
		});

		devToolsHost.then(function (devToolsHost) {
			devToolsHost.addSession({sessionId: bqSessionId});
		});
	}

})(window.blueriq, window.ko);