a0ff85d74e
* The templates are no longer `.html` files and are dispersed throughout the source code. * The Sass files are also no longer all in one place * Add a section on webpack aliases for modifying templates without touching the original files Updates #2603
72 lines
2.7 KiB
ReStructuredText
72 lines
2.7 KiB
ReStructuredText
.. 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>
|
|
|
|
.. _theming:
|
|
|
|
=======
|
|
Theming
|
|
=======
|
|
|
|
Setting up your environment
|
|
===========================
|
|
|
|
In order to theme Converse, you first need to set up a :ref:`development` environment
|
|
and then you'll also want to follow the guide to :ref:`webserver`.
|
|
|
|
Modifying the HTML templates of Converse
|
|
========================================
|
|
|
|
Converse uses `lit-html <https://lit-html.polymer-project.org/guide>`_ as HTML
|
|
templating library, and the HTML source code is contained in JavaScript ``.js``
|
|
files in various ``./template`` directories in the source code.
|
|
|
|
Some top-level templates are found in the ``./src/templates`` directory, but
|
|
usually the templates that are relevant to a specific plugin will be find
|
|
inside that plugin's subdirectory.
|
|
|
|
For example: `src/plugins/chatview/templates <https://github.com/conversejs/converse.js/tree/master/src/plugins/chatview/templates>`_.
|
|
|
|
You can modify HTML markup that Converse generates by modifying these files.
|
|
|
|
Use webpack aliases to modify templates without changing the original files
|
|
---------------------------------------------------------------------------
|
|
|
|
Generally what I do when creating a modified version of Converse for a project
|
|
or customer, is that I create a new JavaScript package with its own
|
|
``package.json`` and I then add ``converse.js`` as a dependency (e.g. via ``npm
|
|
install --save converse.js``) to the ``package.json``.
|
|
|
|
Then I add a Webpack configuration and use `webpack aliases <https://webpack.js.org/configuration/resolve/#resolvealias>`_
|
|
to resolve template paths to my own modified files.
|
|
|
|
For example, in the webpack configuration snippet below, I add two aliases, so
|
|
that the ``message-body.js`` and ``message.js`` templates can be replaced with
|
|
two of my own custom templates.
|
|
|
|
.. code-block:: javascript
|
|
|
|
resolve: {
|
|
extensions: ['.js'],
|
|
alias: {
|
|
'./message-body.js': path.resolve(__dirname, 'path/to/my/custom/message-body.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
|