# Apostrophe core object, browser-side
Apostrophe always creates an
apos object and attaches it to the
window object in the browser, making it globally available.
Most of Apostrophe's browser-side functionality is implemented by its individual modules, many of which can be accessed through aliases on the
apos object, such as
This article is a reference guide to the options and methods of the browser-side
apos object itself. Most of the time you'll be more interested in Apostrophe's modules.
This article is not the right place to start learning Apostrophe. For that, see the tutorials.
Since Apostrophe is responsible for generating the webpage, there will only be one
apos object in the browser.
The name of a cookie used to implement Angular-style CSRF protection, which is applied to all jQuery ajax operations.
Automatically set based on the project's
shortName if not otherwise configured as an option to the
apostrophe-express module on the server side.
modules is an object in which the keys are the names of Apostrophe modules and the values are objects. Usually the properties of this object set options for the module and become available in its own
Not all Apostrophe modules have a browser-side object; only those that require one to implement a UI. And many have one only if a user is logged in.
Passed through to the browser by the server,
apos.prefix will match its value on the server side if a site is running as a "virtual subdirectory." Apostrophe also automatically adjusts jQuery's AJAX behavior to respect the prefix and provides
apos.ui.redirect, a convenience method that prepends the prefix to whatever is passed to it. So in most cases you will not need to prepend this yourself. See the prefix option.
The instance of
moog that powers
apos.define, etc. on the browser side, providing object-oriented programming features. Can also be used directly (
Refreshes the div with the
data-apos-refreshable attribute, which will typically contain everything except the Apostrophe admin bar. Apostrophe will refetch the page via an AJAX request and the server will automatically use its
ajaxLayout to return only that portion of the page.
In addition, a
change event is emitted on the
apos object, which receives
what is an object, and otherwise receives
apos.change is invoked by the "edit" modals of pieces in order to refresh content on the page that might potentially include the piece that was just modified. This makes the editing experience feel more seamless by avoiding the need for a manual page refresh.
create(typeName, optionsObject, [callback])
Creates an object. Specifically, an instance of any moog type that is defined on the browser side. You will see
apos.create calls when you peek at "view source" because server-side modules push them to create singletons that provide their UI.
The callback is optional, provided that neither the type you are creating nor any of its base classes take a callback in their constructor. If there is a callback it will receive
See also createModule.
# createModule(type, options, alias)
Creates a singleton instance of the named module on the browser side by invoking apos.create. The module is made available as a property of the
apos object with the specified
alias, if any, and is instantiated with the provided
options. The module is also made available as a property of
apos.modules under its full name.
To avoid problems with double-registration of event handlers when the main body of the content is refreshed, if the module already exists in
apos.modules it is not re-created.
Many, but not all, modules push a call to this method from the server side; you will see those calls in "view source."
Typical modules have a
user.js file on the browser side, which invokes apos.define with the same type name as the module. This method is used to actually create the object, after project-level code and other modules have had a chance to extend the definition via implicit subclassing.
This method enables CSRF protection for all AJAX operations carried out via jQuery. A call to this method is pushed automatically by the
This method automatically prefixes any AJAX operations carried out via jQuery with
apos.prefix, if the
prefix option was set when configuring the project. A call to this method is pushed automatically by the
Defines a new moog type on the browser side.
apos.define is seen in every core module that does browser-side work. Its use allows easy subclassing and enhancement at the project level. An alias for
apos.synth.define. Many of the core Apostrophe source files on the browser side consist entirely of an
apos.define call. The object is then created later via
definitionObject looks exactly like an
index.js file on the server side, with properties to set default values for options and often
afterConstruct functions. Both the browser and the server rely on moog to support highly flexible object-oriented programming.
Apostrophe provides an event mechanism. The
apos.emit method takes an event name and additional, optional arguments and invokes all event listeners for that event name. Apostrophe emits many events on the browser side.
Returns true if the specified moog type is defined. An alias for
Prints a message to
console.log, gracefully doing nothing in browsers that do not provide
An alias for
apos.synth.mirror. See moog.
Registers an event handler to be invoked when the named event is emitted (see emit). The event handler function will receive any additional arguments passed to
Frequently used events include:
ready, which is emitted when a page is loaded, or when its main content area is fully refreshed due to an action such as editing a piece that might impact what it should display.
enhance, which is emitted both for new pages and whenever new content is added to the page (most notably for AJAX updates or additions to the page), and receives a jQuery element containing all of the new content as its first argument.
Removes the specified event handler from the list of event handlers for the named event (see on).
The apostrophe-templates module will push a call to this method automatically, via the
pageReadyWhenCalm method, when loading a new page or refreshing
data-apos-refreshable. This method emits the
pageReady after first waiting for jQuery's DOMready event and then waiting for "next tick" via
Redefines a moog type on the browser side, throwing out any previous definition rather than implicitly subclassing as a second call to
apos.define would do.