module_class.html

---
layout: default
navPage: docs
heading: Module.class.php
breadcrumbs:
  - Module Development,/module_development/
  - Form Tools 3,/module_development/ft3/
  - Anatomy of a Module,/module_development/ft3/anatomy/
  - Module.class.php
prev: Anatomy of a Module,/module_development/ft3/anatomy/
next: index.php,/module_development/ft3/file_index/
categories: module_development
versions: FT3
---

{% include open_section.html nav='nav_module_development_ft3.html' selected='file_module' nav_width=4 %}

	<p>
        Every module has a <code>/code/Module.class.php</code> file that contains the following:
	</p>

    <ul>
        <li>
            High level information about your module: the author name, release date, module name and description
            (in your target language).
        </li>
        <li>
            Installation, uninstallation and upgrade code, should your module require it.
        </li>
        <li>
            Links to JS and CSS resources to get autoloaded in every one of your module pages (very handy!)
        </li>
        <li>
            Defines the module navigation that'll appear in the interface when the user enters your module.
        </li>
        <li>
            Contains any methods you need to expose to the outside world.
        </li>
    </ul>

	<p>
		Let's start with an example.
	</p>

	{% codemirror php %}
<?php

namespace FormTools\Modules\MyModule;

use FormTools\Module as FormToolsModule;

class Module extends FormToolsModule
{
    protected $moduleName = "My Module";
    protected $author = "Your Name";
    protected $authorEmail = "you@something.com";
    protected $authorLink = "https://yoursite.com";
    protected $version = "1.0.0";
    protected $date = "2018-02-20";
    protected $originLanguage = "en_us";
    protected $cssFiles = array(
        // list of CSS files to include here
    );
    protected $jsFiles = array(
        // list of JS files to include here
    );

    protected $nav = array(
        "module_name"  => array("index.php", false),
        "word_submenu" => array("submenu.php", true)
    );

    public function install($module_id)
    {
        return array(true, "");
    }

    public function uninstall($module_id)
    {
        return array(true, "");
    }

    public function upgrade($module_id, $old_module_version)
    {
        return array(true, "");
    }
}
	{% endcodemirror %}

    <h3>Namespace</h3>

    <p>
        Form Tools module code is namespaced to prevent naming conflicts with other modules and the core code. The
        namespace takes the form: <code>FormTools\Modules\YourModuleName</code>. Form Tools folder conventions use
        underscores in folder names, so here your module folder would be named <code>your_folder_name</code>. If your
        folder is named <code>svg_visualizations_lib</code> your namespace needs to be
        <code>FormTools\Modules\SvgVisualizationsLib</code>. If you don't enter the namespace correctly, Form Tools
        will not be able to load or find your module.
    </p>

    <h3>The Module class</h3>

    <p>
        Take a look at <code>global/code/Module.abstract.class.php</code>. All Form Tools modules must extend this
        class - if you forget that step, Form Tools will not recognize your module. Also, note that your class name
        is always <code>Module</code>. You can define as many classes as you want, but the primary module class
        that Form Tools needs to see must be named <code>Module</code>.
    </p>

    <h3>Member variables</h3>

    <div class="row">
        <div class="col-lg-3">
            <code>$moduleName</code>
        </div>
        <div class="col-lg-9">
            The name of your module in the language of your choice. You can also optionally provide a different name for
            people viewing the UI in different languages via your <a href="../file_lang/">language files</a>.
        </div>
    </div>
    <div class="row">
        <div class="col-lg-3">
            <code>$moduleDesc</code>
        </div>
        <div class="col-lg-9">
            <b>This has been removed in 3.1.5.</b> You should now provide a one-liner description of your module
            in the <code>module_description</code> key in your language file. This will allow automatic localization
            of that value in the interface. See the <a href="{{site.baseurl}}/module_development/ft3/file_lang/">Language
            files</a> page for more info.
        </div>
    </div>
	<div class="row">
		<div class="col-lg-3">
			<code>$author</code>
		</div>
		<div class="col-lg-9">
			Your name.
		</div>
	</div>
	<div class="row">
		<div class="col-lg-3">
			<code>$authorLink</code>
		</div>
		<div class="col-lg-9">
			A link to whatever site is relevant for the author.
		</div>
	</div>
	<div class="row">
		<div class="col-lg-3">
			<code>$version</code>
		</div>
		<div class="col-lg-9">
			The current module version. Please follow a simplified semver format of <b>X.Y.Z</b>, where X is the major
            release number, Y is the minor release and Z is for bug fix releases.
		</div>
	</div>
	<div class="row">
		<div class="col-lg-3">
            <code>$date</code>
		</div>
		<div class="col-lg-9">
			The release date of the module version in YYYY-MM-DD format.
		</div>
	</div>
	<div class="row">
		<div class="col-lg-3">
			<code>$originLanguage</code>
		</div>
		<div class="col-lg-9">
			The default language of the module. This maps to the filename of your language file. Set to <code>en_us</code>
            by default.
		</div>
	</div>

	<div class="row">
		<div class="col-lg-3">
			<code>$cssFiles</code>
		</div>
		<div class="col-lg-9">
			This is a convenience option that lets you define CSS files to be included in all of your
            module pages. If you're not using it, just omit the member var altogether. It comes with a couple of handy
            placeholders:

            <ul>
                <li><code>{FTROOT}</code> - the URL of your Form Tools folder, the same value as your
                    <code>$g_root_url</code> value in your
                    <a href="{{site.baseurl}}/userdoc/getting_started/config_file/">config.php</a> file.</li>
                <li><code>{FTVERSION}</code> - your Form Tools version.</li>
                <li><code>{MODULEVERSION}</code> - your module version.</li>
                <li><code>{MODULEROOT}</code> - the URL to your module folder.</li>
            </ul>

            Example:

{% codemirror php %}
protected $cssFiles = array(
    "{MODULEROOT}/styles/css1.css"
    "{MODULEROOT}/styles/css2.css"
);
{% endcodemirror %}

		</div>
	</div>

    <div class="row">
        <div class="col-lg-3">
            <code>$jsFiles</code>
        </div>
        <div class="col-lg-9">
            This works exactly the same as the previous <code>$cssFiles</code> setting and offers the same placeholders.
        </div>
    </div>


	<div class="row">
		<div class="col-lg-3">
            <code>$nav</code>
		</div>
		<div class="col-lg-9">
            This member variable contains your module navigation menu items. They are of the form:
            <code>"lang_key_prop_name" => array("file name", true|false)</code> where the last variable specifies
            whether the menu item should appear as a submenu item. Submenu items are styled differently depending on the
            theme, but they are usuall slightly indented and of a different colour.

            <p>Example:</p>
{% codemirror php %}
protected $nav = array(
    "module_name"   => array("index.php", false),
    "word_settings" => array("/settings/", true)
);
{% endcodemirror %}

            <p>
                Here, your <a href="{{site.baseurl}}/module_development/ft3/file_lang/">language file</a> contains
                at least two properties: "module_nav" and "word_settings" containing the appropriate strings.
            </p>
		</div>
	</div>

    <p>
        Lastly, the <code>install()</code>, <code>uninstall()</code> and <code>upgrade()</code> methods contain
        whatever logic you need to execute for each lifecycle method. If you don't need them, you don't need to
        enter the method. See the following pages for more information, or just keep reading this section to continue
        learning about the basic anatomy of a module.
    </p>

    <ul>
        <li><a href="{{site.baseurl}}/module_development/ft3/installation_method/">Installation method</a></li>
        <li><a href="{{site.baseurl}}/module_development/ft3/uninstallation_method/">Uninstallation method</a></li>
        <li><a href="{{site.baseurl}}/module_development/ft3/upgrade_method/">Upgrade method</a></li>
    </ul>

{% include close_section.html %}