smartVISU
14:31 v3.5.0

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.
  • html pages will be found as the first hit in the following order: ./apps, ./pages/<yourPages>, ./pages/smarthome (if smarthomeNG is configured as backend), ./dropins and ./pages/base.
  • html widgets as well as .svg, .css and .js files will be imported at the end of the page loading process and overwrite definitions made before.
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:
{% import "@widgets/mywidget.html" as mywidget %}
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.
;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"
...
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.
  • small changes can be made in ./pages/<yourPages>/visu.css to override definitions made in the official smartVISU CSS files.
  • CSS belonging to custom widgets should be placed with the widgets in the same folders. They have a higher priority than visu.css in case of conflicts.
  • further custom CSS definitions can be placed in the ./dropins folder or in ./pages/<yourPages>/css. The latter has the highest priority in case of conflicts.

Javascript Extensions

JavaScript extensions besides the .js widget files can be made in the following ways:
  • integrate small JavaScript extensions in ./pages/<yourPages>/visu.js. These are prioritized over the basic smartVISU functions and drivers but below all widgets.
  • putting .js extensions in the widget folders is not recommended but will work.
  • higher priority in case of conflicts is given to JavaScript files in the folders ./dropins or in ./pages/<yourPages>/js. The latter has the highest priority.
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.

Widgets

Design

Misc