mirror of
https://github.com/meteor/meteor.git
synced 2026-05-02 03:01:46 -04:00
146 lines
3.2 KiB
Markdown
146 lines
3.2 KiB
Markdown
# Session
|
|
|
|
Documentation of Meteor's client-side session API.
|
|
|
|
|
|
`Session` provides a global object on the client that you can use to
|
|
store an arbitrary set of key-value pairs. Use it to store things like
|
|
the currently selected item in a list.
|
|
|
|
What's special about `Session` is that it's reactive. If
|
|
you call [`Session.get`](#Session-get)`('currentList')`
|
|
from inside a template, the template will automatically be rerendered
|
|
whenever [`Session.set`](#Session-set)`('currentList', x)` is called.
|
|
|
|
To add `Session` to your application, run this command in your terminal:
|
|
|
|
```bash
|
|
meteor add session
|
|
```
|
|
|
|
<ApiBox name="Session.set" hasCustomExample/>
|
|
|
|
|
|
```js
|
|
import { Session } from 'meteor/session';
|
|
import { Tracker } from 'meteor/tracker';
|
|
import { Meteor } from 'meteor/meteor';
|
|
|
|
Tracker.autorun(() => {
|
|
Meteor.subscribe('chatHistory', { room: Session.get('currentRoomId') });
|
|
});
|
|
|
|
// Causes the function passed to `Tracker.autorun` to be rerun, so that the
|
|
// 'chatHistory' subscription is moved to the room 'home'.
|
|
Session.set('currentRoomId', 'home');
|
|
```
|
|
|
|
|
|
`Session.set` can also be called with an object of keys and values, which is
|
|
equivalent to calling `Session.set` individually on each key/value pair.
|
|
|
|
```js
|
|
Session.set({
|
|
a: 'foo',
|
|
b: 'bar'
|
|
});
|
|
```
|
|
|
|
|
|
<ApiBox name="Session.setDefault"/>
|
|
|
|
This is useful in initialization code, to avoid re-initializing a session
|
|
variable every time a new version of your app is loaded.
|
|
|
|
|
|
<ApiBox name="Session.get" hasCustomExample/>
|
|
|
|
This example in Blaze.js
|
|
::: code-group
|
|
|
|
```html [main.html]
|
|
<template name="main">
|
|
<p>We've always been at war with {{theEnemy}}.</p>
|
|
</template>
|
|
```
|
|
|
|
```js [main.js]
|
|
Template.main.helpers({
|
|
theEnemy() {
|
|
return Session.get('enemy');
|
|
}
|
|
});
|
|
|
|
Session.set('enemy', 'Eastasia');
|
|
// Page will say "We've always been at war with Eastasia"
|
|
|
|
Session.set('enemy', 'Eurasia');
|
|
// Page will change to say "We've always been at war with Eurasia"
|
|
```
|
|
:::
|
|
|
|
|
|
<ApiBox name="Session.equals"/>
|
|
|
|
|
|
If value is a scalar, then these two expressions do the same thing:
|
|
|
|
```js
|
|
Session.get('key') === value
|
|
Session.equals('key', value)
|
|
```
|
|
|
|
...but the second one is always better. It triggers fewer invalidations
|
|
(template redraws), making your program more efficient.
|
|
|
|
This example in Blaze.js:
|
|
|
|
::: code-group
|
|
|
|
```html [main.html]
|
|
|
|
<template name="postsView">
|
|
{{#each posts}}
|
|
{{> postItem}}
|
|
{{/each}}
|
|
</template>
|
|
|
|
<template name="postItem">
|
|
<div class="{{postClass}}">{{title}}</div>
|
|
</template>
|
|
```
|
|
|
|
```js [main.js]
|
|
|
|
Template.postsView.helpers({
|
|
posts() {
|
|
return Posts.find();
|
|
}
|
|
});
|
|
|
|
Template.postItem.helpers({
|
|
postClass() {
|
|
return Session.equals('selectedPost', this._id)
|
|
? 'selected'
|
|
: '';
|
|
}
|
|
});
|
|
|
|
Template.postItem.events({
|
|
'click'() {
|
|
Session.set('selectedPost', this._id);
|
|
}
|
|
});
|
|
```
|
|
|
|
Using Session.equals here means that when the user clicks
|
|
on an item and changes the selection, only the newly selected
|
|
and the newly unselected items are re-rendered.
|
|
|
|
If Session.get had been used instead of Session.equals, then
|
|
when 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)`.
|