wq.app 1.3 alpha

wq.app 1.3 alpha is a preview of the next version of wq.app, as part of the wq 1.3 alpha release. This is perhaps the most ambitious version of wq.app to date, bringing a brand-new UI renderer based on React and Material Design, while maintaining backwards compatibility with jQuery Mobile-based projects (for now).

This release achieves the third goal in the roadmap for wq.app 2.0. In addition to the tasks listed in that goal, the map engine and app install mechanisms have seen significant overhauls. In all, the following replacements have been made:

Deprecated	Replacement
AMD / RequireJS	ES Modules
jQuery Mobile + Mustache	React + Material UI
Leaflet	Mapbox GL
Application Cache	Service Worker
PhoneGap Build	Installable PWA and/or React Native + Expo

The main PRs for this release are #115 and #122.

ES Modules

Projects created with wq 1.3 now use ESM syntax, even when not using npm.

When wq.app was created, there was no standard JavaScript module format. wq.app instead leveraged RequireJS and AMD, which combined (some of) the customization capabilities of the npm ecosystem, together with (some of) the simplicity of using a plain <script> tag. Since then, ECMAScript modules (import/export syntax) have become the standard solution for both web and npm. wq.app 1.3 leverages ESM to provide users a choice between all of the customizability of npm, or all of the simplicity of a script tag. The old RequireJS build system has been deprecated and replaced with ... no build system at all!

Instead, wq.app 1.3 provides a pre-compiled ESM build, wq.js, which contains wq's core modules, the new UI renderer, the new map engine, and the third party dependencies for all of the above. This script can be leveraged via a single <script type=module> tag, or with the small number of configuration modules provided by the new wq start template.

Upgrade Notes

wq.app 1.3 still provides the old RequireJS/AMD build scripts and related commands (wq init, wq optimize, wq babel, etc.) for compatibility with older projects. However, this support will be dropped in wq 2.0. Thus, it may be good to start migrating to an ESM format sooner rather than later.

Switch to npm

The most natural route is likely to switch to using wq start --with-npm, because that provides the option to install @wq/jquery-mobile and (temporarily) defer the need to rewrite the UI layer. In addition, projects with heavily customized r.js configurations will more likely want to leverage the full capabilities of npm. In particular, you will want to use npm if you need to transpile and optimize ES6 code using babel (#83), for example to support Internet Explorer.

Switch to pre-built ESM

On the other hand, if your project contains minimal customization, you may find it easiest to switch directly to the new wq.js and its built-in UI, plugging in the configuration generated by wq.db and then making minor adjustments as needed. Note that the new setup leverages Django's staticfiles app, which means that:

1. The development server will automatically serve the latest contents of the app/ folder (see wq/wq-django-template#21).
2. ./manage.py collectstatic will deploy the app/ folder to the production directory htdocs/static/app/ (see wq/wq-django-template#6).

As of wq.app 1.3, the wq build command can automatically detect the project type by examining wq.yml for an optimize section, and by checking for the existence of package.json (see #119). Projects without either of these are assumed to be using the pre-built ESM.

React + Material UI

@wq/react + @wq/material is the new default UI renderer.

wq.app initially used jQuery Mobile, together with a customized Mustache template engine, to provide offline rendering capability. However, the jQuery Mobile project has not released any update for several years. In addition, the need to generate and compile dozens of Mustache templates into a JSON fixture made wq unecessarily complicated to use, even though the process was partially automated.

wq.app 1.3 instead provides a flexible render based on React, Material UI and React Native Paper. It is enabled by default for new projects, and includes default React components for all @wq/app route types. This means that for simple projects, it is not necessary to explicitly define any UI screens, except to customize the defaults.

To facilitate both rendering modes, the UI is now configured by registering a renderer plugin with @wq/app:

module	description
@wq/react+@wq/material	New Material Design renderer based on React and React Native
@wq/jquery-mobile	Legacy renderer based on jQuery Mobile and Mustache.js

Upgrade Notes

Continue using jQuery Mobile

If you are upgrading from an older version of wq with npm, you will need to to explicitly install and register the @wq/jquery-mobile renderer:

import app from '@wq/app';
import jqmrenderer from '@wq/jquery-mobile';
app.use(jqmrenderer);

If you are upgrading from an older RequireJS/AMD template, wq/jquery-mobile.js will be imported automatically in wq/app.js. However, note again that RequireJS support will be dropped in wq 2.0. The wq maketemplates, wq scss, and wq mustache commands are also deprecated and will be removed in 2.0.

Note that wq/template.js, wq/patterns.js, and wq/photos.js are now contained within @wq/jquery-mobile and do not need to be registered separately.

Switch to @wq/react + @wq/material

@wq/react + @wq/material presents a radical departure from the old rendering system, and there is little that can be directly ported. That said, it should be relatively easy to plug your existing wq.db configuration into the new renderer, and obtain a usable default interface to iterate on. Two main things to keep in mind are:

1. Mustache rendering is no longer used, so templates/, master_templates/ and associated tooling is no longer necessary. In addition, it is no longer necessary to define the UI for the entire application, just for the parts where you want to override the defaults.
2. The old run($page, routeInfo) plugin hook is no longer available, as it relied on the jQuery Mobile-specific $.mobile.activePage object.

In both cases, the new way to provide custom functionality is by registering one or more custom components with @wq/app. Custom components can override individual inputs or entire views.

Mapbox GL

@wq/mapbox is the new default map engine.

wq.app 1.3 provides the option to use Mapbox GL for the map engine. Key advantages over Leaflet include support for vector tiles, and native SDKs for Android and iOS. Leaflet-specific code in the old @wq/map has moved to @wq/leaflet, while the new Mapbox GL renderer is available as @wq/mapbox. Both depend on the @wq/map plugin, which now just handles the map configuration and state.

module	description
@wq/map+@wq/mapbox	Mapbox GL JS integration for web and Mapbox Maps SDK for Android & iOS.
@wq/map+@wq/leaflet	Leaflet integration (web only).

Upgrade Notes

Continue using Leaflet

If you are upgrading from an older version of wq with npm, install and import @wq/leaflet instead of @wq/map. If you are upgrading from an older RequireJS/AMD template, then wq/map.js is actually an alias for @wq/leaflet and should work the same as before. However, note again that RequireJS support will be dropped in wq 2.0.

Switch to @wq/mapbox

@wq/map's layer configuration syntax is designed to be engine-agnostic, so switching from @wq/leaflet to @wq/mapbox will generally just work. However, you will likely want to take advantage of Mapbox GL's vector tile support. To do so, you will need to find a vector tile provider online or host the tiles yourself. Providers known to work with @wq/mapbox include Mapbox (obviously), ESRI, and MapTiler Cloud.

Service Worker

Browsers are removing support for Application Cache, which has been superseded by Service Worker.

The Application Cache standard is being deprecated by browser vendors, and for good reason - it was inflexible and hard to use. wq now includes built-in support for Service Workers instead. The new wq serviceworker command replaces the wq appcache command for projects not using npm. For projects using npm, the provided @wq Create React App template already includes code to generate a service worker.

Upgrade Notes

The wq appcache command will be removed in wq 2.0, and remains in 1.3 for backwards comparability. However, Application Cache has likely already stopped working for your users. To use service workers in an project with npm, change serviceWorker.unregister() to serviceWorker.register() in src/index.js. For projects without npm, use the wq serviceworker command by adding a serviceworker section to your wq.yml, perhaps basing it on the new default template. Then, make sure your service worker is registered by adding the following line to your main JS file:

navigator.serviceWorker.register('/service-worker.js');

Installable PWA

PhoneGap Build is no more... but wq.app generates installable PWAs instead!

PhoneGap Build was the main way to compile wq-based apps for distribution on the Android and iOS stores. However, the service has recently gone offline, and general interest in Cordova/PhoneGap has waned. Installable progressive web apps, or PWAs, provide a full-featured alternative that should be suitable for many projects. On Android in particular, PWAs are effectively indistinguishable from native apps once installed. wq has long supported the "Add to Homescreen" option, but the addition of Service Worker support significantly increases the likelihood that the phone UI will automatically prompt the user to install the application (see #63, #107).

Upgrade Notes

To create a progressive web app, be sure to enable wq.app's service worker support. Then, customize your app icon by editing app/public/images/icon.svg, and saving it to app/public/images/icon-1024.png. Customize the title and colors in app/public/manifest.json, run ./deploy.sh again, and ensure HTTPS is enabled. Your web app should be ready for installation.

The wq phonegap command remains, but will likely fail when sending the payload to the build servers. It will be removed in wq 2.0 (see #121).

React Native + Expo

wq.app now supports React Native and Expo if you need a truly native app.

Sometimes even a progressive web app is not enough, particularly if your app is intended for a wide audience of users who are used to finding apps on the stores. Or, perhaps you may want to take advantage of Mapbox's native SDKs. To support these use cases, @wq/react, @wq/material, and @wq/mapbox all support both React Native and Expo.

Upgrade Notes

To use React Native or Expo, it may be easiest to start by creating a project using the recommended tools for each platform. Then, replace the contents of src/ with the contents of @wq/cra-template's src/ directory. It is possible (and recommended) to use the same src/ directory for both the web and native deployments of a wq.app-based project. Finally, you will need to install all additional dependencies as described in the documentation for @wq/material and @wq/mapbox.