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:
|AMD / RequireJS||ES Modules|
|jQuery Mobile + Mustache||React + Material UI|
|Application Cache||Service Worker|
|PhoneGap Build||Installable PWA and/or React Native + Expo|
The main PRs for this release are #115 and #122.
Projects created with wq 1.3 now use ESM syntax, even when not using npm.
<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.
wq.app 1.3 still provides the old RequireJS/AMD build scripts and related commands (
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:
- The development server will automatically serve the latest contents of the
app/folder (see wq/wq-django-template#21).
./manage.py collectstaticwill deploy the
app/folder to the production directory
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:
|@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|
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
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 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:
- Mustache rendering is no longer used, so
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.
- The old
run($page, routeInfo)plugin hook is no longer available, as it relied on the jQuery Mobile-specific
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.
@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.
|@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).|
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.
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.
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
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:
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).
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
./deploy.sh again, and ensure HTTPS is enabled. Your web app should be ready for installation.
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.
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.