itemconsulting / enonic-wizardry Goto Github PK

Functional utility library for Enonic XP

License: MIT License

TypeScript 100.00%

typescript enonic enonic-xp functional-programming

enonic-wizardry's Introduction

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
}

We import an interface Article { ... } generated by xp-codegen-plugin.
We use the imported Request and Response to control the shape of our controller.
We use the pipe function from fp-ts to pipe the result of one function into the next one.
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>>>
The last thing we usually do in pipe is to unpack the IOEither. This is done with fold(handleError, handleSuccess).
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.
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.
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

enonic-wizardry's People

Stargazers

Watchers

enonic-wizardry's Issues

Make json-parsing util return `IOEither`

Add xml-parsing for idprovider

Make building the cli part of `enonic project deploy`

Make the compilation of the typescript code in cli part of the enonic project deploy process.

Create a gradle task, that triggers rendering of all typescript interfaces.

Also document steps for building and running in README.md.

Make a script that will apply the ts-generation to all content-types, sites pages, and parts

Make a script, that when run will navigate the file structure of an Enonic-project, and generate interfaces for all entries in the following directories:

./src/main/resources/site/site.xml
./src/main/resources/site/content-types/*
./src/main/resources/site/parts/*
./src/main/resources/site/pages/*

When ` type="ContentSelector"` and maximum = 1, render type as `string`

If we have the case where input is of type ContentSelector, and occurences/@maximum = 1, then Enonic will not return an Array<string>, but only string.

So given this xml:

<input name="fabTarget" type="ContentSelector">
  <label>FAB button target</label>
  <occurrences minimum="0" maximum="1"/>
</input>

We should get:

export interface DefaultPageConfig {
  /**
   * FAB button target
   */
  fabTarget?: string;
}

(and not fabTarget?: Array<string>;)

Modify the xml-parsing code for content-types to handle sites, pages, and parts too

Modify the xml parsing code to handle:

sites
pages
parts

It's possible that it's only the outer most tag that changes between these xml-file-types.

Upgrade to support [email protected]

Make interface code generation support mixins

Fix cli/src missing in npm because of .npmignore

Build crashes on missing mixins-directory

Add function to unwrap `Content.data`, but keep the `_id`

Create a new function named getContentDataWithId, that takes Content<T> and returns T & { _id: string }

Use IO-monad for context.run()

On `type="ContentSelector"`, generated typescript type should be `Array<string>`.

https://github.com/ItemConsulting/ofo-employee-registry/blob/bde69b8f3e303366bc565a95dddc78bc4093e1bf/src/main/resources/site/content-types/group/group.xml#L15-L21

When <input type="ContentSelector"> the generated ts-code, should have the type Array<string>

Example:

<content-type>
  <display-name>Group</display-name>
  <super-type>base:structured</super-type>
  <form>
    <input name="members" type="ContentSelector">
      <label>Members</label>
      <occurrences minimum="0" maximum="0"/>
      <config>
        <allowContentType>employee</allowContentType>
      </config>
    </input>
  </form>
</content-type>

should generate:

export interface Group {
  members: Array<string>;
}

Generate Typescript interfaces from xml-files

Create a script that can be run from npm, that parses an excel file, and produces a typescript interface file, that will correspond to the json structure created by the content type.

The name of the interface should be determined by the name of the content type (file name), and should be PascalCase. The file name should be the same as the content type file name, but ending with .ts as its type.
Use occurences/@minimum = 0 to determin if the type is nullable or not (see lastName).
The <item-set> element will create nested structures, and needs to be handled recursivly, since the nesting level is not contrained.

<content-type>
  <display-name>Employee</display-name>
  <super-type>base:structured</super-type>
  <form>
    <input type="TextLine" name="firstName">
      <label>First name</label>
      <occurrences minimum="1" maximum="1"/>
    </input>
    <input type="TextLine" name="lastName">
      <label>Last name</label>
      <occurrences minimum="0" maximum="1"/>
    </input>
    <item-set name="contactInfo">
      <label>Contact Info</label>
      <occurrences minimum="0" maximum="0"/>
      <items>
        <input name="label" type="TextLine">
          <label>Label</label>
          <occurrences minimum="0" maximum="1"/>
        </input>
        <input name="phoneNumber" type="TextLine">
          <label>Phone Number</label>
          <occurrences minimum="0" maximum="1"/>
        </input>
      </items>
    </item-set>
  </form>
</content-type>

export interface Employee {
  firstName: string
  lastName?: string
  contactInfo: Array<{
    label: string
    phoneNumber: string
  }>
}

Input of type="Checkbox" should generate typescript field of type boolean

<input name="gdprSigned" type="CheckBox">
 <label>GDPR Signed</label>
</input>

Shoud generate

export interafce MyInterface {
  gdprSigned?: boolean;
}

"lint-staged": {
    "*.ts": [
      "eslint --fix 'src/**/*.ts'",
      "git add"
    ]
  }

createAndPublish
deleteAndPublish
modifyAndPublish