User:Daniel Kinzler (WMDE)/MCR-SlotRoleHandler

Sketch of the interface for SlotRoleHandler and SlotRoleRegistry, as well as SlotParserOutputProvider and RenderedRevision:

SlotRoleHandler
Considerations:

SlotRoleHandler is a base class. It can be extended to override some behaviors. This allows us to add more methods later, without making a breaking change. Since most slots do not need custom behavior, this seems a good approach.

The below design assumes that a given SlotRoleHandler instance may support multiple content models. The default SlotRoleHandler implementation should indeed work for any model.

Interface:


 * getRole returns the role name this SlotRoleHandler is associated with.
 * getRawHtml( SlotRecord $record, SlotParserOutputProvider $provider, ParserOutput $target = null ).
 * Returns HTML for the content of record, wrapped in a div, perhaps together with some kind of heading. Calling code is expected to combine this HTML with the HTML from other slots and then pass it to target->setText.
 * $provider is used to acquire a ParserOutput object for the slot's content, if this is needed to generate the HTML. This is typically but not necessarily the case.
 * If $target is passed to getRawHtml, all the necessary head-items and directives will be registered in it, but no link tracking data is copied. Calling code is expected to do that. This enforces a separation of meta-data needed for display from derived data to be stored in the database.
 * getOutputPlacementHints returns an associative array of hints that tell calling code where on the page the HTML returned by getRawHtml should be placed. Calling code is free to ignore these hints.
 * __construct( $role, MessageLocalizer $localizer )
 * $role the name of the role handled by this handler.
 * $localizer used to determine the heading text. They message key is constructed using the role name as a suffix.

SlotRoleRegistry
Interface:


 * defineRole( $role, $defaultModel, callable $instantiator ):
 * $role the name of the role to define.
 * $defaultModel the default content model to use for this role. May be overwritten, especially for the main slot.
 * $instantiator a callback returning a SlotRoleHandler
 * getRoleHandler( $role, $title ) Provides a handler for the given role. Note that the same role may have different handlers depending on the page title - particularly for the main slot (maybe only for the main slot)
 * returns a SlotRoleHandler.
 * $title could be a PageIdentity (to be introduced) instead of a LinkTarget
 * getDefaultContentModel( $role, LinkTarget $title ) returns the default model to use for the given slot on the given page. This should only be used when creating a new page, otherwise a slot will just keep the model it has in the latest revision. The default content model returned here may be different from the one registered with the role, specially for the main slot.
 * getALlowedRoles( $title ): returns a list of roles supported for the given title. This informs the UI layer which roles should be offered when creating or editing the page. This does not guarantee that no other slots may exist on the page. If additional slots exist, they must at least be "looped through" all edits, and must be accessible when addressed explicitly.
 * getRequiredRoles( $title ): returns a list of roles required for the given title. This informs the UI which roles to require during user interaction. This does not guarantee that no revisions exist on the page that do not have all of these slots. All operations must still be possible if any of the slots missing (except the main slot).
 * getDefinedRoles returns the list of roles defined by calling defineRole.
 * getKnownRoles returns the list of known roles, including the ones returned by getDefinedRoles, and roles that exist in the database.