Resco JavaScript Bridge
Resco JavaScript Bridge (also known as JSBridge) is a part of the Resco Mobile CRM application (client application) which offers interaction of custom HTML pages with the client application. It provides an API for accessing/modifying the data and controlling the user interface components from within the JavaScript.
This document contains the description of the main principles of the JavaScript Bridge, main features and API areas, as well as a brief description of common errors and debugging guidelines. It covers the very basics and getting started topics like including the JSBridge.js file or recommended HTML page structure. It also contains many examples with their description, but for the full list of all available methods and functions see the JavaScript Bridge Reference document: https://www.resco.net/javascript-bridge-reference/
The main objective of this document is to make you familiar with the JSBridge concepts and showcase the most common functionality on the examples. After reading this document, you should be able to create and debug your own custom pages and include them into the client application, however, the knowledge of HTML and JavaScript technology is recommended at least on a medium level.
Including the JSBridge.js file
To start using the features described in this document, it is necessary to include the JavaScript Bridge file into the custom page. This is done by simply including JSBridge.js file e.g. like this:
<script type="text/javascript" src="JSBridge.js"></script>
You can always download the latest version of this file at Resco GitHub page:
While every client application version has a corresponding JSBridge version with specific features, we recommend using the same JSBridge.js file as your client app.
- Find recent versions in GitHub history: https://github.com/Resconet/JSBridge/blob/master/src/JSBridge.js
- Find older versions in this archive: http://www.resco.net/MobileCRM/downloads/JSBridge_Versions.zip
However, it is not enough to include the above-mentioned line into your page or script, it is necessary that also the file itself is present at the specified location. If you are going to use your pages as Offline HTML (see part also and https://youtu.be/R7GpdC_y17Y) you also need to upload the JSBridge.js file as the Offline HTML. Similarly, if you are accessing these pages online, the JSBridge.js file should be present at the respective location.
Recommended META tags
When constructing your HTML pages, there are couple META tags that are useful to know and use.
The first one is used on the platforms that utilize Internet Explorer (Windows 7, 8?) and it makes sure that Internet Explorer 9 Document Mode is being used. Without this line, you might get errors when trying to use some of the methods from JavaScript Bridge on these platforms (Typically, a “Javascript Runtime error: ‘MobileCRM’ is undefined” error).
To enable IE9 Document Mode include following line into the page’s HEAD section:
<!-- Activate IE9 document mode, if available -->
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
The second useful tag is for iOS devices. Not using this one won't result in errors (so it is optional if you are going to use it or not), however, it will allow the page to be pinch zoomed, which is undesired for the custom UI components that are typically built on top of JSBridge. Also, the page and its UI might be loaded in smaller size (to fit the screen) which is typically another undesired effect.
To disable pinch zooming and to load the page on iOS in its corresponding size, use the following code snippet in the HEAD section:
<!-- Defined iOS viewport -->
<meta name="viewport" content="initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=false">
Note that using any of those tags on platforms that don’t support them (e.g., Android) doesn’t cause any issues, so it is a good practice to include these on all the pages.
Offline HTML
Resco JavaScript Bridge comes really handy when you want to visualize mobile data in a very specific way or if you need to capture more complex business logic in the application. But it wouldn’t be such a powerful tool without the possibility to include the custom pages into the customization package, so they don’t have to be available always online.
The option to include the pages (and generally any files) into the customization package is referred to as the Offline HTML capability. You can find this section in the app project in Woodford. You can use it to upload local files and include them in your project. Then, during synchronization, these files are downloaded to the device and available also locally – even offline.
As has been mentioned in previous sections, don’t forget to upload the JSBridge.js file if your pages make use of the Resco JavaScript Bridge. Besides that, you can upload any file – HTML pages, JavaScript files, images, etc., and then reference them on an iframe in the project. To distinguish the local offline files, start the URL with file:// and then continue with the path as in Offline HTML directory. For example, if you have uploaded the file Test.html into the root folder of Offline HTML, the URL would look like this file://Test.html). You can also click Browse to select from files in the Offline HTML folder.
URL parameters
When constructing the URLs for iframes on entity forms, you can use the following syntax to dynamically create the URL from an entity’s properties. When you use an entity field's logical name (all lowercase) in curly brackets, for example {address1_latitude}, the application replaces the parameter at run time with the content of the field.
If you use the URL file://mypage.html?{name} and you have a field “name” on the entity, at run time, the following URL could be used file://mypage.html?John.
Because of platform-specific limitations, we recommend getting the full URL with all the parameters using MobileCRM.Platform.getURL function. Some platforms will ignore the additional parameters, so if you try to access them via standard means, e.g., document.URL you might get different results on different platforms.
All this can be very useful for a dynamic construction of the URLs and for passing parameters. However, there are some limitations.
Due to these limitations, it might be a better idea to access entity properties via the Entity Form object, instead of passing the parameters via URL. While the parameters you can pass are more or less limited to the entity fields and the same fields can be accessed via the entity object on the Entity Form, this is the recommended and cleaner way to do it – see section Entity form for an example.
Limitation of external web pages
The Windows 8.1 version of the app does not support JSBridge.
Web browser component
In Resco mobile apps, HTML pages are displayed by using Web Browser Component or its equivalent on the respective mobile platform. This means that the browser window is displayed in the mobile app with your custom content.
The browser is, in fact, the standard browser installed on that particular device – on iOS it's Safari, on Android Chrome, and on Windows devices it's Edge or Internet Explorer. So, when creating your custom pages, consider the capabilities of the corresponding mobile browser. To display the content correctly on all platforms, make sure that you are using HTML and JavaScript features supported by all browsers and their versions on the targeted mobile devices.
Another important aspect to consider is that when a page is displayed in Web Browser Component, some of the features might not be enabled. A typical example is Window.Print() – even though this function is supported by many mobile browsers, when the browsers are running in the Web Browser Component (i.e. in Resco mobile application) this feature is disabled.
Unfortunately, there is no universal list of disabled features, commands, or tags – this differs from platform to platform, browser version, OS version, and so on. To be entirely sure, make sure you test the application and the custom content on all the devices.