Update development docs and add theming info
This commit is contained in:
parent
7e9861ba8f
commit
0b172be3d0
|
@ -760,6 +760,8 @@ loglevel
|
||||||
|
|
||||||
You can also set this value by changing a URL fragment `#converse?loglevel=debug`
|
You can also set this value by changing a URL fragment `#converse?loglevel=debug`
|
||||||
|
|
||||||
|
.. _`dark_theme`:
|
||||||
|
|
||||||
dark_theme
|
dark_theme
|
||||||
----------
|
----------
|
||||||
|
|
||||||
|
@ -2163,6 +2165,8 @@ If set to ``false``, this feature is disabled.
|
||||||
|
|
||||||
If set to ``a resource name``, Converse will synchronize only with a client that has that particular resource assigned to it.
|
If set to ``a resource name``, Converse will synchronize only with a client that has that particular resource assigned to it.
|
||||||
|
|
||||||
|
.. _`theme`:
|
||||||
|
|
||||||
theme
|
theme
|
||||||
-----
|
-----
|
||||||
|
|
||||||
|
|
|
@ -2,9 +2,11 @@
|
||||||
|
|
||||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
||||||
|
|
||||||
=============================
|
.. _`development`:
|
||||||
Starting up a dev environment
|
|
||||||
=============================
|
============================
|
||||||
|
Setting up a dev environment
|
||||||
|
============================
|
||||||
|
|
||||||
Installing the 3rd party dependencies
|
Installing the 3rd party dependencies
|
||||||
=====================================
|
=====================================
|
||||||
|
@ -88,3 +90,50 @@ which requires all other dependent JavaScript code to also be open sourced under
|
||||||
license. You might not be willing to adhere to those terms, which is why you
|
license. You might not be willing to adhere to those terms, which is why you
|
||||||
need to decide for yourself whether you're going to load libsignal or not.
|
need to decide for yourself whether you're going to load libsignal or not.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`webserver`:
|
||||||
|
|
||||||
|
Setting up a webserver
|
||||||
|
======================
|
||||||
|
|
||||||
|
When making changes to Converse, either development or theming changes,
|
||||||
|
you'll want to preview them in your browser.
|
||||||
|
|
||||||
|
For this, you'll need to serve the development files via a web server,
|
||||||
|
so that you can see your local changes in the browser.
|
||||||
|
|
||||||
|
Manually starting a web server
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
To both set up the development environment and also start up a web browser to
|
||||||
|
serve the files for you, you can run::
|
||||||
|
|
||||||
|
make serve
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
|
||||||
|
installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
|
||||||
|
available via your package manager. For Mac, you'll need to install XCode and in
|
||||||
|
Windows you can use `Chocolatey <https://chocolatey.org/>`_.
|
||||||
|
|
||||||
|
After running ``make serve`` you can open http://localhost:8000 in your webbrowser to see the Converse website.
|
||||||
|
|
||||||
|
When developing or changing the theme, you'll want to load all the
|
||||||
|
unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html instead.
|
||||||
|
|
||||||
|
You might want to open `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_ in your text editor or IDE as well, to see
|
||||||
|
how ``converse.initialize`` is called and to potentially change any of the
|
||||||
|
settings.
|
||||||
|
|
||||||
|
Starting a web server with live reloading
|
||||||
|
-----------------------------------------
|
||||||
|
|
||||||
|
Alternatively, if you want to have live reloading whenever any of the source files change, you
|
||||||
|
can run ``make devserver`` (which will use `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_).
|
||||||
|
|
||||||
|
Instead of ``dev.html`` being used, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
|
||||||
|
is now being used as the HTML template, and you'll need to modify that file if
|
||||||
|
you want to change the settings passed to ``converse.initialize``.
|
||||||
|
|
||||||
|
If you're running ``make devserver``, you need to open http://localhost:8080.
|
||||||
|
|
||||||
|
|
|
@ -23,11 +23,10 @@ to fix a bug or to add new functionality.
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
dependencies
|
setup_dev_environment
|
||||||
style_guide
|
|
||||||
webserver
|
|
||||||
plugin_development
|
plugin_development
|
||||||
api/index
|
api/index
|
||||||
testing
|
testing
|
||||||
other_frameworks
|
other_frameworks
|
||||||
builds
|
builds
|
||||||
|
style_guide
|
||||||
|
|
140
docs/source/setup_dev_environment.rst
Normal file
140
docs/source/setup_dev_environment.rst
Normal file
|
@ -0,0 +1,140 @@
|
||||||
|
.. raw:: html
|
||||||
|
|
||||||
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
||||||
|
|
||||||
|
.. _`setup_dev_environment`:
|
||||||
|
|
||||||
|
============================
|
||||||
|
Setting up a dev environment
|
||||||
|
============================
|
||||||
|
|
||||||
|
Installing the 3rd party dependencies
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
To develop and customize Converse, you'll first need to check out Converse's Git
|
||||||
|
repository:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
git clone https://github.com/conversejs/converse.js.git
|
||||||
|
cd converse.js
|
||||||
|
|
||||||
|
|
||||||
|
We use development tools which depend on Node.js and NPM (the Node package manager).
|
||||||
|
|
||||||
|
It's recommended that you use `NVM <https://github.com/nvm-sh/nvm>`_ (the Node version manager)
|
||||||
|
to make sure you have the right version of Node.
|
||||||
|
|
||||||
|
Refer to the `NVM Github page <https://github.com/nvm-sh/nvm#install--update-script>`_ for instructions on how to install it.
|
||||||
|
|
||||||
|
Once NVM is installed, you can run the following inside your checkout of the Converse Git repository:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
nvm install
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
You will always have to first run ``nvm install`` in a new terminal session in order to use the
|
||||||
|
recommended version of Node before working on Converse.
|
||||||
|
|
||||||
|
|
||||||
|
To set up the Converse development environment, you now run ``make dev``.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
make dev
|
||||||
|
|
||||||
|
Alternatively, if you're using Windows, or don't have GNU Make installed, you can run the
|
||||||
|
following:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
npm install
|
||||||
|
npm run lerna
|
||||||
|
|
||||||
|
This will install the Node development tools and Converse's dependencies.
|
||||||
|
|
||||||
|
The front-end dependencies are those JavaScript files on which
|
||||||
|
Converse directly depends and which will be loaded in the browser as part of
|
||||||
|
the bundle in ``dist/converse.js`` (or ``dist/converse.min.js``).
|
||||||
|
|
||||||
|
To see the 3rd party dependencies (not just the front-end dependencies, but
|
||||||
|
also ones necessary for development tasks like making builds), take a look at
|
||||||
|
the list under the ``devDependencies`` in `package.json <https://github.com/jcbrand/converse.js/blob/master/package.json>`_.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
After running ```make dev```, you should now have a new *node_modules* directory
|
||||||
|
which contains all the external dependencies of Converse.
|
||||||
|
If this directory does NOT exist, something must have gone wrong.
|
||||||
|
Double-check the output of ```make dev``` to see if there are any errors
|
||||||
|
listed. For support, you can ask in our chatroom: `dicuss@conference.conversejs.org <xmpp:discuss@conference.conversejs.org>`_.
|
||||||
|
|
||||||
|
If you don't have an XMPP client installed, follow this link to
|
||||||
|
`conversejs.org <https://conversejs.org/fullscreen#converse/room?jid=discuss@conference.conversejs.org>`_
|
||||||
|
where you can log in and be taken directly to the chatroom.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`dependency-libsignal`:
|
||||||
|
|
||||||
|
Libsignal
|
||||||
|
---------
|
||||||
|
|
||||||
|
If you want OMEMO encryption, you need to load `libsignal <https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in your page.
|
||||||
|
|
||||||
|
For example::
|
||||||
|
|
||||||
|
<script src="3rdparty/libsignal-protocol-javascript/dist/libsignal-protocol.js"></script>
|
||||||
|
|
||||||
|
The reason libsignal needs to be loaded separately is because it's released
|
||||||
|
under the `GPLv3 <https://github.com/signalapp/libsignal-protocol-javascript/blob/master/LICENSE>`_
|
||||||
|
which requires all other dependent JavaScript code to also be open sourced under the same
|
||||||
|
license. You might not be willing to adhere to those terms, which is why you
|
||||||
|
need to decide for yourself whether you're going to load libsignal or not.
|
||||||
|
|
||||||
|
|
||||||
|
.. _`webserver`:
|
||||||
|
|
||||||
|
Setting up a webserver
|
||||||
|
======================
|
||||||
|
|
||||||
|
When making changes to Converse, either development or theming changes,
|
||||||
|
you'll want to preview them in your browser.
|
||||||
|
|
||||||
|
For this, you'll need to serve the development files via a web server,
|
||||||
|
so that you can see your local changes in the browser.
|
||||||
|
|
||||||
|
Manually starting a web server
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
To both set up the development environment and also start up a web browser to
|
||||||
|
serve the files for you, you can run::
|
||||||
|
|
||||||
|
make serve
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
|
||||||
|
installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
|
||||||
|
available via your package manager. For Mac, you'll need to install XCode and in
|
||||||
|
Windows you can use `Chocolatey <https://chocolatey.org/>`_.
|
||||||
|
|
||||||
|
After running ``make serve`` you can open http://localhost:8000 in your webbrowser to see the Converse website.
|
||||||
|
|
||||||
|
When developing or changing the theme, you'll want to load all the
|
||||||
|
unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html instead.
|
||||||
|
|
||||||
|
You might want to open `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_ in your text editor or IDE as well, to see
|
||||||
|
how ``converse.initialize`` is called and to potentially change any of the
|
||||||
|
settings.
|
||||||
|
|
||||||
|
Starting a web server with live reloading
|
||||||
|
-----------------------------------------
|
||||||
|
|
||||||
|
Alternatively, if you want to have live reloading whenever any of the source files change, you
|
||||||
|
can run ``make devserver`` (which will use `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_).
|
||||||
|
|
||||||
|
Instead of ``dev.html`` being used, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
|
||||||
|
is now being used as the HTML template, and you'll need to modify that file if
|
||||||
|
you want to change the settings passed to ``converse.initialize``.
|
||||||
|
|
||||||
|
If you're running ``make devserver``, you need to open http://localhost:8080.
|
||||||
|
|
|
@ -11,19 +11,109 @@ Theming
|
||||||
Setting up your environment
|
Setting up your environment
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
In order to theme Converse, you first need to set up a :ref:`development` environment
|
In order to theme Converse, you first need to follow the steps for :ref:`setup_dev_environment`, including :ref:`webserver`.
|
||||||
and then you'll also want to follow the guide to :ref:`webserver`.
|
|
||||||
|
Creating a custom theme
|
||||||
|
=======================
|
||||||
|
|
||||||
|
Converse can be themed via CSS custom properties (aka CSS variables) and it has
|
||||||
|
some themes available in its source repository.
|
||||||
|
|
||||||
|
A theme is a CSS file with a specific rule that defines the theme's CSS properties.
|
||||||
|
The rule has a specific selector that must include (and determines) the theme name.
|
||||||
|
|
||||||
|
Inside this CSS rule, various CSS variables are assigned values.
|
||||||
|
The CSS variables mainly refer to the colors that comprise the theme.
|
||||||
|
If you don't specify a value for a specific CSS variable, then the value from
|
||||||
|
the ``classic`` theme is used, as defined in `classic.scss <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes/classic.scss>`_.
|
||||||
|
|
||||||
|
The native theme files can be found in `shared/styles/themes <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes>`_.
|
||||||
|
|
||||||
|
Note, the Converse theme files have a ``.scss`` extension because they are compiled
|
||||||
|
by the Sass compiler into normal CSS files. It's however not necessary to use
|
||||||
|
Sass, basic CSS files will also suffice.
|
||||||
|
|
||||||
|
The theme that Converse uses can be set via the :ref:`theme` configuration
|
||||||
|
setting (and the :ref:`dark_theme` configuration setting for dark mode).
|
||||||
|
|
||||||
|
How are themes applied?
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
When you set a value for the :ref:`theme` configuration setting, Converse will add
|
||||||
|
a class ``theme-${api.settings.get('theme')}`` on the ``converse-root`` DOM
|
||||||
|
element.
|
||||||
|
|
||||||
|
So, for example, if you set the ``theme`` setting to ``"dracula"``, then the
|
||||||
|
``converse-root`` element will get the class ``theme-dracula``.
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
|
||||||
|
converse.initialize({ theme: "dracula" });
|
||||||
|
|
||||||
|
|
||||||
|
.. code-block:: html
|
||||||
|
|
||||||
|
<converse-root class="conversejs theme-dracula"></converse-root>
|
||||||
|
|
||||||
|
|
||||||
|
The apply a theme, there then needs to be a CSS rule with a selector that matches the
|
||||||
|
``theme-dracula`` class on the ``converse-root`` element.
|
||||||
|
|
||||||
|
If you take a look at the theme file `dracula.scss <https://github.com/conversejs/converse.js/tree/master/src/shared/styles/themes/dracula.scss>`_
|
||||||
|
you'll see that it defines a CSS rule with the selector
|
||||||
|
``.conversejs.theme-dracula``.
|
||||||
|
|
||||||
|
This selector matches any DOM element with both the classes ``.conversejs`` and
|
||||||
|
``.theme-dracula``. The ``converse-root`` element will already have the class
|
||||||
|
``.conversejs`` and it will have the class ``.theme-dracula`` if the ``theme``
|
||||||
|
(or ``dark_theme`` in dark mode) configuration setting is set to ``"dracula"``.
|
||||||
|
|
||||||
|
This is how themes are applied, by defining a CSS selector that matches the
|
||||||
|
class ``.theme-${name}`` (where ``name`` is a variable containing the name of
|
||||||
|
the theme), and then setting the ``theme`` (and/or ``dark_theme``) configuration
|
||||||
|
setting.
|
||||||
|
|
||||||
|
To create your own theme, you can create a similar CSS rule that matches
|
||||||
|
your theme's name and then you set the ``theme`` configuration setting to that
|
||||||
|
name. This CSS rule can be in any CSS file that is loaded in your website, or
|
||||||
|
you can even put it in the DOM as an inline style.
|
||||||
|
|
||||||
|
Modifying the CSS
|
||||||
|
=================
|
||||||
|
|
||||||
|
To create a new theme with different colors, it should be enough to create a
|
||||||
|
theme file that sets the various CSS variables (as described above).
|
||||||
|
|
||||||
|
For other CSS-related changes, you can make a specific
|
||||||
|
CSS rule with that matches the element you want to change.
|
||||||
|
|
||||||
|
Sometimes it might however be neccessary to modify the core CSS files from
|
||||||
|
Converse, for example if you're developing new features or fixing styling bugs.
|
||||||
|
|
||||||
|
The CSS files are generated from `Sass <http://sass-lang.com>`_ files that end in ``.scss`` and
|
||||||
|
which are distributed throughout the source code.
|
||||||
|
|
||||||
|
The CSS that is relevant to a particular plugin
|
||||||
|
is usually inside the ``./styles`` directory inside the relevant plugin directory.
|
||||||
|
|
||||||
|
For example: `src/plugins/controlbox/styles <https://github.com/conversejs/converse.js/tree/master/src/plugins/controlbox/styles>`_.
|
||||||
|
|
||||||
|
If you're running ``make watch``, then the CSS will automatically be
|
||||||
|
regenerated when you've changed any of the ``.scss``.
|
||||||
|
|
||||||
|
You can also manually generate the CSS::
|
||||||
|
|
||||||
|
make css
|
||||||
|
|
||||||
Modifying the HTML templates of Converse
|
Modifying the HTML templates of Converse
|
||||||
========================================
|
========================================
|
||||||
|
|
||||||
Converse uses `lit-html <https://lit-html.polymer-project.org/guide>`_ as HTML
|
Converse uses `lit-html <https://lit.dev/docs/libraries/standalone-templates/>`_ as HTML
|
||||||
templating library, and the HTML source code is contained in JavaScript ``.js``
|
templating library, and the HTML source code is contained in JavaScript ``.js``
|
||||||
files in various ``./template`` directories in the source code.
|
files in various ``./template`` directories in the source code.
|
||||||
|
|
||||||
Some top-level templates are found in the ``./src/templates`` directory, but
|
Some top-level templates are also in the ``./src/templates`` directory, but
|
||||||
usually the templates that are relevant to a specific plugin will be find
|
the templates that are relevant to a specific plugin should be inside that plugin's subdirectory.
|
||||||
inside that plugin's subdirectory.
|
|
||||||
|
|
||||||
For example: `src/plugins/chatview/templates <https://github.com/conversejs/converse.js/tree/master/src/plugins/chatview/templates>`_.
|
For example: `src/plugins/chatview/templates <https://github.com/conversejs/converse.js/tree/master/src/plugins/chatview/templates>`_.
|
||||||
|
|
||||||
|
@ -53,19 +143,3 @@ two of my own custom templates.
|
||||||
'./templates/message.js': path.resolve(__dirname, 'path/to/my/custom/chat_message.js'),
|
'./templates/message.js': path.resolve(__dirname, 'path/to/my/custom/chat_message.js'),
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
Modifying the CSS
|
|
||||||
=================
|
|
||||||
|
|
||||||
The CSS files are generated from `Sass <http://sass-lang.com>`_ files that end in ``.scss`` and
|
|
||||||
which are distributed throughout the source code.
|
|
||||||
|
|
||||||
Similarly to the template files, the CSS that is relevant to a particular plugin
|
|
||||||
is usually inside the ``./styles`` directory inside the relevant plugin
|
|
||||||
directory.
|
|
||||||
|
|
||||||
For example: `src/plugins/controlbox/styles <https://github.com/conversejs/converse.js/tree/master/src/plugins/controlbox/styles>`_.
|
|
||||||
|
|
||||||
To generate the CSS you can run::
|
|
||||||
|
|
||||||
make css
|
|
||||||
|
|
|
@ -1,51 +0,0 @@
|
||||||
.. raw:: html
|
|
||||||
|
|
||||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/webserver.rst">Edit me on GitHub</a></div>
|
|
||||||
|
|
||||||
|
|
||||||
.. _`webserver`:
|
|
||||||
|
|
||||||
Setting up a webserver
|
|
||||||
======================
|
|
||||||
|
|
||||||
When making changes to Converse, either development or theming changes,
|
|
||||||
you'll want to preview them in your browser.
|
|
||||||
|
|
||||||
For this, you'll need to serve the development files via a web server,
|
|
||||||
so that you can see your local changes in the browser.
|
|
||||||
|
|
||||||
Manually starting a web server
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
To both set up the development environment and also start up a web browser to
|
|
||||||
serve the files for you, you can run::
|
|
||||||
|
|
||||||
make serve
|
|
||||||
|
|
||||||
.. note::
|
|
||||||
To run the "make" commands, you'll need `GNUMake <https://www.gnu.org/software/make>`_
|
|
||||||
installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or
|
|
||||||
available via your package manager. For Mac, you'll need to install XCode and in
|
|
||||||
Windows you can use `Chocolatey <https://chocolatey.org/>`_.
|
|
||||||
|
|
||||||
After running ``make serve`` you can open http://localhost:8000 in your webbrowser to see the Converse website.
|
|
||||||
|
|
||||||
When developing or changing the theme, you'll want to load all the
|
|
||||||
unminified JS and CSS resources as separate files. To do this, open http://localhost:8000/dev.html instead.
|
|
||||||
|
|
||||||
You might want to open `dev.html <https://github.com/conversejs/converse.js/blob/master/dev.html>`_ in your text editor or IDE as well, to see
|
|
||||||
how ``converse.initialize`` is called and to potentially change any of the
|
|
||||||
settings.
|
|
||||||
|
|
||||||
Starting a web server with live reloading
|
|
||||||
-----------------------------------------
|
|
||||||
|
|
||||||
Alternatively, if you want to have live reloading whenever any of the source files change, you
|
|
||||||
can run ``make devserver`` (which will use `webpack-dev-server <https://github.com/webpack/webpack-dev-server>`_).
|
|
||||||
|
|
||||||
Instead of ``dev.html`` being used, `webpack.html <https://github.com/conversejs/converse.js/blob/master/webpack.html>`_
|
|
||||||
is now being used as the HTML template, and you'll need to modify that file if
|
|
||||||
you want to change the settings passed to ``converse.initialize``.
|
|
||||||
|
|
||||||
If you're running ``make devserver``, you need to open http://localhost:8080.
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user