Session

Documentation of Meteor's client-side session API.

Session provides a global object on the client that you can use tostore an arbitrary set of key-value pairs. Use it to store things likethe currently selected item in a list.

What’s special about Session is that it’s reactive. Ifyou call Session.get('currentList')from inside a template, the template will automatically be rerenderedwhenever Session.set('currentList', x) is called.

To add Session to your application, run this command in your terminal:

  1. meteor add session

Client

Session.set(key, value)

import { Session } from 'meteor/session' (session/session.js, line 8)

Set a variable in the session. Notify any listeners that the valuehas changed (eg: redraw templates, and rerun anyTracker.autorun computations, that calledSession.get on this key.)

Arguments

  • keyString

  • The key to set, eg, selectedItem

  • valueEJSON-able Object or undefined

  • The new value for key

Example:

  1. Tracker.autorun(() => {
  2.   Meteor.subscribe('chatHistory', { room: Session.get('currentRoomId') });
  3. });
  5. // Causes the function passed to `Tracker.autorun` to be rerun, so that the
  6. // 'chatHistory' subscription is moved to the room 'home'.
  7. Session.set('currentRoomId', 'home');

Session.set can also be called with an object of keys and values, which isequivalent to calling Session.set individually on each key/value pair.

  1. Session.set({
  2.   a: 'foo',
  3.   b: 'bar'
  4. });

Client

Session.setDefault(key, value)

import { Session } from 'meteor/session' (session/session.js, line 20)

Set a variable in the session if it hasn't been set before.Otherwise works exactly the same as Session.set.

Arguments

  • keyString

  • The key to set, eg, selectedItem

  • valueEJSON-able Object or undefined

  • The new value for key

This is useful in initialization code, to avoid re-initializing a sessionvariable every time a new version of your app is loaded.

Client

Session.get(key)

import { Session } from 'meteor/session' (session/session.js, line 30)

Get the value of a session variable. If inside a reactivecomputation, invalidate the computation the next time thevalue of the variable is changed by Session.set. Thisreturns a clone of the session value, so if it's an object or an array,mutating the returned value has no effect on the value stored in thesession.

Arguments

  • keyString
  • The name of the session variable to return

Example:

  1. <!-- main.html -->
  2. <template name="main">
  3.   <p>We've always been at war with {{theEnemy}}.</p>
  4. </template>
  1. // main.js
  2. Template.main.helpers({
  3.   theEnemy() {
  4.     return Session.get('enemy');
  5.   }
  6. });
  8. Session.set('enemy', 'Eastasia');
  9. // Page will say "We've always been at war with Eastasia"
  11. Session.set('enemy', 'Eurasia');
  12. // Page will change to say "We've always been at war with Eurasia"

Client

Session.equals(key, value)

import { Session } from 'meteor/session' (session/session.js, line 43)

Test if a session variable is equal to a value. If inside areactive computation, invalidate the computation the nexttime the variable changes to or from the value.

Arguments

  • keyString

  • The name of the session variable to test

  • valueString, Number, Boolean, null, or undefined

  • The value totest against

If value is a scalar, then these two expressions do the same thing:

  1. Session.get('key') === value
  2. Session.equals('key', value)

…but the second one is always better. It triggers fewer invalidations(template redraws), making your program more efficient.

Example:

  1. <template name="postsView">
  2.   {{! Show a dynamically updating list of items. Let the user click on an item
  3.       to select it. The selected item is given a CSS class, so it can be
  4.       rendered differently. }}
  6.   {{#each posts}}
  7.     {{> postItem}}
  8.   {{/each}}
  9. </template>
  11. <template name="postItem">
  12.   <div class="{{postClass}}">{{title}}</div>
  13. </template>
  1. Template.postsView.helpers({
  2.   posts() {
  3.     return Posts.find();
  4.   }
  5. });
  7. Template.postItem.helpers({
  8.   postClass() {
  9.     return Session.equals('selectedPost', this._id)
  10.       ? 'selected'
  11.       : '';
  12.   }
  13. });
  15. Template.postItem.events({
  16.   'click'() {
  17.     Session.set('selectedPost', this._id);
  18.   }
  19. });

Using Session.equals here means that when the user clickson an item and changes the selection, only the newly selectedand the newly unselected items are re-rendered.

If Session.get had been used instead of Session.equals, thenwhen the selection changed, all the items would be re-rendered.

For object and array session values, you cannot use Session.equals; instead,you need to use the underscore package and write_.isEqual(Session.get(key), value).