Miga: Administrator's guide

Miga is a lightweight framework for displaying an intelligent client-side browsing interface around a set of structured data. It requires administrators to provide the bare minimum amount of information: one or more data tables, in CSV form; as well as schema information in a separate file using a lightweight syntax; and an optional listing of additional pages that the app should display, also using a lightweight syntax.

The data is all downloaded and stored to the user's own browser, which makes for a slight delay at the beginning of usage, but after that results in a very fast browsing experience, and one that will work offline as well.

A single Miga installation can power any number of separate "apps", each with its own data set.

Browser support

Miga relies on Web SQL Database to store all its data. Web SQL Database, though quite useful, is unfortunately not supported on all browsers, due to a W3C objection that Web SQL requires the use of SQLite and is thus not a technology-independent standard; you can read more about that here.

Miga is thus not supported on the following browsers:

Miga will work on the following browsers:

Logic

Miga takes care of almost all of the details of the display, based on the size and nature of the data. That is done in order to make the task of setting up an app as simple as possible, as well as based on a philosophy that the "best practices" for data display should be determinable based on only the size and structure of the data. Here are some of the rules that Miga follows:

Entity name display

Entities/rows are displayed by their "Name" field when listed. If they have an "Image URL" field, that is displayed as well (ideally, it's a thumbnail image). And the first field for that category of type "Text" is displayed below the name, in a different color, to provide more at-a-glance information.

Pagination

If there are more than 250 items for any set of results, the items are split up into "pages" of 250 results each.

Filtering

Any field can in theory be used as a filter. Fields of type "Number" or "Date" will always be used as filters. Fields of other types will only be used as filters if they have less than 50% "diffusion": in other words, if the number of distinct values for that field overall, divided by the number of total values, is less than 50%.

For Number fields, values are grouped into eight or fewer "buckets", each comprising a certain numerical range. When constructing the ranges, Miga attempts to make the buckets of approximately sizes, while still keeping the numbers as round (i.e., with as few significant digits) as possible.

For Date fields (which includes "Start time" fields), Miga splits up the dates into buckets of either centuries, decades, years, months or days, depending on the range of the data in question.

For Number and Date filters, users can keep drilling down using the same filter, with the ranges getting progressively smaller each time, until individual ranges start holding a single value each.

For other types (in practice, this is almost always "Text" or "Entity"), a filter can only be used once. Also, there is no attempt to group values together: if a field called "Country" has some values that are "USA" and some that are "U.S.A", for instance, those will show up as two separate filter values. Values are case-sensitive, so values like "green" and "Green" will similarly be displayed separately.

Finally, there are "compound" filters that can appear. If a field in category B is an "Entity" link to a field in category A, and category B is nameless, i.e. without a "Name" field of its own, then among the set of filters for category A may be one or more of category B's fields.

Linking

For fields that are of type "Entity", all values will link to the page for that entity in the application, if there is such a page.

Search

Search in Miga is done using a very simple, case-insensitive search - the search text entered must appear in the text exactly as entered (though with any casing) for it to show up in search results. Both item names and their values are searched; the two types of search results are displayed in separate lists.

Search is always done across an entire category; there is certainly a case to be made for allowing searches to happen only within the set of results returned by the set of filter/value pairs that the user has already selected - i.e., to have the text search function as an additional filter - but this is not currently possible.

Faceted search

A "hidden" feature of Miga is the ability to do a faceted search, i.e. have a search form that contains checkboxes for selecting one or more values for each (text-based) filter. This feature is not linked to anywhere from the standard interface; to be able to get users to access it, you would have to link to it from somewhere, like the start page, header, footer, etc. To go to the faceted search page for a specific category, just add "/_search" to the URL for that category; see here, for example.

Mapping

Any category that contains a field of type Coordinates will have a mapping display automatically enabled - users viewing any set of items will be able to toggle back and forth, using tabs, between a "View items" and a "View map" display. Mapping can be done with either Google Maps (the default service) or Open Layers/OpenStreetMap; both services have their advantages and disadvantages. (For how to specify one or the other, see Settings.)

If a category contains more than one field of type Coordinates, only the first one will be used - additional fields will be ignored.

Events

If a category has both a "Start time" and "End time" field, it is considered to be holding "events". If that's the case, and if the user's current time falls between the start and end times of one or more such events, the main screen will include an additional link to only the currently-happening events for that category.