Confluence Docs 3.0 : Content by Label Macro This page last changed on Oct 02, 2009 by ggaskell. The Content by Label macro lists content which has been tagged with specific labels. On this page: Usage with the Macro Browser Usage with the Wiki Markup Editor Parameters Examples 1. Show content from a specific space 2. Show only results in current space 3. Show results from all spaces 4. Show only content of a specified type 5. Do not show the labels in the results 6. Do not show the space names in the results 7. Display excerpts in the results 8. Specify the maximum number of results to display 9. Sort by modification date 10. Change the sort order ## Usage with the Macro Browser To insert the content by label macro into a page using the Macro Browser, Open your desired Confluence page, then click the 'Edit' button. The 'Edit Page' mode opens. Next, click the Macro Browser icon on the editor toolbar. The Macro Browser will open in the middle of the screen. In the Macro Browser, type the name of your desired macro into the search box at the top right of the window. Macros with a matching name will appear in the centre pane. Click on the desired macro to see its options screen. Here, you can set the macro parameters then click 'insert' to put the macro into the page. Once you've found the content by label macro, click 'insert' to add it to your page. ## Usage with the Wiki Markup Editor To display all pages with the label `needs-fixing`, use:
    {contentbylabel:label=needs-fixing|showLabels=false|showSpace=false|maxResults=99|space=@self}
Below is a working example of the 'Content by Label' macro. In the example, we have restricted the display to 5 results. By default, Confluence lists all the labels for each result displayed. See the optional parameters below for more information.
What you need to type | What you will get
--- | ---
{contentbylabel:label=documentation|maxResults=5} |
Related Labels Macro (Confluence 2.0) Labels: documentation
Character encodings in Confluence (Confluence Docs 2.10) Labels: documentation, internal, http, database, confluence, utf8, unicode, encoding, character
2.1 Connecting Crowd to a Database (Crowd 1.2) Labels: database, setup, configuration, installation, crowd, documentation
Connecting CrowdID to a Database (Crowd 1.4) Labels: crowdid, database, setup, configuration, installation, crowd, documentation
Connecting Crowd to a Database (Crowd 1.5) Labels: documentation, crowd, installation, configuration, setup, database
Showing first 5 of 237 results
## Parameters Parameters are settings for Confluence macros that allow the user to control their content or presentation. The table below lists relevant parameters for this macro. Parameter names are displayed differently in the macro browser interface and in wiki markup. Below, parameter names used in the macro browser are indicated in Bold text, while their equivalents in wiki markup are indicated in (`bracketed`) text. If the latter is not shown, then in wiki markup, the parameter's name should be omitted and only its value should be added immediately after the colon symbol (`:`).
Parameter | Default | Description
--- | --- | ---
(`author`) | None | Filter the results by author. The macro will display only the pages etc which are written or updated by the author(s) you specify here. You can specify one or more authors, separated by a comma.
Label(s) (`label`) or (`labels`) | None | This parameter is required. Use this parameter to filter the results by label. The macro will display only the pages etc which are tagged with the label(s) you specify here. You can specify one or more label values, separated by a comma or a space. To exclude content which matches a given label, put a minus sign (-) immediately in front of that label value. For example: If you specify a label value of `-badpage` you will get only content which is not labelled with 'badpage'. To indicate that the results must match a given label value, put a plus sign (+) immediately in front of that label value. For example: If you specify a label value of `+superpage,+goodpage` you will get only content which has at least two labels, being 'superpage' and 'goodpage'.
Maximum Number of Pages (`max`) or (`maxResults`) | 15 | Specify the maximum number of results to be displayed. Note that the results are sorted first, and then the maximum parameter is applied.
(`operator`) | OR | The operator to apply to the supplied lists of labels. By default, a page with any of the non-prefixed labels (that is, labels without a plus (+) or minus (-) sign immediately preceding it) will be listed. By using `operator=AND`, only pages with all of the supplied non-prefixed labels will be listed. Be aware that this parameter only modifies the behaviour of the 'Label(s)' parameter and only affects label values without a plus (+) or minus (-) sign prefix. To avoid confusion or unexpected results, it is not recommended that the operator parameter be used in conjunction with any label values prefixed with '+' or '-' signs.
Show Labels for Each Page (`showLabels`) | true | Show or hide labels for results.
Show Space Name for Each Page (`showSpace`) | true | Show or hide spaces for results.
Reverse Sort (`reverse`) | false | Use this parameter in conjunction with the `sort` parameter described below. Set `reverse=true` to change the sort from ascending to descending. this parameter is ignored if the `sort` parameter is not specified.
Sort By (`sort`) | modified | Specify how the results should be sorted. To change the sort order from ascending to descending, use the `reverse` parameter described above. Note: If this parameter is not specified, the sort order defaults to descending order based on the last modification date. Values: `creation` — Sort by the date on which the content was added. `title` — Sort alphabetically by title. `modified` — Sort by the date on which the content was last updated.
Restrict to these Spaces (`space`) or (`spaces`) | @all, i.e. all spaces in your Confluence site. | This parameter allows you to filter content by space. The macro will display only the pages etc. which belong to the space(s) you specify here. You can specify one or more space keys, separated by a comma or a space. To exclude content in a specific space, put a minus sign (-) immediately in front of that space key. For example: If you specify a space key of `-BADSPACE` you will get only content which is not in the BADSPACE. To indicate that the results must come from a specific space, put a plus sign (+) immediately in front of that space key. For example: If you specify a space key of `+GOODSPACE` you will get only content in GOODSPACE. (Note that this is not particularly useful, because each content item belongs to one space only. If you put a plus sign next to one space key and list other space keys too, the other space keys will be ignored.) Special values: `@self` — The current space. `@personal` — All personal spaces. `@global` — All global spaces. `@favorite` — The spaces you have marked as favourite. `@favourite` — The same as `@favorite` above. `@all` — All spaces in your Confluence site. `*` — The same as `@all` above. When specifying a personal space, remember to use the tilde (~) sign in front of the username, such as `~jbloggs` or `~jbloggs@example.com`.
List Title (`title`) | None | Adds a title or heading to the list.
Include these Content Types Only (`type`) | all | This parameter allows you to filter content by content type. The macro will display only the content of the type you specify here. You can specify one or more types, separated by a comma or a space. To exclude content of a given content type, put a minus sign (-) immediately in front of that content type. For example: If you specify a content type of `-blogpost` you will get pages and all other content except for blog posts. Available values: `page` — Pages. `blogpost` or `news` — Blog posts, also known as news items.
Display Excerpts (`excerpts`) | false | Displays the first line of excerpts for each page.
## Examples #### 1. Show content from a specific space
    {contentbylabel:label=dogs,cats|space=PETS}
#### 2. Show only results in current space
    {contentbylabel:label=dogs,cats|space=@self}
#### 3. Show results from all spaces
    {contentbylabel:label=dogs,cats|space=@all}
#### 4. Show only content of a specified type The code below will show only pages (but not news items or other content types) with the labels 'dogs' or 'cats':
    {contentbylabel:label=dogs,cats|type=page}
#### 5. Do not show the labels in the results
    {contentbylabel:label=dogs,cats|showLabels=false}
#### 6. Do not show the space names in the results
    {contentbylabel:label=dogs,cats|showSpace=false}
#### 7. Display excerpts in the results
    {contentbylabel:label=dogs,cats|excerpt=true}
#### 8. Specify the maximum number of results to display
    {contentbylabel:label=dogs,cats|max=99}
#### 9. Sort by modification date
    {contentbylabel:label=dogs,cats|sort=modified}
#### 10. Change the sort order
    {contentbylabel:label=dogs,cats|sort=modified|reverse=true}
##### RELATED TOPICS Related Labels Macro Navmap Macro Recently Used Labels Macro Working with Labels Overview Working with Macros Take me back to the Confluence User Guide.

Document generated by Confluence on Nov 05, 2009 23:35