HTML Templates
Within your application's dev directory you'll find a html directory that will contain any templates you create to use in your application. There's three sub-directories:
- admin/ contains templates for any AdminCP interfaces
- front/ contains templates for user-facing, front-end interfaces
- global/ contains templates that are used by both admin and front-end areas
Within each of this directories you should create sub-directories that group your templates into logical areas; typically, each module in your application will have a corresponding directory in both the admin and front template folders, although you're free to group them however you wish.
Templates are created as files with the extension .phtml when in developer mode. When your application is built and installed by others, these template files get compiled.
To use templates within your application code, you write:
\IPS\Theme::i()->getTemplate( 'group', 'app', 'location' )->template_name( ... );
Where each value is:
-
group
The name of the folder you created within the admin/front/global folder. e.g. myModule -
app
Your application key -
location
The location of the group, i.e. one of admin, front or global -
template_name
The name of the template, which is the filename without the .phtml extension.
Any parameters your template requires can be passed in as normal, since template_name gets compiled to a function.
The template file itself must contain a special header line as the very first line:
<ips:template parameters="$example1=array(), $example2=FALSE" />
The parameters attribute simply defines the parameters this template expects. The syntax of this attribute is identical to defining parameters in a PHP function. If you don't require any parameters, you must still include the header and the parameters attribute, but simply leave it empty.
CSS Files
CSS files that your application needs should be created in the dev/css/ directory of your application. As with HTML templates, there's three subdirectories for admin CSS, front-end CSS, and shared CSS. Files you create here need to be loaded manually in your code, like so:
\IPS\Output::i()->cssFiles = array_merge( \IPS\Output::i()->cssFiles, \IPS\Theme::i()->css( 'filename.css', 'app', 'location' ) );
Where each value is:
-
filename.css
The name of your CSS file (with suffix) -
app
Your application key -
location
The location of your CSS file (one of admin, front or global)
Where to load CSS files
Since you load CSS files manually with the above code, where you place this code matters. If your CSS file is very specific to a particular page, you may want to only load it the controller method(s) that handle that page. However, more often, a CSS file will apply to a whole controller within your application. In this case, you can load your CSS file in the controller's execute() method. See the controller documentation for more information.
If you need the CSS for all front-end or admin pages of your application, you can put the .css file directly in the /admin or /front directories, with the file named the same as your application. in this case, IPS4 will automatically bundle and load the CSS file for all pages of your application. For example, if our app key was my_app, we could create a CSS file at /dev/css/front/my_app.css, and it would be included in all front-end pages of our app.
Javascript Files
Javascript files are handled in a similar way to CSS files; that is, they are created as .js files in the appropriate directory, and then loaded on-demand in your code. There is one slight difference: because of the way javascript files are bundled, when include your javascript file you should specify the bundle name rather than the specific javascript file. Javascript files are bundled by location and group, and that forms the filename of the resulting bundle.
For example, if we created javascript files in dev/js/front/mygroup/somefile.js, then the bundle name would be front_mygroup.js (location, underscore, groupname), and loaded as follows:
\IPS\Output::i()->jsFiles = array_merge( \IPS\Output::i()->jsFiles, \IPS\Output::i()->js( 'front_mygroup.js', 'app', 'location' ) );
Images and Other Resources
Images (and other resources, such as fonts) should be placed in the /dev/resources directory, and as usual, there's /front, /admin and /global locations. To use a resource file in a template, you'd use:
<img src='{resource="example.jpg" app="yourapp" location="front"}'>
...changing the filename, application key and location as appropriate.
Report Document