Extension repository request for macro-card

Development
1

Hi, I would like to contribute an extension that will allow to display cards which can contains links, something like this:

macro_card-1
macro_card-11244×836 66.3 KB

I’m not sure about the name of the macro, I suggest macro-card, but if you have any others ideas, please let me know. Also, can you please create me a repository on xwiki-contrib and a JIRA project?
Thanks!

2

Hi, in order to help pick a name:

  • how would you use the macro? ie how do you specify the contents of the cards?
  • What would be the name of the macro?

At first sight, it seems like this could be a livetable display mode (card view).

I guess doing it at the LT macro is more complex and is something we need to plan in the generic LT 2.0 requirements. @mflorea could you confirm it’s listed in the requirements for it BTW? :slight_smile: (the ability to have several layouts: table layout, card layout, etc).

Thx

3

Hi!

So, yes, its displaying mode seems more like a LT functionality (the card macro is using two another integrated macros for displaying it using on rows and cols). From this point of view, it seems like an integration to LT makes more sense. Also, from what I know, the new LT will be based on JS, so I’m not sure how easy it would be to integrate it with some velocity macros.

From another point of view, it makes more sense to split the card macro (one that is responsible for displaying a content using a layout - bootstrap rows/cols) and one that will display the card - which can eventually used in the LT.

4

It is.

5

Hi!

It pretty much works like a table. The user defines rows and specifies content for cards. The card format is mostly given by some CSS. Here’s an example of usage:

{{row classes="home-card-row"}}
{{card title="[[XWiki>>Main.WebHome]]" buttons="no" image="xwiki.png" top-bgcolor="" link-bgcolor="" classes="col-lg-4 col-md-4 col-sm-6"}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
* [[Link with my own colors>>url:http://www.xwiki.org]]
{{/card}}
{{/row}}

For now, I would split the code into two macros: one that will display any type of content using Bootstrap columns & rows (to create a table aspect) and one that will apply CSS over the content to give the aspect of a card.

For naming, I was thinking of displayer-bootstrap-grid and displayer-cards-format, but I think they’re not so expressive.

6

Wy not use the existing {{container}} macro with potentially a custom layout instead, provided by your application? (see https://extensions.xwiki.org/xwiki/bin/view/Extension/Container%20Macro).

In this manner you only need to provide the {{card}} macro.

7

The concept of “displayer” is special in xwiki so we shouldn’t use that. If it’s a macro it needs to start with “macro-”, see https://contrib.xwiki.org/xwiki/bin/view/Main/WebHome#HChoosingthename.

So macro-card sounds good to me.

8

It’s not great to mix wiki markup in macro parameters. I’d advise against that if possible.

9

From what I understand, the {{container}} macro supports only inline content, which could be a limitation for the purpose of a card view (eg. any card should have a title; eventually using a header tag).

10

The container macro can take whatever content you want to put in it, and its layouter will decide how to display it. For example, today there is only one implementer layouter, the columns layout strategy, which expects groups in the content of the container macro and displays each group as a column.
So the content of the macro can be anything, it’s the layouter that will need to guide that.

11

So the problem was caused by the way I called the macro inside the {{container}} macro. The indentation used for calling the card macro will break the separation from the context.
Wrong way, {{card}} macro call is 2-spaces indented, this will not work

{{container layoutStyle="columns"}}
(((
  {{card title="Some fancy title" buttons="aligned" image="xwiki.png" text-height="120px" image-width="80" classes="col-lg-4 col-md-6 col-sm-6" icon="edit"}}
  ---macro content
  {{/card}}
)))
{{/container}}

Right way: no space for indentation

{{container layoutStyle="columns"}}
(((
{{card title="Some fancy title" buttons="aligned" image="xwiki.png" text-height="120px" image-width="80" classes="col-lg-4 col-md-6 col-sm-6" icon="edit"}}
  --macro content
{{/card}}
)))
{{/container}}

@vmassol, do you belive that we can add this case in https://www.xwiki.org/xwiki/bin/view/FAQ/Why%20do%20I%20get%20a%20"Not%20an%20inline"%20macro%20error?

12

Why we should avoid it?

Also, if all is fine with from your side, could you please create the repository & the JIRA project? The name should be macro-card.

13

I don’t think we should. The doc is already very explicit IMO. We cannot add all possible use cases and this use case is not a typical one that users get.

That depends on the card macro. If it supports inline then it’ll work.

It also depends if this is all wrapped by a {{velocity}} macro, in which case it’ll remove leading spaces, see the filter param on https://extensions.xwiki.org/xwiki/bin/view/Extension/Velocity%20Macro

14

Because parameters are not meant to contain wiki markup. You’ll also need to do special escaping to escape wiki markup syntax because it’s in a macro parameter syntax.

Wiki markup are meant to be defined in the content. Note that the box macro did the same mistake and will need to be refactored at some point because of that.

One other limitation is if you edit the macro inline, it’s probably not going to work.

15

Done:

Thanks