Improve the Encyclopedia template

[mflorea]

Hi everyone,

The Encyclopedia template is one of the few templates we bundle in XWiki Standard. While working on XWIKI-20712 I noticed that it has some issues:

• The text doesn’t extend below the boxes on the right. The template basically has two columns, but the second (right) “column” (with the boxes) is most of the time way shorter than the first. This means there is a lot of space lost on the second column, below the boxes. I know that long lines of text are harder to read than short-width columns, but I don’t think this was the purpose here (to make the “content column” thinner). As its name suggests, the template is actually trying to provide a layout similar to the one from Wikipedia, where the text is expanding below the right boxes.
• Sections titles are missing the Edit pencil icon, because the headings are wrapped in some DIV HTML tags.
• The wiki syntax is using the group XWiki syntax (% class="box" %)(((...))) instead of the Box macro, probably because the Box macro was not editable in-line when this template was written.
• The wiki syntax is more complex than it should be, making it harder to edit with the WYSIWYG editor. In general, CKEditor editing experience when your content has DIV tags is not the best, so we should try to avoid it, if possible. It’s fine when those DIV tags come from a macro (ideally editable inline), because they are read-only.

I’d like to update the content of the Encyclopedia template to fix the mentioned issues:

• use the Box macro for the right boxes
• wrap the 2 right boxes in a floatinginfobox DIV, so that the text extends below them
  • Remove the top margin (6px) from the floatinginfobox to align it with the content of the left. I think this makes sense in all cases when floatinginfobox is used.
  • Increase the left and bottom margin to match the @grid-gutter-width. I think it makes sense to have this kind of spacing for the floatinginfobox in general.
• improve the styling so that the background color of the jumbotron doesn’t go below the right boxes

  .floatinginfobox + .jumbotron {
    overflow-x: auto;
  }
  

• Remove unnecessary DIV wrappers from the content, so that sections get their edit icon.

The result:

• Before
  
• After
  

Note that this also improves the result in the PDF export.

• Before
  
• After
  

WDYT?

Thanks,
Marius

[lucaa]

What a good idea, +1!

2 concerns, though:

• ideally, the template should be something reproducible by a user using a wysiwyg editor (actually, I think we may have voted on this in the past…). It was not the case before and it will probably not be the case now, but I guess it gets closer and closer. I was thinking that if we change it, we could try to bring it the closest possible to something do-able with the editor.
• I’m wondering what kind of impact this could have on upgrade, and I can think of 2 situations:
  • on a wiki intensively using the template, they will end-up with 2 “generations” of pages, one from before the upgrade and one from after. This corpus won’t behave in a unitary way (editing will be different, pdf print will be different, etc), which may be difficult to understand by regular users (not admins)
    • I am wondering what way out there is? Could we even think about any form of “migration” ? Probably not…
• if anyone has written any custom CSS for this, it won’t apply the same (after upgrade or on a mixed corpus), but this is a more rare situation and it can be relatively easily fixed.

Thanks,
Anca

[mflorea]

@lucaa

ideally, the template should be something reproducible by a user using a wysiwyg editor (actually, I think we may have voted on this in the past…). It was not the case before and it will probably not be the case now, but I guess it gets closer and closer. I was thinking that if we change it, we could try to bring it the closest possible to something do-able with the editor.

I agree it would be nice to be able to re-create this template from the WYSIWYG editor. With the new version I’m proposing there are only two things missing:

• a floating box macro, editable in-line
• a jumbotron macro, also editable in-line

Both should be easy to implement, provided we don’t add too many parameters.

@lucaa

I’m wondering what kind of impact this could have on upgrade, and I can think of 2 situations:

• on a wiki intensively using the template, they will end-up with 2 “generations” of pages, one from before the upgrade and one from after. This corpus won’t behave in a unitary way (editing will be different, pdf print will be different, etc), which may be difficult to understand by regular users (not admins)
  • I am wondering what way out there is? Could we even think about any form of “migration” ? Probably not…

There are two problems:

1. We don’t know if a page was created with such a template or not. There is a template field in XWikiDocument but

   @todo this field is not used yet since it’s not currently saved in the database.

   There is also a defaultTemplate field, but

   The view template (vm file) to use. When not set the default view template is used.

2. Even if we could query the pages that were created with this template, we couldn’t do much because the layout is not enforced in any way. The user is free to change it, because it’s part of the content. So even if a page was created initially from the Encyclopedia template, the user may have removed all the content and transformed the page into completely something else. Thus, I don’t see how we could implement a migration.

@lucaa

if anyone has written any custom CSS for this, it won’t apply the same (after upgrade or on a mixed corpus), but this is a more rare situation and it can be relatively easily fixed.

Not exactly. The only big change I’m proposing is to replace the usage of Bootstrap grid (columns) with a floating box. The jumbotron at the top of the page and the boxes on the right are the same. So if someone has styled them (not inline from the content, obviously) then those styles should be preserved. And they should be preserved even if we introduce the floating box and jumbotron macros, since they will generate the same HTML structure.

Thanks for the feedback,
Marius

[mflorea]

@mflorea

I agree it would be nice to be able to re-create this template from the WYSIWYG editor. With the new version I’m proposing there are only two things missing:

• a floating box macro, editable in-line
• a jumbotron macro, also editable in-line

Both should be easy to implement, provided we don’t add too many parameters.

Should I also implement these 2 macros as part of the proposed changes? What do the others think?

Thanks,
Marius

[lucaa]

@mflorea

The only big change I’m proposing is to replace the usage of Bootstrap grid (columns) with a floating box. The jumbotron at the top of the page and the boxes on the right are the same. So if someone has styled them (not inline from the content, obviously) then those styles should be preserved.

You said you removed some containers also, so it may have an impact depending on how the CSS was wrote, but well, it needs to be some bad CSS and I agree that it’s a corner case, let’s not spend too much time on it.

@mflorea

wrap the 2 right boxes in a floatinginfobox DIV, so that the text extends below them

Actually, I just thought of it, could you also make the floatinginfobox mobile-friendly while at it?
IIRC it was not the best layout on all screen sizes…

Thanks,
Anca

[vmassol]

Sounds good, thanks @mflorea

[mflorea]

@lucaa

Actually, I just thought of it, could you also make the floatinginfobox mobile-friendly while at it?
IIRC it was not the best layout on all screen sizes…

The easiest is to disable the floating on small screens. I can do that.

[lucaa]

yes, this is what I meant. Depending on the size of the floating box, on some screens it should just be not floating.