About two years ago a Feature Request was filed for the Web Framework to allow users to handle incoming requests in standalone apps for things which would normally return an HTTP 404 Missing Page error. At the time, there were a few obstacles in our way which prevented bringing this request to fruition, but no more…
Starting in 2014r3, there is a new event available on the App class named HandleURL. This new event works similarly to HandleSpecialURL but the circumstances under which it fires are different. The goals for this feature were:
- Overriding HTTP Error Pages.
- Handling generic page requests.
- Make search engine indexing possible.
What can I do with this?
- Serve regular files with your web app, including HTML, CSS and Javascript.
- Override what happens if a browser requests something that doesn’t exist in your app. Right now we return a generic 404 Error page, but you may want to customize the HTML which gets returned to give the browser or client more information about what went wrong or customize it to look more like your app.
- You can optionally return other content for the root level directory, like an index file on a website.
- Return data that a search engine will understand so your app can be properly indexed.
What can’t I do?
For obvious reasons, we don’t allow you to intercept requests that would normally go to the app. This means that URLs that we currently use will never be passed to this event. This includes:
- Session URLs – Every session gets an identifier and all of its events are sent through a URL that looks something like this: /B156D2E6338304E2AAD151DC5680F50E/comm/push.
- Framework URLs – Framework files are located under /framework.
- Special & API – Requests that would go to App.HandleSpecialURL ( so we don’t break existing apps ).
- Reserved URLs – We’ve also reserved /xojo and any URL that begins with /_ (forward slash + underscore.
Great Power / Great Responsibility
For the record, this is an advanced user feature. We’ve gone to great lengths to make this feature powerful enough to allow developers to do the things that they want to do, while making it hard to actually break your app. That said, this feature gives you an opportunity to return files in response to requests that would never have existed before. If things start acting strangely comment out this method and see if things go back to normal.
Sample
Returning a custom 404 error page is really simple:
// Don't override an empty request, or a session won't start. If Request.Path <> "" Then // First, create the HTML answer Request.Print "<html><body>" Request.Print "Oops! You took a wrong turn. " Request.Print "Please put it in reverse and try again." Request.Print "</body></html>" // Set the status code. The default value is 404, // but if you leave it that way, some browsers // will show their own. A value of 200 will make // the browser show your text instead. Request.Status = 200 // You MUST return True if you want to override the output. Return True End If
For a list of HTTP Status codes click here.
We really hope you like this new highly requested feature. If you think you’ll be using this feature in your projects, please tell us about it below!