From a0ff85d74eb08c31c31d2f8bbdc0f49f4b542af2 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Wed, 25 Aug 2021 11:55:06 +0200 Subject: [PATCH] Update theming and development documentation * 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 --- docs/source/development.rst | 3 +- docs/source/index.rst | 2 +- docs/source/testing.rst | 14 +++--- docs/source/theming.rst | 88 ++++++++++++++++++------------------- docs/source/webserver.rst | 51 +++++++++++++++++++++ 5 files changed, 103 insertions(+), 55 deletions(-) create mode 100644 docs/source/webserver.rst diff --git a/docs/source/development.rst b/docs/source/development.rst index a6d55056a..2be65b773 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -2,7 +2,7 @@ -.. _development: +.. _`development`: =========== Development @@ -25,6 +25,7 @@ to fix a bug or to add new functionality. dependencies style_guide + webserver plugin_development api/index testing diff --git a/docs/source/index.rst b/docs/source/index.rst index 78665bdab..6c5005a7d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -47,8 +47,8 @@ Table of Contents session configuration development - security theming + security translations troubleshooting documentation diff --git a/docs/source/testing.rst b/docs/source/testing.rst index d1f66a6cf..ef079a553 100644 --- a/docs/source/testing.rst +++ b/docs/source/testing.rst @@ -29,21 +29,17 @@ Automatically run tests on file changes *************************************** To automatically run the tests whenever you make a change to any of the -Converse source code, you can run ``make watch`` in one terminal, and ``make -tests`` or ``make check`` in another. +Converse source code, you can run ``make watch`` in one terminal, and ``make tests`` in another. -``make watch`` will build development bundles of Converse.js (in -``dist/converse.js`` and ``dist/converse.css``) and automatically rebuild them -whenever a source file is modified. - -Similarly, Karma will make sure that the tests are re-executed when the -bundle files are rebuilt. +``make watch`` will build development bundles of Converse (in ``dist/converse.js`` and ``dist/converse.css``) +and automatically rebuild them whenever a source file is modified. +Similarly, Karma will make sure that the tests are re-executed when the bundle files are rebuilt. Running individual tests ************************ -Converse has over 400 tests, and it can take a few minutes to run through all of them. +Converse has over 400 tests, and it can take a while to run through all of them. When developing on Converse, it's often preferable to have a more rapid turnaround time between editing a file and checking whether the most relevant diff --git a/docs/source/theming.rst b/docs/source/theming.rst index 4b2187cac..c3549ecae 100644 --- a/docs/source/theming.rst +++ b/docs/source/theming.rst @@ -11,61 +11,61 @@ Theming Setting up your environment =========================== -In order to theme Converse, you first need to set up a :ref:`development` environment. - -You'll also want to preview the changes you make in your browser, for which a -webserver will be useful. - -To both set up the development environment and also start up a web browser to -serve the files for you, simply run:: - - make serve - -.. note:: - To run the "make" commands, you'll need `GNUMake `_ - installed on your computer. If you use GNU/Linux or \*BSD, it should be installed or - available via your package manager. For Mac, I think you need to install XCode and in - Windows you can use `Chocolatey `_. - -After running ``make serve`` you can open http://localhost:8000 in your webbrowser you'll -see the Converse website. - -However, 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. - +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 ======================================== -The HTML markup of Converse is contained in small ``.html`` files in the -``./src/templates`` directory. +Converse uses `lit-html `_ 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 `_. 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 `_ +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 `_ files in the ``./sass`` directory. +The CSS files are generated from `Sass `_ 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 `_. To generate the CSS you can run:: make css - -Testing your changes -==================== - -The recommended way to test your changes is to run the tests that are part of the Converse source code. -By executing ``make test`` you'll run all tests (which live in the ``spec`` folder) which will open a browser window in which tests are processed. - -You can run a single test by changing ``it(`` to ``fit(`` so that only that one test runs. Then you click the "debug" button in the browser when the tests run. After the test has run, the opened chats will still be visible. - - -Creating dist files -=================== - -Once you've themed Converse, you'll want to create new minified distribution -files of all the JavaScript and CSS. - -Please refer to the :doc:`builds` section for information on how this is done. - diff --git a/docs/source/webserver.rst b/docs/source/webserver.rst new file mode 100644 index 000000000..a2bc0e456 --- /dev/null +++ b/docs/source/webserver.rst @@ -0,0 +1,51 @@ +.. raw:: html + + + + +.. _`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 `_ + 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 `_. + +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 `_ in your text editor or IDE as well, to see +how ``converse.initialize`` is called and to potentially change any of the +settings. + +If you're running ``make devserver``, you need to open http://localhost:8080 +instead. + +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 `_). + +Instead of ``dev.html`` being used, `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``.