| Info |
|---|
The following is for MultiExcerpt Server and Data Center. MultiExcerpt Cloud information may be found here. |
The MultiExcerpt app performs similarly to the excerpt macro while also allowing for multiple excerpts from multiple spaces.
Demo
| Widget Connector | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
| Table of Contents |
|---|
Features
Ability to seamlessly transfer content between multiple pages and spaces
Reduces need for rewriting boilerplate documentation
Can be transferred inline with current content or in a resizable block
MultiExcerpts can contain Informational boxes, Flow Boards, and JIRA issues
MultiExcerpts can render inline comments from excerpted content
Allows admin to turn off visibility of inline comments for anonymous users (not possible using Confluence permissions)
Allows users to toggle visibility of inline comments on a page
User Guide
The MultiExcerpt function is a two-step process involving both macros:
Creating the MultiExcerpt key - the text you want to multiply and display in various locations.
Inserting the MultiExcerpt Include to display the key text.
Create the MultiExcerpt key
Select the MultiExcerpt macro.
Name the MultiExcerpt, then click Insert.
.png?version=1&modificationDate=1558109907264&cacheVersion=1&api=v2&width=306)
The MultiExcerpt key is displayed on the page..png?version=1&modificationDate=1558109907163&cacheVersion=1&api=v2&width=306)
Add the text you want to display in multiple locations inside the MultiExcerpt macro body.
.png?version=1&modificationDate=1558109907065&cacheVersion=1&api=v2&width=306)
Insert the MultiExcerpt Include
Select the MultiExcerpt Include macro. To include the MultiExcerpt inline with the current content, select MultiExcerpt Fast Include (Inline). Or, select MultiExcerpt Fast Include (Block) to insert the content as a resizable block.
.png?version=1&modificationDate=1558109906954&cacheVersion=1&api=v2&width=306)
Add where the MultiExcerpt key is located (Space and Page) and its Name, then click Insert.
.png?version=1&modificationDate=1558109906843&cacheVersion=1&api=v2&width=306)
The MultiExcerpt Include block displays while the Confluence page is in edit mode.
.png?version=1&modificationDate=1558109906722&cacheVersion=1&api=v2&width=204)
In view mode, your text displays exactly how it looks in the key MultiExcerpt.
.png?version=1&modificationDate=1558109906607&cacheVersion=1&api=v2)
Find MultiExcerpt Includes
You can search for all the locations where a specific MultiExcerpt has been included.
Navigate to the page where the MultiExcerpt is located.
Click
(page edit mode) to view the MultiExcerpt macro.
Click the MultiExcerpt macro and few options are displayed.
Click Find Includes.
The list of pages that include MultiExcerpt are listed. Click any link to go to that page.
MultiExcerpt integration with Comala Document Management (CDM)
MultiExcerpt macros works with other apps like the Comala Document Management plugin. To make this integration work smoothly, administrators must enable the feature from the app's Configuration page as well as from CDM.
The following points must be remembered:
A MultiExcerpt Include renders the latest approved version of MultiExcerpt content.
If the MultiExcerpt content was not approved and only draft versions exist, users without the relevant permissions cannot see the draft content in a MultiExcerpt Include. Instead, an error message that says they are not allowed to see drafts is displayed.
| Note |
|---|
Administrators must select the Comala Published Version Integration Enabled parameter in the MultiExcerpt Admin configuration page (Settings > Appfire Configuration > MultiExcerpt in the left sidebar). The same feature must be enabled (Published View Macro Transform parameter in CDM's configuration) from the Comala plugin as well. |
 |  |
| Note |
|---|
MultiExcerpt Enhanced Permissions
The 'MultiExcerpt Enhanced Permissions' feature allows users to include content from restricted pages and restricted spaces with specific users and/or groups. Use this feature to render content in a controlled way to anyone you want.
This macro is in its own module so it can easily be enabled/disabled by an administrator for the Confluence Server. It is disabled by default.
The "enhanced permissions" feature is complex enough that we document it in its own article: MultiExcerpt Enhanced Permissions.
MultiExcerpt Include Server Cache
Using several instances of MultiExcerpt Include on the same page in Confluence Server may cause slower page performance if you use several instances of MultiExcerpt Includes on a single Confluence page and if caching is disabled. To improve page performance when using several instances of MultiExcerpt Include, select the Cache Enabled box in the MultiExcerpt Include macro.
| Note |
|---|
Loading the page for the first time after enabling caching may still be slow while everything is cached in memory. Page performance will increase once everything has been cached. You may experience slowness for subsequent visits to the page if you leave it before this caching is complete. So if you have hundreds of MultiExcerpt Includes, we suggest you pull up the page and let it do its thing while you do something else. Or stare at it. Whatever method works for you to give it some time. |
How to enable/disable cache for your site:
Access the MultiExcerpt Admin tool under Confluence Administration:
| Info |
|---|
Other Admin Settings"Case Sensitive MultiExcerptNames" is used to enforce case-sensitivity for excerpts names, as specified by a MultiExcerpt Include. The default is true because the proper functioning of the cache and the "Find Includes" button depends on case-sensitive MultiExcerpt names. You can opt-out of this if you have a large number of mismatched references to excerpts and need time to fix them all. In old releases of MultiExcerpt, the names were case-insensitive and this may have allowed some users to mismatch their names/keys for excerpts. "Find Includes" is a feature that can be used by page authors to find a list of the location of the MultiExcerpt Includes that include their MultiExcerpt. It can be a DB and CPU intensive operation so some admins prefer to disable this feature. "Regular Expression to Match For MultiExcerpt-Include" is for a beta feature of MultiExcerpt Include. It allows the inclusion of other macros that are not MultiExcerpt macros. The regular expression is used to match the type/name of a macro. For example, the Code Block macro name/type is "code" so you could set the regular expression to "code" (without quotes) to include Code Block macros with MultiExcerpt Include. In the MultiExcerpt Include macro instead of using a MultiExcerpt name you would use a colon-delimited set of parameters that match the Code Block macro you want to include. For example, language=java:title=HelloWorldExample. This could be used to include a Code Block macro from one page to another page. Note that the "Find Includes" button does not work for includes that use this beta feature for inclusion of other macros. This beta feature is not wired up to the "Find Includes" functionality. |
| Expand | ||
|---|---|---|
| ||
An access check is performed on the cached value to ensure that a user has permission to see the included content before it is rendered, but this permission check is based only on Confluence permissions for the source of the original content (page permissions for the page with the MultiExcerpt on it). Therefore, all users who have permission to see the excerpt content (based on Confluence permissions) will have access to the cached value.This works for most scenarios but imagine a complex scenario in which you are nesting 3rd party macros in your MultiExcerpt that either restrict their content using something other than the Confluence restrictions for the page they are on or the 3rd party macros do something like render content that differs per-user. In such a scenario you would want to disable the cache for your MultiExcerpt Include macro. Another scenario where you may want to disable the cache for a MultiExcerpt Include is when you are including complex content that is subject to intermittent responses from whatever service(s) are behind them and/or the included content is implemented with poor/unreliable error handling and is prone to occasionally render “bad” responses. Such “bad” responses are normally solved in web apps with a page refresh and may not be noticed often enough by your users for them to report it to you. However, if a bad response ends up in the MultiExcerpt Include cache then it will become more noticeable. The admin tool allows you to flush the cache anytime, but if you ever encounter intermittent problems with rendering any included content that comes from 3rd party macros then consider disabling the MultiExcerpt cache. You can either disable the caching per MultiExcerpt Include or globally. We recommend you disable it at the MultiExcerpt level so that you have the flexibility you need depending on your usage and your environment. |
How to disable cache for individual MultiExcerpt Includes
Select the Disable Caching box for the individual MultiExcerpt Name and click Save.
.png?version=1&modificationDate=1558109906508&cacheVersion=1&api=v2&width=340)
Cache flush and performance tuning
Use the Cache Management tool in Confluence administration: General Configuration > Cache Management > Show advanced view and scroll down to our app.
Inline Comments
As of MuliExcerpt 5.5.0, we have added the ability to make inline comments on our MultiExcerpt and Atlassian's Excerpts that are also visible on the MultiExcerpt Include and on Atlassian's Includes.
| Warning |
|---|
LimitationsUsers will not be able to create inline comments on the content displayed on the Include page (Confluence limitation see CONFSERVER-36235)
|
Disable Inline Comment Viewing for Anonymous Users
At the time of the release of MultiExcerpt 5.5.0, Confluence has no way for admins (or anyone else) to use permissions to disable the viewing of comments for anonymous users on pages that the anonymous users are allowed to view.
Now your site admin has the power to hide inline comments from anonymous users using the MultiExcerpt Admin tool:
Users Can Toggle Inline Comment Visibility on a Page
MultiExcerpt adds an item to the page menu that allows users to show/hide inline comments for that page (only for that user). This setting is persisted and is used for subsequent page visits by that user until they change it.
Enable Inline Comment Viewing in Excerpted/Included Content
Allows your site admin to enable/disable the viewing of inline comments in MultiExcerpt Includes, where the comments have been made in the body of a MultiExcerpt on some other page that contains the MultiExcerpt that is included by the MultiExcerpt Include.
That’s a long way to say, “You can now view inline comments on included content!”
This feature works on both the MultiExcerpt Include macro and on Confluence’s “out of the box” Excerpt Include macro.
Specify Custom Colors for Included Inline Comments
Allows your site admin to specify custom colors for inline comments that are rendered in an include. They can specify both a color for an inline comment when it is not selected and when it is selected (via the user, using their mouse).
This feature works on both the MultiExcerpt Include macro and on Confluence’s “out of the box” Excerpt Include macro.
Per-macro control over inline comments
In the MultiExcerpt macro, there is a new parameter available in the macro editor to configure whether or not inline comments will be rendered in MultiExcerpt Includes that include the excerpt:
Admin control for inline comments in MultiExcerpt Includes vs Confluence Excerpt Includes
The admin configuration tool for the MultiExcerpt plugin has been enhanced to allow an admin to separately configure the rendering of inline comments for MultiExcerpt Include macros and for Confluence Excerpt Include macros:
Migrating MultiExcerpt from Server to Cloud or from Cloud to Server
There are MultiExcerpt apps for both Confluence Server and Confluence Cloud. There is a migration path for either direction:
Migrating MultiExcerpt from Server/Data Center to Cloud
Migrating MultiExcerpt from Cloud to Server/Data Center
Release Notes
Knowledge Base & Support Info
Additional Related Articles
| Filter by label (Content by label) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
General Articles
| Filter by label (Content by label) | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|