Macros comparable to Confluence excerpt and excerpt include

Help / Discuss
#1

Hi, All. New here, and a long-time Confluence user that may switch. One feature we use fairly often in Confluence is the excerpt macro, which allows an arbitrary piece of content (for example, a single sentence in a longer document) to be marked as an excerpt. That text can then be included in another page.

I’ve looked at the Include macro, and can pull in an entire page or a section (based on a heading), but not an arbitrary portion of a page. Does anyone know if this can be done, and if so, how? Thanks in advance.

#2

Nothing like this exist out of the box as far as I know. The closest is to include a specific section in a page (the content associated with a specific heading).

Implementing something like this should not be very hard I guess:

  • a special include macro which get the target page content and search the rendering block for
  • a special macro or a parameter in a GroupBlock or FormatBlock (div/span) to mark some content (or both)
  • return the found blocks

If you want to give it a try you could take a look at https://rendering.xwiki.org/xwiki/bin/view/Main/ExtendingMacro and https://rendering.xwiki.org/xwiki/bin/view/Main/GettingStarted in general to see how to manipulate blocks.

#3

Another idea would to include the first paragraph found after an IdBlock (i.e. after a label/anchor that you set with the {{id name='something(/}}.

You’d include it like this: {{include reference="ref" anchor|label="something'/}}.

More specifically it could work like this:

  • If the IdBlock is inline, then include only the block after it.
  • If the IdBlock is standalone, then include the next standalone element (the paragraph, the list, the table, etc).

WDYT?

@DavidKing Note that this can be scripted easily using the XWiki XDOM API. See https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Scripting/APIGuide/#HFindXDOMBlocks

EDIT: For fun I’ve just coded a crude version that you can put in a wiki macro (see https://www.xwiki.org/xwiki/bin/view/Documentation/DevGuide/Tutorials/WritingMacros/WikiMacroTutorial/):

{{velocity}}
#set ($mydoc = $xwiki.getDocument('Sandbox.WebHome'))
#foreach ($block in $mydoc.getXDOM().getBlocks('class:MacroBlock', 'DESCENDANT'))
  #if ($block.id == 'id' && $block.parameters.name == 'something')
    $services.rendering.render($block.nextSibling, $doc.syntax.toIdString())
  #end
#end
{{/velocity}}

Example usage: see https://playground.xwiki.org/xwiki/bin/view/Main/VMA/ (Note: this playground wiki is reset every night).

#4

Thanks, all, for the thoughtful suggestions. As I said I am brand new to XWiki, so I need to spend more time both with syntax and with features that can be enabled via the API.

#5

It seems there has been made some progress on this subject.

The excerpt macro has been developed: https://github.com/xwikisas/xwiki-pro-macros/issues/13

But the excerpt-include macro (https://github.com/xwikisas/xwiki-pro-macros/issues/26) is not finished yet, due to [CONFLUENCE-75] Empty parameter name and value after import - XWiki.org JIRA

1 Like
#6

I have now found a way to implement some of the excerpt / include functionality with sections and the include macro.

On my page Sandbox/TestPage1 I have added a section, in source code view:

== MyValue ==
Basis

== Alternatives ==
* Basic
* Start

According to https://extensions.xwiki.org/xwiki/bin/view/Extension/Include%20Macro, the section will have the name HMyValue. It is important that the Heading will not have spaces itself, otherwise excludeFirstHeading will only exclude the first word of the heading.

On another page, Sandbox/TestPage2, I have inserted the macro like this, in source code view:

{{include reference="Sandbox.TestPage1" section="HMyValue" excludeFirstHeading="true"/}}

After saving, I will see Basis on the TestPage2.

Hint: the name of the macro is translated, so in a German installation, in the WYSIWYG Editor, when adding a macro, search for “Einbinden” instead of “Include”…

#7

Thanks Vincent, I implemented the excerpt-include macro using this.

https://github.com/xwikisas/xwiki-pro-macros/issues/26#issuecomment-1798449443