Re: [xwiki-devs] [Discussion] Defining Sheets

Hi Marius, On Wed, Aug 3, 2011 at 10:49 AM, Marius Dumitru Florea< mariusdumitru.florea(a)xwiki.com&gt; wrote: > Hi Guillaume, > > First of all, thanks for your feedback. See my comments below. > > On 08/01/2011 03:40 PM, Guillaume Lerouge wrote: >> Hi Marius, >> >> please see my answers below. >> >> On Mon, Jul 11, 2011 at 3:06 PM, Marius Dumitru Florea< >> mariusdumitru.florea(a)xwiki.com&gt; wrote: >> >>> Hi devs, >>> >>> I'd like to make the following proposal based on your feedback: >>> >>> (1) a sheet is a document that has an object of type XWiki.SheetClass >>> >> >> Ok. >> >> >>> (2) the sheet code is stored in the sheet document content >>> >> >> Ok. >> >> >>> (3) XWiki.SheetClass has the following properties: >>> >>> display: Static List ('page', 'inline', 'meta') >>> action: String ('view', 'edit', etc.) >>> >>> The 'display' property specifies where to place the sheet output: >>> >>> * page: the sheet output overwrites the 'mainContentArea',

>>> and 'xwikidata' DIVs. This means everything besides the header (logo

>>> top menu), the content menu, the footer (version and license info) and >>> the side columns (panels). >>> >> >> Ok. >> >> >>> * inline: the sheet output overwrites the content of the

Yes, that would be good.

Why not? These are wiki-wide document options. Why should they not be available for all content types? This would go towards standardizing the display of wiki pages in edition mode. What's not to like about that?

> * meta: the sheet output is aggregated under the "Objects" document >>> extra tab. The bottom tabs are displayed only in view mode currently

>>> we can imagine ways to display 'meta' sheets in edit mode too. >>> >> > >> I think it would be better to be able to create a custom tab rather

Ok. It's indeed less important than the other 2 options at this stage anyway. >> In that case you would need to be able to define the title to display

> the >> tab, maybe through a translation key stored in a field of the

Even with actions implemented as components, you can still

generate a list of existing actions and provide a list interface to

them. As we can see from WYSIWYG macros, users tend to be lost when they cannot pick from a list of explicit values when they have to fill a field that

accepts values from a predefined subset.

>> (4) Sheets can control the UI elements outside of their scope through >>> parameters, depending on the value of the display property: > >> I'm not sure I agree with this. Panels should not be affected by > something >> else than their existing interface, that will confuse users. I'm not

> I >> see the added value of defining panels at the class level. It's a

> to >> define them at the space level (and there's very often an

I still don't agree about it, unless I get further details about this use case that make me change my mind of course :-) > * page: since sheets of this type control most of what is displayed the >>> only useful parameter is the list of left/right panels. >>> * inline: list of left/right panels, show/hide breadcrumb, show/hide >>> title, show/hide bottom tabs, list of bottom tabs, show/hide version >>> summary in edit mode. > >> And default bottom tab. I think all these options should be provided

>> every page in the wiki under an "advanced" section (including normal

>> pages). I don't see a reason to restrict those options only to pages

Right. Indeed, I agree. Guillaume > As for the interface, checkboxes would do. I'm not sure where they would > be >> stored though, maybe in a new "XWikiDocument" object? >> >> >>> * meta: no parameters because sheets of this type are used to display >>> secondary objects. >>> >>> Now, regarding the way to set these parameters I think we have three >>> options: >>> >> >> Based on what I said above, the need for such an interface would be

> for >> page-level settings. I have no preference about how to store them, a

>> area would be fine as long as the user interface is made of checkboxes > and >> lists. >> >> (4A) String parameters >>> >>> Use a generic class, XWiki.ParameterClass, with two string properties, >>> key and value. >>> >>> pro: we can easily add a new parameter to the sheet (by adding a new >>> parameter object to the sheet document) without modifying the

>>> class. >>> >>> con: error prone >>> >>> (4B) Typed parameters >>> >>> Use a specific class, XWiki.SheetConfigClass, with properties matching >>> configuration parameters. >>> >>> pro: less error prone since parameters are typed and their names are >>> hard-coded >>> >>> con: harder to add/remove/rename parameters >>> >>> (4C) Velocity parameters >>> >>> Add a TextArea property to the XWiki.SheetClass, called 'parameters', >>> where we can set velocity variables. The value of this property will

>>> evaluated in startpage.vm after xwikivars.vm and layoutvars.vm. >>> >>> I prefer (4C). >>> >>> (5) In order to declare a sheet a xclass (or a plain document) has to >>> use an object of type XWiki.SheetInclude that has only one Database

>>> property called 'sheet' which, obviously, specifies the sheet to be >>> applied. A xclass can include zero (no sheets) or more sheets (a >>> different sheet for a different action). >>> >> > >> Ok. We'll also need to update the XWiki.ClassSheet page to provide a

>> interface for this. > > For sure. > >> >> (6) The only case when sheets can conflict is when a document has >>> objects of different types that declare 'page' sheets for the same >>> action. Multiple objects with 'meta' sheets are aggregated under the >>> 'Objects' tab. Multiple objects with 'inline' sheets are aggregated >>> inside the 'xwikicontent' element in view mode and inside the same

>>> form in edit mode. A 'page' sheet can choose to display 'inline' and >>> 'meta' sheets, and of course 'inline' and 'meta' sheets can be

>>> by the default view mode. >>> >>> The conflict between 'page' sheets can be resolved by defining an

>>> between objects. I prefer an inherent order (e.g. the object that was >>> added first is the most/less important) rather than an explicit

>>> field. >>> >> >> I think that's going to be an edge use case. Usually when you go

> the >> hassle of building a complete new page to display specific objects,

>> display is very customized anyway and you can write a page sheet that >> aggregates 2 other page sheets if needed. > > Yep. > >> >> (7) Sheet resolution: >>> >>> * if the current document has an object of type XWiki.SheetInclude and >>> the specified sheet has display:page and matches the current action

>>> apply it >> >> >> Ok. >> >> >>> (in case there are more XWiki.SheetInclude objects that satisfy >>> this constraint then use the one with the lowest/highest index). >>> >> >> I think that this is actually the sign of an error on the part of the

>> who created the application, but your solution would work. >> >> >>> * if the current document has objects whose xclass declares a 'page' >>> sheet, then resolve the conflict and use the proper sheet. >>> * if there is no 'page' sheet included either by the current document

>>> by one of its objects then aggregate all 'inline' and 'meta' sheets >>> (from the objects and from the document itself). >>> * if there are no 'inline' sheets then simply display the default >>> view/edit mode. >>> >> >> Ok. >> >> WDYT? >>> >> > >> That I'm looking forward to seeing all this implemented ;-) > > I'm going to create a feature branch ASAP. > > Thanks again for your feedback, > Marius > >> >> Thanks, >> >> Guillaume >> >> Thanks, >>> Marius >>> >>> On 06/28/2011 07:43 PM, Marius Dumitru Florea wrote: >>>> Hi devs, >>>> >>>> A prerequisite for Application Within Minutes [1] is to be able to >>>> specify the sheet that will be used to display a document without >>>> touching the content of that document [2]. This can be done in

>>>> ways, depending on how we define the notion of a sheet. >>>> >>>> >>>> (1) Class sheets vs. document sheets >>>> >>>> A class sheet displays an object of a particular type and is

>>>> in the definition of that type. This means that when you create or

>>>> a class, i.e. a type of object, you can specify which sheet should be >>>> used to display the instances of that class. >>>> >>>> Pro: Documents don't have to specify a sheet. >>>> Con: We have to determine which sheet to use in case there are

>>>> objects attached to a document. >>>> >>>> A document sheet displays a document of a particular type and is >>>> specified at document level because the document type, unlike the >>>> xclass, does not exist actually. The document type is inferred from

>>>> type of objects the document has, or from its content, or, why not, > from >>>> the type of attachments it has. >>>> >>>> Pro: Doesn't have the class sheet con. >>>> Con: Each document has to specify which sheet to use. >>>> >>>> Class sheets are enough for Application Within Minutes because the >>>> wizard will create a single class (with a sheet) and so the

>>>> items will have only one object that specifies a sheet. >>>> >>>> >>>> (2) Separate sheets per action? >>>> >>>> The current practice is to define a single (class) sheet which either >>>> checks for the current action in its code or uses doc.display method >>>> whose output is action specific. >>>> >>>> How often did you had the need to write separate sheets per action > (e.g. >>>> create, view, edit, search, changes)? >>>> >>>> >>>> (3) Which actions require a sheet? >>>> >>>> If we're talking about class sheets then the list of actions that > target >>>> an object and which require a sheet is limited. Currently we have > "view" >>>> and "edit", but Ludovic proposed also "create", "search" and

>>>> >>>> If we're talking about document sheets then we can have custom

>>>> and so we need an extensible mechanism to map actions to sheets. >>>> >>>> >>>> (4) Sheet parameters? >>>> >>>> If we're talking about class sheets then they only need to specify

>>>> an object is displayed. Document sheets on the other hand may need to >>>> control elements like: >>>> >>>> * which tabs (comments, annotations, attachments, etc.), if any, are >>>> displayed >>>> * show title field in edit mode >>>> * the side panels >>>> * the form buttons >>>> >>>> >>>> WDYT? >>>> >>>> Thanks, >>>> Marius >>>> >>>> [1] > http://dev.xwiki.org/xwiki/bin/view/Design/ApplicationWithinMinutes >>>> [2] >>>> >>> >