Jeroens blog

One of the big new features in Maps 0.5 will be strict parameter validation. This means Maps will allow you to get specific errors or warnings when entering invalid values or parameters.

The setting determining the strictness of the validation, which can be changes in your LocalSettings file, currently accepts 4 values:

• Maps_ERRORS_NONE : Maps will not show any errors, and make the best of the imput it got.
• Maps_ERRORS_WARN : Maps will make the best of the imput it got, but will show warnings for omitted coordinates.
• Maps_ERRORS_SHOW : Maps will make the best of the imput it got, but will show a list of all errors.
• Maps_ERRORS_STRICT: Maps will only show a map when there are no errors, if there are, a list of them will be shown.

The underneath example demonstrates an error list that can be generated when the validation level is on Maps_ERRORS_SHOW or Maps_ERRORS_STRICT. In case of the former, it’ll be shown below the map,while in case of the later, it’ll be shown instead of any map. The error messages are of course fully internationalized.

The validation is done via a new class dedicated to parameter validation. To be able to validate anything, you need to feed it two things: an associative array containing the raw parameter names and their values, and a somewhat more complex, nested, array containing the allowed parameter and their meta data, such as aliases and default values. The class also provides a hook for validation types, allowing you to do specific or complex validation that is not build in. The handling of the different strictness levels and generation of the actual error messages is done by another class that uses the first to validate and get the errors. Both classes do not contain any Maps specific code, so can be used to validate the parameter of any parser function. I’m planning to split this code, after it has reached a beta level, into a separate extension, that will probably be named “Validator”. This extension will be bundled with Maps, and will not any additional steps to the installation process.

Together with implementing this new feature, I did a big overhaul of the parameter handling in Maps and Semantic Maps. Instead of the two level system, containing general parameters, and service specific parameters, that was used in Maps, there now is a four level system. The first level are the general parameters, shared by everything. These include things like width, height and zoom. Feature specific parameters make up the second level, while the third one holds service specific parameters. The last level are the parameters specific to a combination of service and feature. Maps goes through these levels, starting with the upper one, and overriding it with the following. This allows more specific behaviour and is required to be able to validate the parameters in some instances.

The changes I made to Maps and Semantic Maps during these rewrites are responsible for what are probably my biggest commits to both extensions yet.

• Changes to Maps (rev 59531)
• Changes to Semantic Maps (rev 59532)

Due to the extend of changes I made, and the lack of thorough tests yet, I expect multiple issues with this code, including several severe ones, so I advice against using the latest SVN code for the moment, except for testing purposes of course. I hope to have the code refined and bug hunted in the coming week, so I can put it in a new extension and release it. During this period I’ll also start working on the other new features planned for 0.5, so you can expect more news on this soon.

It’s been almost 2 months since Maps version 0.3.4 was released. Although I did waste a lot of my time at school, I managed to get quite some important work done in that period. Version 0.4 mainly addressed new functionality, and some thorough refactoring for Maps, and only introduced 2 bug fixes for Semantic Maps. So lets have a look at everything that changed

New features

• I added a display_map parser function, that’s obviously meant to display maps. The code handling this parser function is optimized to display maps, and does not hold into account any possible markers, ect. The main reason for adding this function is that it’ll be used for the Wikimedia Foundation implementation of Maps.
• Smart geocoding support. Maps is now able to determine if a value is a set of coordinates, or an address. This enables automatic geocoding of addresses, making the specification of the value type unneeded, and allows you to mix coordinates and addresses in location lists. This functionality is implemented for display_map’s default parameter, the one of display_point(s), and display_point(s) centre property.
• OpenStreetMap service. This service uses OpenLayers to display OpenStreetMap tiles. It’s optimized for OSM, and does not allow you to display other tile sources with it. This is another of the requirements for WF usage that’s now been completed. This service is only implemented in Maps ATM, and will be added to Semantic Maps in version 0.5.
• Support for DM (Decimal Minutes) and DD (Decimal Degrees) coordinate notations. Someone requested these to be added. Several other variants, such as GPS coordinates, might be put into Maps in the future.
• Added a setting specifying the minimum and maximum width and height of maps. When a value falls out of this range, it’ll be changed to the nearest allowed value. This is to prevent post-stamp or wallpaper maps, and is inspired by the similar functionality in the SlippyMap extension.
• Parsing of marker-specific title and label values. I actually marked the lack of this feature a bug a while ago, which I changed at the point where I remembered I simply did not add such a thing yet, and only map-wide title and label value’s got parsed.

Refactoring (“under the hood” changes)

• A new hook system for the parser functions, allowing the adding or removing of additional parser function support. Each mapping service will now have one class for handling on specific parser function. Again, the main reason behind this change is that it’s required for the WF usage of Maps, where at the start, only display_map will be used. Another great advantage is that you can now very easily add new parser functions without having to mess up the core extension code. An example of such a function is display_route, which might be added at some point to maps.
• Change the geocoding functionality into a true feature hook element, so it can be easily removed. This is not easy to do, since the geocoding functionality is currently used at various points by the parser functions. So before I can start making it a feature hook element, the parser function code will have to be restructured.
• Create service hook for the geocoding feature – separate from the mapping services hook. This will allow adding and removing support for a specific geocoding service.
• Since Maps is now able to distinguish coordinates from addresses, the display_address and display_addresses parser functions have been removed. For backward compatibility, calls to them will be routed to display_point(s). This will of course eventually be removed.
• Removed a redundant path variable. One of the messy remains of the initial Maps release, which even caused problems on some installations.

Bug fixes

• Fixed a mayor bug in the initialization method causing hook code to get executed at a probably wrong moment. This bug can be the cause of some weird problems that surfaced since 0.3.3.
• Fixed a rather annoying issue with size of popups in Google Maps. They did not stretch far enough vertically for large contents. I’m happy I got this fixed now, since I’ve been aware of it for quite a while now, but simply could not find a solution. Yaron pointed me to a helpful blog where a certain post set me on the right track. The solution was ridiculously simple, and one line (in the JS code) long.
• Fixed some problems with the display of the mapping result formats on the Special:Ask page of Semantic MediaWiki. I’ve done this by adding an aliasing system for result formats to SMW itself. So to be able to benefit from this, you need to have that version of SMW, or later. Maps has a build in check to see if the aliasing functionality of SMW is present, and if not, uses the old, but a lot less efficient, solution.

For the change log listing, see Maps version history and Semantic Maps version history.

The documentation has been completely updated for both extensions. I only have to change the demo’s on my demo wiki to reflect the new syntaxis of the parser functions. After that I can get to work on the to-do’s for version 0.5, which will include the long awaited static map support

Did I mention Semantic Maps now supports over 50 languages? :p

Downloads

• Maps 0.4 (zip, 7z)
• Semantic Maps 0.4 (zip, 7z)
• Maps and Semantic Maps 0.4 (zip, 7z)
• Maps 0.4 SVN tag
• Semantic Maps 0.4 SVN tag

Today a new version of Maps and Semantic Maps where released. This version, 0.3.4, mainly focused on the internal structure of the extensions, performance issues and bug fixes. Some small new features have been added though.

Bug fixes

• Fixed some issues with invalid parameter handling. This comes down to 2 things. The first is that before this version, an empty parameter (so || instead of |name=value|) would override the default value when it occurred after the default. So #display_point:coordinates=1,1||service=openlayers would end up showing an error that no coordinates where provided. The second one is a fix in the error message you would get when entering a coordinate parameter with an empty value, like |coordinates=|, this previously caused the error that location “” could not be displayed, and has now been replaced by an error message saying that no coordinates have been provided, as is the case.
• In the from handling code, I fixed a more severe bug, one that caused a wiki with SM installed to fail in case Semantic Forms was not installed and enabled. Someone pointed out this bug to me via a talk page. Surprisingly, no one had noticed this pretty big bug before, which demonstrates the wide use of SF, at least by the people also using SM.
• Another bug pointed out by someone on the talk page of SM is that SM only displayed the last coordinate property in a result of a query on a map. Semantic Google Maps supported this feature, but a some point, presumably at version 0.2, I accidentally removed it while refactoring the query result handling code. Anyway, it’s back now.

Refactoring

• The biggest change in this release is the introduction of a new feature hook system. This hook system allows you to add new mapping features to Maps, very much like the mapping service hook system. This has great consequences for the modularity of Maps, which has taken a big step forward. Every feature is loaded and initialized from the initialization method of Maps. This allows any extension to adds it’s own functionality to Maps, that can then use the general mapping functions of Maps, and the services hook system, and of course then be used in other extensions. This change has rendered Semantic Maps into a simple holder of 2 features: query printers and form inputs. It does not do any initialization on it’s own any more, and simply hooks into Maps. Obviously, this new hook system brought with it a whole list of extensive changes made in both maps and Semantic Maps.
• Added internationalization for the mapping service names, and to the list notation at several places.
• Moved the SM related JS present in Maps files to separate files in SM.
• Fixed tiny performance issues all over the code.
• Added fall-back mechanism to the geocoding methods, and re-introduced the old style request, for cases where cURL is disabled.

New features

The only real new functionality is that you now can configure which mapping features should be enabled, and which should not. This is of course a direct result from the new feature hook system.

You can view a complete list of changes to Maps and changes to Semantic Maps at the relevant documentation pages.

So, what’s next?

Before 0.4, which will introduce some big new features, I’m planning to release at least one update to the 0.3.x branch. This update will have geocoding as a feature in the new hook, a hook system for parser functions, a new mapping service called OSM (optimized OSM code working with OpenLayers) and a new parser function display_map, to simply display a map without any markers.

Just like version 0.2 of both Maps and Semantic Maps, version 0.3 will feature a variety of large structural changes, aimed at increasing the performance of the extensions, making it possible to add new features, but most of all, make it more modular, to allow people to easily extend them. Here you have a list of the mayor changes that have been completed so far, with some explanation of the advantages they bring.

• Base class that bundles common functionality between MapsBaseMap, SMMapPrinter and SMFormInput, and gets inherited by those classes. This class has been named MapsMapFeature. This is a great step towards the complete centralization of all common code, but sadly enough was not implementable the whole way: MapsMapFeature cannot be inherited by SMMapPrinter, since this class already inherits the SMW QP. Yaron suggested to use a ‘has-a’ implementation, witch means creating an instance of one of the classes you want to inherit as a class field, instead of the ‘is-a’ which is the regular inheritance. Although this is doable in theory, it will bring with it some other problems, so will have to wait till another version.

• Separation between the common and specific parameters, and their default values. Each mapping service now holds an array containing the extra parameters they add (so the allowed ones), and another array containing their default values. Note that both arrays are merged with the common arrays at runtime, and will override similarity named items. This allows to change the default value of a common property, or change the aliases.

• Yes, indeed, that’s right, aliases! Property names now have aliases. This means you can add several alternative ways to name the same parameter, for instance, you can make so that ‘auto zoom’ and ‘auto-zoom’ will do excellently the same as the main parameter ‘autozoom’. This is particularly handy for parameters such as ‘centre’ (British spelling) and ‘center’ (American spelling).

• Hook like system for mapping services. This is without a doubt the most important change since 0.1. All hard-coded references to mapping services in the core code have been removed. A service is now added by one multi dimensional array in Maps.php (note that this can also be done in the initialization file of another extension!), which holds the name of the parser functions class and it’s location, the aliases for the service name (feature added in 0.2), and their allowed specific parameters and their aliases. This architecture will allow other people to create their own mapping extension using the Maps (and Semantic Maps) ‘API’, which enables them to focus on the mapping service specific code rather then extension related code, or common mapping code. There are numerous more advantages, like the fact that their ‘extension’ will follow some general norms, which will make it easier for uses to use (and install!) and for developers to work on, and the fact that their code will also benefit from improvements made to the core code of Maps and Semantic Maps. Once 0.3 is release, I’m going to create a new section in both the Maps and Semantic Maps documentation, which will hold a list of why people should consider choosing that approach, as opposed to creating their own little mapping extension, a list of the advantages, and documentation on how to effectively do it.

The above improvements have been made in Maps, but still have to be implemented in Semantic Maps, which is now on the top of my to-do list. I’m also busy with the adding of new functionality, and got some great results so far, but I’ll post about those when more of the work for 0.3 is done.