├── docs
├── 404.md
├── reference
│ ├── modules
│ │ ├── apostrophe-assets
│ │ │ └── browser-apostrophe-assets.md
│ │ ├── apostrophe-module
│ │ │ ├── browser-apostrophe-module.md
│ │ │ ├── browser-apostrophe-module-editor.md
│ │ │ └── browser-apostrophe-module-manager-modal.md
│ │ ├── apostrophe-files
│ │ │ ├── server-apostrophe-files-cursor.md
│ │ │ ├── browser-apostrophe-files.md
│ │ │ ├── browser-apostrophe-files-chooser.md
│ │ │ ├── README.md
│ │ │ ├── browser-apostrophe-files-manager-modal.md
│ │ │ ├── browser-apostrophe-files-relationship-editor.md
│ │ │ └── browser-apostrophe-files-editor-modal.md
│ │ ├── apostrophe-tags
│ │ │ ├── server-apostrophe-tags-cursor.md
│ │ │ ├── browser-apostrophe-tags-chooser.md
│ │ │ ├── browser-apostrophe-tags-editor-modal.md
│ │ │ ├── browser-apostrophe-tags.md
│ │ │ ├── browser-apostrophe-tags-relationship-editor.md
│ │ │ ├── browser-apostrophe-tags-manager-modal.md
│ │ │ └── README.md
│ │ ├── apostrophe-global
│ │ │ ├── server-apostrophe-global-cursor.md
│ │ │ ├── browser-apostrophe-global-chooser.md
│ │ │ ├── browser-apostrophe-global-editor-modal.md
│ │ │ ├── browser-apostrophe-global-manager-modal.md
│ │ │ ├── browser-apostrophe-global.md
│ │ │ └── browser-apostrophe-global-relationship-editor.md
│ │ ├── apostrophe-groups
│ │ │ ├── server-apostrophe-groups-cursor.md
│ │ │ ├── browser-apostrophe-groups.md
│ │ │ ├── browser-apostrophe-groups-chooser.md
│ │ │ ├── browser-apostrophe-groups-editor-modal.md
│ │ │ ├── browser-apostrophe-groups-manager-modal.md
│ │ │ ├── browser-apostrophe-groups-relationship-editor.md
│ │ │ └── README.md
│ │ ├── apostrophe-search
│ │ │ ├── server-apostrophe-search-cursor.md
│ │ │ ├── browser-apostrophe-search.md
│ │ │ ├── browser-apostrophe-search-chooser.md
│ │ │ └── browser-apostrophe-search-relationship-editor.md
│ │ ├── apostrophe-pieces-pages
│ │ │ ├── server-apostrophe-pieces-pages-cursor.md
│ │ │ ├── browser-apostrophe-pieces-pages.md
│ │ │ ├── browser-apostrophe-pieces-pages-chooser.md
│ │ │ └── browser-apostrophe-pieces-pages-relationship-editor.md
│ │ ├── apostrophe-any-page-manager
│ │ │ ├── server-apostrophe-any-page-manager-cursor.md
│ │ │ ├── browser-apostrophe-any-page-manager-relationship-editor.md
│ │ │ ├── browser-apostrophe-any-page-manager-chooser.md
│ │ │ ├── browser-apostrophe-any-page-manager.md
│ │ │ └── README.md
│ │ ├── apostrophe-polymorphic-manager
│ │ │ ├── server-apostrophe-polymorphic-manager-cursor.md
│ │ │ ├── README.md
│ │ │ ├── browser-apostrophe-polymorphic-manager.md
│ │ │ ├── browser-apostrophe-polymorphic-manager-chooser.md
│ │ │ ├── browser-apostrophe-polymorphic-manager-relationship-editor.md
│ │ │ └── browser-apostrophe-polymorphic-manager-manager-modal.md
│ │ ├── apostrophe-users
│ │ │ ├── server-apostrophe-users-cursor.md
│ │ │ ├── browser-apostrophe-users-chooser.md
│ │ │ ├── browser-apostrophe-users.md
│ │ │ ├── browser-apostrophe-users-manager-modal.md
│ │ │ ├── browser-apostrophe-users-relationship-editor.md
│ │ │ └── browser-apostrophe-users-editor-modal.md
│ │ ├── apostrophe-csrf.md
│ │ ├── apostrophe-login
│ │ │ └── browser-apostrophe-login.md
│ │ ├── apostrophe-images
│ │ │ ├── browser-apostrophe-images.md
│ │ │ ├── browser-apostrophe-images-relationship-editor.md
│ │ │ ├── browser-apostrophe-images-focal-point-editor.md
│ │ │ ├── browser-apostrophe-images-manager-modal.md
│ │ │ ├── browser-apostrophe-images-chooser.md
│ │ │ ├── browser-apostrophe-images-editor-modal.md
│ │ │ └── server-apostrophe-images-cursor.md
│ │ ├── apostrophe-html-widgets
│ │ │ ├── browser-apostrophe-html-widgets.md
│ │ │ ├── browser-apostrophe-html-widgets-editor.md
│ │ │ └── README.md
│ │ ├── apostrophe-pieces-widgets
│ │ │ ├── browser-apostrophe-pieces-widgets.md
│ │ │ └── browser-apostrophe-pieces-widgets-editor.md
│ │ ├── apostrophe-pages
│ │ │ ├── browser-apostrophe-pages-editor-copy.md
│ │ │ ├── browser-apostrophe-pages-editor-update.md
│ │ │ ├── browser-apostrophe-pages.md
│ │ │ ├── browser-apostrophe-pages-editor.md
│ │ │ └── server-apostrophe-pages-cursor.md
│ │ ├── apostrophe-files-widgets
│ │ │ ├── browser-apostrophe-files-widgets.md
│ │ │ ├── browser-apostrophe-files-widgets-editor.md
│ │ │ └── README.md
│ │ ├── apostrophe-custom-pages
│ │ │ ├── browser-apostrophe-custom-pages.md
│ │ │ ├── browser-apostrophe-custom-pages-chooser.md
│ │ │ ├── browser-apostrophe-custom-pages-relationship-editor.md
│ │ │ └── server-apostrophe-custom-pages-cursor.md
│ │ ├── apostrophe-video-widgets
│ │ │ ├── browser-apostrophe-video-widgets-editor.md
│ │ │ ├── browser-apostrophe-video-widgets.md
│ │ │ └── README.md
│ │ ├── apostrophe-pieces
│ │ │ ├── browser-apostrophe-pieces-chooser.md
│ │ │ ├── browser-apostrophe-pieces-relationship-editor.md
│ │ │ ├── browser-apostrophe-pieces-batch-permissions-modal.md
│ │ │ ├── server-apostrophe-pieces-cursor.md
│ │ │ ├── browser-apostrophe-pieces.md
│ │ │ └── browser-apostrophe-pieces-editor-modal.md
│ │ ├── apostrophe-modal
│ │ │ └── README.md
│ │ ├── apostrophe-doc-type-manager
│ │ │ ├── browser-apostrophe-doc-type-manager-manager-modal.md
│ │ │ ├── browser-apostrophe-doc-type-manager-relationship-editor.md
│ │ │ ├── server-apostrophe-doc-type-manager-cursor.md
│ │ │ ├── browser-apostrophe-doc-type-manager.md
│ │ │ └── browser-apostrophe-doc-type-manager-chooser.md
│ │ ├── apostrophe-images-widgets
│ │ │ ├── browser-apostrophe-images-widgets-editor.md
│ │ │ ├── browser-apostrophe-images-widgets.md
│ │ │ └── README.md
│ │ ├── apostrophe-launder.md
│ │ ├── apostrophe-service-bridge.md
│ │ ├── apostrophe-soft-redirects.md
│ │ ├── apostrophe-browser-utils
│ │ │ └── README.md
│ │ ├── apostrophe-admin-bar
│ │ │ └── browser-apostrophe-admin-bar.md
│ │ ├── apostrophe-versions
│ │ │ ├── browser-apostrophe-versions-editor.md
│ │ │ ├── browser-apostrophe-versions.md
│ │ │ └── README.md
│ │ ├── apostrophe-jobs
│ │ │ ├── browser-apostrophe-jobs-modal.md
│ │ │ └── browser-apostrophe-jobs.md
│ │ ├── apostrophe-widgets
│ │ │ ├── browser-apostrophe-widgets-editor.md
│ │ │ └── browser-apostrophe-widgets.md
│ │ ├── apostrophe-pager.md
│ │ ├── apostrophe-attachments
│ │ │ ├── browser-apostrophe-attachments-crop-editor.md
│ │ │ ├── browser-apostrophe-attachments-focal-point-editor.md
│ │ │ └── browser-apostrophe-attachments.md
│ │ ├── apostrophe-video-fields
│ │ │ ├── browser-apostrophe-video-fields.md
│ │ │ └── README.md
│ │ ├── apostrophe-ui
│ │ │ └── README.md
│ │ ├── apostrophe-rich-text-widgets
│ │ │ ├── browser-apostrophe-rich-text-widgets.md
│ │ │ ├── browser-apostrophe-rich-text-widgets-editor.md
│ │ │ └── README.md
│ │ ├── apostrophe-email.md
│ │ ├── apostrophe-notifications
│ │ │ └── browser-apostrophe-notifications.md
│ │ ├── apostrophe-oembed
│ │ │ └── browser-apostrophe-oembed.md
│ │ ├── apostrophe-i18n.md
│ │ ├── apostrophe-db.md
│ │ ├── apostrophe-utils
│ │ │ └── browser-apostrophe-context.md
│ │ ├── apostrophe-locks.md
│ │ ├── apostrophe-docs
│ │ │ └── browser-apostrophe-docs.md
│ │ ├── README.md
│ │ └── apostrophe-urls.md
│ ├── README.md
│ ├── field-properties
│ │ ├── options.md
│ │ ├── sortify.md
│ │ └── README.md
│ └── field-types
│ │ ├── password.md
│ │ ├── url.md
│ │ ├── object.md
│ │ ├── integer.md
│ │ ├── float.md
│ │ ├── slug.md
│ │ ├── email.md
│ │ ├── range.md
│ │ ├── select.md
│ │ ├── checkbox.md
│ │ ├── boolean.md
│ │ ├── singleton.md
│ │ ├── date.md
│ │ ├── string.md
│ │ ├── tags.md
│ │ ├── time.md
│ │ ├── area.md
│ │ ├── video.md
│ │ ├── color.md
│ │ ├── joinbyonereverse.md
│ │ ├── joinbyarrayreverse.md
│ │ └── attachment.md
├── .vuepress
│ ├── public
│ │ └── images
│ │ │ └── apos-dark.png
│ └── styles
│ │ └── palette.styl
├── core-concepts
│ ├── apostrophe-search
│ │ └── README.md
│ ├── front-end-assets
│ │ └── README.md
│ ├── global-settings
│ │ ├── README.md
│ │ └── global.md
│ ├── README.md
│ ├── editable-content-on-pages
│ │ └── README.md
│ ├── modules
│ │ ├── README.md
│ │ └── nested-module-folders.md
│ ├── working-with-templates
│ │ └── README.md
│ ├── pages-and-navigation
│ │ └── README.md
│ ├── reusable-content-pieces
│ │ └── README.md
│ └── users-and-permissions
│ │ ├── README.md
│ │ ├── apostrophe-passport.md
│ │ └── users-and-groups.md
├── advanced-topics
│ ├── promise-events
│ │ └── README.md
│ ├── advanced-pages-topics
│ │ ├── README.md
│ │ └── children-and-joins.md
│ ├── advanced-pieces-topics
│ │ ├── permissions-for-pieces.md
│ │ ├── adding-filters.md
│ │ ├── README.md
│ │ ├── suppressing-pieces-from-a-listing.md
│ │ ├── adding-fields-to-all-pieces.md
│ │ ├── next-previous-links.md
│ │ └── extending-the-pieces-editor-modal.md
│ ├── database
│ │ ├── README.md
│ │ └── replica-set.md
│ ├── README.md
│ ├── how-apostrophe-starts-up.md
│ └── migrations.md
├── devops
│ ├── README.md
│ ├── cloud
│ │ ├── README.md
│ │ ├── storing-images-and-files-in-azure-blob-storage.md
│ │ ├── storing-images-and-files-in-google-cloud-storage.md
│ │ └── storing-images-and-files-in-amazon-s3.md
│ └── deployment
│ │ └── README.md
├── howtos
│ ├── how-do-i-create-a-404-not-found-page.md
│ ├── README.md
│ ├── user-redirect.md
│ ├── storing-sessions-in-redis.md
│ └── windows.md
└── getting-started
│ └── README.md
├── .gitignore
├── images
└── assets
│ ├── user-menu.png
│ ├── user-group-bar.png
│ ├── create_new_page2.png
│ ├── user-add-editor.png
│ ├── favicon
│ ├── favicon-128.png
│ ├── favicon-152.png
│ ├── favicon-167.png
│ ├── favicon-180.png
│ ├── favicon-192.png
│ ├── favicon-196.png
│ └── favicon-32.png
│ ├── tutorial-new-image.png
│ ├── tutorial-slideshow.gif
│ ├── user-select-group.png
│ ├── boilerplate_loggedin.png
│ ├── boilerplate_loggedout.png
│ ├── boilerplate_singleton.png
│ ├── tutorial-plus-button.png
│ ├── ezgif.com-video-to-gif-1.gif
│ ├── ezgif.com-video-to-gif.gif
│ ├── tutorial-images-library.png
│ ├── tutorial-select-images.png
│ ├── user-group-permissions.png
│ ├── tutorial-rich-text-editor.png
│ ├── technical-overview-apostrophe-doc-types.png
│ └── technical-overview-apostrophe-on-the-page.png
├── install
├── .eslintrc
├── _api-reference-generator
├── lib
│ └── modules
│ │ └── documentation
│ │ ├── views
│ │ └── scripts.html
│ │ └── phantomjs-print-definitions.js
├── .gitignore
├── package.json
└── app.js
├── generate
├── deploy
├── package.json
├── LICENSE.md
├── _tip-ins
└── modules.md
└── HOW_TO_UPDATE_THE_DOCUMENTATION.md
/docs/404.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Page not found'
3 | layout: NotFound
4 | ---
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # ignore vim swapfiles
2 | *.swp
3 | *.DS_Store
4 | npm-debug.log
5 | node_modules
6 | dist
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-assets/browser-apostrophe-assets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-assets (browser)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-module/browser-apostrophe-module.md:
--------------------------------------------------------------------------------
1 | # apostrophe-module (browser)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/server-apostrophe-files-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/server-apostrophe-tags-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/server-apostrophe-global-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/server-apostrophe-groups-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-module/browser-apostrophe-module-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-module-editor (browser)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-search/server-apostrophe-search-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-search-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/images/assets/user-menu.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/user-menu.png
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-module/browser-apostrophe-module-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-module-manager-modal (browser)
2 |
3 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-pages/server-apostrophe-pieces-pages-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-pages-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/images/assets/user-group-bar.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/user-group-bar.png
--------------------------------------------------------------------------------
/images/assets/create_new_page2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/create_new_page2.png
--------------------------------------------------------------------------------
/images/assets/user-add-editor.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/user-add-editor.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-128.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-128.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-152.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-152.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-167.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-167.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-180.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-180.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-192.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-192.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-196.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-196.png
--------------------------------------------------------------------------------
/images/assets/favicon/favicon-32.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/favicon/favicon-32.png
--------------------------------------------------------------------------------
/images/assets/tutorial-new-image.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-new-image.png
--------------------------------------------------------------------------------
/images/assets/tutorial-slideshow.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-slideshow.gif
--------------------------------------------------------------------------------
/images/assets/user-select-group.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/user-select-group.png
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-any-page-manager/server-apostrophe-any-page-manager-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-any-page-manager-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/images/assets/boilerplate_loggedin.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/boilerplate_loggedin.png
--------------------------------------------------------------------------------
/images/assets/boilerplate_loggedout.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/boilerplate_loggedout.png
--------------------------------------------------------------------------------
/images/assets/boilerplate_singleton.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/boilerplate_singleton.png
--------------------------------------------------------------------------------
/images/assets/tutorial-plus-button.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-plus-button.png
--------------------------------------------------------------------------------
/install:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | npm install && (cd _api-reference-generator && npm install) &&
4 | mkdir -p _api-reference-generator/data && cd ..
5 |
6 |
--------------------------------------------------------------------------------
/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 | "extends": "apostrophe",
3 | "ignorePatterns": [
4 | "**/node_modules",
5 | "**/public/modules",
6 | "!/docs/**"
7 | ]
8 | }
--------------------------------------------------------------------------------
/docs/.vuepress/public/images/apos-dark.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/docs/.vuepress/public/images/apos-dark.png
--------------------------------------------------------------------------------
/images/assets/ezgif.com-video-to-gif-1.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/ezgif.com-video-to-gif-1.gif
--------------------------------------------------------------------------------
/images/assets/ezgif.com-video-to-gif.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/ezgif.com-video-to-gif.gif
--------------------------------------------------------------------------------
/images/assets/tutorial-images-library.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-images-library.png
--------------------------------------------------------------------------------
/images/assets/tutorial-select-images.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-select-images.png
--------------------------------------------------------------------------------
/images/assets/user-group-permissions.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/user-group-permissions.png
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/server-apostrophe-polymorphic-manager-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager-cursor (server)
2 |
3 |
--------------------------------------------------------------------------------
/images/assets/tutorial-rich-text-editor.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/tutorial-rich-text-editor.png
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/server-apostrophe-users-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users-cursor (server)
2 |
3 | ## Methods
4 | ### singleGroup(*value*)
5 |
6 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-csrf.md:
--------------------------------------------------------------------------------
1 | # apostrophe-csrf
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 |
4 | ## Methods
5 | ### enableMiddleware()
6 |
7 |
--------------------------------------------------------------------------------
/images/assets/technical-overview-apostrophe-doc-types.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/technical-overview-apostrophe-doc-types.png
--------------------------------------------------------------------------------
/images/assets/technical-overview-apostrophe-on-the-page.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/apostrophecms/apostrophe-documentation/main/images/assets/technical-overview-apostrophe-on-the-page.png
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/browser-apostrophe-files.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files (browser)
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/browser-apostrophe-pieces.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-login/browser-apostrophe-login.md:
--------------------------------------------------------------------------------
1 | # apostrophe-login (browser)
2 |
3 | ## Methods
4 | ### resetKnownPassword()
5 |
6 | ### enableResetKnownPassword()
7 |
8 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/browser-apostrophe-groups.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups (browser)
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/browser-apostrophe-pieces.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images (browser)
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/browser-apostrophe-pieces.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/README.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-html-widgets/browser-apostrophe-html-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-html-widgets (browser)
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/browser-apostrophe-widgets.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-search/browser-apostrophe-search.md:
--------------------------------------------------------------------------------
1 | # apostrophe-search (browser)
2 | ## Inherits from: [apostrophe-custom-pages](../apostrophe-custom-pages/browser-apostrophe-custom-pages.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-widgets (browser)
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/browser-apostrophe-widgets.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/browser-apostrophe-tags-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/browser-apostrophe-files-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/browser-apostrophe-global-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/browser-apostrophe-groups-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pages/browser-apostrophe-pages-editor-copy.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pages-editor-copy (browser)
2 | ## Inherits from: [apostrophe-pages-editor](../apostrophe-pages/browser-apostrophe-pages-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/browser-apostrophe-users-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/README.md)
3 | ### `apos.files`
4 |
5 | ## Methods
6 | ### addUrls(*req*, *files*, *callback*)
7 |
8 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pages/browser-apostrophe-pages-editor-update.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pages-editor-update (browser)
2 | ## Inherits from: [apostrophe-pages-editor](../apostrophe-pages/browser-apostrophe-pages-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-pages/browser-apostrophe-pieces-pages.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-pages (browser)
2 | ## Inherits from: [apostrophe-custom-pages](../apostrophe-custom-pages/browser-apostrophe-custom-pages.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/browser-apostrophe-users.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users (browser)
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/browser-apostrophe-pieces.md)
3 |
4 | ## Methods
5 | ### clickHandlers()
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files-widgets/browser-apostrophe-files-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-widgets (browser)
2 | ## Inherits from: [apostrophe-pieces-widgets](../apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/browser-apostrophe-tags-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-custom-pages/browser-apostrophe-custom-pages.md:
--------------------------------------------------------------------------------
1 | # apostrophe-custom-pages (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/browser-apostrophe-global-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/browser-apostrophe-groups-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-html-widgets/browser-apostrophe-html-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-html-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-widgets-editor](../apostrophe-widgets/browser-apostrophe-widgets-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-search/browser-apostrophe-search-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-search-chooser (browser)
2 | ## Inherits from: [apostrophe-custom-pages-chooser](../apostrophe-custom-pages/browser-apostrophe-custom-pages-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-video-widgets/browser-apostrophe-video-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-video-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-widgets-editor](../apostrophe-widgets/browser-apostrophe-widgets-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/browser-apostrophe-files-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-manager-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-manager-modal](../apostrophe-pieces/browser-apostrophe-pieces-manager-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/browser-apostrophe-global-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global-manager-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-manager-modal](../apostrophe-pieces/browser-apostrophe-pieces-manager-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/browser-apostrophe-groups-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups-manager-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-manager-modal](../apostrophe-pieces/browser-apostrophe-pieces-manager-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/browser-apostrophe-users-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users-manager-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-manager-modal](../apostrophe-pieces/browser-apostrophe-pieces-manager-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/browser-apostrophe-pieces-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-chooser (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-chooser](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-modal/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-modal
2 | ## Inherits from: [apostrophe-module](../apostrophe-module/README.md)
3 | This module provides a base class for modal dialog boxes and supplies
4 | related markup and LESS files.
5 |
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/browser-apostrophe-tags.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### enableClickHandlers()
6 |
7 | ### manage()
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/browser-apostrophe-global.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global (browser)
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/browser-apostrophe-pieces.md)
3 |
4 | ## Methods
5 | ### manage()
6 |
7 | ### addClickHandlers()
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-pages/browser-apostrophe-pieces-pages-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-pages-chooser (browser)
2 | ## Inherits from: [apostrophe-custom-pages-chooser](../apostrophe-custom-pages/browser-apostrophe-custom-pages-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/browser-apostrophe-polymorphic-manager.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files-widgets/browser-apostrophe-files-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-widgets-editor](../apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/browser-apostrophe-files-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-relationship-editor](../apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/browser-apostrophe-tags-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-relationship-editor](../apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/browser-apostrophe-users-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-relationship-editor](../apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-custom-pages/browser-apostrophe-custom-pages-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-custom-pages-chooser (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-chooser](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-chooser.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-global/browser-apostrophe-global-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-global-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-relationship-editor](../apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/browser-apostrophe-groups-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-relationship-editor](../apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-doc-type-manager-manager-modal (browser)
2 | ## Inherits from: [apostrophe-module-manager-modal](../apostrophe-module/browser-apostrophe-module-manager-modal.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-video-widgets/browser-apostrophe-video-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-video-widgets (browser)
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/browser-apostrophe-widgets.md)
3 |
4 | ## Methods
5 | ### play(*$widget*, *data*, *options*)
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-search/browser-apostrophe-search-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-search-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-custom-pages-relationship-editor](../apostrophe-custom-pages/browser-apostrophe-custom-pages-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/browser-apostrophe-pieces-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-relationship-editor](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-pages/browser-apostrophe-pieces-pages-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-pages-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-custom-pages-relationship-editor](../apostrophe-custom-pages/browser-apostrophe-custom-pages-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/core-concepts/apostrophe-search/README.md:
--------------------------------------------------------------------------------
1 | # Apostrophe Search
2 |
3 | Site search is an important tool to help your users find the information they need. Apostrophe provides built in powerful site search to maximize your users' experience.
4 |
5 | * [Enabling Search](/core-concepts/apostrophe-search/search.md)
6 |
--------------------------------------------------------------------------------
/docs/reference/README.md:
--------------------------------------------------------------------------------
1 | # Reference
2 |
3 | - [Glossary](glossary.md)
4 | - [Schema Field Types](field-types/)
5 | - [Schema Field Properties](field-properties/)
6 | - [Apostrophe core object, browser-side](core-browser.md)
7 | - [Apostrophe core object, server-side](core-server.md)
8 | - [Module Reference](modules/)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images-widgets/browser-apostrophe-images-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-pieces-widgets-editor](../apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets-editor.md)
3 |
4 | ## Methods
5 | ### beforeShow(*callback*)
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-custom-pages/browser-apostrophe-custom-pages-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-custom-pages-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-relationship-editor](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/_api-reference-generator/lib/modules/documentation/views/scripts.html:
--------------------------------------------------------------------------------
1 | {{ apos.assets.scripts(data.when) }}
2 |
9 |
--------------------------------------------------------------------------------
/docs/advanced-topics/promise-events/README.md:
--------------------------------------------------------------------------------
1 | # Custom Server-side Event Handlers with Promise Events
2 |
3 | Promise Events are how Apostrophe enables you to create custom events and add more dynamic elements to your site.
4 |
5 | * [Custom Server-side Event Handlers with Promise Events](/advanced-topics/promise-events/promise-events.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-any-page-manager/browser-apostrophe-any-page-manager-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-any-page-manager-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-relationship-editor](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### retrieve(*callback*)
6 |
7 | ### edit()
8 |
9 | ### crop()
10 |
11 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/browser-apostrophe-polymorphic-manager-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager-chooser (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-chooser](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-chooser.md)
3 |
4 | ## Methods
5 | ### launchBrowser()
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/browser-apostrophe-polymorphic-manager-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-relationship-editor](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-relationship-editor.md)
3 |
4 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-relationship-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-doc-type-manager-relationship-editor (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 |
4 | ## Methods
5 | ### beforeShow(*callback*)
6 |
7 | ### saveContent(*callback*)
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-any-page-manager/browser-apostrophe-any-page-manager-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-any-page-manager-chooser (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager-chooser](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-chooser.md)
3 |
4 | ## Methods
5 | ### decorateManager(*manager*, *options*)
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-any-page-manager/browser-apostrophe-any-page-manager.md:
--------------------------------------------------------------------------------
1 | # apostrophe-any-page-manager (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md)
3 |
4 | ## Methods
5 | ### getTool(*name*, *options*, *callback*)
6 |
7 | ### getToolType(*name*)
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-doc-type-manager/server-apostrophe-doc-type-manager-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-doc-type-manager-cursor (server)
2 | Cursor for fetching docs of this specific type. The `afterConstruct`
3 | method locks the results down to this type by calling the
4 | `self.type` filter for us. Subclasses frequently add new filters.
5 |
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files-widgets/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-widgets
2 | ## Inherits from: [apostrophe-pieces-widgets](../apostrophe-pieces-widgets/README.md)
3 | Provides widgets for downloading PDF files and other files that have been
4 | uploaded to the file library provided by [apostrophe-files](/reference/modules/apostrophe-files).
5 |
6 |
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-launder.md:
--------------------------------------------------------------------------------
1 | # apostrophe-launder
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | This module attaches an instance of the [launder](https://npmjs.org/package/launder)
4 | npm module as `apos.launder`. The `apos.launder` object is then used throughout
5 | Apostrophe to sanitize user input.
6 |
7 |
8 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-widgets-editor](../apostrophe-widgets/browser-apostrophe-widgets-editor.md)
3 |
4 | ## Methods
5 | ### shouldSkipModal()
6 |
7 | ### beforeShow(*callback*)
8 |
9 | ### afterShow()
10 |
11 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pages-topics/README.md:
--------------------------------------------------------------------------------
1 | # Advanced Pages Topics
2 |
3 | In this section, you'll learn more about using custom schemas in pages.
4 |
5 | * [Custom Schemas for Pages](/advanced-topics/advanced-pages-topics/custom-schema-fields-for-pages.md)
6 | * [Accessing the children of joined pages](/advanced-topics/advanced-pages-topics/children-and-joins.md)
7 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-service-bridge.md:
--------------------------------------------------------------------------------
1 | # apostrophe-service-bridge
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | This module is always the last module loaded by default by Apostrophe,
4 | before any modules added by the user. It invokes the
5 | `servicesReady` method of all modules that have one. This may
6 | optionally take a callback.
7 |
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-soft-redirects.md:
--------------------------------------------------------------------------------
1 | # apostrophe-soft-redirects
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 |
4 | ## Methods
5 | ### ensureIndexes(*callback*)
6 |
7 | ### pageNotFound(*req*, *callback*)
8 |
9 | ### pageBeforeSend(*req*, *callback*)
10 |
11 | ### local(*url*)
12 | Remove any protocol, // and host/port/auth from URL
13 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images-focal-point-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-focal-point-editor (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 | Interface between the image chooser and the attachment focal point editor.
4 |
5 |
6 | ## Methods
7 | ### retrieve(*callback*)
8 |
9 | ### edit()
10 |
11 |
--------------------------------------------------------------------------------
/docs/core-concepts/front-end-assets/README.md:
--------------------------------------------------------------------------------
1 | # Front End Assets
2 |
3 | In order to have anything other than a plain, generic site, you'll need to use stylesheets and other assets to provide the backbone for your look and feel.
4 |
5 | * [Pushing assets to the browser](/core-concepts/front-end-assets/pushing-assets.md)
6 | * [Lean frontend assets: Apostrophe without jQuery](/core-concepts/front-end-assets/lean-frontend-assets.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-browser-utils/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-browser-utils
2 | ## Inherits from: [apostrophe-module](../apostrophe-module/README.md)
3 | Pushes utility methods to the browser as the `apos.utils` singleton. This module
4 | is separate from [apostrophe-utils](/reference/modules/apostrophe-utils) because that
5 | module is initialized very early, before it is possible to push assets to the browser.
6 |
7 |
8 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-admin-bar/browser-apostrophe-admin-bar.md:
--------------------------------------------------------------------------------
1 | # apostrophe-admin-bar (browser)
2 |
3 | ## Methods
4 | ### link(*name*, *callback*)
5 | When the specified admin bar item is clicked, call the specified function
6 | ### enhance()
7 | Implement the admin bar's toggle behavior and graceful close of dropdowns at
8 | appropriate times.
9 | ### collapse(*$bar*)
10 |
11 | ### autoCollapse(*$bar*)
12 |
13 |
--------------------------------------------------------------------------------
/docs/core-concepts/global-settings/README.md:
--------------------------------------------------------------------------------
1 | # Global Settings
2 |
3 | In Apostrophe, aspects of what you do will be limited to a single pages, while other aspects will need to be part of the every page on the site. Global settings are how you manage items which are meant for the entire site.
4 |
5 | * [Global Settings](/core-concepts/global-settings/settings.md)
6 | * [Sharing Content Across Pages](/core-concepts/global-settings/global.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images-widgets/browser-apostrophe-images-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-widgets (browser)
2 | ## Inherits from: [apostrophe-pieces-widgets](../apostrophe-pieces-widgets/browser-apostrophe-pieces-widgets.md)
3 | example of a widget manager with a play method.
4 | You don't need this file at all if you
5 | don't need a player.
6 |
7 |
8 | ## Methods
9 | ### play(*$widget*, *data*, *options*)
10 |
11 |
--------------------------------------------------------------------------------
/docs/devops/README.md:
--------------------------------------------------------------------------------
1 | # DevOps
2 |
3 | DevOps describes the tasks where the lines between the developer and operations or system administration is blurred. In this section, you'll find guides for deploying and setting Apostrophe up for various platforms.
4 |
5 | - [Deploying Apostrophe for Production](deployment/)
6 | - [Sending Email from your Apostrophe Project](email.md)
7 | - [Running Apostrophe on Multiple Cores and/or Servers](multicore.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/browser-apostrophe-pieces-batch-permissions-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-batch-permissions-modal (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 | A modal for selecting permissions to be applied to a batch of pieces
4 |
5 |
6 | ## Methods
7 | ### beforeShow(*callback*)
8 |
9 | ### saveContent(*callback*)
10 |
11 | ### afterHide()
12 |
13 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-versions/browser-apostrophe-versions-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-versions-editor (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 | A modal that displays a list of past versions and allows the user
4 | to explore changes and commit to rolling back to a particular previous
5 | version of a doc.
6 |
7 |
8 | ## Methods
9 | ### beforeShow(*callback*)
10 |
11 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-manager-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-manager-modal](../apostrophe-pieces/browser-apostrophe-pieces-manager-modal.md)
3 | Image Gallery
4 |
5 |
6 | ## Methods
7 | ### enableButtonEvents()
8 |
9 | ### focusElement(*$el*)
10 |
11 | ### afterRefresh()
12 |
13 | ### displayChoiceInCheckbox(*id*, *state*)
14 |
15 |
--------------------------------------------------------------------------------
/docs/howtos/how-do-i-create-a-404-not-found-page.md:
--------------------------------------------------------------------------------
1 | # How do I create a 404 Not Found page?
2 |
3 | To get 404 not found pages to display (instead of an error saying you don't have one), just create:
4 |
5 | ```
6 | lib/modules/apostrophe-pages/views/notFound.html
7 | ```
8 |
9 | Which works just like any page template; just remember that of course
10 | there is no `data.page`. If you want user-editable content there use
11 | `data.global`.
12 |
--------------------------------------------------------------------------------
/docs/reference/field-properties/options.md:
--------------------------------------------------------------------------------
1 | # `options`
2 |
3 | The `options` property contains additional configuration for configuring a widget `area`.
4 |
5 | ## `widgets`
6 |
7 | The main tag inside of `options` is `widget`. The `widget` tag contains a list of widgets and their configuration. For more information about the configuration for commonly used widgets, see the [Standard Widgets article](/core-concepts/editable-content-on-pages/standard-widgets.md).
8 |
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/server-apostrophe-pieces-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-cursor (server)
2 | Cursor for fetching pieces.
3 |
4 | ## Options
5 |
6 | *Note that `find` does not take an options argument. Instead these
7 | options are usually configured in subclasses or their `beforeConstruct` methods.*
8 |
9 | ### `sort`
10 | The default sort. Defaults to:
11 |
12 | ```javascript
13 | {
14 | updatedAt: -1
15 | }
16 | ```
17 |
18 |
19 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-chooser (browser)
2 | ## Inherits from: [apostrophe-pieces-chooser](../apostrophe-pieces/browser-apostrophe-pieces-chooser.md)
3 | When choosing images, autocomplete by title is not a sensible primary
4 | interface; let them go straight to the browse button and just use the
5 | chooser to edit existing selections
6 |
7 |
8 | ## Methods
9 | ### finalize(*callback*)
10 |
11 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-jobs/browser-apostrophe-jobs-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-jobs-modal (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 | A modal for importing pieces
4 |
5 |
6 | ## Methods
7 | ### beforeShow(*callback*)
8 |
9 | ### startProgress()
10 |
11 | ### updateProgress()
12 |
13 | ### afterHide()
14 |
15 | ### beforeCancel(*callback*)
16 |
17 | ### halt()
18 |
19 | ### enableJobCancel()
20 |
21 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-custom-pages/server-apostrophe-custom-pages-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-custom-pages-cursor (server)
2 | Cursor for fetching docs of this specific type. The `afterConstruct`
3 | method locks the results down to this type by calling the
4 | `self.type` filter for us. Subclasses frequently add new filters.
5 |
6 | We subclass `apostrophe-pages-cursor` so that cursors for page types
7 | are able to use `.children()`, `.ancestors()`, etc.
8 |
9 |
10 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-widgets/browser-apostrophe-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-widgets-editor (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 |
4 | ## Methods
5 | ### saveContent(*callback*)
6 |
7 | ### beforeSave(*callback*)
8 |
9 | ### beforeShow(*callback*)
10 |
11 | ### afterShow()
12 | Wait for afterShow to do things that might pop more modals
13 | ### getData()
14 |
15 | ### onChange(*e*)
16 |
17 |
--------------------------------------------------------------------------------
/docs/core-concepts/README.md:
--------------------------------------------------------------------------------
1 | # Core Concepts
2 |
3 | - [Technical Overview](technical-overview.md)
4 | - [Pages and Navigation](pages-and-navigation/)
5 | - [Widgets](editable-content-on-pages/)
6 | - [Pieces](reusable-content-pieces/)
7 | - [Global Settings](global-settings/)
8 | - [Modules](modules/)
9 | - [Front End Assets](front-end-assets/)
10 | - [Users and Permissions](users-and-permissions/)
11 | - [Working with Templates](working-with-templates/)
12 | - [Search](apostrophe-search/)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images-widgets/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-widgets
2 | ## Inherits from: [apostrophe-pieces-widgets](../apostrophe-pieces-widgets/README.md)
3 | Implements widgets that display single images and slideshows.
4 |
5 | See [adding editable content to pages](/core-concepts/editable-content-on-pages/standard-widgets.md#apostrophe-images) for a thorough discussion of the options that can be passed to the widget.
6 |
7 |
8 | ## Methods
9 | ### pushAssets()
10 |
11 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pager.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pager
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | ### `apos.pager`
4 | Provides markup, a Nunjucks helper and styles for a simple pager,
5 | used for pagination both on the front end and the back end.
6 |
7 |
8 | ## Nunjucks template helpers
9 | ### pageRange(*options*)
10 | Generate the right range of page numbers to display in the pager.
11 | Just a little too much math to be comfortable in pure Nunjucks
12 |
--------------------------------------------------------------------------------
/_api-reference-generator/lib/modules/documentation/phantomjs-print-definitions.js:
--------------------------------------------------------------------------------
1 | /* eslint-disable no-console */
2 | const page = require('webpage').create();
3 | const url = 'http://localhost:3000/modules/documentation/scripts';
4 | page.onConsoleMessage = function(msg, lineNum, sourceId) {
5 | console.log(msg);
6 | };
7 | page.open(url, function (status) {
8 | if (status !== 'success') {
9 | throw status;
10 | }
11 | setTimeout(function() {
12 | window.phantom.exit();
13 | }, 5000);
14 | });
15 |
--------------------------------------------------------------------------------
/docs/devops/cloud/README.md:
--------------------------------------------------------------------------------
1 | # Storing Apostrophe Images and Files in the Cloud
2 |
3 | Most Apostrophe deployments won't rely on a local data store, but will instead use cloud services. Here we have provided instructions for integration with some popular services.
4 |
5 | * [Amazon S3](/devops/cloud/storing-images-and-files-in-amazon-s3.md)
6 | * [Azure Blob Storage](/devops/cloud/storing-images-and-files-in-azure-blob-storage.md)
7 | * [Google Cloud Storage](/devops/cloud/storing-images-and-files-in-google-cloud-storage.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/browser-apostrophe-tags-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags-manager-modal (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 |
4 | ## Methods
5 | ### beforeShow(*callback*)
6 |
7 | ### addClickHandlers()
8 |
9 | ### refresh(*callback*)
10 |
11 | ### add(*$el*)
12 |
13 | ### edit(*$el*, *value*)
14 |
15 | ### rename(*$el*, *value*)
16 |
17 | ### delete(*$el*, *value*)
18 |
19 | ### beforeRefresh(*options*)
20 |
21 | ### afterRefresh()
22 |
23 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-files/browser-apostrophe-files-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-files-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 |
4 | ## Methods
5 | ### beforeShow(*callback*)
6 |
7 | ### enableTitleFromAttachment()
8 | If the attachment is updated and the title field has not yet been set,
9 | set it based on the filename
10 | ### titleFromAttachmentListener(*info*)
11 | This event listener implements updating the title from the attachment's name
12 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-html-widgets/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-html-widgets
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/README.md)
3 | Provides the "raw HTML widget" (the `apostrophe-html` widget).
4 | Use of this widget is not recommended if it can be avoided. The
5 | improper use of HTML can easily break pages. If a page becomes
6 | unusable, add `?safe_mode=1` to the URL to make it work temporarily
7 | without the offending code being rendered.
8 |
9 |
10 | ## Methods
11 | ### addHelper()
12 |
13 | ### safeRender(*code*)
14 |
15 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/browser-apostrophe-images-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 |
4 | ## Methods
5 | ### beforeShow(*callback*)
6 |
7 | ### enableTitleFromAttachment()
8 | If the attachment is updated and the title field has not yet been set,
9 | set it based on the filename
10 | ### titleFromAttachmentListener(*info*)
11 | This event listener implements updating the title from the attachment's name
12 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-versions/browser-apostrophe-versions.md:
--------------------------------------------------------------------------------
1 | # apostrophe-versions (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 | A singleton that provides a jQuery click handler to open the
4 | version editor when [data-apos-versions-page="id"] is clicked,
5 | and also an `edit` method to be invoked by
6 | [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md).
7 |
8 |
9 | ## Methods
10 | ### addLinks()
11 |
12 | ### edit(*id*, *afterRevert*)
13 |
14 |
--------------------------------------------------------------------------------
/_api-reference-generator/.gitignore:
--------------------------------------------------------------------------------
1 | locales
2 | npm-debug.log
3 | data/*
4 | public/uploads
5 | public/apos-minified
6 | public/js/_site-compiled.js
7 | temp/uploadfs
8 | node_modules
9 | # This folder is created on the fly and contains symlinks updated at startup (we'll come up with a Windows solution that actually copies things)
10 | public/modules
11 | # We don't commit CSS, only LESS
12 | public/css/*.css
13 | # Don't commit masters generated on the fly at startup, these import all the rest
14 | public/css/master-*.less
15 | .jshintrc
16 | .DS_Store
17 | *.DS_Store
18 |
--------------------------------------------------------------------------------
/generate:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | (
4 | cd _api-reference-generator/ &&
5 | echo "Removing existing modules references..."
6 | rm -rf ../docs/reference/modules/ &&
7 | # Not optional, we need to be documenting the latest published release
8 | echo "Updating generator packages..."
9 | npm update &&
10 | echo "Running generator tasks..."
11 | node app apostrophe:generation &&
12 | node app documentation:generate &&
13 | echo "Copying in the modules landing page..."
14 | cat ../_tip-ins/modules.md > ../docs/reference/modules/README.md
15 | ) &&
16 | echo "Done!"
17 |
--------------------------------------------------------------------------------
/docs/core-concepts/editable-content-on-pages/README.md:
--------------------------------------------------------------------------------
1 | # Editable Content on Pages with Widgets
2 |
3 | Once you have a page, you need to give that page a purpose. In Apostrophe, whatever that purpose is, you can accopmlish it with Widgets. In Apostrophe you have several kinds of widgets to use, and you can create your own widgets as well.
4 |
5 | * [Standard widgets](/core-concepts/editable-content-on-pages/standard-widgets.md)
6 | * [Custom widgets](/core-concepts/editable-content-on-pages/custom-widgets.md)
7 | * [Layout / Nested widgets](/core-concepts/editable-content-on-pages/layout-widgets.md)
--------------------------------------------------------------------------------
/docs/core-concepts/modules/README.md:
--------------------------------------------------------------------------------
1 | # Modules
2 |
3 | Each aspect of Apostrophe is divided into its own module. Pages, widgets, assets, and anything else are all divided into their own modules and loaded separately. For more information on how module loading works, you can read about it in [How Apostrophe Starts Up](/advanced-topics/how-apostrophe-starts-up.md).
4 |
5 | * [How Apostrophe Modules are Structured](/core-concepts/modules/how-apostrophe-modules-are-structured.md)
6 | * [Nested Module Folders](/core-concepts/modules/nested-module-folders.md)
7 | * [More Modules](/core-concepts/modules/more-modules.md)
--------------------------------------------------------------------------------
/_api-reference-generator/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "apostrophe-reference-generator",
3 | "version": "0.1.0",
4 | "description": "",
5 | "main": "app.js",
6 | "private": true,
7 | "scripts": {
8 | "test": "echo \"Error: no test specified\" && exit 1"
9 | },
10 | "author": "",
11 | "license": "MIT",
12 | "dependencies": {
13 | "apostrophe": "^2.220.7",
14 | "async": "^2.6.3",
15 | "boring": "^0.1.0",
16 | "glob": "^7.2.0",
17 | "js-tokenizer": "^1.3.3",
18 | "lodash": "^4.17.21",
19 | "mkdirp": "^1.x",
20 | "phantomjs-prebuilt": "^2.1.16"
21 | }
22 | }
23 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-attachments/browser-apostrophe-attachments-crop-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-attachments-crop-editor (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 |
4 | ## Methods
5 | ### afterShow()
6 | Use afterShow so that .width() works
7 | ### initCropper()
8 |
9 | ### testMinimumSize(*e*)
10 |
11 | ### zoom(*e*)
12 |
13 | ### getCropperData()
14 |
15 | ### saveContent(*callback*)
16 |
17 | ### scaleDown(*coord*)
18 |
19 | ### scaleUp(*coord*)
20 |
21 | ### deserializeCrop(*data*)
22 |
23 | ### serializeCrop(*data*)
24 |
25 | ### busy(*state*)
26 |
27 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-video-fields/browser-apostrophe-video-fields.md:
--------------------------------------------------------------------------------
1 | # apostrophe-video-fields (browser)
2 |
3 | ## Methods
4 | ### addFieldType()
5 |
6 | ### populate(*object*, *name*, *$field*, *$el*, *field*, *callback*)
7 |
8 | ### convert(*data*, *name*, *$field*, *$el*, *field*, *callback*)
9 |
10 | ### preview(*$fieldset*, *value*, *field*)
11 | Preview the given value. Also acts as a validator by updating
12 | the `valid` jquery data attribute of the fieldset to true or false
13 | after it clears the `busy` attribute.
14 | ### debouncePreview()
15 |
16 | ### preview(*$fieldset*, *value*, *field*)
17 |
18 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-ui/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-ui
2 | ## Inherits from: [apostrophe-module](../apostrophe-module/README.md)
3 | Provides the [apos.ui](/reference/modules/apostrophe-ui/browser-apostrophe-ui.md) singleton on the browser side, which
4 | implements various general purpose UI features for Apostrophe sites, and also
5 | the [apostrophe-context](/reference/modules/apostrophe-utils/browser-apostrophe-context.md) base class on the browser side,
6 | which is the base class of modals and of other types that benefit from being
7 | able to make API calls conveniently via `self.action` and link click handlers based on
8 | `self.$el`.
9 |
10 |
11 |
--------------------------------------------------------------------------------
/docs/core-concepts/working-with-templates/README.md:
--------------------------------------------------------------------------------
1 | # Working with Templates
2 |
3 | Apostrophe using Nunjucks to supercharge your HTML and provide dynamic and responsive capabilities to your pages.
4 |
5 | * [Data Available in Templates](/core-concepts/working-with-templates/data-properties.md)
6 | * [Nunjucks Filters](/core-concepts/working-with-templates/nunjucks-filters.md)
7 | * [Nunjucks Helper Functions](/core-concepts/working-with-templates/nunjucks-helper-functions.md)
8 | * [Accessing images inside related pages](/core-concepts/working-with-templates/thumbnails-and-areas-of-child-pages.md)
9 | * [Responsive Images](/core-concepts/working-with-templates/responsive-images.md)
--------------------------------------------------------------------------------
/docs/core-concepts/pages-and-navigation/README.md:
--------------------------------------------------------------------------------
1 | # Pages and Navigation
2 |
3 | At its root, any website is a series of pages, containing content and applications, connected through navigation. Maybe a site is a single page with a blog, or maybe it's 100s of complex pages integrated with a web application for online shopping. Either way, it all starts with pages, and how use them to connect users with content.
4 |
5 | * [Page Templates](/core-concepts/pages-and-navigation/page-templates.md)
6 | * [Widgets, Singletons, and Areas](/core-concepts/pages-and-navigation/widgets-singletons-and-areas.md)
7 | * [Connecting Pages with Navigation](/core-concepts/pages-and-navigation/connecting-pages.md)
--------------------------------------------------------------------------------
/docs/devops/deployment/README.md:
--------------------------------------------------------------------------------
1 | # Deploying Apostrophe for Production
2 |
3 | There are a number of different options for deploying Apostrophe, whether hosting on your own system or using various hosting providers. This section provides instructions on getting set up with some popular options.
4 |
5 | * [Hosting Apostrophe in Production](/devops/deployment/deployment.md)
6 | * [Deploying Apostrophe in the Cloud with Heroku](/devops/deployment/deploying-apostrophe-in-the-cloud-with-heroku.md)
7 | * [Deploying Apostrophe with AWS and Elastic Beanstalk](/devops/deployment/deploying-apostrophe-in-the-cloud-with-aws.md)
8 | * [Deploying Apostrophe to a Linode Linux Server](/devops/deployment/linode.md)
--------------------------------------------------------------------------------
/deploy:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | if [ -z "$ENV" ]; then
4 | echo "💁♀️ Usage: ENV=staging npm run deploy"
5 | echo "(or as appropriate)"
6 | echo
7 | rm -r ./dist
8 | exit 1
9 | fi
10 |
11 | read -p "THIS WILL CRUSH THE SITE'S CONTENT ON $ENV. Are you sure? " -n 1 -r
12 | echo
13 | if [[ ! $REPLY =~ ^[Yy]$ ]]
14 | then
15 | exit 1
16 | fi
17 |
18 | if [ $ENV == "staging" ]
19 | then
20 | ipAddress=34.207.22.194
21 | elif [ $ENV == "production" ]
22 | then
23 | ipAddress=100.24.96.198
24 | else
25 | echo "🤷♀️ Target unknown"
26 | exit 1
27 | fi
28 |
29 | rsync -av --delete --exclude '.git' --exclude '**/node_modules' ./ nodeapps@$ipAddress:/opt/static/apos-docs &&
30 | echo "Synced up to $ENV"
31 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-attachments/browser-apostrophe-attachments-focal-point-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-attachments-focal-point-editor (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 |
4 | ## Methods
5 | ### afterShow()
6 | Use afterShow so that imagesReady and width() work
7 | ### click(*event*)
8 | jQuery event handler for clicks on the image,
9 | which updates the focal point.
10 | ### saveContent(*callback*)
11 |
12 | ### render()
13 |
14 | ### scaleToAbsoluteX(*percentage*)
15 |
16 | ### scaleToAbsoluteY(*percentage*)
17 |
18 | ### scaleToPercentageX(*absolute*)
19 |
20 | ### scaleToPercentageY(*absolute*)
21 |
22 | ### busy(*state*)
23 |
24 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/permissions-for-pieces.md:
--------------------------------------------------------------------------------
1 | # Fine-grained Permissions for Pieces
2 |
3 | In our [Permissions section](/core-concepts/users-and-permissions/README.md), you can learn more about managing permissions for pages with options like "Login Required," or to "Certain People", and so on. This feature is also available for pieces. By default, it is disabled because it is not used as often.
4 |
5 | To enable it for your module, just set `permissionsFields: true` in `lib/modules/people/index.js`:
6 |
7 | ```javascript
8 | // lib/modules/your-piece/index.js
9 | module.exports = {
10 | extend: 'apostrophe-pieces',
11 | permissionsFields: true,
12 | // ... other settings ...
13 | };
14 | ```
15 |
--------------------------------------------------------------------------------
/docs/core-concepts/reusable-content-pieces/README.md:
--------------------------------------------------------------------------------
1 | # Pieces in Apostrophe
2 |
3 | Pieces are a powerful tool provided by Apostrophe. You can use them to create dynamic content or content based web applications. Many of Apostrophe's most powerful content management features are based around pieces, so read on to learn more.
4 |
5 | * [Reusable content with pieces](/core-concepts/reusable-content-pieces/reusable-content-with-pieces.md)
6 | * [Displaying Pieces With Widgets](/core-concepts/reusable-content-pieces/displaying-pieces-with-widgets.md)
7 | * [Browsing a Directory of Pieces](/core-concepts/reusable-content-pieces/browsing-directory-of-pieces.md)
8 | * [Joins: Connecting Piece Types to One Another](/core-concepts/reusable-content-pieces/joins.md)
9 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-rich-text-widgets/browser-apostrophe-rich-text-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-rich-text-widgets (browser)
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/browser-apostrophe-widgets.md)
3 |
4 | ## Methods
5 | ### getData(*$widget*)
6 |
7 | ### edit(*data*, *options*, *save*)
8 |
9 | ### startEditing(*$widget*)
10 | does not use a modal, start and stop editing
11 | contextually via ckeditor instead
12 | ### stopEditing(*$widget*)
13 |
14 | ### play(*$widget*, *data*, *options*)
15 | If we're logged in, rich text has a "player"
16 | to implement the "click to start editing" behavior
17 | ### isEmpty(*$widget*)
18 | Area editor calls this to determine whether to apply an empty state
19 | class for the widget
20 |
--------------------------------------------------------------------------------
/docs/advanced-topics/database/README.md:
--------------------------------------------------------------------------------
1 | # Apostrophe Database Operations
2 |
3 | At the root of any data you create and store in Apostophe is the database. Apostrophe uses MongoDB, and there are a number of direct and indirect options to access and use the database to unlock the full power and potential of Apostrophe.
4 |
5 | * [Apostrophe's model layer: working with the database](/advanced-topics/database/model-layer.md)
6 | * [Working with cursors](/advanced-topics/database/cursors.md)
7 | * [Accessing the database directly](/advanced-topics/database/accessing-the-database-directly.md)
8 | * [Writing database migrations](/advanced-topics/database/migrations.md)
9 | * [Using MongoDB replica sets with Apostrophe](/advanced-topics/database/replica-set.md)
10 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md:
--------------------------------------------------------------------------------
1 | # apostrophe-doc-type-manager (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### getTool(*name*, *options*, *callback*)
6 | Fetch a related tool such as the chooser, manager-modal or editor-modal for this type.
7 |
8 | Return false if no such tool is available.
9 |
10 | Options are merged with the options of this manager.
11 |
12 | Callback argument can be omitted if this tool doesn't require a callback for
13 | constructing new instances.
14 | ### getToolType(*name*)
15 | Figure out the moog type name for a related tool such as the chooser, manager-modal
16 | or editor for this type.
17 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-polymorphic-manager/browser-apostrophe-polymorphic-manager-manager-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-polymorphic-manager-manager-modal (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 | A "chooser" modal for multiple doc types simultaneously.
4 |
5 | Type name is `-manager` so that subclassing doc-type-manager will
6 | automatically gives us plumbing to create one.
7 |
8 |
9 | ## Methods
10 | ### enableChooserViews()
11 |
12 | ### hideOthers()
13 |
14 | ### beforeShow(*callback*)
15 |
16 | ### enableChooser(*callback*)
17 |
18 | ### saveContent(*callback*)
19 |
20 | ### afterHide()
21 |
22 | ### reflectChoicesInCheckboxes()
23 |
24 | ### decorateManager(*manager*, *options*)
25 |
26 |
--------------------------------------------------------------------------------
/docs/advanced-topics/README.md:
--------------------------------------------------------------------------------
1 | # Advanced Topics
2 |
3 | These tutorials cover more advanced topics like working directly with the model layer, creating custom "cursor filters" for use in browsing and fetching data, and deploying Apostrophe sites in production.
4 |
5 | - [Guide to Schemas](schema-guide.md)
6 | - [Advanced Pieces Topics](advanced-pieces-topics/)
7 | - [Advanced Pages Topics](advanced-pages-topics/)
8 | - [How Apostrophe handles requests](how-apostrophe-handles-requests.md)
9 | - [How Apostrophe starts up](how-apostrophe-starts-up.md)
10 | - [Custom Server-side Event Handlers with Promise Events](promise-events)
11 | - [Command Line Tasks](command-line-tasks.md)
12 | - [Internationalization and Localization](apostrophe-i18n-config.md)
13 | - [The Database](database/)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-jobs/browser-apostrophe-jobs.md:
--------------------------------------------------------------------------------
1 | # apostrophe-jobs (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### progress(*jobId*, *options*)
6 | Start a progress display for the given job id.
7 | If `options.change` is set, an `apos.change` call is
8 | made with that argument when the progress display
9 | is dismissed.
10 |
11 | If `options.success` is set, it is
12 | invoked after all items have been processed and
13 | receives the `results` property provided by
14 | the server at the end of the job; it is not invoked
15 | if the operation was stopped or canceled by the user.
16 | Note that `options.success` does not take a callback
17 | because the modal has already been dismissed.
18 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-rich-text-widgets/browser-apostrophe-rich-text-widgets-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-rich-text-widgets-editor (browser)
2 |
3 | ## Methods
4 | ### start()
5 | Start contextual editing (on click for instance)
6 | ### stop()
7 | End contextual editing (on blur for instance)
8 | ### setActive(*state*)
9 | Trigger `aposRichTextActive` or `aposRichTextInactive`
10 | on the widget's DOM element and set or clear the
11 | `apos-active` CSS class. Reflects what has already happened
12 | at the ckeditor level, called on blur and focus events.
13 | Does not start and stop editing, not to be called directly.
14 | ### beforeCkeditorInline()
15 | A convenient override point just before
16 | `self.id` and `self.config` are passed to
17 | `CKEDITOR.inline` to launch editing
18 |
--------------------------------------------------------------------------------
/docs/.vuepress/styles/palette.styl:
--------------------------------------------------------------------------------
1 | // colors
2 | $accentColor ?= #66F
3 | $accentDarkColor ?= desaturate(darken(#66F, 60%), 40%)
4 | $textColor ?= #4D4D4D
5 | // $borderColor ?= #eaecef
6 | // $codeBgColor ?= darken(#4D4D4D, 10%)
7 | $arrowBgColor ?= #BCBCBC
8 | $badgeTipColor ?= #00BF9A
9 | $badgeWarningColor ?= #CC9300
10 | $badgeErrorColor ?= #EB4339
11 |
12 | // // layout
13 | // $navbarHeight ?= 3.6rem
14 | // $sidebarWidth ?= 20rem
15 | // $contentWidth ?= 740px
16 | // $homePageWidth ?= 960px
17 |
18 | // // responsive breakpoints
19 | // $MQNarrow ?= 959px
20 | // $MQMobile ?= 719px
21 | // $MQMobileNarrow ?= 419px
22 |
23 | // // code
24 | // $lineNumbersWrapperWidth ?= 3.5rem
25 | // $codeLang ?= js ts html md vue css sass scss less stylus go java c sh yaml py docker dockerfile makefile
26 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-images/server-apostrophe-images-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-images-cursor (server)
2 |
3 | ## Methods
4 | ### minSize(*value*)
5 |
6 | ### orientation(*value*)
7 | Filter. Get images depending on the
8 | orientation of their attachments. This orientation
9 | is computed during import, comparing width and height.
10 | Accessible programmatically using self.find(req).orientation('square')`.
11 | Available options are: `landscape`, `portrait`, `square`.
12 | ### fileType(*value*)
13 | Filter. Get images depending on their
14 | type, the available images extensions come from
15 | `self.fileGroups` in `apostrophe-attachments`.
16 | Accessible programmatically using self.find(req).fileType('jpg')`.
17 | Available options are: `jpg`, `png`, `gif` and `svg` if `svgImages` is enabled.
18 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-users/browser-apostrophe-users-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-users-editor-modal (browser)
2 | ## Inherits from: [apostrophe-pieces-editor-modal](../apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md)
3 | Edit or create a user. Extends the piece editor to suggest full names based on the
4 | first and last name, suggest usernames based on the full name, and require a password
5 | when creating a new user.
6 |
7 |
8 | ## Methods
9 | ### beforeShow(*callback*)
10 |
11 | ### requirePasswordWhenCreating()
12 |
13 | ### enableTitleViaName()
14 |
15 | ### updateTitleViaName()
16 |
17 | ### enableUsernameViaTitle()
18 |
19 | ### updateUsernameViaTitle()
20 |
21 | ### updateUsernameViaTitleAttempt(*username*)
22 |
23 | ### displayError(*result*)
24 |
25 | ### getErrorMessage(*err*)
26 |
27 |
--------------------------------------------------------------------------------
/docs/core-concepts/users-and-permissions/README.md:
--------------------------------------------------------------------------------
1 | # Users and Permissions
2 |
3 | Once you have the design and content for your site mapped out, you need to define what kind of users your site will have and how they will interact with your site. To do this, you'll learn to use Apostrophe's basic groups to manage permissions, and then to customize groups with more powerful, granular permissions control.
4 |
5 | This section also contains information on setting up Apostrophe Passport for single sign-on capabilities, and information about Apostrophe's password recovery and account lockout features.
6 |
7 | * [Users and Groups](users-and-groups.md)
8 | * [Managing Access Control](managing-access-control.md)
9 | * [Single Sign-On with Apostrophe Passport](apostrophe-passport.md)
10 | * [User Login and Password Help](user-login-and-password.md)
11 |
--------------------------------------------------------------------------------
/docs/core-concepts/users-and-permissions/apostrophe-passport.md:
--------------------------------------------------------------------------------
1 | # Single Sign-On with Apostrophe Passport
2 |
3 | Apostrophe uses Passport to provide single sign-on capabilities. The `apostrophe-passport` module is a "universal bridge" compatible with pretty much all Passport strategies that follow best practices, and allows you to implement login via popular services like Google, Twitter, Facebook, Github, and Gitlab, as well as standards like OpenAuth and SAML. To learn more about Passport in general, see the official site for the [Passport strategy module](http://passportjs.org/).
4 |
5 | ## Using Apostrophe Passport
6 |
7 | Apostrophe Passport is not included with the standard Apostrophe distribution and can be installed via npm. For complete details on how to install and configure Apostrophe Passport, see the [official documentation on npmjs.org](https://npmjs.org/package/apostrophe-passport).
8 |
--------------------------------------------------------------------------------
/_api-reference-generator/app.js:
--------------------------------------------------------------------------------
1 | // This apostrophe app exists solely for use as a command line
2 | // utility; invoke with:
3 | //
4 | // node app documentation:generate
5 | //
6 | // It will listen briefly on port 3000, which must be free,
7 | // in order to use phantomjs to introspect the browser side
8 | // moog types.
9 |
10 | var apos = require('apostrophe')({
11 | shortName: 'api-reference-generator',
12 | modules: {
13 | // Make sure apostrophe-pieces-pages gets activated as a module
14 | // so it's not missing from the docs. This requires we have
15 | // a piece type too
16 | dummies: {
17 | extend: 'apostrophe-pieces',
18 | name: 'dummy',
19 | label: 'Dummy',
20 | pluralLabel: 'Dummies'
21 | },
22 | 'dummies-pages': {
23 | extend: 'apostrophe-pieces-pages'
24 | },
25 | // Documentation generator
26 | documentation: {}
27 | }
28 | });
29 |
--------------------------------------------------------------------------------
/docs/reference/field-types/password.md:
--------------------------------------------------------------------------------
1 | # `password`
2 |
3 | `password` fields are identical to `string` fields except that the user's input is not visible and they do not support the `textarea` or `searchable` properties.
4 |
5 | ## Settings
6 |
7 | | Property | Type | Default | Description |
8 | |---|---|---|---|
9 | |name | `string` | | Sets the name of the field in the database |
10 | |label | `string` | | Sets the label of the field that the user sees |
11 | |required | `boolean` | false | If true, the field is mandatory |
12 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
13 | |type | `string` | | Specifies the field type |
14 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
15 | |help | `string` | | Help text for the field that will appear with the field's label |
16 | |htmlHelp | `string` | | Help text with support for HTML markup |
17 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pages/browser-apostrophe-pages.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pages (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md)
3 | This singleton provides jquery event handlers to trigger various operations
4 | on pages, such as insert, update, reorganize and trash. Most of the logic
5 | lies elsewhere in modals for those particular tasks.
6 |
7 |
8 | ## Methods
9 | ### addLinks()
10 |
11 | ### pageSettings(*options*)
12 | page settings for current page
13 | ### reorganize()
14 | Display UI permitting the user to reorganize the page tree
15 | ### chooserModal(*options*)
16 | options.chooser is required
17 | ### trash(*_id*, *callback*)
18 |
19 | ### rescue(*_id*, *callback*)
20 | Rescue a page from the trash. Currently invoked
21 | only when trashInSchema option is true
22 | ### deleteFromTrash(*_id*, *callback*)
23 | Irrevocably delete something from the trash
24 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-video-fields/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-video-fields
2 | ## Inherits from: [apostrophe-module](../apostrophe-module/README.md)
3 | ### `apos.videoFields`
4 | Implements the ["video" apostrophe schema field type](/reference/field-types/video.md).
5 |
6 | The value of the field is an object with `url`, `title` and `thumbnail` properties, the latter
7 | two being as obtained by `oembetter` at the time the URL was originally pasted and fetched
8 | via the `oembed` protocol.
9 |
10 | This field type is locked down to accept only URLs whose oembed response type
11 | is `video`.
12 |
13 | Videos are not actually hosted or stored by Apostrophe. They are displayed via
14 | oembed-capable third party services like Vimeo and YouTube.
15 |
16 |
17 | ## Methods
18 | ### addFieldType() *[schemaField]*
19 |
20 | ### fieldTypePartial(*data*) *[schemaField]*
21 |
22 | ### pushAssets() *[browser]*
23 |
24 | ### pushCreateSingleton() *[browser]*
25 |
26 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "apostrophe-documentation",
3 | "version": "2.0.0-alpha",
4 | "description": "",
5 | "private": true,
6 | "main": "index.js",
7 | "scripts": {
8 | "dev": "npm run docs:dev",
9 | "docs:dev": "vuepress dev docs",
10 | "docs:build": "vuepress build docs --dest dist",
11 | "build": "npm run docs:build",
12 | "test": "npx eslint .",
13 | "deploy": "npm run build && bash ./deploy && rm -r ./dist",
14 | "generate": "bash ./generate"
15 | },
16 | "author": "Apostrophe Technologies, Inc.",
17 | "license": "MIT",
18 | "devDependencies": {
19 | "eslint": "^7.1.0",
20 | "eslint-config-apostrophe": "^3.4.1",
21 | "eslint-config-standard": "^14.1.0",
22 | "eslint-plugin-import": "^2.22.1",
23 | "eslint-plugin-node": "^11.0.0",
24 | "eslint-plugin-promise": "^4.2.1",
25 | "eslint-plugin-standard": "^4.1.0",
26 | "esm": "^3.2.25",
27 | "vuepress": "^1.8.2",
28 | "vuepress-plugin-sitemap": "^2.3.1",
29 | "vuepress-theme-apostrophe": "^1.2.0"
30 | }
31 | }
32 |
--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
1 | Copyright (c) 2020 Apostrophe Technologies, Inc.
2 |
3 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4 |
5 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6 |
7 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
8 |
--------------------------------------------------------------------------------
/docs/howtos/README.md:
--------------------------------------------------------------------------------
1 | # HOWTOs
2 |
3 | Not everything in Apostrophe fits neatly into a category. In this section you'll find some useful odds and ends that might answer an important question that doesn't fit into any of the other categories.
4 |
5 |
6 | - [How do I Create a Custom schema field type?](custom-schema-field-types.md)
7 | - [Storing sessions in Redis and other session stores](storing-sessions-in-redis.md)
8 | - [Running Apostrophe on Windows](windows.md)
9 | - [Building Docker images for Apostrophe projects](docker.md)
10 | - [Migrating from Apostrophe 0.5](migration.md)
11 | - [Building Forms with Apostrophe](forms.md)
12 | - [Building combined menus and custom buttons with the admin bar](admin-bar.md)
13 | - [How do I create a 404 Not Found page?](how-do-i-create-a-404-not-found-page.md)
14 | - [How do I add an Intranet to my site?](intranet.md)
15 | - [Configuring CKEditor in Apostrophe](ckeditor.md)
16 | - [Facebook open graph tags in Apostrophe](facebook.md)
17 | - [Sending user notifications](sending-user-notifications.md)
18 | - [How do I Redirect a User on Login?](user-redirect.md)
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-rich-text-widgets/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-rich-text-widgets
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/README.md)
3 | Implements rich text editor widgets. Unlike most widget types, the rich text
4 | editor does not use a modal; instead you edit in context on the page.
5 |
6 |
7 | ## Methods
8 | ### getRichText(*widget*)
9 | Return just the rich text of the widget, which may be undefined or null if it has not yet been edited
10 | ### load(*req*, *widgets*, *callback*)
11 | TODO We may want to use the default widget load, if we start having nested
12 | areas in rich text widgets to support lockups
13 | ### sanitize(*req*, *input*, *callback*)
14 |
15 | ### filterForDataAttribute(*widget*)
16 | Rich text editor content is found in the
17 | div itself as markup, so don't redundantly
18 | represent it as a data attribute.
19 | ### addSearchTexts(*item*, *texts*)
20 |
21 | ### compare(*old*, *current*)
22 |
23 | ### isEmpty(*widget*)
24 |
25 | ### pushAssets()
26 |
27 | ### getWidgetClasses(*widget*)
28 |
29 | ### getWidgetWrapperClasses(*widget*)
30 |
31 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/adding-filters.md:
--------------------------------------------------------------------------------
1 | # Filters for the "manage" modal
2 |
3 | In the "manage" modal, enabling a "tags" filter for admins is often handy:
4 |
5 | ```javascript
6 | // lib/modules/your-piece/index.js
7 | module.exports = {
8 | // Other configuration options, then...
9 | addFilters: [
10 | {
11 | name: 'tags',
12 | label: 'Tags'
13 | }
14 | ]
15 | };
16 | ```
17 |
18 | You can also allow multiple tags to be selected, in which case pieces with at least one of those tags are displayed:
19 |
20 | ```javascript
21 | // lib/modules/your-piece/index.js
22 | module.exports = {
23 | // Other configuration options, then...
24 | addFilters: [
25 | {
26 | name: 'tags',
27 | label: 'Tags',
28 | multiple: true
29 | }
30 | ]
31 | };
32 | ```
33 |
34 | The same approach works for most types of schema fields, including joins. We do not recommend using it if the number of items in the dropdown will be very large. However, adding options to support filters that employ typeahead and avoid sending a large list of options to the browser is on our roadmap for the future.
35 |
--------------------------------------------------------------------------------
/docs/reference/field-properties/sortify.md:
--------------------------------------------------------------------------------
1 | # `sortify`
2 |
3 | Any field type which has its value stored as a string can have a "Sortified" version which will make sorting case-insensitive and ignore punctuation.
4 |
5 | ## Case-insensitive, intuitive sorting
6 |
7 | Setting `sortify: true` creates a parallel `Sortified` version of the field that is more intuitive for sorting purposes. Apostrophe will automatically use it if a request is made to sort on the original field.
8 |
9 | For instance, if your field's `name` is `lastName` and you set `sortify: true`, `lastNameSortified` will automatically be created and used when sorting on the `lastName` field. This provides case-insensitive sorting that also ignores punctuation differences.
10 |
11 | ::: tip
12 | Note: If you add `sortify: true` to an existing field, existing objects will get the sortified version of the field on the next deployment via the `apostrophe-migrations:migrate` command line task, or at the next startup when in development on your computer. Migrations like this only need to be run once because on future updates or inserts of a document the sortified property is automatically set.
13 | :::
14 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-email.md:
--------------------------------------------------------------------------------
1 | # apostrophe-email
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 |
4 | ## Methods
5 | ### emailForModule(*req*, *templateName*, *data*, *options*, *module*, *callback*)
6 | Implements the `email` method available in all modules.
7 |
8 | See `apostrophe-module` for coverage of the `email` method that
9 | every module has. You won't need to call `emailForModule` directly.
10 | ### getContent(*req*, *templateName*, *data*, *options*, *module*)
11 | Compute the content of the email. This is an interesting override point
12 | to add properties that will be passed to nodemailer transport when
13 | sending the email.
14 | ### getTransport(*req*, *data*, *options*)
15 | Fetch the nodemailer-compatible transport object, that is going to be
16 | used to send the email. It may be a convenient override point to decide
17 | which transport to use according to the parameters passed. The default
18 | implementation creates a transport via `nodemailer.createTransport`
19 | on the first call, passing it the value of the `nodemailer` option
20 | configured for the `apostrophe-email` module. If there is none,
21 | a fatal error is thrown.
22 |
--------------------------------------------------------------------------------
/docs/reference/field-types/url.md:
--------------------------------------------------------------------------------
1 | # `url`
2 |
3 | `url` adds an editable URL field to the schema.
4 |
5 | ::: tip
6 | Apostrophe will detect common mistakes, like leaving off `http://`, and add them. Common XSS attack vectors are laundered and discarded. Only "safe" URL schemes, e.g. `http`, `https`, `ftp` and `mailto`, are permitted.
7 | :::
8 |
9 | ## Example
10 |
11 | ```javascript
12 | {
13 | name: 'portfolio',
14 | label: 'Portfolio URL',
15 | type: 'url'
16 | }
17 | ```
18 |
19 | ## Settings
20 |
21 | | Property | Type | Default | Description |
22 | |---|---|---|---|
23 | |name | `string` | | Sets the name of the field in the database |
24 | |label | `string` | | Sets the label of the field that the user sees |
25 | |required | `boolean` | false | If true, the field is mandatory |
26 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
27 | |type | `string` | | Specifies the field type |
28 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
29 | |help | `string` | | Help text for the field that will appear with the field's label |
30 | |htmlHelp | `string` | | Help text with support for HTML markup |
31 |
--------------------------------------------------------------------------------
/docs/howtos/user-redirect.md:
--------------------------------------------------------------------------------
1 | # How do I Redirect a User on Login?
2 |
3 | By default, after a user logs in, they are redirected to the homepage.
4 |
5 | It is possible to customize this behavior.
6 |
7 | You can implement a `loginAfterLogin` method in any module. This method takes `req` and an optional callback.
8 |
9 | Setting req.redirect will cause Apostrophe to redirect the user to that location.
10 |
11 | ```javascript
12 | // lib/modules/my-module/index.js
13 | module.exports = {
14 | construct: function(self, options) {
15 | self.loginAfterLogin = function(req) {
16 | if (req.user.isSpecialInSomeWay) {
17 | req.redirect = '/special';
18 | } else {
19 | // Just let them go go the home page
20 | }
21 | };
22 | }
23 | };
24 | ```
25 |
26 | *Don't forget to enable your module in `app.js`.*
27 |
28 | If you do not set `req.redirect`, the user is redirected to the home page.
29 |
30 | For a complete example, check out the [apostrophe-second-chance-login](https://npmjs.org/package/apostrophe-second-chance-login) module, which turns 404's into an opportunity to log in, if a page exists that the user might have the privilege of seeing after logging in.
31 |
32 |
--------------------------------------------------------------------------------
/docs/reference/field-types/object.md:
--------------------------------------------------------------------------------
1 | # `object`
2 |
3 | An `object` field has its own schema, and is very similar to an [`array`](array.md) field. However there is always exactly one object, represented as an object property of the doc in the database \(a sub-object\).
4 |
5 | Using `object` instead of `array` when only dealing with a single object prevents unnecessary prefixing of field names and nesting docs in the form.
6 |
7 | ## Settings
8 |
9 | | Property | Type | Default | Description |
10 | |---|---|---|---|
11 | |name | `string` | | Sets the name of the field in the database |
12 | |label | `string` | | Sets the label of the field that the user sees |
13 | |required | `boolean` | false | If true, the field is mandatory |
14 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
15 | |type | `string` | | Specifies the field type |
16 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
17 | |help | `string` | | Help text for the field that will appear with the field's label |
18 | |htmlHelp | `string` | | Help text with support for HTML markup |
19 | |schema | `schema` | | The set of fields present for configuring the object |
20 |
--------------------------------------------------------------------------------
/docs/reference/field-types/integer.md:
--------------------------------------------------------------------------------
1 | # `integer`
2 |
3 | `integer` adds an editable integer field to the schema. You may set minimum and maximum values using the `min` and `max` options. Any fractional part is discarded.
4 |
5 | ## Example
6 |
7 | ```javascript
8 | {
9 | name: 'children',
10 | label: 'How many children do you have?',
11 | type: 'integer'
12 | }
13 | ```
14 |
15 | ## Settings
16 |
17 | | Property | Type | Default | Description |
18 | |---|---|---|---|
19 | |name | `string` | | Sets the name of the field in the database |
20 | |label | `string` | | Sets the label of the field that the user sees |
21 | |required | `boolean` | false | If true, the field is mandatory |
22 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
23 | |type | `string` | | Specifies the field type |
24 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
25 | |help | `string` | | Help text for the field that will appear with the field's label |
26 | |htmlHelp | `string` | | Help text with support for HTML markup |
27 | |min | `int` | | The minimum acceptable value for the field |
28 | |max | `int` | | The maximum acceptable value for the field |
29 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-any-page-manager/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-any-page-manager
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/README.md)
3 | This module provides a special doc type manager for the `apostrophe-page` type, which
4 | actually refers to any page in the tree, regardless of type. This
5 | allows you to create [apostrophe-schemas](/advanced-topics/schema-guide.md) that can link to
6 | any page in the page tree, rather than one specific page type.
7 |
8 |
9 | ## Methods
10 | ### find(*req*, *criteria*, *projection*)
11 | Return a cursor for finding pages of any type (but only pages, never pieces).
12 | `apostrophe-pages-cursor` takes care of ensuring that pieces don't creep in.
13 | ### getAutocompleteProjection(*query*)
14 |
15 | ### getAutocompleteTitle(*doc*, *query*)
16 | Returns a string to represent the given `doc` in an
17 | autocomplete menu. `doc` will contain only the fields returned
18 | by `getAutocompleteProjection`. `query.field` will contain
19 | the schema field definition for the join the user is attempting
20 | to match titles from. The default behavior is to return
21 | the `title` property, but since this is a page we are including
22 | the slug as well.
23 |
--------------------------------------------------------------------------------
/docs/reference/field-types/float.md:
--------------------------------------------------------------------------------
1 | # `float`
2 |
3 | `float` adds an editable numeric field which supports decimal input to the schema. You may set minimum and maximum values using the `min` and `max` options.
4 |
5 | ## Example
6 |
7 | ```javascript
8 | {
9 | name: 'gpa',
10 | label: 'What is your GPA?',
11 | type: 'float',
12 | min: 1.0,
13 | max: 4.0
14 | }
15 | ```
16 |
17 | ## Settings
18 |
19 | | Property | Type | Default | Description |
20 | |---|---|---|---|
21 | |name | `string` | | Sets the name of the field in the database |
22 | |label | `string` | | Sets the label of the field that the user sees |
23 | |required | `boolean` | false | If true, the field is mandatory |
24 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
25 | |type | `string` | | Specifies the field type |
26 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
27 | |help | `string` | | Help text for the field that will appear with the field's label |
28 | |htmlHelp | `string` | | Help text with support for HTML markup |
29 | |min | `float` | | The minimum acceptable value for the field |
30 | |max | `float` | | The maximum acceptable value for the field |
31 |
--------------------------------------------------------------------------------
/docs/reference/field-types/slug.md:
--------------------------------------------------------------------------------
1 | # `slug`
2 |
3 | `slug` adds a slug field to the schema for specifying the contextual location of content in your site. Usually there is only one, named `slug`, and it is already part of your schema when extending pieces or custom pages.
4 |
5 | By default slugs are sanitized.
6 |
7 | ## Settings
8 |
9 | | Property | Type | Default | Description |
10 | |---|---|---|---|
11 | |name | `string` | | Sets the name of the field in the database |
12 | |label | `string` | | Sets the label of the field that the user sees |
13 | |required | `boolean` | false | If true, the field is mandatory |
14 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
15 | |type | `string` | | Specifies the field type |
16 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
17 | |help | `string` | | Help text for the field that will appear with the field's label |
18 | |htmlHelp | `string` | | Help text with support for HTML markup |
19 | |page | `boolean` | false | If true, then the slug field is describing a page and slashes are allowed |
20 | |[sortify](/reference/field-properties/sortify.md) | `boolean` | false | If true, creates "sortified" fields |
21 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/browser-apostrophe-pieces.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces (browser)
2 | ## Inherits from: [apostrophe-doc-type-manager](../apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager.md)
3 | The browser-side doc type manager for a type of piece. Provides jQuery event handlers
4 | for edit, rescue, create and version rollback based on data attributes that can
5 | appear anywhere, which is useful for contextual pieces.
6 |
7 |
8 | ## Methods
9 | ### globalLink(*action*, *fn*)
10 | Globally link up clicks on data-apos-${action} where the piece
11 | type name is made properly attribute-name-friendly
12 | ### clickHandlers()
13 |
14 | ### manage()
15 |
16 | ### edit(*_id*, *options*)
17 | `options` object is merged with the options passed to the editor modal,
18 | in particular you can pass a `hint` to be displayed
19 | at the top of the modal to provide context for why the edit operation
20 | was undertaken
21 | ### create(*options*)
22 | `options` object is merged with the options passed to the editor modal,
23 | in particular you can pass a `hint` to be displayed
24 | at the top of the modal to provide context for why the edit operation
25 | was undertaken
26 | ### rescue(*_id*)
27 |
28 | ### launchBatchPermissionsModal(*data*, *callback*)
29 |
30 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/README.md:
--------------------------------------------------------------------------------
1 | # Advanced Pieces Topics
2 |
3 | In the main pieces section, you covered the basics of creating and displaying pieces, as well as some concepts like filters and joins. This section contains more information on how to use pieces to build dynamic, responsive sites.
4 |
5 | * [AJAX Features: Enhanced Browsing for Pieces](/advanced-topics/advanced-pieces-topics/ajax-pieces.md)
6 | * [Fine-grained Permissions for Pieces](/advanced-topics/advanced-pieces-topics/permissions-for-pieces.md)
7 | * [Adding Filters](/advanced-topics/advanced-pieces-topics/adding-filters.md)
8 | * [Adding Columns](/advanced-topics/advanced-pieces-topics/adding-columns.md)
9 | * [Next and Previous Links](/advanced-topics/advanced-pieces-topics/next-previous-links.md)
10 | * [Suppressing Pieces from a Listing](/advanced-topics/advanced-pieces-topics/suppressing-pieces-from-a-listing.md)
11 | * [Adding Fields to All Pieces](/advanced-topics/advanced-pieces-topics/adding-fields-to-all-pieces.md)
12 | * [Adding new batch operations for pieces](/advanced-topics/advanced-pieces-topics/adding-new-batch-operations.md)
13 | * [Extending the Pieces Editor Modal](/advanced-topics/advanced-pieces-topics/extending-the-pieces-editor-modal.md)
14 | * [Overriding the URLs of pieces](/advanced-topics/advanced-pieces-topics/overriding-piece-urls.md)
15 |
--------------------------------------------------------------------------------
/docs/reference/field-types/email.md:
--------------------------------------------------------------------------------
1 | # `email`
2 |
3 | `email` fields operate similarly to `string` fields, but will only accept a valid email address.
4 |
5 | ## Example
6 |
7 | ```javascript
8 | // Single line, optional
9 | {
10 | name: 'contact',
11 | label: 'Contact',
12 | type: 'email'
13 | }
14 | ```
15 |
16 | ```javascript
17 | // Single line, required
18 | {
19 | name: 'contact',
20 | label: 'Contact',
21 | type: 'email',
22 | required: true
23 | }
24 | ```
25 |
26 | ## Settings
27 |
28 | | Property | Type | Default | Description |
29 | |---|---|---|---|
30 | |name | `string` | | Sets the name of the field in the database |
31 | |label | `string` | | Sets the label of the field that the user sees |
32 | |required | `boolean` | false | If true, the field is mandatory |
33 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
34 | |type | `string` | | Specifies the field type |
35 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
36 | |help | `string` | | Help text for the field that will appear with the field's label |
37 | |htmlHelp | `string` | | Help text with support for HTML markup |
38 | |[sortify](/reference/field-properties/sortify.md) | `boolean` | false | If true, make sort() operations on the field case insensitive and otherwise more intuitive |
39 |
--------------------------------------------------------------------------------
/docs/core-concepts/global-settings/global.md:
--------------------------------------------------------------------------------
1 | # The global doc: sharing content across pages
2 |
3 | In the [previous global settings section](settings.md) you explored different ways of using global content. But what if your users need more control over their footer?
4 |
5 | You can use `data.global` to reference the same doc from anywhere on the site. It looks like this:
6 |
7 | ```markup
8 | {% block main %}
9 |
10 | {{ apos.singleton(data.global, 'footer', 'apostrophe-rich-text', {
11 | toolbar: [ 'Bold', 'Italic', 'Styles', 'Link', 'Unlink' ]
12 | }) }}
13 |
14 | {% endblock %}
15 | ```
16 |
17 | Just like `data.page`, `data.global` can contain Apostrophe areas and singletons. Unlike `data.page`, it _always refers to the same, shared document_. So it is ideal for a footer, banner or other sitewide content element.
18 |
19 | ::: tip
20 | `data.global` is great, but don't put your entire site in there! Sometimes beginning Apostrophe developers will add hundreds of areas to `global`. This is not a good idea. A good rule of thumb is that you should store your content with the appropriate page, or the appropriate [piece](/core-concepts/reusable-content-pieces/reusable-content-with-pieces.md), unless it is needed at least 50% of the time... because the global doc has to be loaded by the server 100% of the time.
21 | :::
22 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-notifications/browser-apostrophe-notifications.md:
--------------------------------------------------------------------------------
1 | # apostrophe-notifications (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### trigger(*message*, *options*)
6 | Call with a message, followed by any interpolated strings which must correspond
7 | to %s placeholders in `message` (variable number of arguments), followed by an
8 | `options` object if desired.
9 |
10 | `options.type` styles the notification and may be set to `error`,
11 | `warn` or `success`. If not set, a "plain" default style is used.
12 |
13 | If `options.dismiss` is set to `true`, the message will auto-dismiss after 5 seconds.
14 | If it is set to a number of seconds, it will dismiss after that number of seconds.
15 | Otherwise it will not dismiss unless clicked.
16 |
17 | This method is aliased as `apos.notify` for convenience.
18 |
19 | The message is internationalized by the server, which is why the use of
20 | %s placeholders for any inserted titles, etc. is important.
21 | ### enable()
22 |
23 | ### display(*notification*)
24 | Display a notification received from the server.
25 | You want `apos.notify`, not this method, unless you are
26 | overriding how notifications are displayed.
27 | ### createContainer()
28 |
29 | ### reparentContainer()
30 |
31 | ### addToContainer(*$notification*)
32 |
33 | ### dismiss(*$notification*, *fromServer*)
34 |
35 |
--------------------------------------------------------------------------------
/docs/reference/field-types/range.md:
--------------------------------------------------------------------------------
1 | # `range`
2 |
3 | A `range` field provides [range input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range) for selecting a numeric value, often represented in the browser as a slider. The step option may be used along with min and max, if desired, to effectively limit the results to integers.
4 |
5 | ## Example
6 |
7 | ```javascript
8 | {
9 | type: 'range',
10 | name: 'fontSize',
11 | label: 'Font Size',
12 | min: 18,
13 | max: 32,
14 | step: 2 // optional
15 | }
16 | ```
17 |
18 | ## Settings
19 |
20 | | Property | Type | Default | Description |
21 | |---|---|---|---|
22 | |name | `string` | | Sets the name of the field in the database |
23 | |label | `string` | | Sets the label of the field that the user sees |
24 | |required | `boolean` | false | If true, the field is mandatory |
25 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
26 | |type | `string` | | Specifies the field type |
27 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
28 | |help | `string` | | Help text for the field that will appear with the field's label |
29 | |htmlHelp | `string` | | Help text with support for HTML markup |
30 | |min | `int` | | The minimum acceptable value for the field |
31 | |max | `int` | | The maximum acceptable value for the field |
32 | |step | `int` | | The interval between numbers |
33 |
--------------------------------------------------------------------------------
/docs/reference/field-types/select.md:
--------------------------------------------------------------------------------
1 | # `select`
2 |
3 | A single-select input field. The contents of the menu are set using the [`choices`](/reference/field-properties/choices.md) property and its sub-properties.
4 |
5 | ## Settings
6 |
7 | | Property | Type | Default | Description | Sub-properties |
8 | |---|---|---|---|---|
9 | |name | `string` | | Sets the name of the field in the database | |
10 | |label | `string` | | Sets the label of the field that the user sees | |
11 | |required | `boolean` | false | If true, the field is mandatory | |
12 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box | |
13 | |type | `string` | | Specifies the field type | |
14 | |readOnly | `boolean` | false | If true, prevents the user from editing the field | |
15 | |help | `string` | | Help text for the field that will appear with the field's label | |
16 | |htmlHelp | `string` | | Help text with support for HTML markup | |
17 | |[choices](/reference/field-properties/choices.md) | `array` | | An array of choices that the user can select from. Each must be an object with value and label properties. | [**showFields**](/reference/field-properties/choices.md#showfields) |
18 | |widgetControls | `boolean` | false | If true, `select` fields can be edited in context on the page if the field is in a widget | |
19 | |[sortify](/reference/field-properties/sortify.md) | `boolean` | false | If true, creates "sortified" fields |
20 |
21 |
--------------------------------------------------------------------------------
/docs/reference/field-types/checkbox.md:
--------------------------------------------------------------------------------
1 | # `checkboxes`
2 |
3 | A `checkboxes` field presents a list of options where a user can select multiple items, or possible none at all depending on the configuration. The values of the checkbox entries are set using the [`choices`](/reference/field-properties/choices.md) property and its sub-properties.
4 |
5 | ## Settings
6 |
7 | | Property | Type | Default | Description | Sub-properties |
8 | |---|---|---|---|---|
9 | |name | `string` | | Sets the name of the field in the database | |
10 | |label | `string` | | Sets the label of the field that the user sees | |
11 | |required | `boolean` | false | If true, the field is mandatory | |
12 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box | |
13 | |type | `string` | | Specifies the field type | |
14 | |readOnly | `boolean` | false | If true, prevents the user from editing the field | |
15 | |help | `string` | | Help text for the field that will appear with the field's label | |
16 | |htmlHelp | `string` | | Help text with support for HTML markup | |
17 | |[choices](/reference/field-properties/choices.md) | `array` | | An array of choices that the user can select from. Each must be an object with value and label properties. | [**showFields**](/reference/field-properties/choices.md#showfields) |
18 | |widgetContols | `boolean` | false | If true, `checkbox` fields can be edited in line on the page if the field is in a widget | |
19 |
--------------------------------------------------------------------------------
/docs/devops/cloud/storing-images-and-files-in-azure-blob-storage.md:
--------------------------------------------------------------------------------
1 | # Storing images and files in Azure Blob Storage
2 |
3 | You can store your images and files in Azure Blob Storage if you wish. You don't have to use the local file system.
4 |
5 | If you host your servers on Azure virtual machines, this is essential to host your Apostrophe site in a multiserver configuration where the Node processes don't share the same filesystem (hint: they are separate virtual computers).
6 |
7 | Just take advantage of the [uploadfs](https://github.com/apostrophecms/uploadfs) module, which is built into Apostrophe.
8 |
9 | First sign up for [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) and create a blob storage container. Also obtain an API key.
10 |
11 | Now add an `uploadfs` property to your configuration in `app.js`:
12 |
13 | ```javascript
14 | modules: {
15 | 'apostrophe-attachments': {
16 | uploadfs: {
17 | storage: 'azure',
18 | account: 'myaccountname',
19 | container: 'mycontainername',
20 | key: 'YOUR-key-goes-here',
21 | disabledFileKey: 'YOU-set-this-random-string'
22 | }
23 | }
24 | }
25 | ```
26 |
27 | > To distinguish dev from production, consider using
28 | `process.env.AZURE_BLOB_ACCOUNT`, `process.env.AZURE_BLOB_KEY`, etc. to read
29 | these values from environment variables as well.
30 |
31 | With this configuration all file uploads are written to the Azure Blob Storage service instead of the local file system.
32 |
33 |
--------------------------------------------------------------------------------
/docs/howtos/storing-sessions-in-redis.md:
--------------------------------------------------------------------------------
1 | # Storing sessions in Redis and other session stores
2 |
3 | By default, Apostrophe stores sessions in its MongoDB database. That makes it easier to install Apostrophe. But many developers prefer Redis for sessions. Here's how to configure that.
4 |
5 | 1. Add the `connect-redis` module to your project's npm dependencies:
6 |
7 | ```
8 | npm install --save connect-redis
9 | ```
10 |
11 | 2. In `app.js`, configure the `apostrophe-express` module to use it:
12 |
13 | ```javascript
14 | 'apostrophe-express': {
15 | session: {
16 | secret: 'your-secret-here',
17 | store: {
18 | name: 'connect-redis',
19 | options: {
20 | // redis-specific options here. If you don't give any,
21 | // the redis server on localhost is used
22 | }
23 | }
24 | }
25 | }
26 | ```
27 |
28 | Notice that you don't have to use `require` because Apostrophe does it for you.
29 |
30 | This technique is not limited to Redis. You can use any store that follows the standard conventions for connect/Express session store modules.
31 |
32 | The `options` object you supply is passed on to the store when it is created. For more information about options for Redis, see the [connect-redis](https://www.npmjs.com/package/connect-redis) documentation.
33 |
34 | ## "What about caches?"
35 |
36 | You can also remap Apostrophe's cache mechanism to Redis. Check out the optional [apostrophe-caches-redis](https://npmjs.org/package/apostrophe-caches-redis) module.
37 |
--------------------------------------------------------------------------------
/docs/reference/field-types/boolean.md:
--------------------------------------------------------------------------------
1 | # `boolean`
2 |
3 | A `boolean` field is a simple "True/False" choice. The value stored in the database will be either `true` or `false`. To customize the displayed values, use the `label` sub-property of [`choices`](/reference/field-properties/choices.md). The `value` for each choice must always be "true" or "false".
4 |
5 | ## Settings
6 |
7 | | Property | Type | Default | Description | Sub-properties |
8 | |---|---|---|---|---|
9 | |name | `string` | | Sets the name of the field in the database | |
10 | |label | `string` | | Sets the label of the field that the user sees | |
11 | |required | `boolean` | false | If true, the field is mandatory | |
12 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box | |
13 | |type | `string` | | Specifies the field type | |
14 | |readOnly | `boolean` | false | If true, prevents the user from editing the field | |
15 | |help | `string` | | Help text for the field that will appear with the field's label | |
16 | |htmlHelp | `string` | | Help text with support for HTML markup | |
17 | |mandatory | `string` | | If set, the string is displayed if the user does not complete the field, often used for Terms and Conditions or similar content | |
18 | |[choices](/reference/field-properties/choices.md) | `array` | | An array of choices that the user can select from. Each must be an object with value and label properties. | [**showFields**](/reference/field-properties/choices.md#showfields) |
19 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-video-widgets/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-video-widgets
2 | ## Inherits from: [apostrophe-widgets](../apostrophe-widgets/README.md)
3 | Provides the `apostrophe-video` widget, which displays videos, powered
4 | by [apostrophe-video-field](/reference/modules/apostrophe-video-fields) and
5 | [apostrophe-oembed](/reference/modules/apostrophe-oembed). The video
6 | widget accepts the URL of a video on any website that supports the
7 | [oembed](http://oembed.com/) standard.
8 |
9 | Configurations differ between website implementations, but standard
10 | supported providers include, but are not limited to:
11 |
12 | - YouTube
13 | - Vimeo
14 | - Facebook
15 | - Dailymotion
16 | - Flickr
17 | - Scribd
18 | - Photobucket
19 |
20 | In some cases the results are refined by oembetter filters configured
21 | by the `apostrophe-oembed` module. It is possible to configure new filters
22 | for that module to handle video sites that don't natively support oembed.
23 |
24 | Videos are not actually hosted or stored by Apostrophe.
25 |
26 | ## Options
27 |
28 | ### player: true
29 |
30 | If you have set `lean: true` for the `apostrophe-assets` module,
31 | the standard oembed-based video player does not get pushed to the
32 | browser, as it is part of the legacy jQuery-based frontend.
33 |
34 | However, you may opt in to a similar player that uses only a
35 | few lines of lean JavaScript by setting the `player` option
36 | of this module to `true`. You may of course skip this and
37 | write your own.
38 |
39 |
40 |
--------------------------------------------------------------------------------
/docs/reference/field-types/singleton.md:
--------------------------------------------------------------------------------
1 | # `singleton`
2 |
3 | The `singleton` field type adds a single widget to your schema. It is exactly like calling `apos.singleton` in a page template.
4 |
5 | The widget type is set by the `widgetType` property. The `options` property is passed on to the widget as its options object.
6 |
7 | ## Example
8 |
9 | ```javascript
10 | {
11 | name: 'thumbnail',
12 | label: 'Thumbnail',
13 | type: 'singleton',
14 | widgetType: 'slideshow',
15 | options: {
16 | aspectRatio: [ 4, 3 ],
17 | minSize: [ 400, 300 ],
18 | limit: 1
19 | }
20 | }
21 | ```
22 |
23 | ## Settings
24 |
25 | | Property | Type | Default | Description |
26 | |---|---|---|---|
27 | |name | `string` | | Sets the name of the field in the database |
28 | |label | `string` | | Sets the label of the field that the user sees |
29 | |required | `boolean` | false | If true, the field is mandatory |
30 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
31 | |type | `string` | | Specifies the field type |
32 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
33 | |help | `string` | | Help text for the field that will appear with the field's label |
34 | |htmlHelp | `string` | | Help text with support for HTML markup |
35 | |widgetType | `string` | | The name of the widget type to be displayed |
36 | |options | `object` | | An object containing options which can be set on a field |
37 | |searchable | `boolean` | true | If false, content from the area will not appear in search results |
38 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pages/browser-apostrophe-pages-editor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pages-editor (browser)
2 | Edit page settings.
3 |
4 | Typically instantiated by the page settings button, however it can be instantiated
5 | programmatically to edit the page settings of a different page, in which case
6 | `options.page` must provide at least the `_id` and `type` properties.
7 |
8 | If the page settings of the current page are edited, after editing is complete the
9 | user is redirected to the page on save, to reflect all changes including slug edits.
10 |
11 | `options.afterSave` may be a function which takes a page object and a callback.
12 | The page object is the page as returned by the server after the save operation.
13 |
14 |
15 | ## Methods
16 | ### beforeShow(*callback*)
17 |
18 | ### addTypeChangeHandler()
19 | Add a change event handler to the type field.
20 | This is installed at initial load time and also
21 | when the content is re-rendered due to a page
22 | type change, resulting in a new type field element.
23 | ### open(*callback*)
24 |
25 | ### afterShow()
26 | Make sure the field indicated by options.field is initially visible
27 | ### populate(*data*, *callback*)
28 |
29 | ### beforeSave(*callback*)
30 |
31 | ### afterSave(*callback*)
32 |
33 | ### convert(*page*, *callback*)
34 |
35 | ### saveContent(*callback*)
36 | For pages, saveContent never invokes its callback except on an error,
37 | because it redirects to the new page URL. To aid you in doing something
38 | before that happens, the afterSave method is provided and can be overridden
39 | as you see fit.
40 | ### changedType(*type*)
41 |
42 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-doc-type-manager/browser-apostrophe-doc-type-manager-chooser.md:
--------------------------------------------------------------------------------
1 | # apostrophe-doc-type-manager-chooser (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### load(*callback*)
6 |
7 | ### set(*choices*)
8 | Set a new array of currently selected choices. Each should have
9 | label and value properties at a minimum
10 | ### get(*callback*)
11 |
12 | ### getFinal(*callback*)
13 |
14 | ### finalize(*callback*)
15 |
16 | ### add(*_id*)
17 |
18 | ### clear()
19 |
20 | ### remove(*_id*, *refresh*)
21 |
22 | ### refresh(*options*)
23 |
24 | ### convertInlineRelationships(*callback*)
25 |
26 | ### decrementRefreshing()
27 |
28 | ### enableLinks()
29 |
30 | ### enableAutocomplete()
31 |
32 | ### enableSortable()
33 |
34 | ### getBrowserType()
35 |
36 | ### launchBrowser()
37 |
38 | ### clone(*options*, *callback*)
39 | Create a new chooser with the same data and options, merging in any
40 | additional options from the first argument. Async because
41 | the constructor is async. Delivers (err, newChooser)
42 | ### onChange()
43 |
44 | ### enableInlineSchema()
45 |
46 | ### decorateManager(*manager*, *options*)
47 | Adds and overrides methods of the apostrophe-pieces-manager-modal to
48 | accommodate its use as a full-featured selection tool for the chooser,
49 | including the ability to create new items on the fly and choose them
50 | ### afterManagerSave()
51 |
52 | ### afterManagerCancel()
53 |
54 | ### pieceInsertedListener(*piece*)
55 | This listener only actually gets installed for a chooser appearing in a manager
56 | ### pieceIsRelevant(*piece*)
57 |
58 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-oembed/browser-apostrophe-oembed.md:
--------------------------------------------------------------------------------
1 | # apostrophe-oembed (browser)
2 | The browser-side `apos.oembed` singleton. Provides the
3 | `apos.oembed.query` and `apos.oembed.queryAndPlay` methods.
4 |
5 |
6 | ## Methods
7 | ### queryAndPlay(*$el*, *options*, *callback*)
8 | Populate the specified div with the oembed result for the specified URL.
9 | Adds the apos-oembed-busy class to $el during the interim.
10 |
11 | options.url must be set to the URL for the oembed query.
12 |
13 | If options.type is set, the type property of the oembed response must match,
14 | or it is treated as invalid.
15 |
16 | On success the title and thumbnail URL oembed result properties are made
17 | available as the `title` and `thumbnail` jQuery data properties of
18 | $el.
19 |
20 | The callback is optional and is invoked when the video has been
21 | displayed and sized. It receives (null, $el, result).
22 | ### query(*options*, *callback*)
23 | apos.oembed.query: a convenience wrapper for making oembed requests
24 | through Apostrophe's built-in proxy. options.url must be set to the
25 | URL for the oembed query.
26 | ### play(*$el*, *result*, *callback*)
27 | apos.oembed.play accepts a jQuery div and an oembed response
28 | from apos.oembed.query. The div is repopulated with the oembed result.
29 | The callback is optional and is invoked when the video has been
30 | displayed and sized. It receives (null, $el, result).
31 |
32 | On success the title and thumbnail URL oembed result properties are made
33 | available as the `title` and `thumbnail` jQuery data properties of
34 | $el.
35 |
36 | Normally `apos.oembed.queryAndPlay` is the most convenient approach.
37 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-groups/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-groups
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/README.md)
3 | ### `apos.groups`
4 | Provide a way to group [apostrophe-users](/reference/modules/apostrophe-users) together
5 | and assign permissions to them. This module is always active "under the hood," even if
6 | you take advantage of the `groups` option of `apostrophe-users` to skip a separate
7 | admin bar button for managing groups. **To make an admin bar button available
8 | for managing groups, do NOT set the `groups` option when configuring the
9 | `apostrophe-users` module. That option configures a hardcoded list of groups
10 | as a simplified alternative.**
11 |
12 | By default the `published` schema field is removed. As a general rule we believe
13 | that conflating users and groups, who can log into the website, with public directories
14 | of people most often leads to confusion. Use a separate subclass of pieces to
15 | represent departments, etc.
16 |
17 | If you do add the `published` field back you will need to extend the cursor to make
18 | `published(true)` the default again.
19 |
20 | This module is **not** intended to be extended with new subclass modules, although
21 | you may implicitly subclass it at project level to change its behavior.
22 |
23 |
24 | ## Methods
25 | ### modulesReady()
26 |
27 | ### setPermissionsChoices()
28 |
29 | ### removeTotpFromSchemaIfUnsuitable()
30 |
31 | ### addToAdminBar()
32 |
33 | ### addToAdminBarIfSuitable()
34 | Adds an admin bar button if and only if the `apostrophe-users` module
35 | is not using its `groups` option for simplified group administration.
36 | ### enableAddGroupTask()
37 |
38 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-i18n.md:
--------------------------------------------------------------------------------
1 | # apostrophe-i18n
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | This module makes an instance of the [i18n](https://npmjs.org/package/i18n) npm module available
4 | as `apos.i18n`. Apostrophe also makes this available in Nunjucks templates via the
5 | usual `__ns('apostrophe', )` helper function. Any options passed to this module are passed on to `i18n`.
6 |
7 | By default i18n locale files are generated in the `locales` subdirectory of the project.
8 |
9 | ## Options
10 |
11 | `localesDir`: if specified, the locale `.json` files are stored here, otherwise they
12 | are stored in the `locales` subdirectory of the project root.
13 |
14 | `namespaces`: if set to `true`, the translation key is prefixed like this
15 | so that translation teams can tell the difference between Apostrophe's
16 | UI phrases and your own phrases:
17 |
18 | "apostrophe<:>Phrase Here"
19 |
20 | The separator was chosen to be unlikely to be part of your actual text,
21 | but you can change the separator with the `namespaceOperator` option.
22 |
23 | ## Namespacing your own i18n calls
24 |
25 | You can optionally namespace your own i18n calls by invoking
26 | `__ns('namespace', 'phrase')` rather than `__('phrase')`,
27 | `__ns_n` rather than `__n`, etc.
28 |
29 | Currently the namespaced wrapper calls only support being invoked with a key as the
30 | second argument. Other variations are not supported with namespaces.
31 |
32 | *If you are using the `objectNotation` option to i18n, do not use your
33 | objectNotation separator character in a namespace name.*
34 |
35 |
36 | ## Methods
37 | ### namespacesMiddleware(*req*, *res*, *next*)
38 |
39 |
--------------------------------------------------------------------------------
/docs/reference/field-types/date.md:
--------------------------------------------------------------------------------
1 | # `date`
2 |
3 | `date` adds an editable date field to the schema. A friendly date picker UI is presented when the field is clicked. Dates are stored as strings in `YYYY-MM-DD` format.
4 |
5 | ## Example 1
6 |
7 | ```javascript
8 | {
9 | name: 'date',
10 | label: 'Date',
11 | type: 'date'
12 | }
13 | ```
14 |
15 | The date picker UI uses [pikaday](https://github.com/dbushell/Pikaday#usage) for configuration.
16 |
17 | ## Example with configuration of date picker
18 |
19 | ```javascript
20 | {
21 | name: 'date',
22 | label: 'Date',
23 | type: 'date',
24 | pikadayOptions: {
25 | format: 'DD/MM/YYYY',
26 | firstDay: 1
27 | }
28 | }
29 | ```
30 |
31 | ::: tip NOTE
32 | Apostrophe tries its best to convert any date picker format to the above mentioned `YYYY-MM-DD` friendly sorting format, but very advanced configurations may not work out of the box, so please keep that in mind.
33 | :::
34 |
35 | ## Settings
36 |
37 | | Property | Type | Default | Description |
38 | |---|---|---|---|
39 | |name | `string` | | Sets the name of the field in the database |
40 | |label | `string` | | Sets the label of the field that the user sees |
41 | |required | `boolean` | false | If true, the field is mandatory |
42 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
43 | |type | `string` | | Specifies the field type |
44 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
45 | |help | `string` | | Help text for the field that will appear with the field's label |
46 | |htmlHelp | `string` | | Help text with support for HTML markup |
47 | |pikadayOptions | `object` | | Allows configuration of the date format |
48 |
--------------------------------------------------------------------------------
/docs/reference/field-types/string.md:
--------------------------------------------------------------------------------
1 | # `string`
2 |
3 | `string` adds an editable text field to the schema.
4 |
5 | ## Example
6 |
7 | ```javascript
8 | // Single line
9 | {
10 | name: 'author',
11 | label: 'Author',
12 | type: 'string'
13 | }
14 | ```
15 |
16 | ```javascript
17 | // Multiple line
18 | {
19 | name: 'authors',
20 | label: 'Authors',
21 | type: 'string',
22 | textarea: true
23 | }
24 | ```
25 |
26 | ## Settings
27 |
28 | | Property | Type | Default | Description |
29 | |---|---|---|---|
30 | |name | `string` | | Sets the name of the field in the database |
31 | |label | `string` | | Sets the label of the field that the user sees |
32 | |required | `boolean` | false | If true, the field is mandatory |
33 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
34 | |type | `string` | | Specifies the field type |
35 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
36 | |help | `string` | | Help text for the field that will appear with the field's label |
37 | |htmlHelp | `string` | | Help text with support for HTML markup |
38 | |pattern | `string` | | Regular expression to validate entries |
39 | |patternErrorMessage | `string` | | Error message to display if `pattern` does not match |
40 | |textArea | `boolean` | false | If true, create a larger text areas |
41 | |searchable | `boolean` | true | If false, content from the area will not appear in search results. |
42 | |min | `integer` | | Sets the minimum number of characters allowed |
43 | |max | `integer` | | Sets the maximum number of characters allowed |
44 | |[sortify](/reference/field-properties/sortify.md) | `boolean` | false | If true, creates "sortified" fields |
45 |
--------------------------------------------------------------------------------
/docs/getting-started/README.md:
--------------------------------------------------------------------------------
1 | # Getting Started
2 |
3 | [The "getting started" tutorial](setting-up-your-environment.md) is written for developers who are new to Apostrophe. They will walk you through the process of getting your environment set up and creating a basic website.
4 |
5 | Practical examples of these concepts are illustrated in the "Open Musuem" project, a fully featured Apostrophe site. [You can access the code](https://github.com/apostrophecms/apostrophe-open-museum) or [try a live demo](http://demo.apostrophecms.com).
6 |
7 | ## Core Concepts
8 |
9 | [The Core Concepts tutorials](/core-concepts) go through each piece of Apostrophe that you need to understand to build a webite. They will help you get more comfortable with Apostrophe and node.js.
10 |
11 | ## Advanced Topics
12 |
13 | [Advanced Topics](/advanced-topics) dives deepers into the features of Apostrophe and the concepts behind it to provide the knowledge and tools you need to build dynamic, responsive sites.
14 |
15 | ## DevOps
16 |
17 | [DevOps](/devops) covers all you need to know to deploy and configure Apostrophe for a production environment.
18 |
19 |
20 | ## HOWTOs
21 |
22 | [The HOWTOs](/howtos) cover miscellaneous topics including development. configuration, and customization.
23 |
24 | ## What's the right level for me?
25 |
26 | If you're brand new to Apostrophe, go to [Setting Up Your Environment](/getting-started/setting-up-your-environment.md) first to learn how to set up Apostrophe locally for development and testing, then how to create a project. Once you have Apostrophe set up, [Core Concepts](/core-concepts) will help you get a good grasp on Apostrophe's tools. After that, you can dig deeper with [Advanced Topics](/advanced-topics) or get ready for production with [DevOps](/devops).
27 |
--------------------------------------------------------------------------------
/docs/reference/field-types/tags.md:
--------------------------------------------------------------------------------
1 | # `tags`
2 |
3 | `tags` adds a field allowing the user to enter one or more tags. The interface will suggest completions for each tag, based on existing `tags` for the site.
4 |
5 | Usually a doc has only one `tags` field, called `tags`. You may create an additional field for storing tags, but the autocomplete feature only uses the original `tags` field.
6 |
7 | If the `lock` option of the [`apostrophe-tags`](/reference/modules/apostrophe-tags/README.md) module has been set to `true`, users cannot create brand-new tags when filling out a `tags` field. In this case never-before-seen tags must be created via the "Tags" admin bar button.
8 |
9 | By default, tags are converted to lowercase and leading and trailing whitespace is trimmed. This behavior can be overridden by configuring the [`apostrophe-launder`](/reference/modules/apostrophe-launder.md) module's `filterTag` option to a function that accepts a string, filters it as desired, and returns a new string.
10 |
11 | ## Settings
12 |
13 | | Property | Type | Default | Description |
14 | |---|---|---|---|
15 | |name | `string` | | Sets the name of the field in the database |
16 | |label | `string` | | Sets the label of the field that the user sees |
17 | |required | `boolean` | false | If true, the field is mandatory |
18 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
19 | |type | `string` | | Specifies the field type |
20 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
21 | |help | `string` | | Help text for the field that will appear with the field's label |
22 | |htmlHelp | `string` | | Help text with support for HTML markup |
23 | |limit | `int` | | Sets the number of tags that can be defined in a given field |
24 |
--------------------------------------------------------------------------------
/docs/reference/field-types/time.md:
--------------------------------------------------------------------------------
1 | # `time`
2 |
3 | `time` adds an editable time field to the schema. No special time picker is presented, however Apostrophe is very tolerant of different time formats users may enter, such as "6p" or "6:37pm" or "17:45".
4 |
5 | Times are stored in 24 hour "HH:MM:SS" format.
6 |
7 | The default "local" time format, displayed to the user when editing, is American-style 12 hour time. You may change this by configuring the [`apostrophe-ui`](/reference/modules/apostrophe-ui/README.md) module and setting the `userTimeFormat` option to a different [moment](https://npmjs.org/package/moment) format string.
8 |
9 | ::: warning NOTE
10 | While "moment" supports many time formats, in Apostrophe you must use a standard 24-hour or 12-hour time separated by colons \(`:`\) for the field to be understood.
11 | :::
12 |
13 | ## Settings
14 |
15 | | Property | Type | Default | Description |
16 | |---|---|---|---|
17 | |name | `string` | | Sets the name of the field in the database |
18 | |label | `string` | | Sets the label of the field that the user sees |
19 | |required | `boolean` | false | If true, the field is mandatory |
20 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
21 | |type | `string` | | Specifies the field type |
22 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
23 | |help | `string` | | Help text for the field that will appear with the field's label |
24 | |htmlHelp | `string` | | Help text with support for HTML markup |
25 | |userTimeFormat | | | Allows configuration of the time format |
26 | |def | | | Sets the default time that is displayed |
27 |
28 | ::: warning NOTE
29 | If you do not set `def: null` or `required: true`, the time defaults to the current time.
30 | :::
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-db.md:
--------------------------------------------------------------------------------
1 | # apostrophe-db
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 |
4 | ## Methods
5 | ### connectToMongo(*callback*)
6 | Open the database connection. Always use MongoClient with its
7 | sensible defaults. Build a URI if we need to, so we can call it
8 | in a consistent way.
9 |
10 | One default we override: if the connection is lost, we keep
11 | attempting to reconnect forever. This is the most sensible behavior
12 | for a persistent process that requires MongoDB in order to operate.
13 | ### keepalive()
14 | Query the server status every 10 seconds just to prevent
15 | the mongodb module version 2.1.19+ or better from allowing
16 | the connection to time out. That module provides no error messages or clues
17 | that we need to reconnect it.
18 | ### earlyResetTask(*callback*)
19 | Remove ALL collections from the database as part of the
20 | `apostrophe-db:reset` task. Then Apostrophe carries out the usual
21 | reinitialization of collection indexes and creation of parked pages, etc.
22 |
23 | PLEASE NOTE: this will drop collections UNRELATED to apostrophe.
24 | If that is a concern for you, drop Apostrophe's collections yourself
25 | and start up your app, which will recreate them.
26 | ### bcPatch()
27 | Just a bc wrapper now that we are using emulate-mongo-2-driver,
28 | which already adds findWithProjection as a synonym.
29 | ### resetFromTask(*callback*)
30 |
31 | ### dropAllCollections(*callback*)
32 |
33 | ### apostropheDestroy(*callback*)
34 | Invoked by `callAll` when `apos.destroy` is called.
35 | Closes the database connection and the keepalive
36 | interval timer. Sets `apos.db.closed` to true,
37 | allowing detection of the fact that the database
38 | connection is no longer available by code that
39 | might still be in progress.
40 | ### trace()
41 |
42 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-attachments/browser-apostrophe-attachments.md:
--------------------------------------------------------------------------------
1 | # apostrophe-attachments (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 |
4 | ## Methods
5 | ### url(*file*, *options*)
6 | Given an attachment field value,
7 | return the file URL. If options.size is set, return the URL for
8 | that size (one-third, one-half, two-thirds, full). full is
9 | "full width" (1140px), not the original.
10 |
11 | If you don't pass the options object, or options does not
12 | have a size property, you'll get the URL of the original.
13 |
14 | You can also pass a crop object (the crop must already exist).
15 | ### crop(*attachment*, *options*, *callback*)
16 | Invoke with an attachment, options (such as minSize), and a callback.
17 | Callback receives (err, crop). If no err, crop has coordinates and
18 | can be stored as the crop property of the attachment (when there is
19 | one and only one crop ever for this attachment), or stored as part
20 | of a relationship to the doc containing the attachment; that part
21 | is up to you.
22 | ### focalPoint(*attachment*, *options*, *callback*)
23 | Invoke with an attachment, options (such as minSize), and a callback.
24 | Callback receives (err, focalPoint). If no err, focalPoint has x and y
25 | properties and can be stored as the focalPoint property of the attachment
26 | (when there is one and only one focal point ever for this attachment), or
27 | stored as part of a relationship to the doc containing the attachment; that part
28 | is up to you.
29 | ### addFieldType()
30 |
31 | ### populate(*object*, *name*, *$field*, *$el*, *field*, *callback*)
32 |
33 | ### convert(*data*, *name*, *$field*, *$el*, *field*, *callback*)
34 |
35 | ### autocrop(*field*, *attachment*, *callback*)
36 |
37 | ### addHandlers()
38 |
39 | ### updateExisting(*$fieldset*, *info*, *field*)
40 |
41 |
--------------------------------------------------------------------------------
/docs/reference/field-types/area.md:
--------------------------------------------------------------------------------
1 | # `area`
2 |
3 | The `area` field type defines an editable content area that allows users to add a series of widgets. It is exactly like calling `apos.area` in a page template.
4 |
5 | The properties configured in `options` specify the allowed widget types and the configuration for those widgets. You can learn more about widget configuration in templates in [Nunjucks Helper Functions](/core-concepts/working-with-templates/nunjucks-helper-functions.md).
6 |
7 | ## Example
8 |
9 | ```javascript
10 | {
11 | name: 'body',
12 | label: 'Biography',
13 | type: 'area',
14 | options: {
15 | // just like apos.area in a template
16 | widgets: {
17 | 'apostrophe-rich-text': {
18 | toolbar: [ 'Bold', 'Italic', 'Link', 'Unlink' ]
19 | },
20 | 'apostrophe-images': {}
21 | }
22 | }
23 | }
24 | ```
25 | ## Settings
26 |
27 | | Property | Type | Default | Description | Sub-properties |
28 | |---|---|---|---|----|
29 | |name | `string` | | Sets the name of the field in the database | |
30 | |label | `string` | | Sets the label of the field that the user sees | |
31 | |required | `boolean` | false | If true, the field is mandatory | |
32 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
33 | |type | `string` | | Specifies the field type | |
34 | |readOnly | `boolean` | false | If true, prevents the user from editing the field | |
35 | |help | `string` | | Help text for the field that will appear with the field's label | |
36 | |htmlHelp | `string` | | Help text with support for HTML markup | universal | |
37 | |limit | `int` | | Sets the number of widgets that can be added to an area | |
38 | |[options](/reference/field-properties/options.md)| `object` | | An object containing options to be passed to `apos.area` | [`widgets`](/reference/field-properties/options.md#widgets) |
39 |
40 |
--------------------------------------------------------------------------------
/docs/reference/field-types/video.md:
--------------------------------------------------------------------------------
1 | # `video`
2 |
3 | A `video` field allows the user to embed video hosted by any [oembed](http://oembed.com/)—compatible video hosting site, or any site for which you have provided an [oembetter](https://github.com/apostrophecms/oembetter) filter via the [apostrophe-oembed](/reference/modules/apostrophe-oembed/README.md) module.
4 |
5 | The user pastes a URL and sees an immediate preview.
6 |
7 | The value of the property on the object will have `url`, `title` and `thumbnail` properties. `title` and `thumbnail` are snapshots from the oembed response at the time the field was saved. `thumbnail` is the URL of a thumbnail image as provided by the oembed response.
8 |
9 | **The video field is primarily intended to be used as part of the core video widget rather than in custom schemas**, however [apostrophe-oembed](/reference/modules/apostrophe-oembed/README.md) provides browser-side methods to display the video via client-side JavaScript. See the [apostrophe-video-widgets](/reference/modules/apostrophe-video-widgets/README.md) source code for an example of using these methods to play a video in a `div` element.
10 |
11 | ## Example
12 |
13 | ```javascript
14 | {
15 | type: 'video',
16 | name: 'video',
17 | label: 'Video'
18 | }
19 | ```
20 |
21 | ## Settings
22 |
23 | | Property | Type | Default | Description |
24 | |---|---|---|---|
25 | |name | `string` | | Sets the name of the field in the database |
26 | |label | `string` | | Sets the label of the field that the user sees |
27 | |required | `boolean` | false | If true, the field is mandatory |
28 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
29 | |type | `string` | | Specifies the field type |
30 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
31 | |help | `string` | | Help text for the field that will appear with the field's label |
32 | |htmlHelp | `string` | | Help text with support for HTML markup |
33 |
--------------------------------------------------------------------------------
/docs/devops/cloud/storing-images-and-files-in-google-cloud-storage.md:
--------------------------------------------------------------------------------
1 | # Storing images and files in Google Cloud Storage (GCS)
2 |
3 | You can store your images and files in Google Cloud Storage (GCS) if you wish. You don't have to use the local file system.
4 |
5 | If you host in the Google cloud, this is essential to host an Apostrophe site in a multiserver configuration where the Node processes don't share the same filesystem (hint: they are on separate computers).
6 |
7 | Just take advantage of the [uploadfs](https://github.com/apostrophecms/uploadfs) module, which is built into Apostrophe.
8 |
9 | First sign up for [Google Cloud Storage](https://cloud.google.com/storage/) and create a Google Cloud Storage bucket in which to store your files.
10 |
11 | > When you create your bucket you must turn on support for Object ACLs.
12 |
13 | Next, [go to "Credentials" in the Google Cloud Platform console](https://console.cloud.google.com/apis/credentials). Create a service account if you haven't already giving it the role "Cloud Storage Admin." Then create a "service account key under that account. The key will be downloaded to your computer. Move that file to your project.
14 |
15 | Now add an `uploadfs` property to your configuration in `app.js`:
16 |
17 | ```javascript
18 | modules: {
19 | 'apostrophe-attachments': {
20 | uploadfs: {
21 | backend: 'gcs',
22 | bucket: 'yourownbucketnamefromgcs',
23 | region: 'us-east1'
24 | }
25 | }
26 | }
27 | ```
28 |
29 | Finally, **when you launch Apostrophe, make sure you set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable** to the location of the credentials file that you downloaded from the console. If you do not do this, you will get errors and it will not work.
30 |
31 | > To distinguish dev from production, consider using
32 | `process.env.GCS_BUCKET`, `process.env.GCS_REGION`, etc. to read
33 | these values from environment variables as well.
34 |
35 | With this configuration all file uploads are written to Google Cloud Storage instead of the local file system.
36 |
37 |
--------------------------------------------------------------------------------
/docs/reference/field-types/color.md:
--------------------------------------------------------------------------------
1 | # `color`
2 |
3 | A `color` field provides a colorpicker interface to the editor for choosing/inserting a color. Colors are saved as strings with a preferred format set in the optional `spectrumOptions` configuration object. The default is hex.
4 |
5 | Valid formats include `name`, `hex`, `hex8`, `rgb`, `hsl`, and `hsv`.
6 |
7 | The colorpicker interface is powered by Spectrum and you can provide a custom configuration passing a `spectrumOptions` object as part of the field. [Options and documentation for Spectrum here.](https://bgrins.github.io/spectrum/#options)
8 |
9 | ## Example
10 |
11 | ```javascript
12 | {
13 | type: 'color',
14 | name: 'bgColor',
15 | label: 'Background Color',
16 | spectrumOptions: {
17 | showPaletteOnly: true,
18 | showPalette:true,
19 | allowEmpty:true,
20 | palette: [
21 | ['black', 'white', 'blanchedalmond',
22 | 'rgb(255, 128, 0);', 'hsv 100 70 50'],
23 | ['red', 'yellow', 'green', 'blue', 'violet']
24 | ]
25 | }
26 | }
27 | ```
28 | ## Settings
29 |
30 | | Property | Type | Default | Description |
31 | |---|---|---|---|
32 | |name | `string` | | Sets the name of the field in the database |
33 | |label | `string` | | Sets the label of the field that the user sees |
34 | |spectrumOptions | `object` |See below | Provide custom configuration to the colorpicker interface |
35 | |required | `boolean` | false | If true, the field is mandatory |
36 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
37 | |type | `string` | | Specifies the field type |
38 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
39 | |help | `string` | | Help text for the field that will appear with the field's label |
40 | |htmlHelp | `string` | | Help text with support for HTML markup |
41 |
42 | `spectrumOptions` default value is:
43 |
44 | ```javascript
45 | {
46 | showButtons: true,
47 | showAlpha: true,
48 | preferredFormat: 'hex',
49 | showInput: true,
50 | allowEmpty: true
51 | }
52 | ```
53 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/suppressing-pieces-from-a-listing.md:
--------------------------------------------------------------------------------
1 | # Suppressing Pieces from a Listing
2 |
3 | In Apostrophe, you'll often display a nice single page or paginated list of pieces, using a module that extends `apostrophe-pieces-pages`. That could include official modules such as `apostrophe-blog-pages` as well as custom modules you create. We refer to these special pages as "index pages."
4 |
5 | It's common for an index page to have a featured piece, such as a news listing with featured article. It might then make sense to remove that featured piece from the main list so it doesn't appear duplicated on the page. To do this you'll want to add a filter to the index cursor so that it never makes it into your data object.
6 |
7 | In your module extending `apostrophe-pieces-pages`, extend `indexCursor` with the `super` pattern. You'll need to get the IDs of the pieces you're excluding, dropping them into an array. Then in the final return, use the `.and()` cursor method to add the additional MongoDB filter to only call for pieces that don't share those IDs.
8 |
9 | Example:
10 |
11 | ```javascript
12 | construct: function (self, options) {
13 | var superIndexCursor = self.indexCursor;
14 | self.indexCursor = function (req) {
15 | // 1. Establish an array to omit later. This is just one way to do this part.
16 | var omitIds = [];
17 |
18 | // 2. Do stuff to populate the array with IDs. This is based on a real example, but it'll vary based on your use case.
19 | var features = _.filter(req.data.page.['name-of-feature-area'].items, function (obj) {
20 | return obj.type === 'blog'; // Set this to the widget type name.
21 | });
22 |
23 | if (features.length > 0) {
24 | _.forEach(features, function (widget) {
25 | _.forEach(widget._pieces, function (piece) {
26 | omit.push(piece._id);
27 | });
28 | });
29 | }
30 |
31 | // 3. Return `superIndexCursor` filtering out pieces with the IDs. This is the key.
32 | return superIndexCursor(req).and({_id: {$nin: omitIds}});
33 | };
34 | }
35 | ```
36 |
37 |
--------------------------------------------------------------------------------
/docs/advanced-topics/database/replica-set.md:
--------------------------------------------------------------------------------
1 | # Using MongoDB replica sets with Apostrophe
2 |
3 | MongoDB *replica sets* provide redundant, highly available storage. Their purpose is to enhance reliability, not speed. For more information, see the [MongoDB documentation](https://docs.mongodb.com/manual/replication/).
4 |
5 | Once you have created a MongoDB replica set, you can connect to it by configuring Apostrophe to use the replica set's URI:
6 |
7 | ```javascript
8 | // app.js
9 | modules: {
10 | // Other modules, then...
11 | 'apostrophe-db': {
12 | uri: 'mongodb://host1,host2,host3/database-name?replicaSet=replica-set-name'
13 | }
14 | }
15 | ```
16 |
17 | `host1`, `host2` and `host3` are the hosts that make up your replica set. You should substitute the correct hostnames. This is just an example. If necessary you can specify nonstandard ports as well. See the MongoDB URI documentation.
18 |
19 | `database-name` should be the database name for your site, typically the same as the shortname of the site.
20 |
21 | `replica-set-name` should be the name that was given to the replica set while configuring it. Providing the `replicaSet` parameter in this way ensures that the MongoDB driver for Node.js understands that it is a replica set and can take advantage of a replica set's ability to change primary nodes if one of the servers goes down.
22 |
23 | ## Changing the read preference
24 |
25 | We do not recommend changing the MongoDB "read preference," and generally speaking, [neither does MongoDB](https://docs.mongodb.com/manual/core/read-preference/). It does not enhance throughput significantly and Apostrophe expects data to be reliably readable as soon as it is written. The purpose of using a replica set with Apostrophe is to enhance reliability by providing failover in the event of a server failure.
26 |
27 | ## Performance improvements
28 |
29 | If speed is your concern, replica sets are not the solution to that particular problem. The throughput of MongoDB is quite high, and you will often find that Apostrophe's node processes saturate the CPU before MongoDB does. If so, see the [multiple cores and/or servers](/devops/multicore.md) HOWTO.
30 |
--------------------------------------------------------------------------------
/docs/core-concepts/users-and-permissions/users-and-groups.md:
--------------------------------------------------------------------------------
1 | # Users and Groups
2 |
3 | One of the biggest questions you need to answer in your design is, "Who is going to be doing what?" From there you want to separate concerns for site management and content governance so that each user only has access to what they need is vital from a security perspective. Apostrophe has several options available to help you achieve this.
4 |
5 | ## Users
6 |
7 | The "user" is a concept as old as technology itself. You can imagine that when the wheel was invented, the creator of the wheel was the first user, and they provided permission to their friends to also be users. Access control was managed and enforced by a large club which was used to hit unauthorized users. On modern computer systems, each user is identified by their username, and access is enforced by login credentials which -- while not as fun as clubs -- are more effective at securing computer systems than trying to hit every unauthorized user with a club.
8 |
9 | ## Groups
10 |
11 | The "group" is a necessary extension of users. Rather than individually provide permission to each user, you add users to a group and provide permissions to that group, and by association, all the users who are a member of it. In the above example, the caveman had a group called "Friends" which were given access to the wheel, while all other users were excluded. Apostrophe primarily provides permissions through groups, and not directly to individual users.
12 |
13 | ## Creating Users
14 |
15 | New users are created and assigned to groups through the the admin bar in Apostrophe. To create new users,
16 |
17 | 1. Log on to Apostrophe.
18 |
19 | 2. Click on *Users* in the admin bar.
20 |
21 | 
22 |
23 | 3. Next, click *Add User* and fill in the user's information.
24 |
25 | 4. To define the users permissions, select the group from the select menu.
26 |
27 | 
28 |
29 | 5. Click *Save User* to add the user to the system.
30 |
31 | You can create as many users as you need, and you can edit users by clicking on their name after they are created.
32 |
33 | Next, you'll learn more about using groups and customizing your permissions.
34 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pieces/browser-apostrophe-pieces-editor-modal.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pieces-editor-modal (browser)
2 | ## Inherits from: [apostrophe-modal](../apostrophe-modal/browser-apostrophe-modal.md)
3 | An editor modal for creating and updating pieces. An instance of this modal is created
4 | each time you click "Add" or click to edit an existing piece. Relies on
5 | [apostrophe-schemas](/reference/modules/apostrophe-schemas) to edit the fields.
6 |
7 |
8 | ## Methods
9 | ### beforeShow(*callback*)
10 |
11 | ### afterShow()
12 | Make sure the field indicated by options.field is initially visible
13 | ### edit(*_id*, *callback*)
14 |
15 | ### create(*callback*)
16 |
17 | ### open(*verb*, *data*, *callback*)
18 |
19 | ### populate(*piece*, *callback*)
20 |
21 | ### beforePopulate(*piece*, *callback*)
22 |
23 | ### afterPopulate(*piece*, *callback*)
24 |
25 | ### saveContent(*callback*)
26 |
27 | ### displayError(*result*)
28 | Calls getErrorMessage with result.status and passes the
29 | returned string to apos.notify. This method is a good
30 | candidate for overrides because it has access to the
31 | entire result object. Invoked when result.status
32 | is not `ok`.
33 | ### getErrorMessage(*err*, *result*)
34 |
35 | ### beforeConvert(*piece*, *callback*)
36 |
37 | ### afterConvert(*piece*, *callback*)
38 |
39 | ### displayResponse(*result*, *callback*)
40 | Update the display in response to this item being saved.
41 |
42 | If the piece is brand new and the server provided
43 | a `_url` property and set `contextual: true` for this
44 | type of piece, or the piece has been updated and
45 | apos.pages.piece._id (the in-context piece) matches the
46 | id of the piece just edited, go to `_url`.
47 |
48 | In any case, the main content area is refreshed and the manage
49 | view, if open, refreshes its list (`apos.change` is invoked).
50 | This will all make sense if the URL hasn't changed, and do no
51 | harm if it has.
52 | ### onChange(*e*)
53 |
54 | ### trash(*$el*, *next*)
55 |
56 | ### rescue(*$el*, *next*)
57 |
58 | ### versions(*$el*)
59 |
60 | ### copy(*$el*)
61 | Save this modal, then open a new modal to create a new piece of
62 | this type that starts out as a copy of the current piece
63 | ### displayResponse(*result*, *callback*)
64 |
65 | ### afterHide()
66 |
67 |
--------------------------------------------------------------------------------
/docs/reference/field-types/joinbyonereverse.md:
--------------------------------------------------------------------------------
1 | # `joinByOneReverse`
2 |
3 | A `joinByOneReverse` field allows us to access the other side of a [joinByOne](/reference/field-types/joinbyone.md) relationship. Since this is the "other end" of the relationship, there is no editing interface. It is just a convenience allowing us to "see" the related object from the other point of view.
4 |
5 | ::: tip
6 | For backwards compatibility, you can set the `idField` option instead to match that in the other join, but this is confusing and hard to maintain. Just use `reverseOf`.
7 | :::
8 |
9 | ## Example
10 |
11 | ```javascript
12 | // Part of our schema for fabrics (see the joinByOne example)
13 | {
14 | // No editing interface is currently offered, edit it from the other end
15 | //
16 | // Name is plural because more than one product might be joining to
17 | // each fabric; that's why `_products` will be an array
18 | name: '_products',
19 | type: 'joinByOneReverse',
20 | // Optional since our join name matches the other type's name
21 | withType: 'product',
22 | // Optional since there is only one join to fabrics in the other type
23 | reverseOf: '_fabric',
24 | }
25 | ```
26 |
27 | We can now see `_product` as a property of each `fabric` object that is related to a product.
28 |
29 | ## Settings
30 |
31 | | Property | Type | Default | Description |
32 | |---|---|---|---|
33 | |name | `string` | | Sets the name of the field in the database |
34 | |type | `string` | | Specifies the field type |
35 | |withType | `string` | | The name of the related type, if it differs from the name of the join. If you do not set `withType`, then the name of the join must match the name of the related type, with a leading `_` added. || reverseOf | `string` | | Set to the name of the join you are reversing (optional) |
36 | |ifOnlyOne | `boolean` | false | If true, it will only carry out the join if the query that returned the original document returned only one document. This is useful if the joined information is only to be displayed on the `show.html` page of a piece, for instance, and you don't want the performance impact of loading it on the `index.html` page. |
37 |
38 | ::: tip
39 | In documents with many joins in play, the `ifOnlyOne` option will avoid running through all the possible joins, and can be used to avoid a heavy performance impact in complex documents.
40 | :::
41 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-utils/browser-apostrophe-context.md:
--------------------------------------------------------------------------------
1 | # apostrophe-context (browser)
2 | A base class with convenience methods for modals and other types that
3 | have an action and optionally a jquery element (self.$el). Your
4 | subclass is responsible for setting self.$el in its constructor if
5 | you wish to use methods that expect it, such as self.link. The
6 | other methods just expect options.action to be present.
7 |
8 | Also takes care of setting self.options and self.action for you.
9 |
10 |
11 | ## Methods
12 | ### link(*verb*, *object*, *fn*)
13 | If an element with a `[data-verb-object]`
14 | attribute is clicked, invoke `fn` method
15 | with the jquery element clicked upon, and the
16 | value of the attribute. Mixed case
17 | in `verb` and `object` is converted to
18 | hyphenation before adding the click handler.
19 |
20 | Can also be called with just (verb, fn)
21 | if you are just looking for `[data-verb]`.
22 |
23 | Event propagation and the default behavior of
24 | the click event are both automatically stopped.
25 |
26 | Your subclass must set self.$el to use this method.
27 |
28 | The word "object" refers to "the object of the sentence."
29 | It is a *string*, not a javascript object.
30 | ### api(*route*, *data*, *options*, *success*, *failure*)
31 | Invoke a JSON API route implemented by the Apostrophe module
32 | associated with this object, or by another module if the
33 | ":" syntax is used, like: `module-name:verb`
34 |
35 | `options` and `failure` may be omitted entirely.
36 |
37 | Typical example:
38 |
39 | self.api('update', { age: 50 }, function(result) {
40 | if (result.status === 'ok') { ... }
41 | });
42 |
43 | See $.jsonCall for details of how the call is made.
44 | ### html(*route*, *options*, *data*, *success*, *failure*)
45 | Invoke an API route implemented by the Apostrophe module
46 | associated with this object, or by another module if the
47 | ":" syntax is used, like: `module-name:verb`
48 |
49 | The response is expected to be markup, not JSON. Otherwise
50 | this method is very similar to the `api` method.
51 |
52 | `options` and `failure` may be omitted entirely.
53 |
54 | Typical example:
55 |
56 | self.html('editor', { _id: 5555 }, function(html) {
57 | self.$editorDiv.html(html);
58 | }, function() {
59 | apos.notify('An error occurred', { type: 'error', dismiss: true });
60 | });
61 |
62 | See $.jsonCall for details.
63 |
--------------------------------------------------------------------------------
/docs/core-concepts/modules/nested-module-folders.md:
--------------------------------------------------------------------------------
1 | # Nested module folders
2 |
3 | Apostrophe 2.x has optional support for nested subdirectories of modules, tucked
4 | inside `lib/modules`.
5 |
6 | You must set the `nestedModuleSubdirs` option to `true` in `app.js`, like this:
7 |
8 |
9 | ```javascript
10 | // app.js
11 | require('apostrophe')({
12 | shortName: 'my-project',
13 | nestedModuleSubdirs: true
14 | // etc., you may have additional options here as always
15 | modules: {
16 | // You can still configure some modules here, or move it all to modules.js
17 | // files in subdirectories, as seen below
18 | }
19 | });
20 | ```
21 |
22 |
23 | Now you can nest modules in subdirectories, like this. Start with a `modules.js`
24 | file in the parent `lib/modules/products` folder. Here you can activate all of the
25 | modules that relate to products, making `app.js` shorter:
26 |
27 |
28 | ```javascript
29 | // lib/modules/products/modules.js
30 | module.exports = {
31 | 'products': {},
32 | 'products-pages': {},
33 | 'products-widgets': {}
34 | };
35 | ```
36 |
37 |
38 | And then you can implement those modules in their own sub-subdirectories:
39 |
40 |
41 | ```javascript
42 | // lib/modules/products/products/index.js
43 | module.exports = {
44 | extend: 'apostrophe-pieces',
45 | name: 'product'
46 | };
47 | ```
48 |
49 |
50 | ```javascript
51 | // lib/modules/products/products-pages/index.js
52 | module.exports = {
53 | extend: 'apostrophe-pieces-pages',
54 | label: 'Products Page'
55 | };
56 | ```
57 |
58 |
59 | ```javascript
60 | // lib/modules/products/products-widgets/index.js
61 | module.exports = {
62 | extend: 'apostrophe-pieces-widgets',
63 | label: 'Products'
64 | };
65 | ```
66 |
67 | The resulting directory tree looks like this:
68 |
69 | ```
70 | /app.js
71 | /lib/modules
72 | /lib/modules/products (modules.js lives here, activates three modules)
73 | /lib/modules/products/products (index.js for the product pieces lives here)
74 | /lib/modules/products/product-pages (index.js, views/show.html, etc.)
75 | /lib/modules/products/product-widgets (index.js, views/widget.html, etc.)
76 | ```
77 |
78 | Just remember: **the names of the parent folders do not matter, and the names of the actual
79 | module folders at the bottom MUST still match the name of each module.**
80 |
81 | By following through with this approach you can make `app.js` much shorter.
82 |
83 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-widgets/browser-apostrophe-widgets.md:
--------------------------------------------------------------------------------
1 | # apostrophe-widgets (browser)
2 | ## Inherits from: [apostrophe-context](../apostrophe-utils/browser-apostrophe-context.md)
3 | `apostrophe-widgets` is a parent class for the browser-side managers of
4 | widget types. Each manager object is responsible for *all* widgets of that type.
5 |
6 | Extends `apostrophe-context` in order to gain access to conveniences like
7 | the `self.api` and `self.html` methods. There is no `self.$el`, because
8 | this object manages many widgets.
9 |
10 | The `play` method, if it exists, is invoked when appropriate with `($widget, data, options)`,
11 | and should enhance that specific widget. The `play` method should **never** use
12 | `$(...)` selectors, instead always using `$widget.find(...)` to scope them to that
13 | specific widget.
14 |
15 |
16 | ## Methods
17 | ### getData(*$widget*)
18 | Supply me in your subclass if your widget
19 | needs a player, such as a slideshow animation
20 | self.play = function($widget, data, options) {
21 | }
22 | Get the data associated with the widget. By
23 | default this is just the data attribute's
24 | JSON data, but some widgets, like apostrophe-rich-text,
25 | also store data as markup
26 | ### setData(*$widget*, *data*)
27 |
28 | ### canEdit(*$widget*)
29 | Returns true if we are allowed to edit this widget.
30 | Independent of `getData` because that is sometimes
31 | overridden but this is always the right place to get
32 | the `_edit` flag from.
33 |
34 | If editing would otherwise be permitted but is specifically
35 | disabled for this area for workflow reasons, false is returned.
36 | ### edit(*data*, *options*, *save*)
37 | Opens the editor modal of a widget, unless the widget is contextualOnly,
38 | in which case we simply save the widget and call the save method
39 | Widget can opitonally be set to skipInitialModal which skips the first
40 | edit modal but binds future editing interactions
41 | ### isEmpty(*$widget*)
42 | Area editor calls this to determine whether to apply an empty state
43 | class for the widget
44 | ### getData(*$widget*)
45 |
46 | ### startAutosavingAreaThen(*$widget*, *fn*)
47 | Start autosaving the area containing the given widget,
48 | then invoke the given function. On failure fn is not invoked.
49 | Invoked by widgets that are edited contextually on the page,
50 | like apostrophe-rich-text, as opposed to widgets edited
51 | via a modal.
52 |
--------------------------------------------------------------------------------
/docs/howtos/windows.md:
--------------------------------------------------------------------------------
1 | # Running Apostrophe on Windows
2 |
3 | *Thanks to Andrew Brown for the original version of this HOWTO, which has been updated.*
4 |
5 | ## Step 1: Install Software
6 |
7 | For Apostrophe 2 to work on Windows you need to install:
8 |
9 | * Git
10 | * Nodejs
11 | * MongoDB
12 | * Imagemagick (for image manipulation- required by Apostrophe)
13 |
14 | ## Where to get the software
15 |
16 | To install git go to [Git - Downloads](http://git-scm.com/downloads) and download the appropriate version. **Be sure when asked about adjusting your path environment you select "Use Git from the Windows Command Prompt."**
17 |
18 | To install Node go to [http://nodejs.org/](http://nodejs.org/) and click install. Keep all settings the same and it will also make sure node and npm are accessible at the command line.
19 |
20 | To install MongoDB go to [Downloads - MongoDB](http://www.mongodb.org/downloads) and select the proper download for your computer. Be sure to select 32 or 64 bit depending on your system. Follow all of the prompts.
21 |
22 | To install Imagemagick go to: [ImageMagick : Windows Downloads](http://www.imagemagick.org/script/download.php#windows) and download the latest version. Ensure that "add environmental variables to system path" is checked during the installation process. **Make sure you check the box to install legacy executables.**
23 |
24 | ## MongoDB setup
25 |
26 | MongoDB should automatically start up and begin operation if you allowed it to install itself according to the defaults. If not, you will need to start it manually. See the MongoDB documentation.
27 |
28 | ## Step 2: You're good to go!
29 |
30 | Be aware of the differences in syntax between macOS and Windows terminals. `cp` translates to `copy`, `rm` to `del`, etc.
31 |
32 | Otherwise, the tutorial provided by [Apostrophe: Getting Started](/getting-started/setting-up-your-environment.md) can be followed.
33 |
34 | NOTE: if you get permissions errors, you probably first created the site as Administrator. Make up your mind and stick to one user... which should not be Administrator. It is always a good security policy to avoid using an administrator account when you can.
35 |
36 | > You may get a "Windows Firewall has blocked some features of this app" when you start Apostrophe on Windows for the first time. That's because Apostrophe is a type of web server, and any server process requires your permission. Be sure to grant it.
37 |
38 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-locks.md:
--------------------------------------------------------------------------------
1 | # apostrophe-locks
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | ### `apos.locks`
4 |
5 | ## Methods
6 | ### lock(*name*, *options*, *callback*)
7 | Obtain a lock with the given name. The lock remains exclusive until
8 | we unlock it (except for certain situations in unusual synchronous code,
9 | see below).
10 |
11 | We MUST release the lock later by calling `unlock` with the same name.
12 |
13 | If the lock is in use by another party, this method will wait until it is
14 | no longer in use, unless `options.wait` is present. If `options.wait`
15 | is explicitly `false`, the method will not wait at all, and
16 | the error reported will be the string `'locked'`. If `options.wait`
17 | is a number, the method will wait that many milliseconds before
18 | reporting the `locked` error.
19 |
20 | The `options` argument can be omitted completely.
21 |
22 | Calling this method when you already have the specified lock will
23 | yield an error unless the `waitForSelf` option is true.
24 |
25 | If you call without a callback, a promise is returned instead.
26 |
27 | SYNCHRONOUS CODE: if you need to go more than 30 seconds without ever returning to the
28 | event loop, set `options.idleTimeout` to a longer period of time (in milliseconds).
29 | This applies only to synchronous code. (And seriously, why are you running
30 | without returning for 5 minutes in nodejs? Nobody can see your site while you do that.)
31 | ### unlock(*name*, *callback*)
32 | Release the given lock name. You must first obtain a lock successfully
33 | via `lock`. Calling this method when you do not already have the lock will
34 | yield an error.
35 |
36 | If you call without a callback, a promise is returned instead.
37 | ### withLock(*name*, *fn*, *callback*)
38 | Obtains the named lock, then invokes the provided function,
39 | which must take one argument (a callback), or
40 | take zero arguments and return a promise. Then `callback`
41 | is invoked or, if there is no callback, an error is returned.
42 |
43 | You can think of this as an "upgrade" of your function to
44 | run within a lock in every way. If you use promises,
45 | the promise returned by `withLock` will resolve to the
46 | value that `fn` resolves to. If you use callbacks, the
47 | second argument is passed on as you would expect.
48 |
49 | You may omit `callback`, in which case `withLock`
50 | returns a promise.
51 |
52 | The lock gets released at the end, whether fn results in an
53 | error or not.
54 | ### ensureCollection(*callback*)
55 |
56 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-pages/server-apostrophe-pages-cursor.md:
--------------------------------------------------------------------------------
1 | # apostrophe-pages-cursor (server)
2 | ## Inherits from: [apostrophe-cursor](../apostrophe-docs/server-apostrophe-cursor.md)
3 |
4 | ## Methods
5 | ### ancestorPerformanceRestrictions()
6 | Apply default restrictions suitable for fetching ancestor pages to the cursor as
7 | a starting point before applying the ancestor options. Called by the
8 | ancestors filter here and also by pages.pageBeforeSend when it fetches just
9 | the home page using the same options, in the event ancestors were not loaded,
10 | such as on the home page itself. You should not need to modify or invoke this.
11 | ### isPage(*value*)
12 | Filter. When calling `self.pages.find` our expectation is that we will only get pages,
13 | not docs that are not a part of the page tree. This filter defaults to `true`.
14 | ### ancestors(*value*)
15 | Filter. If set to `true`, retrieve the ancestors of each page and assign them
16 | to the `._ancestors` property. The home page is `._ancestors[0]`. The
17 | page itself is not included in its `._ancestors` array.
18 |
19 | If the argument is an object, do all of the above, and also call the
20 | filters present in the object on the cursor that fetches the ancestors.
21 | For example, you can pass `{ children: true }` to fetch the children of
22 | each ancestor as the `._children` property of each ancestor, or pass
23 | `{ children: { depth: 2 } }` to get really fancy.
24 |
25 | `ancestors` also has its own `depth` option, but it doesn't do what you think.
26 | If the `depth` option is present as a top-level property of the object passed
27 | to `ancestors`, then only that many ancestors are retrieved, counting backwards
28 | from the immediate parent of each page.
29 | ### orphan(*value*)
30 | Filter. if flag is `null`, `undefined` or this method
31 | is never called, return docs regardless of
32 | orphan status. if flag is `true`, return only
33 | orphan docs. If flag is `false`, return only
34 | docs that are not orphans. Orphans are pages that
35 | are not returned by the default behavior of the
36 | `children` filter implemented by `apostrophe-pages-cursor`
37 | and thus are left out of standard navigation.
38 | ### children(*value*)
39 |
40 | ### reorganize(*value*)
41 | Use .reorganize(true) to return only pages that
42 | are suitable for display in the reorganize view.
43 | For instance, if you have thousands of subpages
44 | of a "blog" page, you might want to hide them from
45 | the global reorganize interface by setting their
46 | reorganize property to false.
47 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-docs/browser-apostrophe-docs.md:
--------------------------------------------------------------------------------
1 | # apostrophe-docs (browser)
2 |
3 | ## Methods
4 | ### getManager(*type*)
5 |
6 | ### setManager(*type*, *manager*)
7 |
8 | ### lock(*_id*, *callback*)
9 | Obtain a lock on the given doc _id, interacting with the user
10 | if necessary to give them the option of shattering another
11 | user's lock. Invokes the callback with null on a successful lock,
12 | an error otherwise. If `id` is falsy, the callback succeeds
13 | immediately, because this indicates a new doc that no one
14 | else could know about or have a lock on. The lock is
15 | granted to the current html page.
16 | ### lockAndWatch(*_id*, *callback*)
17 | Obtain a lock via the lock method, then
18 | watch the lock by periodically verifying
19 | whether the lock is still held. If the
20 | lock is lost the user is notified and
21 | the page is reloaded. This method is used
22 | by the modal editor for pieces, since they
23 | do not otherwise carry out autosave operations
24 | that would quickly make the user aware a lock has
25 | been seized by someone else.
26 |
27 | The callback is invoked as soon as
28 | the lock method succeeds, and monitoring
29 | then proceeds in the background, stopping if unlock()
30 | is invoked successfully.
31 | ### unlock(*_id*, *sync*, *callback*)
32 | Release a lock on the given doc _id, if any.
33 | Callback succeeds (receives `null`) as long as the
34 | current HTML page does not have a lock anymore after
35 | the call, whether they initially had one or not.
36 |
37 | If `sync` is true a synchronous call is made.
38 | This is normally a bad thing, but it is appropriate
39 | in a beforeunload handler.
40 |
41 | `callback` is optional.
42 | ### enableFix()
43 | Watch for clicks on links with a [data-apos-fix-id], and open
44 | the relevant document for editing, displaying the
45 | [data-apos-fix-hint] first to explain why the document is being
46 | opened and ask the user to confirm. This is designed for use cases
47 | such as editing a document that is "camping" on the slug we want to
48 | use for another document. The implementation of the hint is currently
49 | an alert, but this API allows for us to gracefully upgrade that
50 | at any time.
51 |
52 | The data-apos-fix-id, data-apos-fix-type and data-apos-fix-url
53 | attributes should be populated on your link or button.
54 | If you know the doc is a piece, not a page, you can skip
55 | the url attribute.
56 |
57 | If data-apos-fix-error is present, the error with the same name
58 | is removed from the enclosing fieldset when the link is clicked.
59 |
--------------------------------------------------------------------------------
/docs/reference/field-types/joinbyarrayreverse.md:
--------------------------------------------------------------------------------
1 | # `joinByArrayReverse`
2 |
3 | A `joinByArrayReverse` field allows us to access the other side of a [joinByArray](/reference/field-types/joinbyarray.md) relationship. Since this is the "other end" of the relationship, there is no editing interface. It is just a convenience allowing us to "see" the related objects from the other point of view.
4 |
5 | ::: tip
6 | For backwards compatibility, you can set the `idField` option instead to match that in the other join, but this is confusing and hard to maintain. Just use `reverseOf`.
7 | :::
8 |
9 | ## Example
10 |
11 | ```javascript
12 | // Part of our schema for fabrics (see the joinByArray example)
13 | {
14 | // No actual editing interface is currently offered, edit it from the other end
15 | name: '_products',
16 | type: 'joinByArrayReverse',
17 | // Optional since the name of our join matches the name of the type, plus an s
18 | withType: 'product',
19 | // Optional since there is only one join with fabrics in the product schema
20 | reverseOf: '_fabrics'
21 | }
22 | ```
23 |
24 | We can now see `_products` as a property of each `fabric` object that is related to a product.
25 |
26 | If desired, we can specify `relationship` and `relationshipsField` just as we would for `joinByArray`. Currently these are not automatic in a reverse join and must be fully specified if relationship properties are to be accessed. Most array joins do not have relationship properties and thus do not require reverse access to them.
27 |
28 | ## Settings
29 |
30 | | Property | Type | Default | Description |
31 | |---|---|---|---|
32 | |name | `string` | | Sets the name of the field in the database |
33 | |type | `string` | | Specifies the field type |
34 | |withType | `string` | | The name of the related type, if it differs from the name of the join. If you do not set `withType`, then the name of the join must match the name of the related type, with a leading `_` added. |
35 | |reverseOf | `string` | | Set to the name of the join you are reversing (optional) |
36 | |ifOnlyOne | `boolean` | false | If true, it will only carry out the join if the query that returned the original document returned only one document. This is useful if the joined information is only to be displayed on the `show.html` page of a piece, for instance, and you don't want the performance impact of loading it on the `index.html` page. |
37 |
38 | ::: tip
39 | In documents with many joins in play, the `ifOnlyOne` option will avoid running through all the possible joins, and can be used to avoid a heavy performance impact in complex documents.
40 | :::
41 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/adding-fields-to-all-pieces.md:
--------------------------------------------------------------------------------
1 | # Adding fields to all pieces
2 |
3 | Apostrophe's schemas are a powerful way to add fields to any type of piece or page. But sometimes you'll have a field you want to add to every type of piece. Here's how to do that.
4 |
5 | ## Adding a field to all pieces
6 |
7 | As explained in the tutorials, the [apostrophe-pieces](/reference/modules/apostrophe-pieces/README.md) module is a great way to create reusable content that appears all over the site — both on [apostrophe-pieces-pages](/reference/modules/apostrophe-pieces-pages/README.md) and in [apostrophe-pieces-widgets](/reference/modules/apostrophe-pieces-widgets/README.md).
8 |
9 | We've seen how we can add fields to these by using the `addFields` option when configuring each module. But sometimes we want to add a field to `every` type of piece. We can do that by configuring the `apostrophe-pieces` module itself.
10 |
11 | *Any configuration we set for `apostrophe-pieces` becomes part of the configuration for all of the modules that extend it.*
12 |
13 | Our first idea might be to do this in `app.js`:
14 |
15 | ```javascript
16 | // lib/modules/apostrophe-pieces/index.js
17 |
18 | // THIS WON'T WORK
19 | modules: {
20 | 'apostrophe-pieces': {
21 | addFields: [
22 | {
23 | type: 'string',
24 | name: 'author',
25 | label: 'Author'
26 | }
27 | ]
28 | }
29 | }
30 | ```
31 |
32 | **This won't quite work.** The reason is that the `addFields` option set for each subclass overrides it.
33 |
34 | Another problem is that we wind up with "Pieces" on the admin bar. If we configure a module in `app.js`, Apostrophe assumes we want to use that module, not just extend it to create new modules.
35 |
36 | So instead, we'll write a `beforeConstruct` function in `lib/modules/apostrophe-pieces/index.js`. The great thing about `beforeConstruct` is that it is *called for the subclasses first*. That means that by the time it is called for us, *all the fields for the subclass are already in `addFields`*. We can simply prepend our own:
37 |
38 |
39 | ```javascript
40 | // lib/modules/apostrophe-pieces/index.js
41 |
42 | // THIS WILL WORK!
43 | module.exports = {
44 |
45 | beforeConstruct: function(self, options) {
46 | options.addFields = [
47 | {
48 | type: 'string',
49 | name: 'author',
50 | label: 'Author'
51 | }
52 | ].concat(options.addFields || [])
53 | }
54 | }
55 | ```
56 |
57 | ### Making exceptions
58 |
59 | If one of your subclasses of pieces doesn't need the `author` field, just use the `removeFields` option in that module.
60 |
61 |
--------------------------------------------------------------------------------
/docs/advanced-topics/how-apostrophe-starts-up.md:
--------------------------------------------------------------------------------
1 | # How Apostrophe starts up
2 |
3 | This tutorial covers how Apostrophe initializes itself. In the process, it provides insight into how you can influence that process and the best times to do things in your own modules.
4 |
5 | ## Initialization of modules
6 |
7 | When the application starts up, the modules initialize in the order found in `node_modules/apostrophe/default.js`, followed by any project level or npm modules, in the order configured in `app.js`.
8 |
9 | ### Initialization of an individual module
10 |
11 | When initializing, an individual module invokes `beforeConstruct` at project level first, then at npm module level; note that project level code runs first here to adjust the `options` if needed before the base class sees them. If a module extends another, the subclass runs first, again getting a chance to adjust `options` before the base class sees them.
12 |
13 | Then `construct` runs for this module, this time starting with the base class, so that the subclasses can override methods assigned there.
14 |
15 | Then `afterConstruct` runs for the module. Ideally `construct` doesn’t do anything but set up methods, so that `afterConstruct` can safely invoke them, knowing that any subclass overrides have already happened.
16 |
17 | See the [moog documentation](https://npmjs.org/package/moog) for more information about `beforeConstruct`, `construct` and `afterConstruct`.
18 |
19 | ### Running code after all modules are constructed
20 |
21 | After all of the modules are initialized, Apostrophe invokes the `modulesReady` methods of any modules that have one, in the order those modules were initialized. This is a good time to do work that requires other modules initialized after yours.
22 |
23 | Note that your `modulesReady` method may optionally take a callback.
24 |
25 | If you are extending another module, be sure to check whether it already has a `modulesReady` method and invoke it via the super pattern if so.
26 |
27 | ### Running code after `modulesReady`
28 |
29 | The last thing Apostrophe does before listening for connections, or running the task in the case of a command line task, is invoking the `afterInit` method of any module that has one.
30 |
31 | Like `modulesReady`, `afterInit` may also take a callback if it needs to do asynchronous work.
32 |
33 | ### `afterInit` in `app.js`
34 |
35 | You may also supply a top-level `afterInit` property in your `app.js` configuration. If provided this function must take a callback. We recommend using `modulesReady` or `afterInit` in a project-level module instead. Cluttering up `app.js` with executable code generally leads to hard-to-understand projects.
36 |
37 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-versions/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-versions
2 | ## Inherits from: [apostrophe-module](../apostrophe-module/README.md)
3 | ### `apos.versions`
4 | Provides versioning for all docs in Apostrophe. Every time a doc
5 | is updated, a new version of it is created in the `aposVersions` collection.
6 | A UI is provided for viewing past versions and rolling back to them.
7 |
8 | Versions contain only properties that are not marked as unsafe
9 | for rollback.
10 |
11 | For space reasons, older versions are gradually pruned to be more sparse
12 | (infrequent) as you go back in time, however an attempt is made to
13 | preserve most transitions between different individuals editing content.
14 |
15 |
16 | ## Methods
17 | ### enableCollection(*callback*) *[api]*
18 |
19 | ### ensureIndexes(*callback*) *[api]*
20 |
21 | ### docAfterSave(*req*, *doc*, *options*, *callback*) *[api]*
22 |
23 | ### pruneOldVersions(*doc*, *callback*) *[api]*
24 | Prune old versions so that the database is not choked
25 | with them. If a version's time difference relative to
26 | the previous version is less than 1/24th the time
27 | difference from the newest version, that version can be
28 | removed. Thus versions become more sparse as we move back
29 | through time. However if two consecutive versions have
30 | different authors we never discard them because
31 | we don't want to create a false audit trail.
32 | ### revert(*req*, *version*, *callback*) *[api]*
33 | Revert to the specified version. The doc need not be passed
34 | because it is already in version._doc.
35 | ### find(*req*, *criteria*, *options*, *callback*) *[api]*
36 | Searches for versions.
37 |
38 | The callback is invoked like this:
39 |
40 | callback(null, versions)
41 |
42 | The most recent version is first in the array.
43 |
44 | options.skip and options.limit may be used to paginate.
45 | If options.compare is set, then for each version ._changes
46 | will be set to an array of changes since the preceding version
47 | in the result set.
48 |
49 | Permissions for the document associated with the returned
50 | versions are checked. Any attempt to retrieve multiple versions
51 | from different documents will result in an error.
52 |
53 | The ._doc property of each version is set to the document.
54 | ### compare(*req*, *doc*, *version1*, *version2*, *callback*) *[api]*
55 | Compares two versions and returns a description of
56 | the differences between them. The description is an
57 | array of objects, which may contain nested `changes`
58 | arrays when changed properties are areas or
59 | schema arrays. version2 is assumed to be the
60 | newer version. The doc is examined to determine what
61 | schema to use.
62 |
--------------------------------------------------------------------------------
/docs/devops/cloud/storing-images-and-files-in-amazon-s3.md:
--------------------------------------------------------------------------------
1 | # Storing images and files in Amazon S3
2 |
3 | You can store your images and files in Amazon S3 if you wish. You don't have to use the local file system.
4 |
5 | This is essential to host an Apostrophe site on Heroku, or an Amazon EC2 instance without persistent storage.
6 |
7 | Just take advantage of the [uploadfs](https://github.com/apostrophecms/uploadfs) module, which is built into Apostrophe.
8 |
9 | First sign up for [Amazon Web Services](http://aws.amazon.com/s3/) and create an S3 bucket in which to store your files. **Do not use the us-east region** for reasons explained below.
10 |
11 | During the signup process you will obtain an AWS secret and key which are needed as part of the configuration.
12 |
13 | Here's a working Amazon S3 configuration. Just add an `uploadfs` property to your configuration in `app.js`:
14 |
15 | ```javascript
16 | modules: {
17 | 'apostrophe-attachments': {
18 | uploadfs: {
19 | backend: 's3',
20 | secret: 'YOUR AMAZON SECRET',
21 | key: 'YOUR AMAZON KEY',
22 | bucket: 'your-bucket-name',
23 | region: 'us-west-2'
24 | }
25 | }
26 | }
27 | ```
28 |
29 | With this configuration all file uploads are written to S3 instead of the local file system.
30 |
31 | > You may pass any options supported by the [knox](https://npmjs.org/package/knox) module.
32 |
33 | ### HTTPS file delivery
34 | To receive file from S3 via the secure HTTPS protocol, add an `https: true` option to your uploadfs options object.
35 |
36 | ## Special requirements for the US-East region
37 |
38 | The US-East region is misnamed; it is really "US Standard," and it serves files from both Oregon and Virginia.
39 |
40 | As a consequence, it does not offer "read after write" consistency. This means that a file that `uploadfs` just stored will **not necessarily be available to view right away.** This is **not a good user experience** for users who are uploading images to Apostrophe and expecting to see them right away.
41 |
42 | [See this article for a detailed description of how long "eventual" consistency can really take.](http://www.stackdriver.com/eventual-consistency-really-eventual/)
43 |
44 | So, just use a bucket in any other region, such as `us-west-2`.
45 |
46 | If the East Coast is the best fit for you, use this instead as your "region" setting:
47 |
48 | `external-1`
49 |
50 | In June 2015, Amazon announced that the US-East region supports read-after-write consistency, but [only if you use the s3-external-1 endpoint](https://forums.aws.amazon.com/ann.jspa?annID=3112). Setting `region` to `external-1` will cause uploadfs to use the proper URLs for this. (Note: do not include the `s3-` in the string.)
51 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-tags/README.md:
--------------------------------------------------------------------------------
1 | # apostrophe-tags
2 | ## Inherits from: [apostrophe-pieces](../apostrophe-pieces/README.md)
3 | ### `apos.tags`
4 | The `apostrophe-tags` module provides administration tools for managing
5 | tags on the site. This module subclasses pieces in order to provide a way
6 | to store tags that were created directly in the tag administration interface
7 | and do not appear on any other types of pieces yet. This ensures that they
8 | are visible when autocompleting tags.
9 |
10 |
11 | ## Methods
12 | ### listTags(*req*, *options*, *callback*) *[api]*
13 | Obtain a list of tags beginning with `options.prefix`, or all tags
14 | if `options.all` is set, or specific tags if `options.tags` is set.
15 | On success, invokes the callack with `(null, tags)`
16 | ### addTag(*req*, *tag*, *callback*) *[api]*
17 | Add a tag, as submitted via the tags admin interface. Other modules
18 | do not need to call this method; they can just add the tag to the
19 | `tags` property of any doc.
20 | ### renameTag(*req*, *tag*, *newTag*, *callback*) *[api]*
21 | Rename an existing tag throughout Apostrophe.
22 | ### deleteTag(*req*, *tag*, *callback*) *[api]*
23 | Delete an existing tag throughout Apostrophe.
24 | ### launder(*tag*) *[api]*
25 | Launder (sanitize) a tag. The default behavior is to call the
26 | `filterTag` method of `launder`, which converts to lowercase and
27 | trims whitespace.
28 |
29 | Fair warning: if you disable conversion to a consistent case, you will have
30 | a lot more trouble with duplicate tags.
31 | ### beforeListTags(*req*, *options*, *callback*) *[implementation]*
32 | Overridable hook
33 | ### afterListTags(*req*, *options*, *callback*) *[implementation]*
34 | Overridable hook
35 | ### beforeAddTag(*req*, *tag*, *callback*) *[implementation]*
36 | Overridable hook
37 | ### afterAddTag(*req*, *tag*, *callback*) *[implementation]*
38 | Overridable hook
39 | ### beforeRenameTag(*req*, *tag*, *newTag*, *callback*) *[implementation]*
40 | Overridable hook
41 | ### afterRenameTag(*req*, *tag*, *newTag*, *callback*) *[implementation]*
42 | Overridable hook
43 | ### beforeDeleteTag(*req*, *tag*, *callback*) *[implementation]*
44 | Overridable hook
45 | ### afterDeleteTag(*req*, *tag*, *callback*) *[implementation]*
46 | Overridable hook
47 | ### createRoutes() *[routes]*
48 |
49 | ### pushAssets() *[browser]*
50 |
51 | ### pushDefinitions() *[browser]*
52 |
53 | ## Nunjucks template helpers
54 | ### menu()
55 |
56 | ## API Routes
57 | ### POST /modules/apostrophe-tags/manager
58 |
59 | ### POST /modules/apostrophe-tags/listTags
60 |
61 | ### POST /modules/apostrophe-tags/addTag
62 |
63 | ### POST /modules/apostrophe-tags/renameTag
64 |
65 | ### POST /modules/apostrophe-tags/deleteTag
66 |
67 | ### POST /modules/apostrophe-tags/autocomplete
68 |
69 |
--------------------------------------------------------------------------------
/_tip-ins/modules.md:
--------------------------------------------------------------------------------
1 | # Modules in Apostrophe
2 |
3 | Every Apostrophe site is made up of modules. You can browse the complete list at left.
4 |
5 | ## Overview
6 |
7 | Each module provides a particular feature, often including both front and back end code, as well as templates and stylesheets. For instance, the [apostrophe-assets](apostrophe-assets/README.md) module provides core services relating to assets like stylesheets.
8 |
9 | Modules are implemented as [moog types](/reference/glossary.md#moog-type), which provide a simple and clean way to write them in an object-oriented style while keeping async programming convenient and providing easy subclassing and overriding.
10 |
11 | For convenience, the `apostrophe` npm module contains all of the "core" Apostrophe modules that are necessary for a functioning website.
12 |
13 | Some of these, like [apostrophe-docs](apostrophe-docs/README.md), are initialized every time Apostrophe starts up; you can [see that list on github](https://github.com/apostrophecms/apostrophe/blob/2.0/defaults.js). Those modules are initialized first, followed by those you configure in `app.js`, in the order you configure them.
14 |
15 | Others, like [apostrophe-pieces](apostrophe-pieces/README.md) and [apostrophe-widgets](apostrophe-widgets/README.md), are "abstract base classes" you can extend to create new modules that provide content types.
16 |
17 | [apostrophe-module](apostrophe-module/README.md) is the base class of **all** modules; it provides features that are convenient in almost any module, like [rendering a template from its `views` folder](apostrophe-module/README.md#render), or [pushing assets from its `public` folder](apostrophe-module/README.md#push-asset).
18 |
19 | Modules can also be installed via npm, and multiple Apostrophe modules can be [shipped as a single npm module via moog bundles](/core-concepts/modules/more-modules.md).
20 |
21 | ## Overriding, configuring and extending modules at "project level"
22 |
23 | Any options you provide for a module via the `modules` property in `app.js` override the default configuration for a module, as described in the [technical overview](/core-concepts/technical-overview.html#project-level-overriding-and-extending-apostrophe-in-your-project). And any configuration provided via the `modules` property in `data/local.js` overrides that, allowing for server-specific settings like API keys.
24 |
25 | You can also provide your own templates in the `lib/modules/module-name/views` folder of your project (**not** in `node_modules`) to override the templates of `module-name`, and provide your own code in `lib/modules/module-name/index.js` to override methods and add functionality. *If your project-level `lib/modules` folder has a module by the same name as a core or npm module, any code you provide automatically subclasses and improves that module.*
26 |
27 |
--------------------------------------------------------------------------------
/docs/reference/modules/README.md:
--------------------------------------------------------------------------------
1 | # Modules in Apostrophe
2 |
3 | Every Apostrophe site is made up of modules. You can browse the complete list at left.
4 |
5 | ## Overview
6 |
7 | Each module provides a particular feature, often including both front and back end code, as well as templates and stylesheets. For instance, the [apostrophe-assets](apostrophe-assets/README.md) module provides core services relating to assets like stylesheets.
8 |
9 | Modules are implemented as [moog types](/reference/glossary.md#moog-type), which provide a simple and clean way to write them in an object-oriented style while keeping async programming convenient and providing easy subclassing and overriding.
10 |
11 | For convenience, the `apostrophe` npm module contains all of the "core" Apostrophe modules that are necessary for a functioning website.
12 |
13 | Some of these, like [apostrophe-docs](apostrophe-docs/README.md), are initialized every time Apostrophe starts up; you can [see that list on github](https://github.com/apostrophecms/apostrophe/blob/2.0/defaults.js). Those modules are initialized first, followed by those you configure in `app.js`, in the order you configure them.
14 |
15 | Others, like [apostrophe-pieces](apostrophe-pieces/README.md) and [apostrophe-widgets](apostrophe-widgets/README.md), are "abstract base classes" you can extend to create new modules that provide content types.
16 |
17 | [apostrophe-module](apostrophe-module/README.md) is the base class of **all** modules; it provides features that are convenient in almost any module, like [rendering a template from its `views` folder](apostrophe-module/README.md#render), or [pushing assets from its `public` folder](apostrophe-module/README.md#push-asset).
18 |
19 | Modules can also be installed via npm, and multiple Apostrophe modules can be [shipped as a single npm module via moog bundles](/core-concepts/modules/more-modules.md).
20 |
21 | ## Overriding, configuring and extending modules at "project level"
22 |
23 | Any options you provide for a module via the `modules` property in `app.js` override the default configuration for a module, as described in the [technical overview](/core-concepts/technical-overview.html#project-level-overriding-and-extending-apostrophe-in-your-project). And any configuration provided via the `modules` property in `data/local.js` overrides that, allowing for server-specific settings like API keys.
24 |
25 | You can also provide your own templates in the `lib/modules/module-name/views` folder of your project (**not** in `node_modules`) to override the templates of `module-name`, and provide your own code in `lib/modules/module-name/index.js` to override methods and add functionality. *If your project-level `lib/modules` folder has a module by the same name as a core or npm module, any code you provide automatically subclasses and improves that module.*
26 |
27 |
--------------------------------------------------------------------------------
/docs/reference/field-properties/README.md:
--------------------------------------------------------------------------------
1 | # Schema Field Property Reference
2 |
3 | Each [Schema Field Type](/reference/field-types) in Apostrophe can take a number of different properties for configuration and display settings. Below is a reference of the most commonly used properties. You can also view the reference for each individual field for a complete list of properties used by that field and an explanation of what it does.
4 |
5 | ## Commonly Used Properties
6 |
7 | | Property | Type | Default | Description | Used By | Sub-properties |
8 | |----------|------|---------|-------------|---------|----------------|
9 | |name | `string` | | Sets the name of the field in the database | universal | |
10 | |label | `string` | | Sets the label of the field that the user sees | universal | |
11 | |required | `boolean` | false | If true, the field is mandatory | universal | |
12 | |type | `string` | | Specifies the field type | universal | |
13 | |readOnly | `boolean` | false | If true, prevents the user from editing the field | universal | |
14 | |help | `string` | | Help text for the field that will appear with the field's label | universal | |
15 | |htmlHelp | `string` | | Help text with support for HTML markup | universal | |
16 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in the dialog box for a widget | universal | |
17 | |permission | `string` | | Specify [the permission level needed](/core-concepts/users-and-permissions/managing-access-control.md) to edit this field | universal | |
18 | |def | depends on field type | | The default value for the field | most fields, excluding areas, singletons, objects, and arrays | |
19 | |[sortify](sortify.md) | `boolean` | false | If true, make sort() operations on the field case-insensitive and more intuitive | [string](../field-types/string.md), [email](../field-types/email.md), [slug](../field-types/slug.md), [select](../field-types/select.md) | |
20 | |searchable | `boolean` | true | If false a field will not inform sitewide search | [string](../field-types/string.md), [area](../field-types/area.md), [singleton](../field-types/singleton.md) | |
21 | |limit | `int` | | sets the max number of tags in a tag field, the max number of widgets in an area, and the max number of entries in an array |[tags](../field-types/tags.md), [area](../field-types/area.md), [array](../field-types/array.md) | |
22 | |[options](options.md) | `object` | | Passed on to apos.area or apos.singleton as appropriate, specifying options for the allowable widgets and so on | [area](../field-types/area.md), [singleton](../field-types/singleton.md) | `widgets` |
23 | |[choices](choices.md) | `array` | | An array of values that the user can select from with each being an object with value and label properties | [boolean](../field-types/boolean.md) [select](../field-types/select.md), [checkbox](../field-types/checkbox.md) | `label`, `value`, `showFields` |
24 |
--------------------------------------------------------------------------------
/HOW_TO_UPDATE_THE_DOCUMENTATION.md:
--------------------------------------------------------------------------------
1 | # How to update Apostrophe CMS documentation
2 | ========================
3 |
4 | This project contains [the documentation site](https://docs.apostrophecms.com)
5 | for [ApostropheCMS](https://apostrophecms.com).
6 |
7 | You don't need to read this page to read the documentation! [Read the
8 | actual documentation here.](https://docs.apostrophecms.com) This page
9 | is about *contributing to* the documentation.
10 |
11 | ## Building the docs
12 |
13 | ### 1. Setup
14 |
15 | Clone the repo.
16 |
17 | ```sh
18 | $ git clone https://github.com/apostrophecms/apostrophe-documentation.git
19 | $ cd apostrophe-documentation
20 | ```
21 |
22 | Next, install the dependencies for the main Vuepress documentation as well as
23 | for the module documentation generator (see below). The `install` script file
24 | will do both with single command.
25 |
26 | ```
27 | ./install
28 | ```
29 |
30 | ### 2. Updating the modules documentation from the source code
31 |
32 | The reference docs for the modules are based on comments inline in the code,
33 | which makes writing reference documentation easy and encourages us to do so.
34 | Comments above the module's source go into the `README.md` for the module's
35 | folder; comments above each method document that method. Helpers, routes and
36 | regular methods (`self.something = function()...`) are all automatically
37 | discovered. Frontend moog classes and methods, too.
38 |
39 | Here's how to generate the docs:
40 |
41 | > First make sure you are not running anything locally on port 3000.
42 |
43 | ```
44 | ./generate
45 | ```
46 |
47 | NOTE: this will `npm update` the version of `apostrophe` being documented first, so the docs are always for the **latest published release**.
48 |
49 | Now commit the changes, as you would if you had made them manually.
50 |
51 | ### 3. Making edits to other pages
52 |
53 | We make changes to other pages by hand and commit them to master.
54 |
55 | **If you add a new page,** you will need to edit `docs/.vuepress/config.js` in the root of the project. Otherwise it will not appear in the sidebar navigation.
56 |
57 | ### 4. Submit for review
58 |
59 | First, make sure you've run the documentations locally (`npm run dev`) and
60 | confirmed that your links work properly. Submit your changes as a pull request
61 | on the [apostrophe-documentation](https://github.com/apostrophecms/apostrophe-documentation/)
62 | repository. Please include as much context for the change as is reasonable in
63 | the PR description.
64 |
65 | ### Note on internal doc links
66 |
67 | When creating links in the body of a documentation page that point to another
68 | page of documentation, either make sure the link is relative and pointing to the
69 | `.md` extension OR use the file path starting starting after the `docs`
70 | directory. So you would link to `docs/devops/email.md` with
71 | `[link text](/devops/email.md)`.
72 |
--------------------------------------------------------------------------------
/docs/reference/modules/apostrophe-urls.md:
--------------------------------------------------------------------------------
1 | # apostrophe-urls
2 | ## Inherits from: [apostrophe-module](./apostrophe-module/README.md)
3 | ### `apos.urls`
4 | Provides the `build` method, a flexible and powerful way to build
5 | URLs with query parameters and more. This method is made available
6 | as the `build` filter in Nunjucks. This is also the logical place
7 | to add new utility methods relating to URLs.
8 |
9 |
10 | ## Methods
11 | ### build(*url*, *path*, *data*)
12 | Build filter URLs. `data` is an object whose properties
13 | become new query parameters. These parameters override any
14 | existing parameters of the same name in the URL. If you
15 | pass a property with a value of `undefined`, `null` or an
16 | empty string, that parameter is removed from the
17 | URL if already present (note that the number `0` does not
18 | do this). This is very useful for maintaining filter
19 | parameters in a query string without redundant code.
20 |
21 | Pretty URLs
22 |
23 | If the optional `path` argument is present, it must be an
24 | array. (You may skip this argument if you are just
25 | adding query parameters.)
26 |
27 | Any properties of `data` whose names appear in `path`
28 | are concatenated to the URL directly, separated by slashes,
29 | in the order they appear in that array.
30 |
31 | The first missing or empty value for a property in `path`
32 | stops this process to prevent an ambiguous URL.
33 |
34 | Note that there is no automatic detection that this has
35 | already happened in an existing URL, so you can't override
36 | existing components of the path.
37 |
38 | If a property's value is not equal to the slugification of
39 | itself as determined by apos.utils.slugify, then a query
40 | parameter is set instead.
41 |
42 | If you don't want to handle a property as a query parameter,
43 | make sure it is always slug-safe.
44 |
45 | Overrides: multiple data objects
46 |
47 | You may pass additional data objects. The last one wins, so
48 | you can pass your existing parameters first and pass new
49 | parameters you are changing as a second data object.
50 |
51 | Working with Arrays
52 |
53 | Normally, a new value for a property replaces any old one,
54 | and `undefined`, `null` or `''` removes the old one. If you
55 | wish to build up an array property instead you'll need
56 | to use the MongoDB-style $addToSet and $pull operators to add and
57 | remove values from an array field in the URL:
58 |
59 | Add tags[]=blue to the query string, if not already present
60 |
61 | `{ tags: { $addToSet: 'blue' } }`
62 |
63 | Remove tags[]=blue from the query string, if present
64 |
65 | `{ tags: { $pull: 'blue' } }`
66 |
67 | All values passed to $addToSet or $pull must be strings or
68 | convertible to strings via `toString()` (e.g. numbers, booleans)
69 |
70 | (The actual query string syntax includes array indices and
71 | is fully URI escaped, so it's slightly different but has
72 | the same impact. PHP does the same thing.)
73 |
--------------------------------------------------------------------------------
/docs/advanced-topics/migrations.md:
--------------------------------------------------------------------------------
1 | # Writing database migrations
2 |
3 | Database migrations are used to handle changes or corrections to your database schema that need to be applied across many or all documents.
4 |
5 | In systems built on SQL databases, migrations are needed even for simple tasks like adding a new field. Since ApostropheCMS is built on MongoDB, there is no need for a migration in those cases. You can add, rename and remove fields without encountering any database errors.
6 |
7 | However, if you are removing or renaming a field, you may want to remove or move the existing data. Here is a simple example of how to write a migration to handle renaming a field.
8 |
9 | In this example, we'll assume the field used to be named `feline` and the new name is `cat`.
10 |
11 | ```javascript
12 | // in lib/modules/pet-owners/index.js
13 |
14 | module.exports = {
15 | extend: 'apostrophe-pieces',
16 | name: 'pet-owner',
17 | addFields: [
18 | {
19 | name: 'cat',
20 | label: 'Cat',
21 | type: 'string'
22 | }
23 | ],
24 | construct(self, options) {
25 | self.apos.migrations.add('renameFelineField', async () => {
26 | await self.apos.migrations.eachDoc({
27 | // This is a raw mongo query, we must take care to leave other piece types alone
28 | type: 'pet-owner',
29 | // Don't bother with docs that never had a feline field
30 | feline: { $exists: 1 }
31 | }, async (doc) => {
32 | // Raw mongodb update so we can use $set and $unset and avoid race conditions
33 | await self.apos.docs.db.updateOne({
34 | _id: doc._id
35 | }, {
36 | $set: {
37 | cat: doc.feline
38 | },
39 | $unset: {
40 | feline: 1
41 | }
42 | });
43 | });
44 | });
45 | };
46 | };
47 | ```
48 |
49 | Notice that:
50 |
51 | * **The migration must be given a name when calling `apos.migrations.add`.** This distinguishes it from all other migrations and allows Apostrophe to make sure it is only invoked once.
52 | * **`self.apos.migrations.eachDoc` iterates over every doc in the database,** filtered by the MongoDB criteria object you supply.
53 | * **`apos.docs.db.updateOne` is used to do a direct MongoDB update on each doc.** This has performance benefits and the use of [`$set`](https://docs.mongodb.com/manual/reference/operator/update/set/) and [`$unset`](https://docs.mongodb.com/manual/reference/operator/update/unset/) avoids race conditions if other fields change between the read operation and the write operation.
54 |
55 | You can find [other migration-related convenience methods in the apostrophe-migrations module documentation](/reference/modules/apostrophe-migrations). Notable examples include `eachWidget`, which can be used to iterate over every occurrence of a particular kind of widget in the entire database.
56 |
57 | ::: tip
58 | Methods of `apos.migrations` should never be used in the normal process of serving a web request. They have no security provisions and are exclusively for use in migrations and [command line tasks](../command-line-tasks).
59 | :::
60 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pages-topics/children-and-joins.md:
--------------------------------------------------------------------------------
1 | # Accessing the children of pages via joins
2 |
3 | [Joins]((/reference/field-types/joinbyone) are one of Apostrophe's best features:
4 |
5 | ```javascript
6 | addFields: [
7 | {
8 | name: '_pages',
9 | type: 'joinByArray',
10 | withType: 'apostrophe-page',
11 | label: 'Pages',
12 | idsField: 'pageIds'
13 | }
14 | ]
15 | ```
16 |
17 | But if you try to access the `_children` property of those pages, you'll be disappointed at first.
18 |
19 | Child pages get fetched only if the `children()` filter is called on the cursor that fetches those docs. This takes extra time and does extra work, and most joins don't need them. So by default, they are not fetched.
20 |
21 | Fortunately, you can turn on extra cursor filters yourself in any join:
22 |
23 | ```javascript
24 | addFields: [
25 | {
26 | name: '_pages',
27 | type: 'joinByArray',
28 | withType: 'apostrophe-page',
29 | label: 'Pages',
30 | idsField: 'pageIds',
31 | filters: {
32 | children: true
33 | }
34 | }
35 | ]
36 | ```
37 |
38 | ## Fetching thumbnails
39 |
40 | By default, `children` will not load any widgets present in the child pages, again for performance reasons.
41 |
42 | Here's how to turn it on for just one area, a singleton widget called `thumbnail`:
43 |
44 | ```javascript
45 | addFields: [
46 | {
47 | name: '_pages',
48 | type: 'joinByArray',
49 | withType: 'apostrophe-page',
50 | label: 'Pages',
51 | idsField: 'pageIds',
52 | filters: {
53 | children: {
54 | areas: [ 'thumbnail' ]
55 | }
56 | }
57 | }
58 | ]
59 | ```
60 |
61 | > If we pass an object to `children`, its properties are invoked as cursor filters when fetching the children. The same trick works with `ancestors`.
62 |
63 | ## Projections and children
64 |
65 | If you are using the `projection` filter to load just the absolute minimum information about those pages, `children` won't work, because it requires a little more information about the original pages to understand their place in the page tree.
66 |
67 | Here is the absolute minimum `projection` needed for use with `children`:
68 |
69 | ```javascript
70 | addFields: [
71 | {
72 | name: '_pages',
73 | type: 'joinByArray',
74 | withType: 'apostrophe-page',
75 | label: 'Pages',
76 | idsField: 'pageIds',
77 | filters: {
78 | children: true,
79 | projection: {
80 | title: 1,
81 | slug: 1,
82 | rank: 1,
83 | level: 1,
84 | path: 1
85 | }
86 | }
87 | }
88 | ]
89 | ```
90 |
91 | But while using projections is fastest, you can improve performance quite a lot just by not loading areas:
92 |
93 | ```javascript
94 | addFields: [
95 | {
96 | name: '_pages',
97 | type: 'joinByArray',
98 | withType: 'apostrophe-page',
99 | label: 'Pages',
100 | idsField: 'pageIds',
101 | filters: {
102 | children: true,
103 | areas: false
104 | }
105 | }
106 | ]
107 | ```
108 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/next-previous-links.md:
--------------------------------------------------------------------------------
1 | # Adding Next and Previous Links
2 |
3 | Sometimes it's desirable to provide links to the "next" and "previous" piece on the "show page" for that piece (the `show.html` template).
4 |
5 | To enable that, just configure your module that subclasses `apostrophe-pieces-pages` appropriately:
6 |
7 | ```javascript
8 | // lib/modules/my-articles-pages/index.js
9 | module.exports = {
10 | extend: 'apostrophe-pieces-pages',
11 | next: true,
12 | previous: true
13 | // other options, etc.
14 | };
15 | ```
16 |
17 | ::: tip NOTE
18 | Here we'e assuming that `my-articles` extends `apostrophe-pieces` directly, and `my-articles-pages` extends `apostrophe-pieces-pages`, but you can also do this trick with modules that extend `apostrophe-blog-pages`, `apostrophe-events-pages` and other existing subclasses.
19 | :::
20 |
21 | Turning on these options causes Apostrophe to load the next and previous documents into `data.previous` and `data.next`, so you can output links like this, often at the bottom of `show.html`:
22 |
23 | ```markup
24 | {# lib/modules/my-articles-pages/views/show.html #}
25 | {% if data.previous %}
26 |
29 | {% endif %}
30 |
31 | {% if data.next %}
32 |
35 | {% endif %}
36 | ```
37 |
38 | By default you can access any property of `data.previous` or `data.next`. For better performance, you may want to limit them with a projection, much as you would for a join:
39 |
40 | ```javascript
41 | // lib/modules/my-articles-pages/index.js
42 | module.exports = {
43 | extend: 'apostrophe-pieces-pages',
44 | previous: {
45 | projection: {
46 | title: 1,
47 | slug: 1,
48 | tags: 1,
49 | type: 1
50 | }
51 | },
52 | next: {
53 | projection: {
54 | title: 1,
55 | slug: 1,
56 | tags: 1,
57 | type: 1
58 | }
59 | }
60 | // other options, etc.
61 | };
62 | ```
63 |
64 | ::: tip
65 | These are the minimum fields recommended. Except for `title`, all of them play a role in building the dynamic `_url` property correctly.
66 | :::
67 |
68 |
69 | ### "Next", "previous" and blog posts
70 |
71 | One thing that might be confusing: for this purpose, "next" means "appears next in the list of pieces in the `index.html` view." and "previous" means "appears previously in the list of pieces in the `index.html` view."
72 |
73 | For most types of pieces, this is intuitive. But since blogs are displayed in reverse chronological order, there it can seem a little backwards. So just keep in mind that you may need to use different language for your links on the front end.
74 |
75 | ## Fetching the `next` or `previous` piece programmatically
76 |
77 | This feature is implemented using the `next` and `previous` cursor filter methods. You can use those yourself:
78 |
79 | ```javascript
80 | // `doc` is a piece we already fetched
81 | return self.find(req).previous(doc).toObject(function(err, previous) { ... });
82 | ```
83 |
84 | The same technique can be used with `next`.
85 |
--------------------------------------------------------------------------------
/docs/reference/field-types/attachment.md:
--------------------------------------------------------------------------------
1 | # `attachment`
2 |
3 | An `attachment` field allows the user to upload a file to the server, or replace a file which was previously [uploaded](/reference/modules/apostrophe-attachments/README.md).
4 |
5 | ::: tip NOTE
6 | The uploaded files are stored in a web-accessible folder, however their names are generated in a way which makes them mathematically impossible to guess.
7 | :::
8 |
9 | Once an attachment field has a value, you can obtain a URL to the file by calling `apos.attachments.url(attachment)`. If the file is an image, you can obtain images of any configured size by calling `apos.attachments.url(attachment, { size: 'one-half' })`, etc.
10 |
11 | Attachments are most often used indirectly via [apostrophe-images-widgets](/reference/modules/apostrophe-images-widgets/README.md) or [apostrophe-files-widgets](/reference/modules/apostrophe-files-widgets/README.md), which are backed by the [apostrophe-images](/reference/modules/apostrophe-images/README.md) and [apostrophe-files](/reference/modules/apostrophe-files/README.md) subclasses of pieces. Each of those piece types contains an attachment field and some metadata fields, making them a convenient way to reuse files.
12 |
13 | However, you may also use attachments directly in your own schemas. Doing so means that the file will not be available via a general-purpose "media library." It will only be readily accessible as a property of your object.
14 |
15 | This is often appropriate for resumes, job applications and other attachments relating to a specific person.
16 |
17 | ## Example
18 |
19 | ```javascript
20 | {
21 | type: 'attachment',
22 | name: 'resume',
23 | label: 'Resume',
24 | group: 'office'
25 | }
26 | ```
27 |
28 | ## Settings
29 |
30 | | Property | Type | Default | Description |
31 | |---|---|---|---|
32 | |name | `string` | | Sets the name of the field in the database |
33 | |label | `string` | | Sets the label of the field that the user sees |
34 | |required | `boolean` | false | If true, the field is mandatory |
35 | |contextual | `boolean` | false | If true, it will prevent the field from appearing in a dialog box |
36 | |type | `string` | | Specifies the field type |
37 | |readOnly | `boolean` | false | If true, prevents the user from editing the field |
38 | |help | `string` | | Help text for the field that will appear with the field's label |
39 | |htmlHelp | `string` | | Help text with support for HTML markup | universal |
40 | |group | `string` | | Can be set to "image" or "office" to limit the file types that can be uploaded. Other groups can be configured via the `fileGroups` option of the [apostrophe-attachments](/reference/modules/apostrophe-attachments/README.md) module. |
41 | |crop | boolean | false | If true, the user may crop the attachment. Only suitable if group is images. |
42 | |aspectRatio | array | | if set to an array like \[ 2, 1 \], the image must have that aspect ratio and will be autocropped if the user does not manually crop. Only suitable if group is images. |
43 | |minSize | array | | if set to an array like \[ 640, 480 \], the image must have at least the specified minimum width and height. Only suitable if group is images. |
44 |
45 |
--------------------------------------------------------------------------------
/docs/advanced-topics/advanced-pieces-topics/extending-the-pieces-editor-modal.md:
--------------------------------------------------------------------------------
1 | # Extending the pieces editor modal
2 |
3 | Let's look at adding a custom button for use when editing a particular subclass of `apostrophe-pieces`.
4 |
5 | *If all you want is an extra field in the form, there's a much easier way. Just use `addFields` to add more schema fields to your subclass of pieces. See the tutorials!*
6 |
7 | For starters, you'll want to override `editorModal.html` for your module.
8 |
9 | ```django
10 | {# lib/modules/mymodule/views/editorModal.html #}
11 | {% extends "editorBase.html" %}
12 | {% import 'apostrophe-ui:components/buttons.html' as buttons with context %}
13 |
14 | {%- block controls -%}
15 | {# The standard controls #}
16 | {{ super() }}
17 | {# Custom button #}
18 | {{ buttons.major('My Label', { action: 'mything' }) }}
19 | {%- endblock -%}
20 | ```
21 |
22 | *You will want to do exactly the same thing for `createModal.html` if your button also makes sense when creating new pieces.*
23 |
24 | Next check out `editor-modal.js`, where the pieces module overrides `beforeShow` to add a bunch of jquery click handlers.
25 |
26 | `self.link('mything', function() { ... })` calls that function when a `data-mything` attribute is found in the context of `self.$el` (the modal).
27 |
28 | You can extend this by creating your own `editor-modal.js` file in your own module's `public/js` folder. Since you are extending `apostrophe-pieces`, which already pushes `editor-modal.js`, your own version automatically gets pushed to the browser too.
29 |
30 | To extend beforeShow at project level you'll want to follow the "super pattern":
31 |
32 | ```javascript
33 | // lib/modules/mymodule/public/js/editor-modal.js
34 | apos.define('mymodule-editor-modal', {
35 | extend: 'apostrophe-pieces-editor-modal',
36 | construct: function(self, options) {
37 | var superBeforeShow = self.beforeShow;
38 | self.beforeShow = function(callback) {
39 | self.link('mything', self.doMyThing);
40 | return superBeforeShow(callback);
41 | };
42 | self.doMyThing = function() {
43 | ... up to you! ...
44 | };
45 | }
46 | });
47 | ```
48 |
49 | If you want to talk to an API route provided by the same module you can call:
50 |
51 | ```javascript
52 | self.api('apiname', { POST object for req.body }, function(result) {
53 | ... do something with result ...
54 | });
55 | ```
56 |
57 | self.api will invoke the URL `/modules/modulename/apiname` as a POST and submit the data object as `req.body`, using the JSON content type.
58 |
59 | On the server side, you'll need to extend your module to implement the API:
60 |
61 | ```javascript
62 | // lib/modules/mymodulename/index.js
63 | module.exports = {
64 | construct: function(self, options) {
65 | self.route('apiname', function(req, res) {
66 | // Validate things with the launder module
67 | var name = self.apos.launder.string(req.body.name);
68 | ... Do more with that ...
69 | // Deliver a JSON resposne
70 | return res.send({ status: 'ok', moreInfo: 'something' });
71 | });
72 | }
73 | };
74 | ```
75 |
76 | Calling `self.route('apiname'...)` is similar to calling `self.apos.app.post('/modules/mymodulename/apiname', ...)`, but it's a lot less work, and you can call again with the same apiname to override it, which you can't do with `app.post`.
77 |
--------------------------------------------------------------------------------