{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Custom Views","type":"basic","slug":"views","excerpt":"","body":"By default, Telescope can rank posts by popularity (`top` view), age (`new`), all-time score (`best`), and more.\n\nAll of these are **post views**. And Telescope also makes it easy to add your own views, sorted according to your own criteria. \n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Out of Date\",\n  \"body\": \"This section is currently out of date. Check back soon for an update!\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Understanding Views\"\n}\n[/block]\nA Telescope view is a function that takes in an optional `terms` argument, and returns a `parameter` object with `find` and `options` properties.\n\nThis `parameter` object is then passed on to **publications** (on the server) and **cursors** (on the client), and its properties are used to create a MongoDB query for the relevant posts.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding a View\"\n}\n[/block]\nYou can add a view using the `Posts.views.add` function, which takes two arguments: the name of the view, and the view function. \n\nFor example, here's how the `telescope:posts` package adds the `userPosts` view (used to display all of a user's posts):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Posts.views.add(\\\"userPosts\\\", function (terms) {\\n  return {\\n    find: {userId: terms.userId},\\n    options: {limit: 5, sort: {postedAt: -1}}\\n  };\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Views\"\n}\n[/block]\nBy itself, just adding a view won't do much. You also need to use it somewhere. This can be done through the **posts list controller**.\n\nFor example, here's how you could use the `userPosts` view mentioned above. In your template, include the `posts_list_controller` template with an `arguments` data context:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<template name=\\\"user_posts\\\">\\n  {{> posts_list_controller arguments}}\\n</template>\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThen define the `arguments` helper like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Template.user_posts.helpers({\\n  arguments: function () {\\n    var user = Meteor.user();\\n    return {\\n      terms: {\\n        view: 'userPosts',\\n        userId: user._id,\\n        limit: 5\\n      }\\n    }\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAlternatively, if you need to build your `arguments` object from URL parameters (as is the case for the `telescope:category` package), you can also generate it inside the router's `data` hook:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Posts.controllers.userPosts = Posts.controllers.list.extend({\\n  data: function () {\\n    var user = Meteor.users.findOne(this.params.userId);\\n    return {\\n      terms: {\\n        view: 'userPosts',\\n        userId: user._id,\\n        limit: 5\\n      }\\n    }\\n  }\\n});\\n\\nRouter.route('/userPosts/:userId', {\\n  controller: Posts.controllers.userPosts,\\n  name: 'userPosts'\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding A Menu Item\"\n}\n[/block]\nYou'll probably also want to add a link to your new view to the `viewsMenu` menu. For example, here's how the `telescope:daily` package adds its menu link:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Telescope.menuItems.add(\\\"viewsMenu\\\", {\\n  route: 'postsDaily',\\n  label: 'daily',\\n  description: 'day_by_day_view'\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Posts List Controllers & Components\"\n}\n[/block]\nPosts list are displayed using the **a template controller**. The controller takes a set of arguments, and then uses them to subscribe to the necessary subscriptions and set the data context for the **component**. \n\nThe posts list controller can take the following options:\n\n- `template`: which template/component to use. Defaults to `posts_list`.\n- `options`: a set of options which will be passed on to the component.\n- `terms`: query terms passed on to the post view function. \n\nThe `posts_list` component can take the following options:\n\n- `title`: the title of the posts list. \n- `postsCursor`: a cursor containing the posts list. \n- `postsCount`: a count of how many posts are loaded.\n- `postsReady`: a boolean variable indicating whether the subscription is ready. \n- `hasMorePosts`: whether there still are more posts to be loaded. \n- `loadMoreHandler`: the callback to execute when the user clicks \"load more\". \n\nTelescope also uses an alternate `posts_list_compact` component, which shows fewer information and uses a table layout.","updates":[],"order":24,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5635b294d209b50d0031dfe8","project":"550a7754635c660d0052808e","createdAt":"2015-05-12T00:30:34.416Z","githubsync":"","user":"5469e5dfa3b67a0e00559b06","category":{"sync":{"isSync":false,"url":""},"pages":["5635b294d209b50d0031dfdf","5635b294d209b50d0031dfe0","5635b294d209b50d0031dfe1","5635b294d209b50d0031dfe2","5635b294d209b50d0031dfe3","5635b294d209b50d0031dfe4","5635b294d209b50d0031dfe5","5635b294d209b50d0031dfe6","5635b294d209b50d0031dfe7","5635b294d209b50d0031dfe8","5635b294d209b50d0031dfe9","5635b294d209b50d0031dfea","5635b294d209b50d0031dfeb","5635b294d209b50d0031dfec"],"title":"Customizing Telescope","slug":"customizing-telescope","order":2,"from_sync":false,"reference":false,"_id":"5635b291d209b50d0031dfc7","createdAt":"2015-04-09T03:24:43.474Z","project":"550a7754635c660d0052808e","__v":1,"version":"5635b290d209b50d0031dfc4"},"version":{"version":"0.25","version_clean":"0.25.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5635b291d209b50d0031dfc5","5635b291d209b50d0031dfc6","5635b291d209b50d0031dfc7","5635b291d209b50d0031dfc8","5635b291d209b50d0031dfc9","5635b291d209b50d0031dfca"],"_id":"5635b290d209b50d0031dfc4","__v":1,"createdAt":"2015-11-01T06:34:56.868Z","project":"550a7754635c660d0052808e","releaseDate":"2015-11-01T06:34:56.868Z"},"__v":1}

Getting Started

Using Telescope

Customizing Telescope

Internals

Case Studies

Custom Views

By default, Telescope can rank posts by popularity (`top` view), age (`new`), all-time score (`best`), and more. All of these are **post views**. And Telescope also makes it easy to add your own views, sorted according to your own criteria. [block:callout] { "type": "danger", "title": "Out of Date", "body": "This section is currently out of date. Check back soon for an update!" } [/block] [block:api-header] { "type": "basic", "title": "Understanding Views" } [/block] A Telescope view is a function that takes in an optional `terms` argument, and returns a `parameter` object with `find` and `options` properties. This `parameter` object is then passed on to **publications** (on the server) and **cursors** (on the client), and its properties are used to create a MongoDB query for the relevant posts. [block:api-header] { "type": "basic", "title": "Adding a View" } [/block] You can add a view using the `Posts.views.add` function, which takes two arguments: the name of the view, and the view function. For example, here's how the `telescope:posts` package adds the `userPosts` view (used to display all of a user's posts): [block:code] { "codes": [ { "code": "Posts.views.add(\"userPosts\", function (terms) {\n return {\n find: {userId: terms.userId},\n options: {limit: 5, sort: {postedAt: -1}}\n };\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Using Views" } [/block] By itself, just adding a view won't do much. You also need to use it somewhere. This can be done through the **posts list controller**. For example, here's how you could use the `userPosts` view mentioned above. In your template, include the `posts_list_controller` template with an `arguments` data context: [block:code] { "codes": [ { "code": "<template name=\"user_posts\">\n {{> posts_list_controller arguments}}\n</template>", "language": "javascript" } ] } [/block] Then define the `arguments` helper like so: [block:code] { "codes": [ { "code": "Template.user_posts.helpers({\n arguments: function () {\n var user = Meteor.user();\n return {\n terms: {\n view: 'userPosts',\n userId: user._id,\n limit: 5\n }\n }\n }\n});", "language": "javascript" } ] } [/block] Alternatively, if you need to build your `arguments` object from URL parameters (as is the case for the `telescope:category` package), you can also generate it inside the router's `data` hook: [block:code] { "codes": [ { "code": "Posts.controllers.userPosts = Posts.controllers.list.extend({\n data: function () {\n var user = Meteor.users.findOne(this.params.userId);\n return {\n terms: {\n view: 'userPosts',\n userId: user._id,\n limit: 5\n }\n }\n }\n});\n\nRouter.route('/userPosts/:userId', {\n controller: Posts.controllers.userPosts,\n name: 'userPosts'\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Adding A Menu Item" } [/block] You'll probably also want to add a link to your new view to the `viewsMenu` menu. For example, here's how the `telescope:daily` package adds its menu link: [block:code] { "codes": [ { "code": "Telescope.menuItems.add(\"viewsMenu\", {\n route: 'postsDaily',\n label: 'daily',\n description: 'day_by_day_view'\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Posts List Controllers & Components" } [/block] Posts list are displayed using the **a template controller**. The controller takes a set of arguments, and then uses them to subscribe to the necessary subscriptions and set the data context for the **component**. The posts list controller can take the following options: - `template`: which template/component to use. Defaults to `posts_list`. - `options`: a set of options which will be passed on to the component. - `terms`: query terms passed on to the post view function. The `posts_list` component can take the following options: - `title`: the title of the posts list. - `postsCursor`: a cursor containing the posts list. - `postsCount`: a count of how many posts are loaded. - `postsReady`: a boolean variable indicating whether the subscription is ready. - `hasMorePosts`: whether there still are more posts to be loaded. - `loadMoreHandler`: the callback to execute when the user clicks "load more". Telescope also uses an alternate `posts_list_compact` component, which shows fewer information and uses a table layout.