Using EnitityBroker in authoring

I will start by looking at a particular use case as an example of what needs to be done to "entify" existing "sakai entities" so users can access them in the context of documents authored within sakai and so users can create them and revise them in the context of authoring documents within sakai.

Use Case: Sakaibrary wants to let users embed or link to collection of citations in a Subject Research Guide. In doing this, it should not be necessary for the client webapp (SRG) to know anything about the entities being referenced (citations). It might be OK for the client to depend on the Citations API, but client should know nothing about rendering citations, creating them, revising them, etc. It should invoke a helper of some sort to do what needs to be done. Ideally there will be some simple way to say, "In this context, users can add collections of citations". Based on that simple indicator, users should be able to get a UI that lets them do all the things currently supported in the Citations Helper to add citations to a Citations List. Additionally, the user might specify that they want the citations expanded inline in the document (i.e. "embedded") or they want them to appear in a pop-up window when a user clicks on a link in the document (i.e. "linked to"). In either case, access to the rendered view of the citations is encoded in a simple RESTful URL. The way the client app uses the URL determines whether the citations are rendered inline or in a pop-up.

Approach: The approach is described in Confluence in this page: Writing and using SuperHelpers within Sakai. That document is loaded with information. I'll try to work through the example of invoking a Citations helper from SRG to help clarify some of the ideas developed there.

Aside: We need to work through some examples like this to illustrate what set of attributes need to be known by a client to invoke helpers in this way. In the SRG example, I expect that we will offer the helper's functionality in a couple ways:

1. Providing access to existing entities
2. Enabling revision of existing entities
3. Enabling creation of new entities of that type

For example, our webapp might be rendering an SRG and reach a point where a collection of citations is embedded in the document. The SRG "tool" might invoke a Citations helper to render that collection of citations. If the document is editable and/or that particular entity within the document is editable by the current user, the Citations helper might include a way to invoke an editor for the citations. Or the page itself might contain a way to select an item for revision, such that if the user selects that action for those citations, the citations helper will be invoked. Similarly, within the document, if the current user has permissions to add entities to the document and specifically if the current user has permissions to add citations within a particular context in the document, it should be possible to invoke a Citations helper to create a new collection of citations in that context.

In specifying a document model or a document template, what set of attributes or properties would be needed to enable these capabilities? I'll try to answer that question through this example.

More to come