{"_id":"5635b294d209b50d0031dfe4","project":"550a7754635c660d0052808e","user":"5469e5dfa3b67a0e00559b06","version":{"_id":"5635b290d209b50d0031dfc4","__v":1,"project":"550a7754635c660d0052808e","createdAt":"2015-11-01T06:34:56.868Z","releaseDate":"2015-11-01T06:34:56.868Z","categories":["5635b291d209b50d0031dfc5","5635b291d209b50d0031dfc6","5635b291d209b50d0031dfc7","5635b291d209b50d0031dfc8","5635b291d209b50d0031dfc9","5635b291d209b50d0031dfca"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.25.0","version":"0.25"},"githubsync":"","category":{"_id":"5635b291d209b50d0031dfc7","pages":["5635b294d209b50d0031dfdf","5635b294d209b50d0031dfe0","5635b294d209b50d0031dfe1","5635b294d209b50d0031dfe2","5635b294d209b50d0031dfe3","5635b294d209b50d0031dfe4","5635b294d209b50d0031dfe5","5635b294d209b50d0031dfe6","5635b294d209b50d0031dfe7","5635b294d209b50d0031dfe8","5635b294d209b50d0031dfe9","5635b294d209b50d0031dfea","5635b294d209b50d0031dfeb","5635b294d209b50d0031dfec"],"project":"550a7754635c660d0052808e","__v":1,"version":"5635b290d209b50d0031dfc4","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-09T03:24:43.474Z","from_sync":false,"order":2,"slug":"customizing-telescope","title":"Customizing Telescope"},"__v":2,"updates":["569d8bf167331a0d002805df","56abcc409327b30d00f7c253"],"next":{"pages":[],"description":""},"createdAt":"2015-05-10T02:25:36.418Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":20,"body":"Telescope makes it easy to override any template in the app, but it also features a **template module** system that lets you *insert* extra templates at specific points. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Why Modules?\"\n}\n[/block]\nBehind the scenes, modules are just regular templates. But unlike template replacement, which switches out a whole section of the app, adding a module doesn't impact the content that already exists. \n\nSo for example, modules make it possible for Telescope's `telescope-newsletter` package to add a newsletter subscription banner to the `hero` zone, while the [Hero Banner plugin](https://atmospherejs.com/jeremy/telescope-plugin-hero) *also* adds a hero banner to the same zone. \n\nIf these packages were using template *replacement* instead, we would only be able to replace the hero zone with one or the other, but not display both at the same time.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding a Module\"\n}\n[/block]\nYou can add a module using the `Telescope.modules.add` method, which takes two arguments: the zone to add the module to, and the module options. \n\nThe module options consists of a `template` name, and an optional `order` property to indicate in what order the module should come within the zone. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Telescope.modules.add(\\\"hero\\\", {\\n  template: \\\"newsletter_banner\\\",\\n  order: 10\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Removing Modules\"\n}\n[/block]\nYou can remove a single module with `Telescope.modules.remove(zoneName, templateName)`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Telescope.modules.remove(\\\"hero\\\", \\\"newsletter_banner\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nAdditionally, you can also remove all modules with `Telescope.modules.removeAll(zone)`: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Telescope.modules.removeAll(\\\"hero\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Module Zones\"\n}\n[/block]\nTelescope features the following module zones out of the box: \n\n- `hero`\n- `footer`\n- `thread`\n- `top`\n- `postComponents`\n- `postThumbnail`\n- `postHeading`\n- `postMeta`\n- `profileDisplay`\n- `profileEdit`\n- `primaryNav`\n- `secondaryNav`\n- `mobileNav`\n- `adminMenu`\n- `commentThreadBottom`\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Displaying Module Zones\",\n  \"body\": \"You can display module zones by holding down the \\\"`\\\" (backtick) key to enable [debug mode](/docs/debug-mode).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating Zones\"\n}\n[/block]\nTo create your own module zone, all you need to do is include the `modules` template anywhere in your templates and pass it your zone name:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{> modules zone=\\\"myZoneName\\\"}}\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThis will then display any module you add to the `myZoneName` zone.","excerpt":"","slug":"template-modules","type":"basic","title":"Template Modules"}
Telescope makes it easy to override any template in the app, but it also features a **template module** system that lets you *insert* extra templates at specific points. [block:api-header] { "type": "basic", "title": "Why Modules?" } [/block] Behind the scenes, modules are just regular templates. But unlike template replacement, which switches out a whole section of the app, adding a module doesn't impact the content that already exists. So for example, modules make it possible for Telescope's `telescope-newsletter` package to add a newsletter subscription banner to the `hero` zone, while the [Hero Banner plugin](https://atmospherejs.com/jeremy/telescope-plugin-hero) *also* adds a hero banner to the same zone. If these packages were using template *replacement* instead, we would only be able to replace the hero zone with one or the other, but not display both at the same time. [block:api-header] { "type": "basic", "title": "Adding a Module" } [/block] You can add a module using the `Telescope.modules.add` method, which takes two arguments: the zone to add the module to, and the module options. The module options consists of a `template` name, and an optional `order` property to indicate in what order the module should come within the zone. [block:code] { "codes": [ { "code": "Telescope.modules.add(\"hero\", {\n template: \"newsletter_banner\",\n order: 10\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Removing Modules" } [/block] You can remove a single module with `Telescope.modules.remove(zoneName, templateName)`: [block:code] { "codes": [ { "code": "Telescope.modules.remove(\"hero\", \"newsletter_banner\");", "language": "javascript" } ] } [/block] Additionally, you can also remove all modules with `Telescope.modules.removeAll(zone)`: [block:code] { "codes": [ { "code": "Telescope.modules.removeAll(\"hero\");", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Module Zones" } [/block] Telescope features the following module zones out of the box: - `hero` - `footer` - `thread` - `top` - `postComponents` - `postThumbnail` - `postHeading` - `postMeta` - `profileDisplay` - `profileEdit` - `primaryNav` - `secondaryNav` - `mobileNav` - `adminMenu` - `commentThreadBottom` [block:callout] { "type": "info", "title": "Displaying Module Zones", "body": "You can display module zones by holding down the \"`\" (backtick) key to enable [debug mode](/docs/debug-mode)." } [/block] [block:api-header] { "type": "basic", "title": "Creating Zones" } [/block] To create your own module zone, all you need to do is include the `modules` template anywhere in your templates and pass it your zone name: [block:code] { "codes": [ { "code": "{{> modules zone=\"myZoneName\"}}", "language": "html" } ] } [/block] This will then display any module you add to the `myZoneName` zone.