3 Aug
2011
3 Aug
'11
10:49 a.m.
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> 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.
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.
* 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.
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.
(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.
* 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.
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.
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
Yep.
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.
(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:
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs 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/ApplicationWithinMinutesCoreChan…