File structure

Note: This documentation assumes you are running your installation with IN_DEV enabled.

Due to the multi-application model that the IPS Social Suite employs, and the way that resources are bundled and served to the browser, there are a number of places in which different types of javascript files are stored.

Development & production

When developing for IPS4, you create your javascript files in the application or global directories, with a single file holding a single module. In production, however, IPS4 bundles related files together (concatenating and minifying them in the process) to reduce file size and the number of HTTP requests needed to fetch the scripts.

You should be aware of how the bundles are built and from where, because this will dictate how you specify javascript files to load in your backend PHP code.

Global resources

Global resources are those that are loaded on every page load. This includes:

• Libraries - jQuery, Underscore etc.
• Application setup - Bootstrap module, loader module, base controller etc.
• Global modules - UI widgets, utilities, global controllers etc.
• Front/admin modules - Controllers global to the front-end/admin control panel, needed on every page in that area.

All of the above files are located at <root>/dev/js/.

Application resources

Applications have their own folder for javascript, located at <appName>/dev/js. Within this folder, there should be three subfolders - admin, front and global. These folders hold javascript specific to those areas (or for the whole application, in the case of global).

Within each of those folders respectively, there are further subfolders for different types of javascript file - controllers, templates and mixins. Therefore, within an application, the file structure looks like this:

• /appName
  • /dev
    • /js
      • /front
        • /controllers
          • /profile
            • ips.profile.main.js
            • ips.profile.body.js
        • /templates
          • ips.templates.profile.js
        • /mixins
      • /admin
        • /controllers
        • /templates
        • /mixins
      • /global
        • /controllers
        • /templates
        • /mixins

Bundles for an application are built based on folder/filenames, and use the format <location>_<directory>.js. Taking the structure above as our example, if we loaded front_profile.js, it would contain:

• /js/front/controllers/profile/ips.profile.body.js
• /js/front/controllers/profile/ips.profile.main.js
• /js/front/templates/ips.templates.profile.js

This bundle would then be included in your PHP code like so:

\IPS\Output::i()->jsFiles = array_merge( \IPS\Output::i()->jsFiles, \IPS\Output::i()->js( 'front_profile.js', 'core' ) );

Third-party libraries

An application has an interface directory at <appName>/interface/. This is where third-party libaries used by individual applications should be stored and loaded from. They are not bundled or minified by IPS4, so you should store the pre-minified rather than the uncompressed version.

Assuming you had added a file to interface at <appName>/interface/jquery/jquery.rangyinputs.js, it can be included in your PHP code like so:

\IPS\Output::i()->jsFiles = array_merge( \IPS\Output::i()->jsFiles, \IPS\Output::i()->js( 'jquery/jquery.rangyinputs.js', 'appName', 'interface' ) );