Hi Marius, On Wed, Aug 3, 2011 at 4:15 PM, Marius Dumitru Florea < [email protected]> wrote:
> Hi Guillaume, > > On 08/03/2011 04:15 PM, Guillaume Lerouge wrote: > > Hi Marius, > > > > On Wed, Aug 3, 2011 at 10:49 AM, Marius Dumitru Florea< > > [email protected]> 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< > >>> [email protected]> 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', > 'xdocFooter' > >>>> and 'xwikidata' DIVs. This means everything besides the header (logo > and > >>>> 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 > 'xwikicontent' > >>>> DIV in view mode and the form fields in edit mode (similar to the > >>>> current inline edit mode). > >>>> > >>> > >> > >>> So the title field is not included, correct? If so, I think it would be > >> good > >>> to display the title field by default in inline mode so that users can > >>> access it and modify it. > >> > >> The output of an inline sheet is placed where the content of the > >> document is currently placed. This means that a sheet with > >> display:inline doesn't control the title of the document, i.e. the title > >> of the document is displayed whatever output the sheet may have. > >> > >> When you edit (inline) a blog post the title of the document is > >> displayed followed by a title input field. They are synchronized because > >> document title is set to $doc.getValue("title"). With the new sheet > >> system we can (and should!) reuse the title and content of a document. > >> For instance we could remove the "title" and "content" fields from the > >> BlogPostClass and use instead the title and the content of the document > >> holding the blog post object. > >> > > > > Yes, that would be good. > > > > > >> With this in mind, do you think the current "inline" edit behaviour > >> (document title displayed read-only followed by sheet output) is bad? I > >> don't think so. I think it's best to let the sheet decide what form > >> fields to display. If we were to display the title input then what do we > >> do about document parent and document syntax? Should we also allow users > >> to edit them in "inline" edit mode? I don't think so. > >> > > > > > 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? > > Regarding the document title, I'm thinking that once we start using it > instead of an object property we might have the need to edit it in a > special way: > > * don't edit at all because it is automatically generated > * edit partially, e.g. only a suffix > > That's why I think it's better to let the sheet decide if and how the > title of the page is edited. > > Regarding the document parent, I'm thinking that for some applications > you may want to enforce a specific parent (e.g. the home page of the > application space). Again, the sheet can decide if the parent should be > editable or should be automatically set. > You're right, I had overlooked those use cases. We might still want to provide sheet creators with tools to easily include the title / parent field should they wish to use them (through a macro maybe?). As for the page syntax, I think it is a bit too technical and you don't > need to change it when you edit the structured data of an XWiki > application. > Indeed. Thanks, Guillaume >>> * meta: the sheet output is aggregated under the "Objects" document > >>>> extra tab. The bottom tabs are displayed only in view mode currently > but > >>>> 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 > than > >> a > >>> generic "Objects" tab. "Objects" is a technical term and I don't think > >> users > >>> would have the reflex to go and look at that tab. > >> > >> I thought about this initially but I gave up the idea because I felt is > >> was too complicated considering how bottom tabs are currently > >> implemented (with velocity templates). I'm going to postpone the "meta" > >> sheets for a while and focus only on "page" and "inline" sheets. > >> > > > > 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 > in > >> the > >>> tab, maybe through a translation key stored in a field of the > ClassSheet > >>> object. > >>> > >>> > >>>> The 'action' property specifies when to apply the sheet. The empty > >>>> string means the sheet can be applied on any action. > >>>> > >>> > >> > >>> What about a multi-select instead of a string given that the list of > >>> existing actions is already known? > >> > >> In the near future actions will be implemented as components (with the > >> help of the xwiki-platform-action module). XWiki applications will be > >> able to define their own actions so we can't use a static list for the > >> "action" sheet property. > >> > > > > > Even with actions implemented as components, you can still > programatically > > generate a list of existing actions and provide a list interface to > select > > 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 > only > > accepts values from a predefined subset. > > We can have an UI (e.g. in ClassSheet) that lets you choose from some > well known actions, but I don't think we should limit the type of the > "action" sheet property to StaticList. > > Thanks, > Marius > > > > >>> (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 > sure > >> I > >>> see the added value of defining panels at the class level. It's a > simple > >> to > >>> define them at the space level (and there's very often an > application<=> > >>> space mapping anyway). > >> > >> Ludovic proposed this btw. > >> > > > > 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 > for > >>> every page in the wiki under an "advanced" section (including normal > wiki > >>> pages). I don't see a reason to restrict those options only to pages > that > >>> have an object. > >> > >> I partially agree with you, but it would be a pain, for instance, to > >> have to configure all the blog post documents when you want change the > >> default bottom tab. It is a lot easier to just configure the > >> BlogPostSheet document and then enforce its configuration to all > >> documents holding a BlogPostClass object. > >> > > > > Right. > > > > > >> I think you'll agree with me that a system that allows us to configure a > >> wiki page, defaulting to the sheet configuration (when that document has > >> a sheet of course) is the best option. > >> > > > > 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 > only > >> for > >>> page-level settings. I have no preference about how to store them, a > text > >>> 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 > parameters > >>>> 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 > be > >>>> 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 > list > >>>> 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 > nice > >>> 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 > HTML > >>>> form in edit mode. A 'page' sheet can choose to display 'inline' and > >>>> 'meta' sheets, and of course 'inline' and 'meta' sheets can be > displayed > >>>> by the default view mode. > >>>> > >>>> The conflict between 'page' sheets can be resolved by defining an > order > >>>> between objects. I prefer an inherent order (e.g. the object that was > >>>> added first is the most/less important) rather than an explicit > priority > >>>> field. > >>>> > >>> > >>> I think that's going to be an edge use case. Usually when you go > through > >> the > >>> hassle of building a complete new page to display specific objects, > your > >>> 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 > then > >>>> 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 > dev > >>> 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 > or > >>>> 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 > multiple > >>>>> 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 > specified > >>>>> in the definition of that type. This means that when you create or > edit > >>>>> 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 > multiple > >>>>> 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 > the > >>>>> 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 > application > >>>>> 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 > "changes". > >>>>> > >>>>> If we're talking about document sheets then we can have custom > actions > >>>>> 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 > how > >>>>> 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] > >>>>> > >>>> > >> > http://dev.xwiki.org/xwiki/bin/view/Design/ApplicationWithinMinutesCoreChangeSheetDisplay > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
