4.2.3. Pages and Files

⁠4.2.3. Pages and Files

The plugin API provides a standard hierarchy and process for adding new pages and files to your plugin. For strict definitions, pages are PHP files that will be executed within the MantisBT core system, while files are defined as a separate set of raw data that will be passed to the client's browser exactly as it appears in the filesystem.

Your Plugin's pages must:

be placed in the pages/ directory,
be named using only letters, numbers and underscores, and
have a .php file extension

To generate a URI to a page in MantisBT, the API function plugin_page() should be used. Our Example plugin will create a page named foo.php, which can then be accessed via plugin_page.php?page=Example/foo:

Example/pages/foo.php

<?php
layout_page_header();
layout_page_begin();
?>

<p>
    Here is a link to <a href="<?php echo plugin_page( 'foo' ) ?>">page foo</a>.
</p>

<?php
layout_page_end();

Note

The calls to layout_page_begin() and layout_page_end() trigger the standard MantisBT header and footer portions, respectively, which also displays things such as the menus and triggers other layout-related events. layout_page_header() pulls in the CSS classes for alternating row colors in the table, amongst other things.

Adding non-PHP files, such as images or CSS stylesheets, follows a very similar pattern as pages. Files should be placed in the plugin's files/ directory, the path to this directory can be retrieved by plugin_file_path() function. The file's URI is generated with the plugin_file() function.

For our Example plugin, we'll create a basic CSS stylesheet, and modify the previously shown page to include the stylesheet:

Example/files/foo.css

p.foo {
    color: red;
}

Example/pages/foo.php
...

<link
	rel="stylesheet"
	type="text/css"
	href="<?php echo plugin_file( 'foo.css' ) ?>"
/>
<p class="foo">
    Our custom stylesheet paints this text red.
</p>

Note

While plugin_page() expects only the page's name without the extension, plugin_file() on the other hand requires the entire filename, so that it can distinguish e.g. between foo.css and a potential image file called foo.png.

The plugin's filesystem structure at this point looks like this:

Example/
	Example.php
	pages/
		foo.php
	files/
		foo.css