×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Add viewports using the REST API

Thomas Walker

Thomas Walker Last update: Aug 7, 2017

Scroll Viewport provides a REST API for creating new viewports. To create a viewport you must send a POST request to the REST endpoint, containing the viewport definition as JSON structure in the request body.

POST application/json to <BASE_URL>/rest/scroll-viewport/1.0/viewport/<SPACE_KEY>

{
    "domainName": "",
    "themeId": "com.k15t.scroll.scroll-viewport:viewport-theme",
    "pathPrefix": "/test",
    "repository": {
        "_type": "ConfluenceSpaceRepository",
        "spaceKey": "TEST",
        "pagesEnabled": true
    }
}

The above is a rather minimal example where only pages are enabled in a space (whereas blogposts are not) and hierarchical page paths are used.

You can always retrieve a complete example for the config JSON structure by sending a GET request:

GET <BASE_URL>/rest/scroll-viewport/1.0/viewport/<SPACE_KEY>/new

 {
    "id": "C0A812D10152D03A986C6F6A37B2BA96",
    "domainName": "",
    "themeId": "com.k15t.scroll.scroll-viewport:scroll-webhelp-theme",
    "draft": true,
    "previewUrl": "/confluence/plugins/scroll-viewport/draft/C0A812D10152D03A986C6F6A37B2BA96",
    "viewportUrl": "http://localhost:1990/confluence/plugins/scroll-viewport/draft/C0A812D10152D03A986C6F6A37B2BA96",
    "pathPrefix": "",
    "repository": {
        "_type": "ConfluenceSpaceRepository",
        "spaceKey": "TEST",
        "pagesEnabled": true,
        "pagePathPrefix": "",
        "pageUrlNaming": {
            "_type": "HierarchicalUrlNaming"
        },
        "blogPostsEnabled": false,
        "blogPostPathPrefix": "/blog",
        "blogPostUrlNaming": {
            "_type": "DefaultBlogPostUrlNaming"
        },
        "repoProperties": []
    }
}

Available JSON fields

NameAPI Default ValueRequiredDescription
id
<empty>(error)When creating a new viewport this field should NOT be contained in the config structure.
domainName
<empty>(error)

The value of the Domain Name field in the viewport config UI.

themeId
com.k15t.scroll.scroll-viewport:scroll-webhelp-theme
(error)The ID of the theme to use for the new viewport.
draft
false
(error)This should either be removed or set to "false" when creating a new viewport
previewUrl
viewportUrl
<empty>(error)These have no effect when creating a new viewport. It is recommended to omit these fields.
pathPrefix
<empty>(error)

The path prefix your viewport will be available at. Only a single viewport per domain name can have a blank path prefix.

In the viewport config UI this defaults to the lowercase space key with a leading slash.

repository._type
 (tick)This must be set to "ConfluenceSpaceRepository".
repository.spaceKey
 (tick)The key of the space you want to assign the viewport to. Must be the same as in the POST URL.
repository.pagesEnabled
repository.blogPostsEnabled
false(tick)Define what content your viewport provides. Make sure to set at least one of them to "true".
repository.pagePathPrefix
repository.blogPostPathPrefix
<empty>(error)

The path prefixes for pages and blogposts. If both pages and blog posts are enabled these must NOT be identical.

In the viewport config UI the prefix for pages is empty by default and the prefix for blogposts is "/blog".

repository.pageUrlNaming._type
HierarchicalUrlNaming
(error)

Defines how page URLs are created. There are two options:

  • HierarchicalUrlNaming

  • FlatUrlNaming

repository.blogPostUrlNaming._type
DefaultBlogPostUrlNaming
(error)

Defines how blog post URLs are created. Currently only "DefaultBlogPostUrlNaming" is supported.

repository.repoProperties
 <empty>(error)Should NOT be included when creating a new viewport.

2x2.11
We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information: click here.
Ok