xmpp.chapril.org-conversejs/docs/source/jsdoc_intro.md

44 lines
1.7 KiB
Markdown
Raw Normal View History

# The Converse API documentation
Welcome to the new Converse API documentation, generated with
[JSDoc](http://usejsdoc.org/).
The old (increasingly out of date and incomplete) API documentation is
currently still [available here](/docs/htmls/developer_api.html).
## The public and private API
Converse has a public API and a private API.
r
The reason we make this distinction between public and private is so that API
methods which might can be used to "impersonate" the user, for example by
sending messages on their behalf, are not available to random scripts running
in the websites.
The public API is accessible via the `window.converse` global and is therefore
available to all JavaScript running in the page.
Tehe private API is only accessible to plugins, which have been whitelisted and
registered before `converse.initialize` (which is a public API method) has been
called. See the [plugin development](https://conversejs.org/docs/html/plugin_development.html)
section for more info on writing plugins.
Inside a plugin, you can get access to the `_converse.api` object. Note the
underscore in front of `_converse`, which indicates that this is a private,
closured object.
## API Namespaces
2018-09-02 15:07:14 +02:00
The Converse API (private and public) makes use of namespaces to logically
group relevant methods.
2018-09-02 15:07:14 +02:00
So, for example, all the XEP-0030 service discovery methods are under the
{@link \_converse.api.disco} namespace, in the [private API]{@link \_converse.api}.
2018-09-02 15:07:14 +02:00
Which means that you access it via `_converse.api.disco`.
2018-09-02 15:07:14 +02:00
Namespaces can be nested. So the {@link \_converse.api.disco} namespace
namespace has {@link \_converse.api.disco.own} as a nested namespace.
2018-09-02 15:07:14 +02:00
Not all methods are however within a namespace. For example {@link converse.initialize}.