Skip to content

ItemConsulting/enonic-wizardry

Repository files navigation

Enonic Wizardry

npm version

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