Use Notification (for module developers)

MMM-CalendarExt can converse with other modules.

Available Request Notifications

notification	payload structure	description
CHANGED_PROFILE	{to:String}	Request for change profile configuration and/or redraw view by profile class name.
CALEXT_TELL_SCHEDULE	{filter:{}, sessionId:'sessionId'}	Request for telling schedules by filter.
CALEXT_MODIFY_CONFIG	{config:{}, sessionId:'sessionId'	Request for modifying current configs. This modifying will be ignored when new configuration is set. And this request cannot add or remove or reset Calendars.
CALEXT_ADD_EVENT	{event:{}, sessionId:'sessionId'}	Request for adding instant event.
CALEXT_REMOVE_EVENT	{uid:'event uid', sessionId:'sessionId'}	Request for removing instant event which you've already added. You should know exact event uid to remove.

How to use

'sessionId'

MM's notification system is not for conversation between 2 modules. Thus when you receive several messages from modules, You cannot distinguish which response notification is for your previous request. So, if you send a notification with this unique sessionId value, MMM-CalendarExt will respond with this sessionId and name of the sender(your module). You can find your right answer with these two values.

CHANGED_PROFILE

MMM-ProfileSwitcher module could emit this notification. But any other module who can broadcast this notification can use. MMM-CalendarExt will change the profile, then redraw views. You can use in your module like this.

this.sendNotification('CHANGED_PROFILE', {to:'daddy'})

See How to use with profiles

Response for CHANGED_PROFILE

After receiving notification, this notification will be broadcasted from MMM-CalendarExt.

notification	payload structure	value description
CALEXT_SAYS_PROFILE_CHANGED
	payload	profile name(class)

CALEXT_TELL_SCHEDULE

MMM-CalendarExt can tell you about events. You can specify events by the filter. What can you do with this feature? Maybe your Chatbot or Voice assistant module could tell schedules to you. (please, make one for me.). Or reminder or alarm module could.

These default values are predefined, so you can omit some fields.

filter: {
  profiles: [], //for all profiles
  names: [], //for all calendar names
  titlePattern: "", //for title Pattern. You can use String or RegExp for searching title
  from: moment().format('x') // start time : now; Unix ms timestamp format
  to: moment().add(2, 'days').format('x') // end time : until 2 days later from now; Unix ms timestamp format
  count: 10 //how many events should be returned.
}

By example;

var filter = {
  profiles: ['daddy', 'John'],
  names: ['excersise plan'],
  titlePattern: "running",
  to: 1514764799000, // 2017-12-31 23:59:59 Unix ms timestamp
  count: 100
}
var notification = {
  filter: filter,
  sessionId: '11223344'
}
this.sendNotification('CALEXT_TELL_SCHEDULE', notification)

This filter means something like 'tell me 100 exercise plan events about running of daddy and John from now until this year ends'.

If events are found, you can get a notification like this;

Response for CALEXT_TELL_SCHEDULE

notification	payload structure	value description
CALEXT_SAYS_SCHEDULE
	payload.message	SCHEDULE_FOUND or SCHEDULE_NOTFOUND
	payload.sender	Your module name.
	payload.sessionId	sessionId of your previous request for this response.
	payload.events	If success, this value will be Array of event objects. Each event Object may have parameters - title, description, location, geo, startDate, endDate If not found, this value will be empty([]).
	payload.filter	Your original filter. I think you would need this for refreshing your memory for previous request.

CALEXT_MODIFY_CONFIG

WARNING:Experimental Feature, Not fully tested.

You can modify the current configuration by this notification. This could be similar to something like runtime configuration without reboot or shutdown. You can overwrite others with described values, even profileConfig and calendars(use carefully). Modified configurations are not saved permanently. It means after reboot, the original configuration will be loaded.

You can use like this.

var config = {
  system: {
    show: ['month']
  },
  views: {
    month: {
      position:'fullscreen_below'
    }
  }
}
var notification = {
  config: config,
  sessionId: '55667788'
}
this.sendNotification('CALEXT_MODIFY_CONFIG', notification)

This request means something like 'change current view to month and display it in fullscreen_below, any other values will remain the same in current configuration'.

you can get a response notification like this;

Response for CALEXT_MODIFY_CONFIG

notification	payload structure	value description
CALEXT_SAYS_CONFIG_MODIFIED
	payload.sender	Your module name.
	payload.sessionId	sessionId of your previous request for this response.

This notification could be receipt before screen redrawn. That is not synchronous.

CALEXT_ADD_EVENT

You can add or update the Instant event of your own. instant means, you cannot keep this event permanently. It will be removed automatically after endDate usually. All instant events are initialized(be removed) after reboot. If you want to operate permanent events, you'd better do in you Office365 or Google Calendar.

So, what can you do with instant events? Your weather module could put weather forecasts of this week here. Your commute information module could put the bus schedules of today for your kids.

All instant events should have unique uid per event by sender module. If the event has same uid with already existed, CALEXT_ADD_EVENT would not create a new event, but would update the event which has that uid.

And you cannot update or remove instant events of other modules or normal events of current static calendars. You can operate just your own event from your module.

At last, your module can put maximum 100 instant events. (I think it's enough. You can update or remove.)

Instant events are predefined like this. so you can omit some fields.

{
  name: sender.name, 
  profiles: [],
  views: [],
  styleName: "",
  symbol: curCfg.calendarDefault.symbol,
  title: null,
  description: null,
  location: null,
  geo: null,
  startDate: moment().valueOf(),
  endDate: moment().valueOf(),
  fullDayEvent: 0,
}

So you can use like this.

var event = {
  uid: '1',
  profiles:['daddy'],
  name: "Notice",
  title: "Uber reservation",
  startDate: 123456789000, // unix ms timestamp format
  endDate: 123456789000 // unix ms timestamp format
}
var notification = {
  event: event,
  sessionId: '9900AABBCC'
}
this.sendNotification('CALEXT_ADD_EVENT', notification)

This instant event - 'Uber reservation' will be added and be shown to daddy's calendar views. If uid is omitted, the uid value will be replaced by sessionId value. However I recommend to write uid manually.

It could cause these response notifications.

Response for CALEXT_ADD_EVENT

notification	payload structure	value description
CALEXT_SAYS_ADD_EVENT_RESULT
	payload.sender	Your module name.
	payload.sessionId	sessionId of your previous request for this response.
	payload.uid	uid of your event for this request
	payload.message	TOO_MANY_EVENTS: not added because already you have 100 instant events. Views will not be redrawn. EVENT_ADDED: success. Your event is added. Views will be redrawn. EVENT_UPDATED: An event of uid already exists, so is updated. Views will be redrawn. EVENT_NOT_UPDATED: An event of uid already exists but there is no difference, so is not updated. Views will not be redrawn.

CALEXT_REMOVE_EVENT

You can also remove your instant event with this notification. You should know exact uid of your own instant event. You cannot remove other's instant event, even you know the uid.

You can use in your module like this.

this.sendNotification('CALEXT_REMOVE_EVENT', {uid:'abcd1234', sessionId:'DDEEFFGGHH'})

If the event has abcd1234 as uid and your module had created this event, this event will be removed.

Response for CALEXT_REMOVE_EVENT

notification	payload structure	value description
CALEXT_SAYS_REMOVE_EVENT_RESULT
	payload.sender	Your module name.
	payload.sessionId	sessionId of your previous request for this response.
	payload.uid	uid of your event for this request
	payload.message	EVENT_REMOVED: The event is removed successfully. Views will be redrawn. EVENT_NOT_REMOVED_UID_FAIL:There is no event with uid.