Revision as of 19:58, 2 July 2022

Basic instructions for working on the new WebApp

Getting started

The WebApp uses Angular, PrimeNG, PrimeFlex v3 and ngx-translate.

Angular is the web framework we use.

PrimeNG is an Angular UI Component Library providing various form controls like text edits, check boxes, radio buttons, sliders as well as tables, panels, overlays etc

PrimeFlex is a lightweight responsive CSS utility library to accompany Prime UI libraries.

ngx-translate handles loading translation.

Development vs Production

We have intentionally checked in the production build artifacts, so that the webapp does not need to be rebuilt every time MythTV is built.

Development

To install the correct version of npm, do as follows:

Do not install npm or related packages from the system repository. If you have, uninstall them.

Go to https://nodejs.org and download LTS version 16.15.1 of nodejs. If that is no longer the latest LTS version, please stick with 16.15.1 until we decide to move to the next version. You can get 16.15.1 from https://nodejs.org/download/release/v16.15.1/ . Choose the appropriate tar for your system, node-v16.15.1-linux-x64.tar.xz in most cases. Extract it and copy the included directories to /usr/local/. Then install angular cli by running sudo npm install -g @angular/cli@13.3.8 since we are using version 13.3.8 of angular.

Then change to mythtv/html/backend and run npm install. This will install all the required dependencies and ensure you are using the same versions as other developers. Occasionally you may need to re-run this if additional dependencies are added or updated

Visual Studio Code

Visual Studio Code (VSC) development environment is recommended to work on the WebApp.

To load the code into VSC cd to /mythtv/html/backend and run code . to start working on the WebApp.

VSC has many useful extensions to aid development. Some useful ones are Lingua - Managing nxg-translations, Code Spell Checker and Trailing Spaces.

Starting the development web server

First start a local copy of mythbackend. Certain URLs will be sent to the backend to be answered. (see proxy.conf.js section for details)

In a terminal in VSC type ng serve to start the development http server and point your web browser to http://localhost:4200/ (alternatively the shortcut ng serve --open). Each time you save something in VSC the dev web server cause your browser to reload the web app making it easy to make changes.

proxy.conf.js

The file mythtv/html/backend/src/proxy.conf.js controls how the development web server handles URLs. Without this configuration, all the API calls to the backend would fail, since they are not part of the url routes handled by the webapp.

You can change this to point to any backend you wish to serve the API from (eg. a backend with guide data). You may create additional stanzas to send different URLs to different backends should you wish.

This allows your development environment to be very flexible.

Translations

We use ngx-translate to handle the loading of translations which allows us to switch translations without reloading the webapp.

The translation files are simple json files which can be edited with any text editor or there are tools designed to create and edit them like BabelEdit.

You can find the translation files in the /mythtv/html/assets/i18n/ folder.

If you are using VSC a good plugin to manage translations is Lingua - Managing nxg-translations

How to make a string in an html file translatable

You simply use the translate pipe like this

<h1>{{ 'setupwizard.title' | translate }}</h1>

and in the various translation files you would add

"setupwizard": {
        "title": "Initial Setup Wizard",
    }

If the string you want translated includes html, for example

{
    ...
    "settings": {
        ...
        "hostaddress": {
            "master_desc": "Host name of the Master Backend. <strong>Read only Setting</strong> This is set by selecting \"<i>This server is the Master Backend</i>\" on that server."
        ...

then you need the following syntax, otherwise the html tags are displayed in the page instead of taking effect:

    <div [innerHTML]="'settings.hostaddress.master_desc' | translate"></div>

How to use the Lingua VSC plugin to add a new translation in an html file

1. Select the text you want to translate
2. Right click on it and choose Lingua: Convert text to translation.
3. Choose the language you want to add the translation to from the list.
4. Choose the key you want to use eg from the example above the key is setupwizard.title.
5. To check it was added OK right click it and choose Lingua: Go to translation - You may have to save the xxx.json file before trying to install them.
6. IMPORTANT: before the WebApp can see the new translation, even when using the Angular dev server, you must do a sudo make install in the html directory since it's the backend server that makes the translation files available to the WebApp.
7. If you want to test outside of the Angular dev server eg. you want to test your changes on a real backend server you must do a npm run build to rebuild the WebApp and install that before you will be able to see your changes.

Themes

Themes in PrimeNG are simple css files that define the look of the components available.

Most of the free themes available for PrimeNG have been added and made available for users to choose from. There are currently 34 to choose from. The free themes aren't particularly exciting but they do provide a little choice of colour and light or dark themes.

You can find the css and fonts for the themes in mythtv/html/assets/themes/ as well as the themes.json file that tells the WebApp which themes are available.

How to add a theme

Use an existing css file for a theme as a template and edit as required then add an entry in the themes.json file for your new theme. You would also have to create an icon for the theme and place it into mythtv/html/images/themes/.

Production

When you are happy with the changes you have made, you should run npm run build which will create a production build of the webapp in mythtv/html/apps/backend. These build artifacts should be checked in. Ultimately they will be served by the backend when you visit the new webserver on the backend (currently runs on port 6744 by default)

This is done so that the webapp does not need to be rebuilt at build time, and none of the npm modules are required on a build server.

Possible Problems

Be aware that we use Angular v13.x and PrimeFlex v3 so many tutorials and examples on the web may not compile or work properly if they was written for earlier versions.

Many examples on the web put their assets like images, data files, fonts, css files etc in the src/assets directory unfortunately because of the way our webapp has to be proxied to get it to work with our web server that does not work. Instead you can put your assets into the mythtv/html/assets directory which is made available to the webapp once it is installed. This can lead to some head scratching if you don't make sure the assets are installed before you start the backend and the assets are in there own folder since the backend will only search for them the first time it is started.