/** * ----------------------------------------------------------------------------- * @package smartVISU * @author Martin Gleiß * @copyright 2012 - 2023 * @license GPL [http://www.gnu.de] * ----------------------------------------------------------------------------- */ {% extends "index.html" %} {% block content %}

User Extensions

Depending on the update method used, smartVISU files can get overwritten during the update, so changes and extensions written by the user can get lost. Therefore it is highly recommended to not change any of the original files and folders that come with smartVISU. There are special protected areas reserved for user-written code.

Custom Pages

Folders with indiviual visu pages shall be added to the folder ./pages. Such a folder is named ./pages/<yourPages> in the present docuemntation. All subfolders in ./pages not originating from smartVISU sources will be protected from being overwritten during an update. Pages can also be added to the ./dropins folder but in favour of a clear page structure and origin this is not recommended.

Dropins Folder for User generated Content

All user generated code should be placed into the ./dropins folder and its subfolders which are protected, too. Generally, the ./dropins folders will be read at the very end of the page loading process. This will result in different behaviour of duplicate filenames depending on the file type. Although there are namespaces and dedicated folder structures now for widgets and icons it is recommended to avoid using duplicate filenames in order to avoid unwanted behaviour. It is good practise to name own extensions e.g. with a "my_" in front which is not used in all official smartVISU content.

Custom Widgets

Place your own widgets .html and .js files in ./dropins/widgets. They will be imported automatically from there. See custom widget docu for the generation of your own documentation page for the widget. If you need to import certain widgets within your own widgets use the '@widgets' namespace:
{% filter trim|escape|nl2br %}{% verbatim %} {% import "@widgets/mywidget.html" as mywidget %} {% endverbatim %}{% endfilter %}
SmarthomeNG - if auto page generation is activated - places plugin widgets in ./dropins/shwidgets. Don't place your own widgets there since smarthomeNG will empty the folder on startup.
Widgets can also be placed in a subfolder of your pages folder: ./pages/<yourPages>/widgets. They will get imported from there but the docu page in the folder will not be found.

Additional Icons

Place your own icons in ./dropins/icons. They will be found automatically there. Normally, white icons are sufficient and should be placed in ./dropins/icons/ws. smartVISU widgets will not use black icons unless you force them to do so by specifying the full path. Black icons should then be placed in ./dropins/icons/sw.
Keep in mind that SVG icons need a certain format to enable dynamic colorization in smartVISU. The forum and also the GitHub wiki provide some hints for that.

Language Customization

smartVISU loads the language information recursively, starting with the configured language file and continuing with the language in the "extends = xx" statement. Extensions of the language files can be placed in the folder ./dropins/lang. The procedure is described in ./lang/readme.txt. Create a file named e.g. "custom.ini", define the base language and fill in your individual formats and texts.
{% filter trim|escape|nl2br %}{% verbatim %} ;define a title or delete the following line ;@label My Language ;define the base language extends = "en" ;do not forget the category names [format] kwh = "%01,3f kWh" ... {% endverbatim %}{% endfilter %}
The custom language will be displayed in the configuration menu with its file name or - if the @label line is present - with the defined label. Select this item to activate the language extension.

Custom CSS definitions

There are many options to place custom CSS definitions for styling pages and widgets.

Javascript Extensions

JavaScript extensions besides the .js widget files can be made in the following ways: Defining a JavaScript function or widget in a folder with high priority will replace the function with the same name read earlier in a low priority folder.

More Information

More information can be found on the wiki pages.
Please contribute there if you like to share your knowledge. We'll integrate the contents into this inline documentation later.
{% endblock %}