github/meteor
1
1
Fork 0
mirror of https://github.com/meteor/meteor.git synced 2026-05-02 03:01:46 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2927 from benjamn/responsive-docs

Browse Source 
My edits to the second half of the basic docs
This commit is contained in:
Sashko Stubailo
2014-10-27 14:01:45 -07:00
parent 02d16f9ab7 95d81f682d
commit a7e58cd1cb
4 changed files with 94 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/client/basic/sections/environment.md
View File

@@ -14,17 +14,19 @@ authentication mechanisms, should be kept in the `server` directory.
{{> autoApiBox "Meteor.startup"}}
On a server, the function will run as soon as the server process is finished
starting. On a client, the function will run as soon as the page is ready.
On the server, the callback function will run as soon as the server
process is finished starting up. On the client, the callback function will
run as soon as the page is ready.
It's good practice to wrap all code that isn't inside template events, template
helpers, methods, publish, or subscribe in `Meteor.startup` so that your
application code isn't executed before the environment is ready.
It's good practice to wrap all code that isn't inside template events,
template helpers, `Meteor.methods`, `Meteor.publish`, or
`Meteor.subscribe` in `Meteor.startup` so that your application code isn't
executed before the environment is ready.
Example:
For example, to create some initial data if the database is empty when the
server starts up, you might use the following pattern:
```
// On server startup, if the database is empty, create some initial data.
if (Meteor.isServer) {
Meteor.startup(function () {
if (Rooms.find().count() === 0) {
@@ -34,4 +36,8 @@ if (Meteor.isServer) {
}
```
{{/template}}
If you call `Meteor.startup` on the server after the server process has
started up, or on the client after the page is ready, the callback will
fire immediately. <!-- XXX It should still fire asynchronously, though -->
{{/template}}

26
docs/client/basic/sections/methods.md
View File

@@ -72,10 +72,15 @@ This is how you call a method.
### On the client
On the client you should pass a callback and the method will run asynchronously:
it will return nothing and instead deliver its results to the callback function.
The callback will be called with two arguments: `error` and `result`.
Methods called on the client run asynchronously, so you need to pass a
callback in order to observe the result of the call. The callback will be
called with two arguments, `error` and `result`. The `error` argument will
be `null` unless an exception was thrown. When an exception is thrown, the
`error` argument is `instanceof Meteor.error` and the `result` argument is
undefined.
Here's an example of calling the `commentOnPost` method with arguments
`comment` and `postId`:
```
// Asynchronous call with a callback on the client
@@ -83,23 +88,24 @@ Meteor.call('commentOnPost', comment, postId, function (error, result) {
if (error) {
// handle error
} else {
// all good!
// examine result
}
});
```
Meteor tracks the database writes performed by methods and does not invoke the
callback until all of the server's writes have been sent to the client.
Meteor tracks the database updates performed as part of a method call, and
waits to invoke the client-side callback until all of those updates have
been sent to the client.
### On the server
On the server, you don't have to pass a callback - the method invocation will
block until the method is complete. It will return the return value of the
method or throw an exception, just like if you had called the function directly.
On the server, you don't have to pass a callback &mdash; the method call
will simply block until the method is complete, returning a result or
throwing an exception, just as if you called the function directly:
```
// Synchronous call on the server with no callback
var result = Meteor.call('foo', comment, postId);
var result = Meteor.call('commentOnPost', comment, postId);
```
{{/template}}

40
docs/client/basic/packages.md → docs/client/basic/sections/packages.md
View File

@@ -1,12 +1,13 @@
{{#template name="basicPackages"}}
# Packages
<h2 id="packages"><span>Packages</span></h2>
All of Meteor's functionality is implemented in modular packages. In addition
to the core packages documented above, there are many others that you can add to
your app to enable useful functionality.
Add or remove packages with `meteor add` and `meteor remove`:
From the command line, you can add and remove packages with `meteor add`
and `meteor remove`:
```bash
# add the less package
@@ -16,23 +17,26 @@ meteor add less
meteor remove less
```
Your app will restart itself automatically when you add or remove a package.
Every app's package dependencies are tracked in `.meteor/packages`, so all of
your collaborators will also get the package when they pull your source code.
Your app will restart itself automatically when you add or remove a
package. An app's package dependencies are tracked in `.meteor/packages`,
so your collaborators will be automatically updated to the same set of
installed packages as you after they pull your source code, because they
have the same `.meteor/packages` file as you.
See which packages are used by your app with `meteor list`.
You can see which packages are used by your app by running `meteor list`
in the app's directory.
## Searching for packages
Currently the best way to search for packages available on the official Meteor
package server is [Atmosphere](https://atmospherejs.com/), the community package
search website maintained by Percolate Studio. You can also search for packages
directly using the `meteor search` command.
Currently the best way to search for packages available from the official
Meteor package server is [Atmosphere](https://atmospherejs.com/), the
community package search website maintained by Percolate Studio. You can
also search for packages directly using the `meteor search` command.
Packages that have a `:` in the name, such as `mquandalle:jade`, are written and
maintained by community members. The prefix before the colon is the name of the
user or organization who created that package. Unprefixed packages are
maintained by Meteor Development Group alongside the Meteor framework.
maintained by Meteor Development Group as part of the Meteor framework.
There are currently over 2000 packages available on Atmosphere. Below is a small
selection of some of the most useful packages.
@@ -79,14 +83,16 @@ the same API. See the [http docs](#/full/http) to see how to use it.
## less
Use the [LESS](http://lesscss.org/) CSS pre-processor in your app. With this
package, `.less` files are automatically compiled into CSS. If you want to use
`@import` to include other files and not have Meteor automatically compile them,
use the `.import.less` extension.
Add the [LESS](http://lesscss.org/) CSS preprocessor to your app to
compile any files with a `.less` extension into standard CSS. If you want
to use `@import` to include other files and not have Meteor automatically
compile them, use the `.import.less` extension.
## markdown
Include [Markdown](http://daringfireball.net/projects/markdown/syntax) code in your templates. It's as easy as using the `{{dstache}}# markdown}}` helper:
Include [Markdown](http://daringfireball.net/projects/markdown/syntax)
code in your templates. It's as easy as using the `{{dstache}}#
markdown}}` helper:
```html
<div class="my-div">
@@ -112,4 +118,4 @@ This package gives your app server-side rendering to allow search engine
crawlers and other bots see your app's contents. If you care about SEO, you
should add this package.
{{/template}}
{{/template}}

75
docs/client/basic/sections/pubsub.md
View File

@@ -2,47 +2,45 @@
<h2 id="pubsub"><span>Publish and subscribe</span></h2>
Meteor servers can publish sets of documents with `Meteor.publish` and clients
can subscribe to those publications with `Meteor.subscribe`. Any data the
client subscribes to will be available through `find` on client collections.
Meteor servers can publish sets of documents with `Meteor.publish`, and
clients can subscribe to those publications with `Meteor.subscribe`. Any
documents the client subscribes to will be available through the `find`
method of client collections.
Every newly created Meteor app contains the `autopublish` function, which
automatically publishes all of the data available on the server. To get more
fine-grained control over what the client gets, remove `autopublish`:
By default, every newly created Meteor app contains the `autopublish`
package, which automatically publishes all available documents to every
client. To exercise finer-grained control over what documents different
clients receive, first remove `autopublish`:
```
$ meteor remove autopublish
```
Then, you can use `Meteor.publish` and `Meteor.subscribe` to control what
data flows from the server to the client.
Now you can use `Meteor.publish` and `Meteor.subscribe` to control what
documents flow from the server to its clients.
{{> autoApiBox "Meteor.publish"}}
To publish data to clients, call `Meteor.publish` on the server with
two parameters: the name of the record set, and a *publish function*
that Meteor will call each time a client subscribes to this name.
To publish data to clients, call `Meteor.publish` on the server with two
arguments: the name of the record set, and a *publish function* that will
be called each time a client subscribes to this record set.
Publish functions can return the result of `collection.find`, in which case
Meteor will publish that query's documents to each subscribed client. You can
also return an array of queries, in which case Meteor will publish all of the
relevant documents.
Inside a publish function, `this.userId` is the current user's _id. When the
logged in user changes, the publish function will automatically rerun with
the new userId. This feature can be used for security and access control -
use `this.userId` to make sure that users never get documents they shouldn't
be seeing, like another user's private messages.
Publish functions typically return the result of calling
`collection.find(query)` on some `collection` with a `query` that narrows
down the set of documents to publish from that collection:
```
// On the server
// Publish the logged in user's posts
Meteor.publish("posts", function () {
return Posts.find({ createdBy: this.userId });
});
```
// Publish a post and its comments
You can publish documents from multiple collections by returning an array
of `collection.find` results:
```
// Publish a single post and its comments
Meteor.publish("postAndComments", function (postId) {
// Check argument
check(postId, String);
@@ -54,17 +52,26 @@ Meteor.publish("postAndComments", function (postId) {
});
```
Inside the publish function, `this.userId` is the current logged-in user's
`_id`, which can be useful for filtering collections so that certain
documents are visible only to certain users. If the logged-in user changes
for a particular client, the publish function will be automatically rerun
with the new `userId`, so the new user will not have access to any
documents that were meant only for the previous user.
{{> autoApiBox "Meteor.subscribe"}}
The client asks the server for data by using Meteor.subscribe. You can
access any data you have subscribed to by using [`collection.find`](#find) on
the client. Whenever data contained in a subsription is changed on the server,
the changes are automatically pushed to the client.
Clients call `Meteor.subscribe` to express interest in document
collections published by the server. Clients can further filter these
collections of documents by calling [`collection.find(query)`](#find).
Whenever any data that was accessed by a publish function changes on the
server, the publish function is automatically rerun and the updated
document collections are pushed to the subscribed client.
The `onReady` callback is called with no arguments when the server has sent all
of the initial data for the subsription. The `onError` callback is called with a
[`Meteor.Error`](#meteor_error) if the subscription fails or is terminated by
the server.
the server. <!-- XXX It would be better to have one Node-style callback -->
`Meteor.subscribe` returns a subscription handle, which is an object with the
following methods:
@@ -76,13 +83,13 @@ client to remove the subscription's data from the client's cache.
{{/dtdd}}
{{#dtdd "ready()"}}
True if the server has [marked the subscription as ready](#publish_ready). A
reactive data source.
Returns true if the server has [marked the subscription as
ready](#publish_ready). A reactive data source.
{{/dtdd}}
</dl>
If you call `Meteor.subscribe` inside [`Tracker.autorun`](#tracker_autorun), the
subscription will automatically be cancelled when the computation reruns,
subscription will automatically be cancelled when the computation is stopped,
meaning you don't have to to call `stop` on subscriptions made from inside
`autorun`.
{{/template}}
`Tracker.autorun`.
{{/template}}