Countly Documentation

Countly Resources

Here you'll find comprehensive guides to help you start working with Countly as quickly as possible.

Frontend (browser) files

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

Relative paths

One thing to consider while developing client frontend side is that Countly can be installed in subdirectory, thus try using either relative paths (like in css files or html) or use path from countly configuration in absolute paths.

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 maindaining same relative state to CSS files.

External dependencies

If you have any external js or css dependencies, put them in the same javascript folder as countly.view.js and countly.model.js (or stylesheets for css respectively) and they will be minified and put together into combined files countly.plugins.js and plugins.min.css respectively. So in production mode you don't need to require them separately.

In development mode you would need to load them using helper function. To differentiate between production and development mode, use global variable production.

if(!production){
  CountlyHelpers.loadJS("ourplugin/javascripts/external.min.js");
  CountlyHelpers.loadCSS("ourplugin/stylesheets/external.min.css");
}

Frontend (browser) files