pwix:collection-behaviors

Preliminary notes

This package is a fork from zimme:collection-behaviors v 1.1.3:

as a prerequisite for zimme:collection-timestampable (itself forked as pwix:collection-timestampable)
unfortunately, it seems no more maintained
I did need to make it compatible with Meteor 2. and incoming Meteor 3.x
so one fix later this package is born.

What is it ?

This Meteor package defines and attaches behaviours to collections.

Installation

This Meteor package is installable with the usual command:

    meteor add pwix:collection-behaviours

Usage

Define a behaviour

1    import { CollectionBehaviours } from 'meteor/pwix:collection-behaviours';
2
3    CollectionBehaviours.define( 'behaviourName', function( options ){
4        var collection = this.collection;
5
6        // Setup some default options for the behaviour
7        var defaultOptions = {
8            exampleOption: "I'm a default value"
9        };
10
11        // Make the behaviour configurable both globally and locally and uses the
12        // defaults if not configured.
13        options = _.defaults( options, this.options, defaultOptions );
14
15        // Behaviour logic goes here
16    });

Attach behaviours

1    // Attach a behavour using the collection identifier
2    Meteor.users.attachBehaviour( 'timestampable' );
3
4    // Attach a behaviour to a colleciton using CollectionBehaviours
5    CollectionBehaviours.attach( Meteor.users, 'timestampable' );
6
7    // Attach multiple behaviours to a collection with default options
8    CollectionBehaviours.attach( Meteor.users, ['timestampable', 'softremovable'] );
9
10    // Attach multiple behaviours to a collcetion with custom options
11    CollectionBehaviours.attach( Meteor.users, {
12        timestampable: {
13            createdAt: 'insertedAt',
14        },
15        softremovable: {
16            removedBy: 'deletedBy',
17        },
18    });
19
20    // Attach a behaviour to multiple collections
21    CollectionBehaviours.attach( [Meteor.users, Posts], 'timestampable' );
22
23    // Attach multiple behaviours to multiple collections
24    CollectionBehaviours.attach(
25        [Meteor.users, Posts],
26        ['timestampable', 'softremovable']
27    );

Provides

`CollectionBehaviours`

The exported CollectionBehaviours global object provides following items:

Functions

`CollectionBehaviours.attach()`

Used to attach behaviour(s) to collection(s).

1    CollectionBehaviours.attach( ColletionIdentifier, behaviourNameOrFunction, options );

CollectionIdentifier: Required. The collection or Array of collections you want to attach the behaviour(s) to.
behaviourNameOrFunction: Required.
- If set to a String, 'behaviourName', will attach the named behaviour.
- If set to a Function, will attach that function as an anonymous behaviour.
- If set to an Array of String/Function, will attach those named or anonymous behaviours.
- If set to an Object, where the keys are named behaviours and the values are the behaviours' options, will attach those named behaviours with the provided options.
options: Optional. See specific behaviour for available options.

`CollectionBehaviours.attachBehaviour()`

Used to attach behaviour(s) to the collection.

1    Meteor.users.attachBehaviour( behaviourNameOrFunction, options );

behaviourNameOrFunction: Required.
- If set to a String, 'behaviourName', will attach the named behaviour.
- If set to a Function, will attach that function as an anonymous behaviour.
- If set to an Array of String/Function, will attach those named or anonymous behaviours.
- If set to an Object, where the keys are named behaviours and the values are the behaviours' options, will attach those named behaviours with the provided options.
options: Optional. See specific behaviour for available options.

`CollectionBehaviours.configure()`

Used to configure behaviours globally.

1    // Configure single behaviour
2    CollectionBehaviours.configure( 'behavioursName', options );
3
4    // Configure multiple behaviours
5    CollectionBehaviours.configure({
6        timestampable: {
7            createdAt: 'insertedAt',
8            updatedBy: 'modifiedBy'
9        },
10        softremovable: {
11            removed: 'deleted'
12        }
13    });

with:

behaviourName: required.
- If set to a String, 'behaviourName', will configure the named behaviour.
- If set to an Object, where the keys are named behaviours and the values are the options for the behaviours, will configure those named behaviours.
options: Optional if behaviourName is an Object.

See specific behaviour for available options.

Note: CollectionBehaviours.config() is an alias for CollectionBehaviours.configure().

`CollectionBehaviours.define( behaviourName, behaviourFunction, options )`

Used to defined a new behaviour or overwrite an already defined behaviour.

1    CollectionBehaviours.define( 'behaviourName', behaviourFunciton, options );

with:

behaviourName: required, the name of the behaviour.
behaviourFunction: required, a Function that takes options as an argument. This function is the behaviour.
options: an optional Object with the options for the behaviour. Thi object may have following keys:
- replace: Optional. Set to true to replace a previously defined behaviour.

Configuration

The package's behavior can be configured through a call to the CollectionBehaviours.configure() method:

1    // Configure behaviour globally i.e. set you own defaults
2    CollectionBehaviours.configure( 'behaviourName', {
3        exampleOption: "I'm a global value"
4    });
5
6    // Attach behaviour with custom options
7    Meteor.users.attachBehaviour( 'behaviourName', {
8        exampleOption: "I'm a local value"
9    });
10
11    // Attach behaviour with custom options, using CollectionBehaviours
12    CollectionBehaviours.attach( Meteor.users, 'behaviourName', {
13        exampleOption: "I'm a local value"
14    });

NPM peer dependencies

None at the moment.

Translations

None at the moment.

Cookies and comparable technologies

None at the moment.

Issues & help

In case of support or error, please report your issue request to our Issues tracker.

Original documentation

The documentation was originally from zimme. See also the Github original repository.

It has been since rewritten for completion and homogenization.

Available behaviours

The behaviours are split into separate packages, which depend on this package.

zimme:collection-softremovable

This behaviour adds .softRemove() and .restore() to collections, which make it possible to mark documents as removed. It also tracks the time and user for the last soft remove and restore.

https://atmospherejs.com/zimme/collection-softremovable
zimme:collection-timestampable

This behaviour timestamps documents on insert and update. It also tracks the user who made the last insert or update.

https://atmospherejs.com/zimme/collection-timestampable

Notes

The inspiration for this package came from sewdn:collection-behaviours.

P. Wieser

Last updated on 2024, Jun. 30th