This is great - the self-description/"reflection" feature will be allow for a big improvement to Special:Ask (and evidently Halo as well). This, in addition to Sergey's previous changes, turns Special:Ask from somewhat of a hacker interface to an easy-to-use entry point for those getting started with Semantic MediaWiki and inline queries. Actually, the more I think about it, the more I think this is a big step forward in turning SMW into a real consumer application, since it will mean that people can run (and administrators can save) queries on the data without needing to read through a lot of documentation.

To that end, I would say that yes, there should be descriptive labels for each printer, retrieved from message files - just as there should be labels for each parameter. Having good inline help is very common among mature software applications - it's considerably easier to use than a user handbook. Obviously, it becomes an issue if someone wants to put whole paragraphs or even pages into the application, but a simple one-sentence description of each concept is, I think, completely reasonable. And I should note another veery important reason to put such information into the application - to enable translation; which should make creating inline queries quite a bit easier for those who can't speak English.

Finally, if you're at all considering adding more meta-data to each printer, let me suggest another field: a "default limit" value, which would override the wiki's value for $smwgQDefaultLimit (though not a "limit=" parameter set in the query). This would allow the "math" formats in SRF (sum, average, min, max) to considerably raise the number of values passed in to them by default, since all of them, especially 'sum', require all values to be passed in to produce a meaningful result. It would similarly be helpful for 'calendar'. A default limit value could also be helpful for the export formats (csv, json, icalendar, rss), although for them there's already a workaround because they create, essentially, a link to themselves, with that link setting the correct limit.


On Sun, Apr 5, 2009 at 12:24 PM, Markus Krötzsch <markus@semantic-mediawiki.org> wrote:
As promised, SMW has now been updated to support some of the requested

* To get the list of all available formats, access $smwgResultFormats.
* To get a result printer object, use SMWQueryProcessor::getResultPrinter().
* To get the name of a printer object, use $printer->getName().

The new functions are documented in the code (or see the API docs).

The format selector for Special:Ask has been improved to use these features.
Note that not all SRF formats provide localised names yet; examples on how to
add translations are found in all SMW result printers and in some of the SRF

There was also another change: printers that only show download links when
used inline can indicate to SMW that no query needs to be executed in this
case. To do this, simply implement the method getQueryMode() as e.g. in
SMW_QP_CSV.php. If you do not do this, SMW will always compute all query
results, even if the printer ignores them anyway.

Besides Name and QueryMode, no further meta-data has been added. Especially, I
do not know yet how to provide information about available parameters. There
is a list of parameter identifiers, but what else should be there for each of
them: localised labels, expected type of input, anything else? Also, I was
unsure whether longer descriptions besides the names should be available for
printers -- doing this feels like moving the user handbook to the message



On Donnerstag, 2. April 2009, Markus Krötzsch wrote:
> On Mittwoch, 1. April 2009, Yaron Koren wrote:
> > I think a way for formats to publish both a description of themselves and
> > the set of parameters they take would be very helpful: it could be that
> > the easiest way to do it is just to expand the information that
> > $smwgResultFormats holds, although maybe the better solution is, as you
> > suggest, to add methods like getDescription() and getAllowedParams() to
> > the SMWResultPrinter class, and allow any format class to override these
> > methods.
> I also agree with Jörg's observation. I strongly favour Yaron's second
> proposal: extending the printer class instead of extending the static
> array. A related solution has been in my mind for some time, but I did not
> find time to implement it yet:
> * In order to keep the information that is available for each result
> printer flexible and extendible, it would be best if the printer objects
> would implement access methods for this information. Two main advantages
> are:
> (1) The meta information is kept with the code of the printer class, so
> printer format extensions like SRF are still easy to implement in one file.
> (2) The abstract result printer parent class can always implement fallback
> methods, so that non-core printers are compatible to new SMW versions even
> if they do not support this meta-data yet.
> * The task then boils down to getting a printer object for a given printer
> identifier (like "ul"). In order to be perfectly compatible with SMW, this
> should be done by calling SMWQueryProcessor::getResultPrinter(). The
> problem is that this function currently requires further parameters:
> especially it depends on the query result. This is not really needed and
> can be avoided with some extra coding from my side.
> * What remains to discuss is what meta information it is that each printer
> should provide. A human readable name would be a good start, I guess.
> Another useful feature might be a function that returns the list of
> supported additional parameters with a short "signature" to indicate their
> input type (How should this look? How do you get labels/descriptions for
> these parameters?). Anything else?
> I think I can provide the implementation over the weekend then.
> -- Markus
> > -Yaron
> >
> > On Wed, Apr 1, 2009 at 4:25 AM, Jörg Heizmann <heizmann@ontoprise.de>
> > > Hi,
> > >
> > > I am working on our query front-end for inline ask queries which, in
> > > the next version, immediately shows your result set while you are
> > > creating your query.
> > > In order to (dynamically) support all available result printers and to
> > > not hardcode all this stuff which might change in the future I found
> > > the array holding name and class of each available result printer
> > > ($smwgResultFormats). That's pretty cool but I cannot get additional
> > > meta information for each printer.
> > >
> > > I doubt that users understand that "ul" stands for "unordered list" so
> > > I would love to have a short description (maybe also a longer one)
> > > method for each result printer.
> > > Also, some printers support additional parameters which are necessary
> > > for the frontend to know about. Here, a second method would be nice to
> > > have in order to not hard-code this information.
> > >
> > > What do you think about these additions?
> > >
> > > cheers,
> > > Jörg
> > >
> > >
> > > -----------------------------------------------------------------------
> > >-- ----- _______________________________________________
> > > Semediawiki-devel mailing list
> > > Semediawiki-devel@lists.sourceforge.net
> > > https://lists.sourceforge.net/lists/listinfo/semediawiki-devel

Markus Krötzsch
Semantic MediaWiki    http://semantic-mediawiki.org
http://korrekt.org    markus@semantic-mediawiki.org