This package contains services for retrieving content and navigation using APIs offered by Crafter CMS.
All of Crafter CMS packages can be used either via npm or in plain html/javascript via regular script imports.
- Install module using
yarn
ornpm
- Yarn:
yarn add @craftercms/content
- npm:
npm install @craftercms/content
- Yarn:
- Import and use the service(s) you need
- Download the bundle and import them in your page.
- The bundle declare a global variable named
craftercms
. You can access all craftercms' packages and functions under this root. - The
content
package depends onrxjs
,@craftercms/utils
,@craftercms/classes
; make sure to import those too before thecontent
script.
Tip: Once you've imported the scripts, type craftercms
on your browser's dev tools console to inspect the package(s)
<div id="myFeature"></div>
<script src="https://unpkg.com/rxjs"></script>
<script src="https://unpkg.com/@craftercms/utils"></script>
<script src="https://unpkg.com/@craftercms/classes"></script>
<script src="https://unpkg.com/@craftercms/content"></script>
<script>
(function ({ content }, { operators }) {
content.getItem(
'/site/website/index.xml',
{ baseUrl: 'http://localhost:8080', site: 'editorial' }
).pipe(
operators.map(content.parseDescriptor)
).subscribe((model) => {
const elem = document.querySelector('#myFeature');
Object.entries(model).forEach(([fieldId, value]) => {
if (fieldId !== 'craftercms') {
const el = document.createElement('div');
el.innerText = `${fieldId}: ${value}`;
elem.appendChild(el);
}
});
});
})(craftercms, rxjs);
</script>
You may pre-configure content services to a certain configuration to then you may omit the config param on subsequent calls to services
import { Item } from '@craftercms/models';
import { getItem } from '@craftercms/content';
import { crafterConf } from '@craftercms/classes';
// Configure crafter services "globally". Your config will be cached.
// All content services use the specified configuration on subsequent calls.
crafterConf.configure({
baseUrl: 'http://authoring.company.com',
site: 'editorial'
});
// Second param "config" will use "http://authoring.company.com" as
// crafter base url and "editorial" as the site to query
getItem('/site/website/index.xml').subscribe((item: Item) => {
console.log(item);
});
The examples below assume usage in the style of using via npm. If you're using the bundles,
directly importing as a script in the browser, these functions will be under the global variable
named craftercms.content
(i.e. window.craftercms.content
).
Parse a Descriptor, Item or a GraphQL response into a Content Instance. It could also be a collection of any of these types.
parseDescriptor(response: Descriptor | Item | GraphQLResponse | Descriptor[] | Item[] | GraphQLResponse)
Parameters | |
---|---|
response | The response of a getItem, getDescriptor or GraphQL fetch call |
- If you want a cleaner/parsed response, you may use
parseDescriptor
util to parse the response for you. You may use it to parse getItem, getDescriptor or GraphQL responses.
import { map } from 'rxjs/operators';
import { ContentInstance } from '@craftercms/models';
import { getChildren, getItem, parseDescriptor } from '@craftercms/content';
getItem('/site/website/index.xml', { site: 'editorial' }).pipe(
map(parseDescriptor)
).subscribe((content: ContentInstance) => {
console.log(content);
});
getChildren('/site/website', { site: 'editorial' }).pipe(
map(parseDescriptor)
).subscribe((content: ContentInstance[]) => {
console.log(content);
});
Inspects and parses elasticsearch hits and pre-parses objects before they can be sent to parseDescriptor @see https://github.com/craftercms/craftercms/issues/4057
import { createQuery, search } from '@craftercms/search';
import { parseDescriptor, preParseSearchResults } from '@craftercms/content';
search(
createQuery({
query: {
bool: {
filter: [/*...*/]
}
}
}),
{ baseUrl: 'http://localhost:8080', site: 'editorial' }
).pipe(
map(({ hits, ...rest }) => ({
...rest,
hits: hits.map(({ _source }) => parseDescriptor(
preParseSearchResults(_source)
))
}))
).subscribe((results) => {
// Do stuff with results...
});
Get an Item from the content store.
getItem(path: string, config?: CrafterConfig)
Parameters | |
---|---|
path | The item’s path in the content store |
config | Crafter configuration. Optional. Default value in here. |
Item - from the content store
- Get the index page from the site:
import { Item } from '@craftercms/models';
import { getItem } from '@craftercms/content';
getItem('/site/website/index.xml', { site: 'editorial' }).subscribe((item: Item) => {
console.log(item);
});
- If you want a cleaner/parsed response, you may use
parseDescriptor
util to parse the response for you.
import { map } from 'rxjs/operators';
import { ContentInstance } from '@craftercms/models';
import { getItem, parseDescriptor } from '@craftercms/content';
getItem('/site/website/index.xml', { site: 'editorial' }).pipe(
map(parseDescriptor)
).subscribe((content: ContentInstance) => {
console.log(content);
});
Get the descriptor data of an Item in the content store.
getDescriptor(path: string, config?: CrafterConfig)
Parameters | |
---|---|
path | The item’s path in the content store |
config | Crafter configuration. Optional. Default value in here. |
Descriptor - from the content store
- Get the index page from the site:
import { map } from 'rxjs/operators';
import { getDescriptor, parseDescriptor } from '@craftercms/content';
import { Descriptor, ContentInstance } from '@craftercms/models';
// Example 1: Supplying config inline, Descriptor response...
getDescriptor('/site/website/index.xml', { site: 'editorial' }).subscribe((descriptor: Descriptor) => {
console.log(descriptor);
});
// Example 2:
// - Omit config (must have configured earlier @see Usage section above)
// - Parse the response
getDescriptor('/site/website/index.xml').pipe(
map(parseDescriptor) // Optional. Use for a cleaner parsed response.
).subscribe((content: ContentInstance) => {
console.log(content);
});
Get the list of Items directly under a folder in the content store.
getChildren(path: string, config?: CrafterConfig)
Parameters | |
---|---|
path | The folder’s path |
config | Crafter configuration. Optional. Default value in here. |
Item[] - List of Items from the content store
- Get the children items under root folder from the site:
import { getChildren } from '@craftercms/content';
// Example 1: Supplying config inline
getChildren('/site/website', { site: 'editorial' }).subscribe((children) => {
console.log(children);
});
// Example 2: Omits the config param (must have been previously configured, see Usage section above)
getChildren('/site/website').subscribe((children) => {
console.log(children);
});
Get the complete Item hierarchy under the specified folder in the content store.
getTree(path: string, depth: number, config: CrafterConfig)
Parameters | |
---|---|
path | The folder’s path |
depth | Amount of levels to include. Optional. Default is 1
|
config | Crafter configuration. Optional. Default value in here. |
Item - from the content store
- Get the items tree under root folder from the site:
import { getTree } from '@craftercms/content';
// This call will get 3 levels of the tree under the specified folder
// Example 1: Config supplied inline
getTree('/site/website', 3, { site: 'editorial' }).subscribe((tree) => {
console.log(tree);
});
// Example 2: Services pre-configured (see "Usage" section above), config param omitted.
getTree('/site/website', 3).subscribe((tree) => {
console.log(tree);
});
Returns the navigation tree with the specified depth for the specified store URL.
getNavTree(path: string, depth: number, currentPageUrl: string, config: CrafterConfig)
Parameters | |
---|---|
path | The folder’s path |
depth | Amount of levels to include. Optional. Default is 1
|
currentPageUrl | The URL of the current page. Optional. Default is ''
|
config | Crafter configuration. Optional. Default value in here. |
NavigationItem - from the content store
- Get the navigation tree of the root folder from the site (depth = 3):
import { getTree } from '@craftercms/content';
// Example 1: Config supplied inline
getTree('/site/website', 3, { site: 'editorial' }).subscribe((tree) => {
console.log(tree);
});
// Example 2: Services pre-configured (see "Usage" section above), config param omitted.
getTree('/site/website', 3).subscribe((tree) => {
console.log(tree);
});
Returns the navigation items that form the breadcrumb for the specified store URL.
getNavBreadcrumb(path: string, root: string, config: CrafterConfig)
Parameters | |
---|---|
path | The folder’s path |
root | the root URL, basically the starting point of the breadcrumb. Optional. Default is ''
|
config | Crafter configuration. Optional. Default value in here. |
NavigationItem[] - List of NavigationItem from the content store
- Get the breadcrumb for the root folder from the site:
import { getNavBreadcrumb } from '@craftercms/content';
// Example 1: Config supplied inline
getNavBreadcrumb('/site/website').subscribe((navBreadcrumb) => {
console.log(navBreadcrumb);
});
// Example 2: Services pre-configured (see "Usage" section above), config param omitted.
getNavBreadcrumb('/site/website').subscribe((navBreadcrumb) => {
console.log(navBreadcrumb);
});
Transforms a URL, based on the current site’s configuration.
transform(transformerName: string, path: string, config: CrafterConfig)
Parameters | |
---|---|
transformerName | Name of the transformer to apply |
path | URL that will be transformed |
config | Crafter configuration. Optional. Default value in here. |
string - URL transformed according to transformer applied.
- Transform a store path into a render path
import { urlTransform } from '@craftercms/content';
// Example 1: Config supplied inline
urlTransform('storeUrlToRenderUrl', '/site/website/style/index.xml', { site: 'editorial' }).subscribe((webUrl) => {
console.log(webUrl); // "/style"
});
// Example 2: Services pre-configured (see "Usage" section above), config param omitted.
urlTransform('storeUrlToRenderUrl', '/site/website/style/index.xml').subscribe((webUrl) => {
console.log(webUrl); // "/style"
});
- Transform a render path into a store path
import { transform } from '@craftercms/content';
// Assuming that you already set the configuration (as explained above)
// Example 1: Config supplied inline
transform('renderUrlToStoreUrl', '/technology', { site: 'editorial' }).subscribe((path) => {
console.log(path); // "/site/website/technology/index.xml"
});
// Example 2: Services pre-configured (see "Usage" section above), config param omitted.
transform('renderUrlToStoreUrl', '/technology').subscribe((path) => {
console.log(path); // "/site/website/technology/index.xml"
})