{"_id":"5635b294d209b50d0031dfe7","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"},"__v":1,"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"},"project":"550a7754635c660d0052808e","githubsync":"","updates":["55ca9d2a27fde72b003e9812","567a7d077b575f0d006ae277"],"next":{"pages":[],"description":""},"createdAt":"2015-05-10T02:25:55.889Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":23,"body":"Telescope is organized around posts and comments, but that doesn't mean you're limited to the default properties. You can easily add and remove fields to completely customize the behavior of your app.\n\nAdding a custom field will add it to all submission and edition forms, and take care of inserting it in the database. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Help! My Fields Are Not Showing Up!\",\n  \"body\": \"Note that adding a custom field *won't* modify the template used to **display** posts or comments, which means you'll still need to modify it by hand if you want your new field to appear. \\n\\nThe exception to this is the user profile, which *does* automatically display new custom fields.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding Fields\"\n}\n[/block]\nYou can add custom fields to the `Posts`, `Comments`, `Users`, and `Settings` collections with the following functions:\n\n- `Posts.addField(field)`\n- `Comments.addField(field)`\n- `Users.addField(field)`\n- `Settings.addField(field)`\n\nAll four take a single `field` argument (or an array of fields), which has the following properties:\n\n- `fieldName`: the **name** of the custom field.\n- `fieldSchema`: the **schema** of the field, defined according to the [SimpleSchema](https://github.com/aldeed/meteor-simple-schema) guidelines.\n\nFor example, here's how the `telescope-subscribe-to-posts` package adds a custom `subscriberCount` field, used to keep track of how many people are subscribed to a post's comment thread. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Posts.addField({\\n  fieldName: 'subscriberCount',\\n  fieldSchema: {\\n    type: Number,\\n    optional: true,\\n    autoform: {\\n      omit: true\\n    }\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nMake sure you check the Field Properties section below to see what properties you should specify. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Namespacing\",\n  \"body\": \"Although this is not yet strictly enforced in Telescope's core codebase, it might be a good idea to add any custom fields inside your package's own namespace to avoid any conflicts.\\n\\nSo rather than `fieldName: 'subscriberCount'`, you would use `fieldName: 'subscribe-to-posts.subscriberCount'`.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Removing a Field\"\n}\n[/block]\nYou can remove a field with:\n\n- `Posts.removeField(fieldName)`\n- `Comments.removeField(fieldName)`\n- `Users.removeField(fieldName)`\n- `Settings.removeField(fieldName)`\n\nNote that removing some key fields like the `Posts` collection's `title` or `URL` might cause bugs when the app expects them and doesn't find them. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Generic Field Properties\"\n}\n[/block]\nThe `fieldSchema` object supports all [SimpleSchema](https://github.com/aldeed/meteor-simple-schema) and [AutoForm](https://github.com/aldeed/meteor-autoform) properties. Some of the most commonly used include:  \n\n**`type`**\n\nThe type of the property: `String`, `Object`, `Number`, etc. To indicate that the field should store an *array* of a certain type, you can specify `[String]`, `[Object]`, etc.\n\n**`optional`**\n\nWhether the field is required. Setting this to `true` will cause the validation to fail if the field is missing.\n\n**`autoform`**\n\nContains options to govern how [Autoform](https://github.com/aldeed/meteor-autoform) should display the field. For example, you can set `autoform.omit` to `true` to make sure a field never appears in an Autoform-generated form. \n\n**`blackbox`**\n\nIf you have a key with type `Object`, the properties of the object will be validated as well, so you must define all allowed properties in the schema. If this is not possible or you don't care to validate the object's properties, use the `blackbox: true` option to skip validation for everything within the object.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Telescope-Specific Properties\"\n}\n[/block]\nIn addition, the following **Telescope-specific** properties are also supported:\n\n**`editableBy`**\n\nShould contain an array to indicate which user roles can edit this field. Possible values include:\n\n- `member`: regular users (they will still need however to **own** the document being edited).\n- `admin`: admin users. \n\nFor example, the `telescope-embedly` package's `thumbnailURL` field should be editable by both regular post authors and admins:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Posts.addField({\\n  fieldName: 'thumbnailUrl',\\n  fieldSchema: {\\n    type: String,\\n    optional: true,\\n    editableBy: [\\\"member\\\", \\\"admin\\\"],\\n    autoform: {\\n      type: 'bootstrap-postthumbnail'\\n    }\\n  }\\n});\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n**`private`** (`Settings` only)\n\nYou can set `private` to `true` to indicate that some fields should be stored in the database, but never published to the client (note that this currently only works for the `Settings` collection. `Posts` and `Comments` will publish *all* fields, and `Users` will publish none by default). \n\nFor example, here's how the `telescope-kadira` package indicates that the `kadiraAppSecret` field is private:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Settings.registerField({\\n  fieldName: \\\"kadiraAppSecret\\\",\\n  propertyGroup: \\\"kadira\\\",\\n  fieldSchema: {\\n    type: String,\\n    optional: true,\\n    private: true,\\n    autoform: {\\n      group: \\\"kadira\\\",\\n      class: \\\"private-field\\\"\\n    }\\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n**`autoform.order`**\n\nControls the order in which the field will appear. \n\nNote that by default, fields don't have any order (and will appear after any fields whose order is specified). So if you want to control the order of a default field, you'll have to remove it first, then add it back with the `autoform.order` property specified.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Users-Specific Properties\"\n}\n[/block]\nFields added to the `Users` collection's schema support a few additional properties:\n\n**`required`**\n\nWhen a user first registers via third-party services such as Twitter or Facebook, their account is automatically created by Meteor with the information provided.\n\nYet this information might not include important fields like `email`. So by setting `required` to `true`, you can indicate that a field is required before a user is able to access your app. \n\nOnce a field is marked as `required`, a prompt will appear as soon as a user is registered, asking them to complete their profile. \n\nNote that unlike `optional: false`, a missing `required` fields does *not* prevent the creation of the user.\n\n**`public`**\n\nAny field you add to the Users schema will remain unpublished to the client by default. Set this field to `true` if you *do* want the field to be published.\n\n**`profile`**\n\nSet this to `true` to have the field appear on user profiles. \n\n**`template`**\n\nThe name of a template used to display the field in user profiles. If not set, the field's contents will just be displayed as a string.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"User Settings\"\n}\n[/block]\nTelescope exposes the `Users.getSetting` and `Users.setSetting` to help manage custom user fields. \n\n`Users.getSetting` takes three arguments:\n\n- `user`.\n- `settingName`: the name of the setting (for example `newsletter.showBanner`). This will automatically be prefixed with `telescope.` when looked up on the user object. \n- `defaultValue`: a value to default to if the setting isn't set on the user object.\n\n`Users.setSetting` also takes three arguments:\n\n- `user`.\n- `settingName`: the name of the setting (for example `newsletter.showBanner`). This will automatically be prefixed with `telescope.` when set on the user object. \n- `value`: the value of the setting.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"The user.telescope Namespace\",\n  \"body\": \"Namespacing is especially important for the `Users` collection, in order to maintain compatibility with other apps or packages which might set their own properties on the user object. \\n\\nFor that reason, every user custom field should be set inside the `user.telescope` namespace.\\n\\nFor example: `fieldName: 'telescope.newsletter.showBanner'`.\"\n}\n[/block]","excerpt":"","slug":"custom-fields","type":"basic","title":"Custom Fields"}
Telescope is organized around posts and comments, but that doesn't mean you're limited to the default properties. You can easily add and remove fields to completely customize the behavior of your app. Adding a custom field will add it to all submission and edition forms, and take care of inserting it in the database. [block:callout] { "type": "info", "title": "Help! My Fields Are Not Showing Up!", "body": "Note that adding a custom field *won't* modify the template used to **display** posts or comments, which means you'll still need to modify it by hand if you want your new field to appear. \n\nThe exception to this is the user profile, which *does* automatically display new custom fields." } [/block] [block:api-header] { "type": "basic", "title": "Adding Fields" } [/block] You can add custom fields to the `Posts`, `Comments`, `Users`, and `Settings` collections with the following functions: - `Posts.addField(field)` - `Comments.addField(field)` - `Users.addField(field)` - `Settings.addField(field)` All four take a single `field` argument (or an array of fields), which has the following properties: - `fieldName`: the **name** of the custom field. - `fieldSchema`: the **schema** of the field, defined according to the [SimpleSchema](https://github.com/aldeed/meteor-simple-schema) guidelines. For example, here's how the `telescope-subscribe-to-posts` package adds a custom `subscriberCount` field, used to keep track of how many people are subscribed to a post's comment thread. [block:code] { "codes": [ { "code": "Posts.addField({\n fieldName: 'subscriberCount',\n fieldSchema: {\n type: Number,\n optional: true,\n autoform: {\n omit: true\n }\n }\n});", "language": "javascript" } ] } [/block] Make sure you check the Field Properties section below to see what properties you should specify. [block:callout] { "type": "info", "title": "Namespacing", "body": "Although this is not yet strictly enforced in Telescope's core codebase, it might be a good idea to add any custom fields inside your package's own namespace to avoid any conflicts.\n\nSo rather than `fieldName: 'subscriberCount'`, you would use `fieldName: 'subscribe-to-posts.subscriberCount'`." } [/block] [block:api-header] { "type": "basic", "title": "Removing a Field" } [/block] You can remove a field with: - `Posts.removeField(fieldName)` - `Comments.removeField(fieldName)` - `Users.removeField(fieldName)` - `Settings.removeField(fieldName)` Note that removing some key fields like the `Posts` collection's `title` or `URL` might cause bugs when the app expects them and doesn't find them. [block:api-header] { "type": "basic", "title": "Generic Field Properties" } [/block] The `fieldSchema` object supports all [SimpleSchema](https://github.com/aldeed/meteor-simple-schema) and [AutoForm](https://github.com/aldeed/meteor-autoform) properties. Some of the most commonly used include: **`type`** The type of the property: `String`, `Object`, `Number`, etc. To indicate that the field should store an *array* of a certain type, you can specify `[String]`, `[Object]`, etc. **`optional`** Whether the field is required. Setting this to `true` will cause the validation to fail if the field is missing. **`autoform`** Contains options to govern how [Autoform](https://github.com/aldeed/meteor-autoform) should display the field. For example, you can set `autoform.omit` to `true` to make sure a field never appears in an Autoform-generated form. **`blackbox`** If you have a key with type `Object`, the properties of the object will be validated as well, so you must define all allowed properties in the schema. If this is not possible or you don't care to validate the object's properties, use the `blackbox: true` option to skip validation for everything within the object. [block:api-header] { "type": "basic", "title": "Telescope-Specific Properties" } [/block] In addition, the following **Telescope-specific** properties are also supported: **`editableBy`** Should contain an array to indicate which user roles can edit this field. Possible values include: - `member`: regular users (they will still need however to **own** the document being edited). - `admin`: admin users. For example, the `telescope-embedly` package's `thumbnailURL` field should be editable by both regular post authors and admins: [block:code] { "codes": [ { "code": "Posts.addField({\n fieldName: 'thumbnailUrl',\n fieldSchema: {\n type: String,\n optional: true,\n editableBy: [\"member\", \"admin\"],\n autoform: {\n type: 'bootstrap-postthumbnail'\n }\n }\n});", "language": "text" } ] } [/block] **`private`** (`Settings` only) You can set `private` to `true` to indicate that some fields should be stored in the database, but never published to the client (note that this currently only works for the `Settings` collection. `Posts` and `Comments` will publish *all* fields, and `Users` will publish none by default). For example, here's how the `telescope-kadira` package indicates that the `kadiraAppSecret` field is private: [block:code] { "codes": [ { "code": "Settings.registerField({\n fieldName: \"kadiraAppSecret\",\n propertyGroup: \"kadira\",\n fieldSchema: {\n type: String,\n optional: true,\n private: true,\n autoform: {\n group: \"kadira\",\n class: \"private-field\"\n }\n }\n});", "language": "javascript" } ] } [/block] **`autoform.order`** Controls the order in which the field will appear. Note that by default, fields don't have any order (and will appear after any fields whose order is specified). So if you want to control the order of a default field, you'll have to remove it first, then add it back with the `autoform.order` property specified. [block:api-header] { "type": "basic", "title": "Users-Specific Properties" } [/block] Fields added to the `Users` collection's schema support a few additional properties: **`required`** When a user first registers via third-party services such as Twitter or Facebook, their account is automatically created by Meteor with the information provided. Yet this information might not include important fields like `email`. So by setting `required` to `true`, you can indicate that a field is required before a user is able to access your app. Once a field is marked as `required`, a prompt will appear as soon as a user is registered, asking them to complete their profile. Note that unlike `optional: false`, a missing `required` fields does *not* prevent the creation of the user. **`public`** Any field you add to the Users schema will remain unpublished to the client by default. Set this field to `true` if you *do* want the field to be published. **`profile`** Set this to `true` to have the field appear on user profiles. **`template`** The name of a template used to display the field in user profiles. If not set, the field's contents will just be displayed as a string. [block:api-header] { "type": "basic", "title": "User Settings" } [/block] Telescope exposes the `Users.getSetting` and `Users.setSetting` to help manage custom user fields. `Users.getSetting` takes three arguments: - `user`. - `settingName`: the name of the setting (for example `newsletter.showBanner`). This will automatically be prefixed with `telescope.` when looked up on the user object. - `defaultValue`: a value to default to if the setting isn't set on the user object. `Users.setSetting` also takes three arguments: - `user`. - `settingName`: the name of the setting (for example `newsletter.showBanner`). This will automatically be prefixed with `telescope.` when set on the user object. - `value`: the value of the setting. [block:callout] { "type": "info", "title": "The user.telescope Namespace", "body": "Namespacing is especially important for the `Users` collection, in order to maintain compatibility with other apps or packages which might set their own properties on the user object. \n\nFor that reason, every user custom field should be set inside the `user.telescope` namespace.\n\nFor example: `fieldName: 'telescope.newsletter.showBanner'`." } [/block]