An app, of course, is not a web site. Locations within an app don’t have “addresses” the way that web sites do—or at least, the way that web sites should. In recent years, many of the “apps” that happen to live on the web are created without any regard to addresses whatsoever, the so-called “single page applications” (SPA’s). You can sit around all day playing with a “single-page” app without the address in your address bar ever changing. This view of a “web app” is well suited to a system like Cordova, where there are, again, no addresses.

However, if you do actually use addresses, then you understand that references have to be portable. When you’re making a link to something, you don’t know, can’t know, and don’t want to know where it will be used. The simplest way to deal with this is to “root” all of your paths, that is, give the full path to everything. For example, instead of referring to style.css, you refer to /style.css. For this to work, you have to assume that site lives at the root of the domain, so the tradeoff is that the site itself is no longer portable (e.g. to a subdirectory).

But this leads to a subtle problem when packaging the site for Cordova, although I confess that I don’t quite understand why, as the workaround is quite simple and not the least bit astonishing. Cordova “serves” files from a static location using a file:// protocol with some arbitrary (and platform-specific) directory prefix. Rooted paths, then, are resolved to a nonsensical location instead of being resolved relative to the location of the index file, as any human would expect.

A few people noticed this problem, starting around 2012^{7 , 8 , 9 , 10 , 11 , 12}, observing that “the problem crops up in those deeper pages” and asking, “But what about a file located deep in my directory structure?”

Clearly, I don’t think much of the suggestion that one just “always use relative paths."¹³ Huh? You always know where that code will be used? Changing willshake itself to use relative paths is a complete non-starter. Thus, we have to make Cordova work with willshake as it is.

Regarding the Android assets folder.

Files that you save here are compiled into an .apk file as-is, and the original filename is preserved. You can navigate this directory in the same way as a typical file system using URIs and read files as a stream of bytes using the AssetManager.¹⁴

The other problem is that Android is very restrictive about the characters allowed in “asset” filenames. And since assets are basically a file system that is accessible via URI, it’s a natural fit for apps that emulate a web server.

But if you have any “funny” characters in any filename, the Android build won’t allow you to add it as an asset, saying, “Invalid filename: Unable to add.” It turns out that

Android requires ASCII filenames for assets. This doesn’t appear to be publicly documented anywhere, but the `aapt` source code has an ASCII check¹⁵

So the file Chassériau-Mac-1.3.jpg, for example, would not be allowed as an asset in Android, on account of that pesky é. Which I find surprising, since Android is supposedly the most popular operating system in the world. What if your app is Greek or Japanese? Doesn’t matter. Your asset names will be ASCII.^{16 , 17 , 18}

One way to deal with this would be to avoid having such filenames in the first place. Well, the last time these things came under threat, it set in motion a process that led to my ultimately porting willshake to another operating system.¹⁹ So, no, that’s a non-starter.

Instead, I’ll leave the site untouched, and adjust the app so that it will still work. This will require a two-part solution:

1. Change the filenames in some predictable way during the build.
2. Reroute requests in the app, using the same logic.

For both problems, the solution must be to intercept and rewrite all network requests. Fortunately, this can be solved fairly straightforwardly with a Cordova plugin, which has a virtual remapURI method.

package net.willshake;

import android.net.Uri;
import org.apache.cordova.CordovaPlugin;

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;

public class FixPaths extends CordovaPlugin {

	@Override
	public Uri remapUri(Uri uri) {
		if (uri != null) {
			String path = uri.toString();
			<<fix path>>
		}

		return null;
	}

	<<make ascii path>>
}

Java has an amazing amount of noise. This is the essence of the function.

final String FILE_PROTOCOL = "file://";
final String ASSETS_PATH = "/android_asset/www";

if (path.startsWith(FILE_PROTOCOL)) {
	String site_path = path.substring(FILE_PROTOCOL.length());

	if (!site_path.startsWith(ASSETS_PATH)) {

		if (site_path.startsWith("/static/images")) {
			site_path = make_ascii(site_path);
		}

		return Uri.parse(FILE_PROTOCOL + ASSETS_PATH + site_path);
	}
}

The path munging function is basically percent-encoding.

static String make_ascii(String path) {
	final int slash = path.lastIndexOf("/");
	if (slash < 0 )
		return path;
	final String dir = path.substring(0, slash + 1);
	final String file = path.substring(slash + 1);
	try {
		return dir + URLEncoder.encode(file, "UTF-8").replace('%', '_');
	} catch (UnsupportedEncodingException __) {
		return path;
	}
}

That’s it, except for the required manifest. Note that

Plugins are not instantiated until they are first referenced by a call from JavaScript, unless <param> with an onload name attribute is set to “true” in config.xml.²⁰

This is important, since the plugin doesn’t have any JavaScript component.

<?xml version="1.0" encoding="utf-8"?>
<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
	id="net.willshake.FixPaths"
	version="1.0.0">
  <name>fix paths</name>
  <description>thing to deal with stupid cordova paths</description>
  <keywords>paths, stupid</keywords>
  <license>Apache 2.0</license>
  <platform name="android">
    <source-file src="FixPaths.java" target-dir="src/net/willshake" />
    <config-file target="config.xml" parent="/*">
      <feature name="FixPaths">
	<param name="android-package" value="net.willshake.FixPaths" />
	<param name="onload" value="true" />
      </feature>
    </config-file>
  </platform>
</plugin>

Now we just add the plugin during the project setup.

cordova plugins add "$project_dir/app/fix-paths"