This page is about the code that will be executed in Countly visitors browser, helping you to create new pages and views for Countly.

On browser side Countly users Backbone.js to render views with Handlebar templating library and Models to load and prepare data for the views

Files you should have

By default Countly expects that you will have:

• One css file named mains.css and located at stylesheets folder
• Two js files named countly.models.js and countly.views.js and located at javascripts folder
• One language file for each language you want to support located in localization folder

These are the files that Countly automatically loads in default dashboard template to be used to modify Countly user interface.

If you need to load additional CSS or Javascript files, you would have to do it dynamically in your countly.views.js file

Localizations

Localization files should be in .properties format for each language you want to support, but should at least have default one in English.

The naming convention for default file in English is your plugin name with properties extension, as ourplugin.properties

Then any additional language should be added in the same directory but with Language ISO standard Alpha 2 code appended to your default file name.

For example:

ourplugin_fr.properties
ourplugin_lv.properties
ourplugin_tr.properties

Images

If your plugin requires to display any kind of images, then they must be located in images folder under folder with your plugin name.

Other files

You can add any additional files in any structure, like creating templates directory and adding files there to fetch them later using ajax request, process using Handlebar and display in your Backbone view.

Example

Assuming your plugin name is "ourplugin", then in your plugins directory, your files should be located as:

 ───frontend
    │
    └───public
        ├───images
        │   └───ourplugin
        │           image1.png
        │           image2.png
        │
        ├───javascripts
        │       countly.models.js
        │       countly.views.js
        │
        ├───localization
        │       ourplugin.properties
        │
        ├───stylesheets
        │       main.css
        │
        └───templates
                tempalte2.html
                template1.html

Production mode

In development mode each plugin file which is requested automatically, like main.css or countly.views.js is requested from its original location and it all works as expected.

But when production mode is enabled, then Countly combines similar files into one and copies them into core, so the server would have less HTTP requests to handle while requesting each files separately.

Javascript files

Both Javascript files (countly.models.js and countly.views.js) from each plugin are precompiled with Uglify.js, so you must make sure your Javascript file can be processed by it and does not error due to incorrect syntax or script errors.

On each plugin enabling or disabling action processes all enabled plugin view and model files by this compiler, and combines them together and saves in {countly}/frontend/express/public/javascripts/min/countly.plugins.js file.

CSS files

All CSS files are also combined in one single file and stored in {countly}/frontend/express/public/stylesheets/main.min.css

But since, as recommended all paths in CSS should be used as relative paths (due to Countly possibly being installed as subdirectory), all your references to images are broken at that point, that is why we come to our last point.

Images

The reason to keeping image structure similar to Countly original structure, is because when in production mode CSS files are copied, a folder with your plugin name in your plugins images directory is also copied, to keep relative links to the CSS file.

So if you had images located at {countly}/plugins/ourplugin/frontend/public/images/ourplugin folder, then in production mode they will be copied and referenced from {countly}/frontend/express/public/images/ourplugin folder maintaining same relative state to CSS files.

External dependencies

If you have some external javascript or CSS files you want to use in your plugin, you can use them of course. If you put javascript files into javascripts directory of your plugin and CSS files respectively into stylesheets directory of your plugin, they will be automatically loaded and used.

But if you place them somewhere else or have a directory of multiple files, you would need to load them manually

CountlyHelpers.loadJS("ourplugin/javascripts/external-lib/external.min.js");
CountlyHelpers.loadCSS("ourplugin/javascripts/external-lib/external.min.css");