enonic/lib-util

lib-util

A toolkit for JavaScript developers working with Enonic XP. Handy functions for your daily tasks.

Please contribute!

Documentation

The documentation can be found in docs

Usage

1. Install the library in build.gradle file.
2. Build your app source using Gradle.
3. Require it in any controller you need it in.
4. Use any function from this lib's /lib/util/ folder (see examples).

Gradle build script (1)

repositories {
    maven {
        url 'http://repo.enonic.com/public'
    }
}

dependencies {

    // Depending on version (3.0.0+), lib-context and lib-admin may also be needed.
    // If problems, and they are not already in your build, add these:
    // include "com.enonic.xp:lib-context:${xpVersion}"
    // include "com.enonic.xp:lib-admin:${xpVersion}"

    // Lib-util:
    include 'com.enonic.lib:lib-util:3.0.0'
}

Controllers (3 & 4)

// (3) Require the library in any controller
var libs = {
    util: require('/lib/util')
}

// (4) Use any of the functions like so (not working examples, just showing the format):
libs.util.log(x);
libs.util.app.getJsonName(x);
libs.util.data.forceArray(x);
libs.util.data.trimArray(x);

Refer to each js-file in /lib/util/ on GitHub for documentation on each function.

Compatibility

Lib version	XP version
3.0.0	7.1.0
2.3.x	7.1.0
2.2.x	7.0.0
2.1.0	7.0.0
2.0.0	7.0.0
1.4.x	6.14.0
1.[1-3].x	6.3.1
1.0.0	6.0.0

Changelog

3.0.0

• Lib dependencies changed from compile to compileOnly to avoid conflict between libraries from different versions of XP

dependencies {
  compileOnly "com.enonic.xp:lib-admin:${xpVersion}"
  compileOnly "com.enonic.xp:lib-content:${xpVersion}"
  compileOnly "com.enonic.xp:lib-context:${xpVersion}"
  compileOnly "com.enonic.xp:lib-portal:${xpVersion}"
}

These 4 libraries were available in an application using lib-util via transitive dependency. From now on you will have to explicitly include them in the app if you are using lib-util:

dependencies {
  include 'com.enonic.lib:lib-util:3.0.0'
  include "com.enonic.xp:lib-admin:${xpVersion}"
  include "com.enonic.xp:lib-content:${xpVersion}"
  include "com.enonic.xp:lib-context:${xpVersion}"
  include "com.enonic.xp:lib-portal:${xpVersion}"
}

2.3.1

• Buildsystem upgrades:
  • Node 12.20.1
  • Upgrade node modules

2.3.0

• Documentation added
• content.exists uses the 7.1 exists method

2.2.1

• Compile lib-context since getSites requires it.

2.2.0

• Added getSites

2.1.0

• Added getAncestors
• Added getChildren

2.0.0

• Compatibility with XP7
• Restructuring (/lib/enonic/util/ -> /lib/util/)

1.4.0

• Added content.getParent
• Added content.getTree
• Added portal.getLocale
• Added value.isFunction
• Source rewritten in ES.next
• Added many tests with global.app, global.log and libXpContent and libXpPortal fakes
• Upgraded required version of Enonic XP to 6.14.0, since there is no lib-admin-6.3.1

1.3.0

• Added value.isObject, value.isString, object.hasProperty and object.dlv

1.2.2

• Fixed library build.

1.2.1

• Fixed library dependencies.

1.2.0

• Introducing the new "value.js" function library that adds handy functions like isSet, isNotSet, valueOr, valueOrEmptyString and ifSetPassToFunction.

1.1.3

• Add dependencies for lib-content and lib-portal as they are used.

lib-util's Issues

Implement methods to fetch child and ancestor content items

Add support for querying, filtering, sorting, mapping etc.

getTree({contentTypes: []}) should mean all contentTypes

Need to check contentTypes.length here:
https://github.com/enonic/lib-util/blob/master/src/main/resources/lib/util/content/getTree.es#L56

classpath problems

All applications that use lib-utli are prone to classpath issues.

Reasons:

• lib-util depends as "compile" on four standard libs and forces their inclusion into apps.
• xp standard libs must be all same versions in one app.
• newer versions of libs don't support older versions of XP. For instance lib-content:7.1.0 requires XP version from 7.1.0 and less than 8.0. It may not work correctly on XP 7.0.0
• app developers include other standard libs with different versions from what lib-utli requires.
• libs shimmed into apps

To fix that

• change lib dependencies from "compile" to "compileOnly"
• documentation should mention, that it is necessary to include standard libraries sepately:

dependencies {
   include 'com.enonic.lib:lib-util:2.4.0'
   include "com.enonic.xp:lib-admin:${xpVersion}"
   include "com.enonic.xp:lib-content:${xpVersion}"
   include "com.enonic.xp:lib-context:${xpVersion}"
   include "com.enonic.xp:lib-portal:${xpVersion}"
}

It is not necessary to include all of them. Just the ones needed.

Versioning and releases

There are no release tags or branches for older versions. People with older versions might want to see the code for their version.

Lib-util - App plugin removal

Remove the usage of the gradle plugin com.enonic.xp.app

getParent( pathOrKey ) - Get the parent content by path or key

Implement getSites method for fetching sites in context

Update Gradle Wrapper

Remove Gradle wrapper?

Libs for XP are never built independently, they are included in other libs. So ... we have no use of the gradle wrapper files right? Should be removed yeah?

image-functions?

Should we have in this lib some image functions, or a separate lib? Anyways:

A function that takes an ID of an image and an object with params. If no params it will return image as attachment, or with defaults, otherwise image will be scaled. Some simple things like this to make use easier.

Add isString and stringOrNull in value.js

These are used in apps like the SEO Metafield apps, among others. Could be nice to have in lib-util =)

function isString(o) {
	return typeof o === 'string' || o instanceof String;
}

function stringOrNull(o) {
	return isString(o) ? o : null;
}

region.get() - Object.values is not a function

The rewrite inside region.es that uses Object.values produces an error when any component (such as a new empty layout) is sent into the get() function.

The old code using for…in instead of Object.values seems to work, though. Here is the old code:

lib-util/src/main/resources/site/lib/enonic/util/region.js

Line 19 in c8a4773

for (var key in regions) {

Also, since 7.0 does not include a name property inside the region object, the region name should be added to each object inside the array that is returned, so that the name is not lost when calling this function.

Lib-util - Compile dependencies

A library A should not have an include dependency to a library B.
The library B (latest in case of conflict) will be included when building the application including library A.

Add function for removing html tags

using this code in the Metafields app now. Might be useful for others. Not sure if it should go into values, or content, or data, or a new security-file. Probably values.js.

	// Strip away all html tags, in case there's any in the description.
	var regex = /(<([^>]+)>)/ig;
	metaDescription = metaDescription.replace(regex, "");

Documentation

How about some documentation for each function in the README?

Add isSet function

To assist checking of vars that might be undefined. Still, shouldn't a "if (v)" be false on both undefined and null? Test and add function if it helps.

function isSet(v) {
return v !== null && typeof v !== 'undefined';
}

Simplify every day JS use

Things like this should be made easier and more robust with lib util. Basically handling undefined/null-issues.

var email = req.params.email;
bean.description = __.nullOrValue(params.description); - perhaps a __.nullOrValue-wrapper to the lib?

data.forceArray applied on undefined

In my opinion data.forceArray should return an empty array when passed undefined. i.e:

forceArray(undefined) -> []

not

forceArray(undefined) -> [undefined]