{"_id":"5635b294d209b50d0031dfe1","__v":0,"project":"550a7754635c660d0052808e","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"},"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"},"updates":["555ef370750e240d00cc30c5"],"next":{"pages":[],"description":""},"createdAt":"2015-04-09T03:36:55.459Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":17,"body":"Telescope relies on **packages** in order to keep a lightweight yet easily extensible core. \n\nIf you'd like to benefit from this modularity, you can create one or more packages that will hold all your custom code. This way, you'll be able to easily turn your customizations on or off, and optionally share your custom packages on [Atmosphere](http://atmospherejs.com).\n\nNote that creating a package is **not** required. You can also place your customization code in your app's root directory, just like in any regular Meteor app. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"There are two main types of packages: “published” packages, which are hosted on Meteor's package server, and “local” packages, which are part of your codebase and live in the `/packages` directory. \\n\\nWe'll focus on local packages for now. You can use them and modify them straight away without having to publish them to the package server, so unless you want to make your code public they are generally easier to work with.\",\n  \"title\": \"Two Types of Packages\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"The Custom Package Template\"\n}\n[/block]\nThe [developer repository](https://github.com/TelescopeJS/Telescope/tree/master/packages/custom) comes with a custom package template in `/packages/custom` to help you get started. You can add it by running the following command from within your app directory:\n\n```\nmeteor add my-custom-package\n```\n\nYou can go ahead and look through the custom package's code, or read on for a more detailed overview of the package system.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating a Package\"\n}\n[/block]\nTo create a package, create a new directory inside `/packages`, and inside that directory add the `package.js` manifest file.\n\nYou'll find more information about `package.js` [in the Meteor documentation](http://docs.meteor.com/#packagejs), so I suggest checking it out. \n\nBriefly speaking, the package manifest is split in two section. The `Package.describe` block is where you describe your packages's content. \n\nThe second block, `Package.onUse`, is where you'll:\n\n- Specify which *other* packages your package depends on, both on the client and/or server, using `api.use`.\n- Specify which files your package makes use of, using `api.addFiles`.\n- Specify which object to export *out* of your package and make available to the rest of your app, using `api.export`. \n\nNote that **all Telescope packages need to depend on `telescope:core`**.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding Packages\"\n}\n[/block]\nAdding a package is pretty simple. Just go to your console and type:\n\n```\nmeteor add xyz\n```\n\nWhere `xyz` is your package's name. Do not literally type `xyz`, unless you've actually named your package `xyz` I guess. But at this point you're just trying to make things more difficult!\n\nAll the `meteor add` command does is add your package's name to the `.meteor/packages` file. So if it seems like your package isn't working, it's always a good idea to double-check there to make sure it has been properly added to the list. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Controlling Load Order\"\n}\n[/block]\nYou can use `api.use()` to control load order even if you're not directly using a package. \n\nSo for example, if you were tweaking the Hubble theme's style and wanted to make sure your CSS gets loaded last, you could make your package depend on `telescope:theme-hubble` with: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" api.use('telescope:theme-hubble');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Exporting\"\n}\n[/block]\nJust like in Las Vegas, what happens in a package stays in a package. So any variable or function you declare *inside* one won't be available to any code located *outside* of that package's directory.\n\nExcept, that is, if you **export** that object using `api.export`:\n\n```js\napi.export([\n  'myVariable',\n  'myFunction'\n]);\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Static Assets\"\n}\n[/block]\nYou can add static assets (images, text files, etc.) to your packages just like regular JS or HTML files:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"api.addAssets([\\n  'public/img/default-avatar.png',\\n  'public/img/loading-balls.svg',\\n  'public/img/loading.svg',\\n], 'client');\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nOnce your files are properly included, a file living in `public/img/sprite.png` in `author:packagename` will be found at `/packages/author_packagename/public/img/sprite.png`. See [Stack Overflow](http://stackoverflow.com/questions/24143504/meteor-package-how-to-add-static-files) for more details.","excerpt":"Learn to use packages to safely extend and customize Telescope.","slug":"custom-packages","type":"basic","title":"Custom Packages"}

Custom Packages

Learn to use packages to safely extend and customize Telescope.

Telescope relies on **packages** in order to keep a lightweight yet easily extensible core. If you'd like to benefit from this modularity, you can create one or more packages that will hold all your custom code. This way, you'll be able to easily turn your customizations on or off, and optionally share your custom packages on [Atmosphere](http://atmospherejs.com). Note that creating a package is **not** required. You can also place your customization code in your app's root directory, just like in any regular Meteor app. [block:callout] { "type": "info", "body": "There are two main types of packages: “published” packages, which are hosted on Meteor's package server, and “local” packages, which are part of your codebase and live in the `/packages` directory. \n\nWe'll focus on local packages for now. You can use them and modify them straight away without having to publish them to the package server, so unless you want to make your code public they are generally easier to work with.", "title": "Two Types of Packages" } [/block] [block:api-header] { "type": "basic", "title": "The Custom Package Template" } [/block] The [developer repository](https://github.com/TelescopeJS/Telescope/tree/master/packages/custom) comes with a custom package template in `/packages/custom` to help you get started. You can add it by running the following command from within your app directory: ``` meteor add my-custom-package ``` You can go ahead and look through the custom package's code, or read on for a more detailed overview of the package system. [block:api-header] { "type": "basic", "title": "Creating a Package" } [/block] To create a package, create a new directory inside `/packages`, and inside that directory add the `package.js` manifest file. You'll find more information about `package.js` [in the Meteor documentation](http://docs.meteor.com/#packagejs), so I suggest checking it out. Briefly speaking, the package manifest is split in two section. The `Package.describe` block is where you describe your packages's content. The second block, `Package.onUse`, is where you'll: - Specify which *other* packages your package depends on, both on the client and/or server, using `api.use`. - Specify which files your package makes use of, using `api.addFiles`. - Specify which object to export *out* of your package and make available to the rest of your app, using `api.export`. Note that **all Telescope packages need to depend on `telescope:core`**. [block:api-header] { "type": "basic", "title": "Adding Packages" } [/block] Adding a package is pretty simple. Just go to your console and type: ``` meteor add xyz ``` Where `xyz` is your package's name. Do not literally type `xyz`, unless you've actually named your package `xyz` I guess. But at this point you're just trying to make things more difficult! All the `meteor add` command does is add your package's name to the `.meteor/packages` file. So if it seems like your package isn't working, it's always a good idea to double-check there to make sure it has been properly added to the list. [block:api-header] { "type": "basic", "title": "Controlling Load Order" } [/block] You can use `api.use()` to control load order even if you're not directly using a package. So for example, if you were tweaking the Hubble theme's style and wanted to make sure your CSS gets loaded last, you could make your package depend on `telescope:theme-hubble` with: [block:code] { "codes": [ { "code": " api.use('telescope:theme-hubble');", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "Exporting" } [/block] Just like in Las Vegas, what happens in a package stays in a package. So any variable or function you declare *inside* one won't be available to any code located *outside* of that package's directory. Except, that is, if you **export** that object using `api.export`: ```js api.export([ 'myVariable', 'myFunction' ]); ``` [block:api-header] { "type": "basic", "title": "Using Static Assets" } [/block] You can add static assets (images, text files, etc.) to your packages just like regular JS or HTML files: [block:code] { "codes": [ { "code": "api.addAssets([\n 'public/img/default-avatar.png',\n 'public/img/loading-balls.svg',\n 'public/img/loading.svg',\n], 'client');", "language": "text" } ] } [/block] Once your files are properly included, a file living in `public/img/sprite.png` in `author:packagename` will be found at `/packages/author_packagename/public/img/sprite.png`. See [Stack Overflow](http://stackoverflow.com/questions/24143504/meteor-package-how-to-add-static-files) for more details.