enonic-wizardry

Enonic Wizardry

Functional utility library for Enonic XP. This library is intended to house reusable and tested code blocks based on enonic-fp that can be used in every project.

Enonic-fp

Enonic-wizardry is intended to supplement enonic-fp with common patterns.

Code generation

We recommend using this library together with the xp-codegen-plugin Gradle plugin. xp-codegen-plugin will create TypeScript interfaces for your content-types. Those interfaces will be very useful together with this library.

Building the project

npm run build

Usage

Get content by key service

In this example we have a service that returns an article by the key as json. Or if something goes wrong, we return an Internal Server Error instead.

import {fold} from "fp-ts/lib/IOEither";
import {pipe} from "fp-ts/lib/pipeable";
import {Request, Response} from "enonic-types/controller";
import {errorResponse, ok} from "enonic-fp/controller";
import {Article} from "../../site/content-types/article/article"; // 1
import {getContentByIds} from "enonic-wizardry/content";
import {forceArray} from "enonic-fp/array";

export function get(req: Request): Response { // 2
  const keys: Array<string> = forceArray(req.params.key); // ["key1", "key2", "key3"]

  const program = pipe( // 3
    getContentByIds<Article>(keys), // 4
    fold( // 5
      errorResponse(req), // 7
      ok // 8
    )
  );

  return program(); // 9
}

1. We import an interface Article { ... } generated by xp-codegen-plugin.
2. We use the imported Request and Response to control the shape of our controller.
3. We use the pipe function from fp-ts to pipe the result of one function into the next one.
4. We can use the getContentByIds function from content that query for the Content<Article> where the id is one of the strings in the keys-Array. The return type here is IOEither<EnonicError, ReadonlyArray<Content<Article>>>
5. The last thing we usually do in pipe is to unpack the IOEither. This is done with fold(handleError, handleSuccess).
6. The errorResponse(req: Request) function returns a new function that can be used as a callback by fold. This "new function", takes the EnonicError object as a parameter, and creates a Json Response with the correct status number, based on the errorKey of the EnonicError.
7. We pass the ok function to fold as the second parameter. The ok creates a Response where the status is 200, and the parameter is the body. In this case the ReadonlyArray<Content<Article>> is assigned to thebody.
8. We have so far constructed a constant program of type IO<Response>, but we have not yet performed a single side effect. It's time to perform those side effects, so we run the IO by calling it, and a Response is returned which out controller function can return.

API

• Content
  • getContentByIds
  • createAll
  • createAndPublish
  • deleteAndPublish
  • modifyAndPublish
  • applyChangesToData
  • createMediaFromAttachment
• Context
  • runAsSuperUser
  • runInDraftContext
• Menu
  • getSubMenuByKey
• Validation
  • validate