Static Files

Including Javascript and CSS files

The necessary libraries are included directly in the templates at the beginning of the file. Sometimes it is also possible to call them from the controller.

Core JS files of the application

tpl::includeJS('autocomplete', true); - one library

tpl::includeJS('autocomplete', true, 3); - one library with version specified

tpl::includeJS(array('autocomplete','comments'), true); - multiple libraries

• the second parameter true indicates the need to include them from the core
• the names of available libraries can be found in the method implementation

Application JS files

• including the file /public_html/js/bootstrap3.min.js

tpl::includeJS('bootstrap3.min', false); - one library

• including the file with version consideration /public_html/js/bootstrap3.min.js?v=3

tpl::includeJS('bootstrap3.min', false, 3); - one library with version specified

External JS files

• including jQuery

tpl::includeJS('http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js');

• including jQuery with the current protocol taken into account

tpl::includeJS(Request::scheme().'://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js');

Core CSS files

• when including core JS libraries, the necessary CSS files are automatically included

Application CSS files

• including a file and directory css
• the second parameter true indicates the need to include the file from the css directory

tpl::includeCSS('style', true); - /css/style.css

• including a file from the js directory

tpl::includeCSS(SITEURL_STATIC.'/js/fotorama', false); - /js/fotorama.css

External CSS files

tpl::includeCSS('//example.com/style', false); - //example.com/style.css

Initializing Javascript

Javascript code declared in templates must be wrapped in js::start/stop calls:

<script type="text/javascript">
<?php js::start(); ?>
$(function(){
    // code
});
<?php js::stop(); ?>
</script>

This wrapping is necessary in order to be able to control the sequential inclusion of libraries and the placement of js code as one block in the footer.

Naming javascript classes and files

If the JS code is declared in a module, it is associated with that module and often with a specific entity and the logic of that specific page. In this case, the naming should follow these rules:

jUsersSearch - a class responsible for the work of the user search page

• j - required prefix
• Users - required module name Users, if there are multiple key entities in the module append the name of that entity, for example:
  • jOrdersOfferForm - the form for adding/editing an Offer in the Orders module
  • jOrdersOfferChat - working with the comment form for an Offer in the Orders module
• the required page name or logical block name, for example:
  • Search - search page
  • Form - add/edit entity page
  • Register - registration page

The JS file is named as follows:

users.search.js - a file implementing the class that works with the user search page

• the name is formed from the name of the js class, without the j prefix, separated by a dot .
• the file is located in the /public_html/js/ directory

Example of a basic JS class and its initialization

var jUsersRegister = (function(){
    var o = {delay:100}, inited = false, a = 100, b = {};

    function init()
    {
        privateMethod();
    }

    function privateMethod()
    {
    }

    return {
        init: function(options)
        {
            if(inited) return; inited = true;
            o = $.extend(o, options || {});
            $(function(){
                init();
            });
        },
        publicMethod: function()
        {}
    };
}());

The JS class has the form of a private class with a basic init method and an input parameter options.

The init method performs the basic initialization of the class.

It is also possible to declare public methods, like publicMethod, and private methods, like privateMethod, in the example.

All properties are private, in the example the properties a and b.

The parameters of the js class are defined by the data passed to the init method and are available through the o (options) property, for example o.delay.

The initialization of this class in the template .php should look like this:

<script type="text/javascript">
    <?php js::start(); ?>
    jUsersRegister.init(<?= func::php2js(array(
        'delay' => 50,
        'param' => $integer,
        'login_url' => Users::url('login'),
        'lang' => array(
            'email' => _t('users', 'E-mail address is incorrect'),
            'pass'  => _t('users', 'Enter a password'),
        ),
    )) ?>);
    <?php js::stop(); ?>
</script>

More details:

• It is mandatory to include js::start and js::stop.
• When calling the init method, the js hash object is formed using the func::php2js method, thereby passing the necessary data from php to js.
• The lang parameter is mandatory and is used to pass all the necessary strings used in the js class. Note the use of the _t() functions.

Naming of class / id elements in HTML code

All class / id elements related to js code must be declared with the prefix j-.

In other words, do not rely on css classes that define the style of the elements.

class="link j-order-link-toggler" - added the necessary j- class to link to js

class="tabs j-tabs"

id="j-orders-tabs"

id="j-header-menu"

IDs are used to name common blocks, and classes are used for inner elements.

<div id="j-cabinet-tabs">
    <a href="#" class="j-tab">tab 1</a>
    <a href="#" class="j-tab">tab 2</a>
</div>

Core libraries

autocomplete - autocomplete, for example when selecting a region / user

autocomplete.fb - Facebook-style autocomplete, used for selecting tags

fancybox2 - Fancybox 2.x gallery

fotorama - Fotorama gallery

history - cross-browser implementation of working with the History API

jcrop - library for working with thumbnail images

maps - classes for working with maps

qquploader - ajax file uploader

tablednd - class implementing dragging (rotation) of rows in a <table>

wysiwyg - bffWysiwyg editor

Core functions

The core provides some basic functions that are used universally. They are declared within the scope of the global class bff (/public_html/js/bff/bff.js).

Here are some of the main ones:

bff.redirect - performs a redirect to the specified URL

bff.isEmail - checks if a string matches a valid email address

bff.ajax - all ajax requests in the application must be made using this method

bff.iframeSubmit - submits a form via iframe (ajax), for cases when the form contains input=file fields

bff.ajaxURL - generates a URL for making an ajax request

bff.maxlength - implements a character limit + counter in textarea and input=text fields

bff.st.includeJS - includes *.js files from javascript

bff.st.includeCSS - includes *.css files from javascript

bff.declension - handles noun declensions, e.g. "1 file, 2 files, 5 files"

bff.cookie - manages cookie data from javascript

bff.map - methods for working with maps (Google, Yandex) - initialization, auxiliary methods

There are also several globally scoped functions:

nothing - implementation of event interruption (event)

intval - converts a variable to an integer

jQuery extensions:

$.autogrow - implements a resizable textarea, height adjusts depending on the text

$.scrollTo - scrolls to the required HTML block

$.deserialize - fills in a form from query string parameters

For the admin panel, the bff class is additionally extended with the necessary functions used in admin forms and lists (/public_html/js/bff/admin/bff.js).

Here are some of the main ones:

bff.confirm - confirms an action before executing it, a wrapper for the standard alert

bff.adminLink - creates an admin link using javascript

bff.userinfo - opens a popup with brief user information

bff.onTab - toggles between tabs

bff.error - displays an error message

bff.success - displays a success message

bff.ajaxToggle - implements ajax toggles (on/off)

bff.ajaxDelete - implements ajax deletion of records

bff.rotateTable - initializes ajax rotation of rows in a <table>

bff.formChecker - checks for required fields in a form

bff.generateKeyword - generates a keyword based on the title

bff.datepicker - initializes the datepicker component for selecting dates