On Saturday, January 12, 2013 at 12:25 PM, Daniel Kinzler wrote:
On 12.01.2013 20:14, Ori Livneh wrote:
ContentHandler powers the Schema: namespace on metawiki, with the relevant code residing in Extension:EventLogging. Here's an example:
http://meta.wikimedia.org/wiki/Schema:SavePageAttempts
I found the ContentHandler API to be useful and extensible, and would be happy to be approached on IRC or whatever with questions.
Oh, cool, I didn't know that!
Perhaps you can tell us what you would have liked more information about when first learning about the ContentHandler? Were there any concepts you had trouble with?
-- daniel
As I said, I found the API well-designed on the whole, but:
* "getForFoo" (getForModelID, getDefaultModelFor) is a confusing pattern for method names. getDefaultModelFor is especially weird: I get what it does, but I don't know why it is where it is, or what need it is fulfilling.
* I don't have a clear mental model of the dividing line between Content and ContentHandler. The documentation (contenthandler.txt) explains that "all manipulation and analysis of page content must be done via the appropriate methods of the Content object", but it's the ContentHandler class that implements serializeContent, getPageLanguage, getAutoSummary, etc. If I think about it, I can sort of understand why things are on one class rather than the other, but it isn't so clear that I know where to look if I need to do something related to content. I usually look both places.
* The way validation is handled is a bit mysterious. Content defines an isValid interface and (if I recall correctly) a return value of false would prevent the content from getting saved. But in such cases you want a helpful error. I ended up implementing a validate() method on the Content class that throws helpful exceptions, calling it from an EditFilterMerged hook handler, but I had the feeling that I was deviating from the design goals of ContentHandler somehow, since it seemed like the sort of thing ContentHandler would handle for you.
* I would expect something like ContentHandler to provide a generic interface for supplying an editor suitable for a particular Content, in lieu of the default editor. For example, it seems clear that the CodeEditor extension should use ContentHandler to associate itself with particular content types (and to load the relevant highlighting / linting support), but I'm not sure what is the best way to implement it. I created a bug for this: https://bugzilla.wikimedia.org/show_bug.cgi?id=42593. There should probably be some kind of GetEditInterface hook that passes handlers a content model, to provide an easy way for extensions to supply enhanced editors for particular types of content.
* I wasn't sure initially which classes to extend for JsonSchemaContent and JsonSchemaContentHandler. I concluded that for all textual content types it's better to extend WikitextContent / WikitextContentHandler rather than the base or abstract content / content handler classes. But I did not feel sufficiently confident to document this as a best practice.
If I remember any more I'll update the thread.
After working with the API for a while I had a head-explodes moment when I realized that MediaWiki is now a generic framework for collaboratively fashioning and editing content objects, and that it provides a generic implementation of a creative workflow based on the concepts of versioning, diffing, etc. I think it's a fucking amazing model for the web and I hope MediaWiki's code and community is nimble enough to fully realize it.
-- Ori Livneh