# Installation & configuration

{% hint style="danger" %}
**Please note:** This page is under construction and has not been finished yet.
{% endhint %}

## Introduction

## Folder structure & files

The table below lists the files that can be used in a plugin. Only few of them are mandatory.&#x20;

{% hint style="info" %}
**Note:** Please replace the cursive *plugin* with the name of the plugin folder. \
(\**menu.php, \*\_setup.php, \*\_shortcodes.php, \*\_sql.php).*&#x20;
{% endhint %}

{% hint style="success" %}
**TIP:** the \_blank plugin contains useful examples as reference material.&#x20;
{% endhint %}

<table><thead><tr><th width="249.33333333333331">Filename / Foldername</th><th>Description</th><th>Mandatory?</th></tr></thead><tbody><tr><td>languages<br><em>(folder)</em></td><td>Contains the <a href="internationalisation">language files</a></td><td><strong>English language files</strong> </td></tr><tr><td>templates <br><em>(folder)</em></td><td></td><td></td></tr><tr><td><a href="#plugin-xml">plugin.xml</a></td><td>Contains all the meta data needed for the plugin to be installed and configured on a basic level. </td><td><strong>Yes</strong></td></tr><tr><td><a href="#plugin_menu.php"><em>plugin</em>_menu.php</a></td><td></td><td>No</td></tr><tr><td><a href="#plugin_setup-php"><em>plugin</em>_setup.php</a></td><td>Allow to run code before or after (un)installing the plugin, or to set checks for newer plugin versions. <br></td><td>No</td></tr><tr><td><a href="#undefined"><em>plugin</em>_shortcodes.php</a></td><td>...<br></td><td>No</td></tr><tr><td><a href="#plugin_sql-php"><em>plugin</em>_sql.php</a></td><td>Contains the database structure.</td><td>No</td></tr><tr><td><a href="#undefined">admin_config.php</a></td><td>Contains the <a href="admin-ui">Admin UI </a>configuration.</td><td>No</td></tr><tr><td>e_*.php addons</td><td><a href="extending-core-functionality-addons">See addons</a>.</td><td>No</td></tr></tbody></table>

## plugin.xml

### Elements & attributes

<table><thead><tr><th width="199">Element</th><th width="150">Sub</th><th width="150">Attributes</th><th width="196.40740740740745">Text / Value</th><th width="150">Mandatory?</th></tr></thead><tbody><tr><td><strong>&#x3C;e107Plugin></strong></td><td></td><td></td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>name</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>version</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>date</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>lan</td><td></td><td>No</td></tr><tr><td></td><td></td><td>compatibility</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>installRequired</td><td></td><td><strong>Yes</strong></td></tr><tr><td><strong>&#x3C;author></strong></td><td></td><td>name</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>url</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>email</td><td></td><td><strong>Yes</strong></td></tr><tr><td><strong>&#x3C;description></strong></td><td></td><td></td><td>Textual description of the plugin</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>lan</td><td>LAN reference to the description</td><td>No</td></tr><tr><td>&#x3C;copyright></td><td></td><td></td><td>Copyright text</td><td>?</td></tr><tr><td><strong>&#x3C;category></strong></td><td></td><td></td><td>Plugin category.  Choose from:<br>- <code>settings</code><br>- <code>users</code><br>- <code>content</code><br>- <code>tools</code><br>- <code>manage</code><br>- <code>misc</code><br>- <code>menu</code><br>- <code>about</code></td><td><strong>Yes</strong></td></tr><tr><td>&#x3C;keywords></td><td></td><td></td><td></td><td>No</td></tr><tr><td>    </td><td>&#x3C;word></td><td></td><td>Keyword</td><td>No</td></tr><tr><td>&#x3C;adminLinks></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;link></td><td></td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>url</td><td>URL of the link</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>description</td><td>Description of the link</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>icons</td><td>icon path</td><td><strong>Yes</strong></td></tr><tr><td>&#x3C;sitelinks></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;link></td><td></td><td>Link name</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>url</td><td>URL of the link</td><td><strong>Yes</strong></td></tr><tr><td>&#x3C;pluginPrefs></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;pref></td><td></td><td>Value of the pref</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>name</td><td>Name of the pref</td><td><strong>Yes</strong></td></tr><tr><td>&#x3C;dependencies></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;plugin></td><td></td><td></td><td>No</td></tr><tr><td></td><td></td><td>name</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>min_version</td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;PHP></td><td></td><td></td><td>No</td></tr><tr><td></td><td></td><td>name</td><td></td><td><strong>Yes (= core)</strong></td></tr><tr><td></td><td></td><td>min_version</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td>&#x3C;MySQL></td><td></td><td></td><td>No</td></tr><tr><td></td><td></td><td>name</td><td></td><td><strong>Yes (= server)</strong></td></tr><tr><td></td><td></td><td>min_version</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td>&#x3C;extension></td><td></td><td></td><td>No</td></tr><tr><td></td><td></td><td>name</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>min version</td><td></td><td>No</td></tr><tr><td>&#x3C;userClasses></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;class></td><td></td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>name</td><td>class_name (lowercase)</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>description</td><td>Description of the userclass</td><td><strong>Yes</strong></td></tr><tr><td>&#x3C;extendedFields></td><td></td><td></td><td></td><td>No</td></tr><tr><td></td><td>&#x3C;field></td><td></td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>name</td><td>Name of the EUF</td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>type</td><td><p>Type of the EUF. Choose from:</p><ul><li>EUF_TEXT</li><li>EUF_RADIO</li><li>EUF_DROPDOWN</li><li>EUF_DB_FIELD</li><li>EUF_TEXTAREA</li><li>EUF_INTEGER</li><li>EUF_DATE</li><li>EUF_LANGUAGE</li><li>EUF_PREDEFINED</li><li>EUF_CHECKBOX</li><li>EUF_PREFIELD</li><li>EUF_ADDON</li><li>EUF_COUNTRY</li><li>EUF_RICHTEXTAREA</li></ul></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>default</td><td></td><td><strong>Yes</strong></td></tr><tr><td></td><td></td><td>active</td><td>true/false</td><td><strong>Yes</strong></td></tr></tbody></table>

### Examples

#### Simple&#x20;

```markup
<?xml version="1.0" encoding="utf-8"?>
<e107Plugin name="Newsfeeds" version="2.0" date="2012-08-01" compatibility="2.0" installRequired="true">
	<author name="e107 Inc." url="http://e107.org" email="@" />
	<description>This plugin's description.</description>
	<category>content</category>
	<adminLinks>
		<link url='admin_config.php' description='Configure Newsfeeds' icon='images/icon_32.png' iconSmall='images/icon_16.png' >LAN_CONFIGURE</link>	
	</adminLinks>
	<siteLinks>
		<link url="/e107_plugins/newsfeed/newsfeed.php" >Newsfeeds</link>
	</siteLinks>	
</e107Plugin>
```

#### Advanced

```markup
<?xml version="1.0" encoding="utf-8"?>
<e107Plugin name="FAQs" version="1.1"  lan="LAN_PLUGIN_XXX_NAME" date="2012-08-01" compatibility="2.0" installRequired="true">
	 <author name="e107 Inc" url="http://www.e107.org" email="@" />
	<summary>Add frequently asked questions to your e107 website.</summary>
	<description  lan="LAN_PLUGIN_XXX_DESCRIPTION">A simple plugin to add Frequently Asked Questions to your website.</description>
	 <copyright>Copyright e107 Inc e107.org, Licensed under GPL</copyright>
	<category>content</category>
	<keywords>
		<word>faq</word>
		<word>question</word>
		<word>answer</word>
	</keywords>
	<adminLinks>
		<link url='admin_config.php' description='Configure FAQs' icon='images/icon_32.png' iconSmall='images/icon_16.png' primary='true'>LAN_CONFIGURE</link>		
	</adminLinks>
	<siteLinks>
		<link url='/e107_plugins/faqs/faqs.php' description='FAQs' icon='images/icon_32.png' iconSmall='images/icon_16.png' function="faqCategories">LAN_PLUGIN_FAQS_NAME</link>		
	</siteLinks>
	<pluginPrefs>
		<pref name="add_faq">255</pref>
		<pref name="submit_question">255</pref>
		<pref name="classic_look">0</pref>
	</pluginPrefs>
	<dependencies>
		<plugin name='chatbox_menu' />
		<plugin name='calendar_menu' min_version='3.70' />
		<PHP name='core' min_version='5.2.5' />
		<MySQL name='server' min_version='4.9' />
		<extension name='curl' min_version='1.3' />
		<extension name='mb_string' />
	</dependencies>
	<userClasses>
		<class name="faq_moderator" description="FAQ moderator" />		
	</userClasses>
	<extendedFields>
		<field name="viewed" type='EUF_TEXTAREA' default='0' active="true" />
		<field name="posts" type='EUF_INTEGER' default='0' active="true" />
	</extendedFields>	
</e107Plugin>
```

### **Commercial plugins**

Commercial plugins can make use of a few extra attributes to the \<e107Plugin> element, so that this information will be displayed correctly in the admin area under :point\_right: "[Find Plugins](https://userguide.e107.org/administration/manage/plugin-manager#find-plugins)".&#x20;

| Attribute | Description                                                                                                                                                                                                                                                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price     | <p>Purchasing price of the plugin (in xx.xx format). <br><br><em>Example: 25.00</em></p>                                                                                                                                                                                                                                                                                          |
| Currency  | <p>Currency codes (ISO 4217)<br><br><em>Example: EUR</em></p>                                                                                                                                                                                                                                                                                                                     |
| URL       | <p>Direct path to the website page where the plugin can be purchased. When the user clicks to download your plugin, the URL will be displayed.</p><p></p><p><span data-gb-custom-inline data-tag="emoji" data-code="2757">❗</span><em>Note: do not add the URL to the generic homepage of your website, but only the URL to the specific page for that specific plugin.</em> </p> |

#### Example

```markup
<e107Plugin name="FAQs" .... price="25.00" currency="EUR" url="http://direct-path-to-my-plugin-purchase-page.com" >
```

## *plugin*\_menu.php

....

## *plugin*\_setup.php

{% hint style="info" %}
Do not forget to use your plugin name in the filename, e.g. "*myplugin\_setup.php*"
{% endhint %}

{% hint style="info" %}
TODO: Add this section, provide example.&#x20;
{% endhint %}

## *plugin\_shortcodes.php*

Please refer to the [Plugin shortcodes](#plugin_shortcodes.php) page

{% content-ref url="plugin-shortcodes" %}
[plugin-shortcodes](https://devguide.e107.org/plugin-development/plugin-shortcodes)
{% endcontent-ref %}

## *plugin*\_sql.php

{% hint style="info" %}
Do not forget to use your plugin name in the filename, e.g. "*myplugin\_sql.php*"
{% endhint %}

This file contains the SQL database structure of the plugin. It will be analyzed on plugin install and missing tables will be installed automatically.&#x20;

Any differences between the defined structure here and the table structure on the server will be detected and the user will be informed in the Admin Area.&#x20;

{% hint style="success" %}
:thumbsup:**TIP:** To check if the table structure is still valid, run  :point\_right:"Admin Area > Tools > Database > [Check for Updates](https://userguide.e107.org/administration/tools/database#check-for-updates)"&#x20;
{% endhint %}

### Supported operations

For the moment, the following operations are supported:

* Create table
* Change field type, field size, field null or not, field default value
* Add index

### Unsupported operations

Operations that are currently NOT supported are:

* **Rename table:** by renaming the tablename, e.g. "blank" > "blank2"). The renamed table will be considered as new!
* **Drop a table:** e.g. if you remove the "blank" table definition from this file, the table will NOT be deleted from the database!)
* **Rename or drop a field:** a renamed field will be considered new, a missing field definition will NOT be recognized at all!
* **Change an index/key:** the change is recognized, but leads to an error message and the change is not applied.&#x20;
* **Rename or drop an index/key:** rename is recognized as a new index and the missing index is not recognized at all!)
* A field definition containing "NULL DEFAULT NULL". The "Check for updates" method will always detect a change.&#x20;
* but fails silently when trying to update. In that case remove the first "NULL" and run the the "Check for updates" again.

{% hint style="success" %}
:thumbsup:**TIP:** Check the *blank\_setup.php* file or the forum\_setup.php file for examples on renaming/dropping/modifying tables, fields and indexes.&#x20;
{% endhint %}

### Example

```sql
CREATE TABLE blank (
  `blank_id` int(10) NOT NULL AUTO_INCREMENT,
  `blank_icon` varchar(255) NOT NULL,
  `blank_type` varchar(10) NOT NULL,
  `blank_name` varchar(50) NOT NULL,
  `blank_folder` varchar(50) DEFAULT NULL,
  `blank_version` varchar(5) NOT NULL,
  `blank_author` varchar(50) NOT NULL,
  `blank_authorURL` varchar(255) NOT NULL,
  `blank_date` int(10) NOT NULL,
  `blank_compatibility` varchar(5) NOT NULL,
  `blank_url` varchar(255) NOT NULL,
  `blank_media` json DEFAULT NULL,
  `blank_class` int(10) NOT NULL,
  PRIMARY KEY (`blank_id`)
) ENGINE=MyISAM;
```

## admin\_config.php

Please refer to the[ Admin-UI (User Interface) page. ](https://devguide.e107.org/plugin-development/admin-ui)

{% content-ref url="admin-ui" %}
[admin-ui](https://devguide.e107.org/plugin-development/admin-ui)
{% endcontent-ref %}
