{"_id":"5635b294d209b50d0031dfdf","project":"550a7754635c660d0052808e","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"},"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"},"githubsync":"","user":"5469e5dfa3b67a0e00559b06","__v":1,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-05-20T00:28:00.011Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":15,"body":"**IMPORTANT: [Nova](https://github.com/TelescopeJS/Telescope/tree/nova) is a new, React-based version of Telescope. Although it's still beta software, it is recommended you use it for any new projects going forward.**\n\nSo you'd like to customize Telescope. Here's what you need to know. \n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Why Editing Telescope's Code Directly Is A Very Bad Idea\",\n  \"body\": \"Telescope and Telescope packages hide their source code for a reason: you're not supposed to edit it. \\n\\nEven if you clone the app's GitHub repo and do have access to the original code, editing it can potentially make it very hard to keep your app up to date, and is neither recommended or supported. \\n\\nInstead, you should always **add** your customizations *on top of* the existing code.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Customizing Telescope\"\n}\n[/block]\nWhile you can already tweak Telescope a lot through its Settings panel, more advanced customizations are also possible. Here's a short overview of this section:\n\n- [Custom Stylesheets](doc:custom-stylesheets): add custom CSS styles to your app. \n- [Custom Templates](doc:custom-templates): select any part of Telescope's UI and replace it with your own markup. \n- [Template Modules](doc:template-hooks): insert additional templates at key points throughout the UI.\n- [Callback Hooks](doc:callback-hooks): add custom code that runs after specific actions.\n- [Custom Views](doc:views): define new ways of filtering and displaying posts and comments. \n- [Custom Menus](doc:custom-menus): add and remove elements from menus.\n- [Custom Icons](doc:custom-icons): tweak or replace Telescope's icons.\n- [Color Hooks](doc:color-hooks): use Telescope's user-defined colors in your own customizations.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Static vs Dynamic Customization\"\n}\n[/block]\nTelescope usually features two ways of customizing things: **static** and **dynamic** customization.\n\nTo understand the difference, let's look at a simple example, adding a menu item to the user menu.\n\nThe **static** way would be replacing the `user_menu` template with your own, and hardcoding in the menu elements you need right in your template.\n\nThe **dynamic** way would be keeping the `user_menu` template intact, and using Telescope's [Custom Menus](doc:custom-menus) system to dynamically add in the extra element to the `user` menu component contained within. \n\n**Static** customization is simpler to implement and works great if you're working on customizing your own app, but **dynamic** customization is much more flexible, and is recommended if you're working on a theme or plugin that you intend to make available to the world. \n\nTo go back to our example, maybe your potential theme customers have already added their *own* extra menu item. Using the dynamic approach means their extra item will appear while using your theme as well without any work on their part. \n\n[Template Modules](doc:template-modules) and [Custom Menus](doc:custom-menus) are both dynamic customization features that can be ignored if you're going for the static-only approach. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Packages (Or Not)\"\n}\n[/block]\nWhen it comes to customizing your Telescope app, you have two options: put your customization code right in your Meteor app's root directory, or create a [custom package](doc:custom-packages) to hold your code.\n\nHere is a comparison of both approaches:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Root Directory\",\n    \"h-1\": \"Custom Package\",\n    \"0-0\": \"Your files will be automatically picked up and used.\",\n    \"0-1\": \"Your files need to be manually added with `api.addFiles()` in your `package.js`.\",\n    \"1-0\": \"You can use Meteor's built-in `/server` and `/client` directories to control where your code will run.\",\n    \"1-1\": \"You need to specify where each file will run by passing \\\"client\\\" or \\\"server\\\" to `api.addFiles()`.\",\n    \"2-0\": \"Your files will automatically load in alphabetical order.\",\n    \"2-1\": \"You can control load order in `package.js`.\",\n    \"3-0\": \"No easy way to turn your customizations on and off.\",\n    \"3-1\": \"You can use `meteor add package` and `meteor remove package` to enable or disable your customizations.\",\n    \"4-0\": \"No easy way to publish and share your code.\",\n    \"4-1\": \"You can share your package on [Atmosphere](http://atmospherejs.com)\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\nTo sum things up, placing your files in your app's root directory is **simpler**, but using packages provides **more fine-grained control** and makes it easy to **share your code** (which is great for things like themes or plug-ins). \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Where Should My Code Go?\",\n  \"body\": \"If you're using the **Root Directory** approach, you should refer to Meteor's [Structuring Your App](http://docs.meteor.com/#/full/structuringyourapp) documentation section.\\n\\nIf you're using the **Custom Package** approach, you can put your code in any location inside your package, as long as you include the file in your `package.js` package manifest. \\n\\nNote that you will need to include each file on the client, server, or both. Most files should be included in both environments, except for template-related (client only) or email-related (server only) code.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nYou'll need to have Telescope running locally. Refer to the [Installing Telescope](doc:installing-telescope) section.\n\n- In most cases, you should choose the **Easy** or **Manual** setup.\n- You should choose the **Developer** setup if you'd like easier access to Telescope's source code. \n\n**Warning**: even with the Developer setup, it is not recommended to modify any of Telescope's  code, as that will make it very hard to keep your codebase up to date moving forward. The one exception to this is if you plan to contribute your changes back to the main repository as a pull request. \n\nApart from reading the documentation, a good first step is to check out [the sample custom project](https://github.com/telescopejs/custom-project).","excerpt":"","slug":"overview","type":"basic","title":"Overview"}
**IMPORTANT: [Nova](https://github.com/TelescopeJS/Telescope/tree/nova) is a new, React-based version of Telescope. Although it's still beta software, it is recommended you use it for any new projects going forward.** So you'd like to customize Telescope. Here's what you need to know. [block:callout] { "type": "danger", "title": "Why Editing Telescope's Code Directly Is A Very Bad Idea", "body": "Telescope and Telescope packages hide their source code for a reason: you're not supposed to edit it. \n\nEven if you clone the app's GitHub repo and do have access to the original code, editing it can potentially make it very hard to keep your app up to date, and is neither recommended or supported. \n\nInstead, you should always **add** your customizations *on top of* the existing code." } [/block] [block:api-header] { "type": "basic", "title": "Customizing Telescope" } [/block] While you can already tweak Telescope a lot through its Settings panel, more advanced customizations are also possible. Here's a short overview of this section: - [Custom Stylesheets](doc:custom-stylesheets): add custom CSS styles to your app. - [Custom Templates](doc:custom-templates): select any part of Telescope's UI and replace it with your own markup. - [Template Modules](doc:template-hooks): insert additional templates at key points throughout the UI. - [Callback Hooks](doc:callback-hooks): add custom code that runs after specific actions. - [Custom Views](doc:views): define new ways of filtering and displaying posts and comments. - [Custom Menus](doc:custom-menus): add and remove elements from menus. - [Custom Icons](doc:custom-icons): tweak or replace Telescope's icons. - [Color Hooks](doc:color-hooks): use Telescope's user-defined colors in your own customizations. [block:api-header] { "type": "basic", "title": "Static vs Dynamic Customization" } [/block] Telescope usually features two ways of customizing things: **static** and **dynamic** customization. To understand the difference, let's look at a simple example, adding a menu item to the user menu. The **static** way would be replacing the `user_menu` template with your own, and hardcoding in the menu elements you need right in your template. The **dynamic** way would be keeping the `user_menu` template intact, and using Telescope's [Custom Menus](doc:custom-menus) system to dynamically add in the extra element to the `user` menu component contained within. **Static** customization is simpler to implement and works great if you're working on customizing your own app, but **dynamic** customization is much more flexible, and is recommended if you're working on a theme or plugin that you intend to make available to the world. To go back to our example, maybe your potential theme customers have already added their *own* extra menu item. Using the dynamic approach means their extra item will appear while using your theme as well without any work on their part. [Template Modules](doc:template-modules) and [Custom Menus](doc:custom-menus) are both dynamic customization features that can be ignored if you're going for the static-only approach. [block:api-header] { "type": "basic", "title": "Using Packages (Or Not)" } [/block] When it comes to customizing your Telescope app, you have two options: put your customization code right in your Meteor app's root directory, or create a [custom package](doc:custom-packages) to hold your code. Here is a comparison of both approaches: [block:parameters] { "data": { "h-0": "Root Directory", "h-1": "Custom Package", "0-0": "Your files will be automatically picked up and used.", "0-1": "Your files need to be manually added with `api.addFiles()` in your `package.js`.", "1-0": "You can use Meteor's built-in `/server` and `/client` directories to control where your code will run.", "1-1": "You need to specify where each file will run by passing \"client\" or \"server\" to `api.addFiles()`.", "2-0": "Your files will automatically load in alphabetical order.", "2-1": "You can control load order in `package.js`.", "3-0": "No easy way to turn your customizations on and off.", "3-1": "You can use `meteor add package` and `meteor remove package` to enable or disable your customizations.", "4-0": "No easy way to publish and share your code.", "4-1": "You can share your package on [Atmosphere](http://atmospherejs.com)" }, "cols": 2, "rows": 5 } [/block] To sum things up, placing your files in your app's root directory is **simpler**, but using packages provides **more fine-grained control** and makes it easy to **share your code** (which is great for things like themes or plug-ins). [block:callout] { "type": "info", "title": "Where Should My Code Go?", "body": "If you're using the **Root Directory** approach, you should refer to Meteor's [Structuring Your App](http://docs.meteor.com/#/full/structuringyourapp) documentation section.\n\nIf you're using the **Custom Package** approach, you can put your code in any location inside your package, as long as you include the file in your `package.js` package manifest. \n\nNote that you will need to include each file on the client, server, or both. Most files should be included in both environments, except for template-related (client only) or email-related (server only) code." } [/block] [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] You'll need to have Telescope running locally. Refer to the [Installing Telescope](doc:installing-telescope) section. - In most cases, you should choose the **Easy** or **Manual** setup. - You should choose the **Developer** setup if you'd like easier access to Telescope's source code. **Warning**: even with the Developer setup, it is not recommended to modify any of Telescope's code, as that will make it very hard to keep your codebase up to date moving forward. The one exception to this is if you plan to contribute your changes back to the main repository as a pull request. Apart from reading the documentation, a good first step is to check out [the sample custom project](https://github.com/telescopejs/custom-project).