Debugging offline HTML

From Resco's Wiki
Jump to: navigation, search
Resco JavaScript Bridge

When creating and testing custom HTML pages and scripts, it is often necessary to debug the JavaScript code to see what is actually happening. You can use alerts and logging as a substitute for this option, but in general, debugging gives you much quicker insight into the actual execution.

Depending on the platform you are working on, there are different ways how to enable debugging. This document describes the approaches for Windows (7 and 8.1) and iOS. It is also described how to enable debugging for Android, but you will need a device with Android OS v4.4 at least.

Resco Mobile CRM JSDev edition

We offer a development/debugging version of Resco Mobile CRM app: https://github.com/Resconet/JSBridge/tree/master/MobileCRM

This version of the app opens a port for JavaScript debugger and allows the HTML root overriding.

Warning Don't use in production!

Windows Desktop/Store

Visual Studio 2012/2013 or later supports script debugging in external applications. It can be attached to Resco mobile apps (the standalone installer version for Windows 7 and the Microsoft Store app version for Windows 10) and you can use it to debug your offline HTML script code.

Before trying this, you have to enable the script debugging in Internet Explorer. Open Internet Options. On the Advanced tab, uncheck Disable script debugging.

Debug 001.png

After that, it will be possible to attach the running process “MobileCRM.exe” to the script debugger in Visual Studio. Uncheck all code types except the “Script”.

Debug 002.png

Visual Studio provides comfortable script debugging including the inline editing. To apply the changes, you need to close the form that contains the web browser. The easiest way to do that is to open the Setup or Sync dialog.

Debug 003.png

It is also possible to debug the Microsoft Store version of the client application. The only limitation is that inline editing is not allowed.

Debug 004.png

Debugging the desktop app (Windows 7) using Chromium browser

  1. In the app, navigate to the iframe that you want to debug.
  2. Open Google Chrome.
  3. In the address bar, enter http://localhost:9222 (debugger port).

This requires using the Resco Mobile CRM JSDev edition.

Debugging the store app (Windows 10) webview using Microsoft Edge DevTools Preview

  1. Install and launch Microsoft Edge DevTools Preview (free app available from the Microsoft Store).
  2. Start Resco Mobile CRM and navigate to a form that uses iframes.
  3. In the DevTools, click the debug target that you want to debug.

Edge devtools.png

Visual Studio integration

To make the script debugging even easier, we provide the Visual Studio extension “Mobile CRM Integration” which adds the command Run in Mobile CRM into the Visual Studio Tools menu and provides a single-click experience for connecting to a running instance of Mobile CRM.

The idea is quite simple – create a project in Visual Studio and add all the HTML, JavaScript, CSS, and other files that you typically have in the offline HTML folder of Woodford’s app project into the VS project. When you execute the command Run in Mobile CRM, it will locate your currently running instance of Windows 7 debug build of Mobile CRM app and replace all the files in the downloaded offline HTML folder with the files from your project.

This makes the deployment of a new field available in one click in Visual Studio. Additionally, it offers automatic debugging support, so when you add breakpoints into your files, these will be triggered, because the command attaches also the debugger to the app. This applies to TypeScript as well, so it is the easiest way to debug TypeScript (the breakpoints are triggered in the TypeScript code, not in the JavaScript code).

Generally, the process has the following steps:

  1. Download and install a development build of Windows 7 version of Resco Mobile CRM app.
  2. Download and install the Resco's VS Integration package. (Visual Studio needs to be installed first.)
  3. Create an app project in Woodford and add the files into the offline HTML section. Note: These can be placeholder (empty) files for the moment – you just need them for the next step.
  4. In the project, add Iframes with HTML files from Offline HTML section to the forms / views / etc. where you want to use them.
    Note: This is the only way to attach an HTML file to an Iframe, so this is where you define where to use which file.
  5. Create a Visual Studio solution / project and add the offline HTML files into the project.
  6. Synchronize the development build of a Windows 7 app with the server/app project to get the Iframes into the app.
  7. Use Run in Mobile CRM command to copy the version of the files from your Visual Studio project into the app’s local folder for comfortable development.

This way you can quickly develop and debug the JavaScript code – just don’t forget that once you are done, you need to upload the files from your VS project back to Woodford app project as offline HTML, since the files were overwriting only the local copy of the offline HTML, not the server version.

VS Integration also allows you to override the Offline HTML root to your solution folder. See this section for further details.

Debug 005.png

Android

Android supports debugging of the web pages opened in third-party applications by using remotely attached Chrome inspector. It has been supported since Android 4.4 (KitKat).

Mobile CRM application doesn’t support debugging by default for security reasons. However, it’s possible to switch it on by calling the method “enableDebug” from your Offline HTML solution. See following link for details: https://www.resco.net/javascript-bridge-reference/#MobileCRM_Bridge_enableDebug

Developers can use the JSDev edition of the Mobile CRM app which supports the debugging by default. It’s available at: https://github.com/Resconet/JSBridge/tree/master/MobileCRM

In addition to enabled debugger, this edition supports the Offline HTML overriding (see below).

To learn more about the Android remote debugging, take a look at Google tutorial: https://developers.google.com/chrome-developer-tools/docs/remote-debugging

iOS

iOS also supports debugging of the web pages opened in third-party applications. However, apps from the AppStore (or even from the TestFlight) live in the sandbox which prevents development tools connecting to them. That’s why we started to provide the special installation that can be used for development purpose. It’s available at

https://github.com/Resconet/JSBridge/tree/master/MobileCRM

Installing Debug Build on iOS Simulator

To install the debug build on iOS Simulator follow these steps:

  1. Open Xcode menu: Xcode / Open Developer Tool / iOS Simulator
  2. Open Terminal, go to iPhoneSimulator directory and type following command:
xcrun simctl install booted MobileCrm.app

Installing Debug Build on iPhone/iPad

To install the debug (JSDev) build follow these steps:

  1. Create iOS Developer account at https://developer.apple.com
  2. Create a Wildcard App ID for bundle ID “*” (Identifiers / App IDs)
  3. Create an iOS app development provisioning profile for this AppID and download it (as Wildcard.mobileprovision file)
  4. Log in to your account from Xcode (Preferences / Accounts)
  5. Create an iOS Development signing identity (View Details button)
  6. Download iResign tool from https://www.resco.net/downloads/iReSign.app.zip
  7. Unzip it and run it
  8. Provide the path to IPA (from this folder), path to Wildcard.mobileprovision file and choose your development signing identity
  9. Specifying custom entitlement is not recommended. Leave that box empty. Entitlements are taken from your provisioning profile automatically.
  10. Changing the bundle ID is optional. Rather leave that box unchecked
  11. Resign the IPA and deploy it via iTunes or Xcode/Devices.
  12. If it didn’t work, make sure that device was included in your provisioning profile.

Preparing the debugging environment

Debugging on iOS (both device and Simulator) is performed by using Safari WebInspector on the Mac. We recommend using the latest version of Safari or at least the version corresponding to Safari version on your device.

To enable remote debugging you will need to enable the WebInspector in Safari settings (option “Advanced”).

Debug 006.png

Then enable the “Develop” menu in Safari preferences (tab Advanced) on Mac.

Debug 007.png

Now you can connect your iPad via USB, open the client application and navigate to the form showing your offline HTML. After that you should observe the submenu “iPad” under Safari Develop menu showing the client application and HTML file opened on its form.

Debug 008.png

Click on it to connect WebInspector.

Debug 009.png

Hint If Safari is still missing the iPad option, try to quit it and restart once more.

Change local copy of offline HTML files

The typical development cycle for Offline HTML development is as follows:

  1. Change the local copy of the Offline HTML solution.
  2. Upload changed files to Woodford.
  3. Publish Woodford mobile project.
  4. Synchronize client app to get new customization.
  5. Verify the changes.

This can be frustrating and time-consuming. Fortunately, there are some shortcuts that can save a vital portion of the development/testing time.

One of the shortcuts is the possibility of changing the local copy of the Offline HTML files, which is possible on iOS Simulator and Windows platforms. Offline HTML reside in the WWW subfolder of the app data.

In case of Windows 7 Desktop application, the application data are stored in the following folder: %APPDATA%\MobileCRM

which is typically: C:\Users\{UserName}\AppData\Roaming\MobileCRM

In case of Windows Store (Win10), it’s %LOCALAPPDATA%\Packages\Resco.MobileCRM_{StoreId}\LocalState\MobileCRM

which is typically: C:\Users\{UserName}\AppData\Local\Packages\ Resco.MobileCRM_{StoreId}\LocalState\MobileCRM

In case of iOS Simulator, app files are also applied to the file system at: ~/Library/Developer/CoreSimulator/Devices/{SimulatorID}/data/Containers/Data/Application

To find the right application within this folder, try to search for a specific file (like JSBridge.js) inside this root.

To find the SimulatorId of the currently booted simulator, open the Terminal app and insert the following command: xcrun simctl list | grep Booted

Override offline HTML root

Another shortcut that can save a lot of development time is overriding the offline HTML root. Once you installed the JSDev edition of our app from Debug Builds (see above), the app handles a special URL that can change the root from which it takes the offline HTML files.

First, place your offline HTML solution on a local or remote HTTP server that's reachable from testing the device. It can be any type of server (for example, IIS or Apache), but we recommend using Visual Studio Typescript project which automatically starts the IIS Express instance with your offline HTML files. We provide a template for an empty offline HTML solution here:

https://www.resco.net/downloads/OfflineHtml.zip

To make the IIS Express available from the local network, specify your IP address as the target URL instead of “localhost” and use the following command to reveal the URL: netsh http add urlacl url=http://10.211.55.5:4199/ user=everyone

When a local copy of offline HTML solution is available via HTTP, follow these steps to override the root:

  1. Go back to your iOS/Android device or simulator.
  2. Open Mobile CRM JSDev edition app and minimize it – let it run on background.
  3. Open the web browser (Safari/Chrome) and type the following URL:
    mobilecrm:// htmlRoot?set=http://{IP Address}:{Port}

Your mobile app should be brought up from the background and display a message that the offline HTML root was changed. From this moment, the app should take all offline HTML files from your HTTP server instead of local app storage.

If you prefer command-line tools instead of typing the URL to browser, use the following ADB command for Android:

adb shell am start -a android.intent.action.VIEW -d mobilecrm://htmlRoot?set=http://{IP Address}:{Port}

or this one for iOS Simulator:

xcrun simctl openurl booted mobilecrm://htmlRoot?set=http://{IP Address}:{Port}