hooks.js
Hooks are functions executed before Sitevision starts rendering a page. Hooks are declared in the hooks.js
file that must be placed directly under the WebApp's /src
folder.
Hooks have access to the Sitevision Public API
, Server side SDK
and any server side utility included in the WebApp.
To get access to the hooks available, simply import hooks in your hooks.js
file.
import hooks from '@sitevision/api/server/hooks';
Available hooks
There are three types of pre render hooks available: beforeRender
, getPageTitle
and addHeadElement
.
beforeRender
The beforeRender hook accepts a function with req
and res
as arguments. This hook is intended to run arbitrary code.
import { beforeRender } from '@sitevision/api/server/hooks';
beforeRender((req, res) => {
...
});
getPageTitle
The getPageTitle hook accepts a function with req
as argument. This hook should return a string that will be used as title of the current page.
import { getPageTitle } from '@sitevision/api/server/hooks';
getPageTitle(req => 'Page title');
A null or blank string will be ignored. Sitevision will always escape the returned string. If multiple WebApps on the same page use this hook, the last successfully invoked getPageTitle-hook will be used as
<title>
of current page.
addHeadElement
The addHeadElement hook accepts a function with req
as argument. This hook should return a string (a valid <head>
element) that will be added to the <head>
section of the current page.
import { addHeadElement } from '@sitevision/api/server/hooks';
addHeadElement(req => ...);
A null or blank returned string will be ignored. Sitevision will not escape the returned string so remember to escape all dynamically inserted values.
Request object (req
)
The request object (req
) is almost identical to the request object in a regular WebApp callback. However, there are two differences:
Additions
- A context object is available that makes it possible to fetch data in a hook and later consume it during rendering of the WebApp. See the example below of how it might be used.
Limitations
- route parameters will not be resolved. If you need to resolve route parameters in a hook, use the req.path property to resolve your captured value.
Response object (res
)
The response object (res
) is limited within the hooks context. The servlet response is not committed in this phase which makes it possible to set cookies and redirect. The following methods are available:
set(name, value)
- Set HTTP headers. Note that Content-Type cannot be set.
cookie(cookie)
- Set cookies
clearCookie(name)
- Clears a cookie
redirect(url, statusCode [@since 2023.03.1])
- Redirect to a given url
- Supported status codes:
- 301 (permanent)
- 302 (temporary)
- 303 [@since 2023.08.1]
- 307 [@since 2023.08.1]
- 308 [@since 2023.08.1]
- Defaults to 302 if no status code is provided
Example
Below is an example of what a hooks.js
might look like
// hooks.js
import {
beforeRender,
addHeadElement,
getPageTitle,
} from '@sitevision/api/server/hooks';
import { getEventData } from '../utils/eventsApi';
import endecUtil from '@sitevision/api/server/EndecUtil';
beforeRender((req) => {
const data = getEventData(req.params.eventId);
// req.context is propagated to the rendering phase (index.js)
req.context.eventData = data;
});
getPageTitle((req) => req.context.eventData.title);
addHeadElement((req) => {
const description = endecUtil.escapeXML(req.context.eventData.description);
return `<meta property="og:description" content="${description}">`;
});
addHeadElement((req) => {
const image = endecUtil.escapeXML(req.context.eventData.image);
return `<meta property="og:image" content="${image}">`;
});
The req.context
object is available during rendering of the WebApp with the data set in the beforeRender
-hook.
// index.js
router.get('/', (req, res) => {
// eventData set in beforeRender hook
console.info(req.context.eventData);
});