# 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="/pages/-M8L8W_7ppyk2VMmNhSr">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="/pages/-M8L8GkIwhEeyiatLNRC#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="/pages/-M8L8GkIwhEeyiatLNRC#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="/pages/-M8L8GkIwhEeyiatLNRC#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="/pages/-M8AVDQ4CL_ofKpUF9gG">Admin UI </a>configuration.</td><td>No</td></tr><tr><td>e_*.php addons</td><td><a href="/pages/-M8L14wz7KtpK1CWoDWE">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="/pages/-MUU-xAktEgx\_STyxzDR" %}
[Plugin shortcodes](/plugin-development/plugin-shortcodes.md)
{% 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. ](/plugin-development/admin-ui.md)

{% content-ref url="/pages/-M8AVDQ4CL\_ofKpUF9gG" %}
[Admin-UI (User Interface)](/plugin-development/admin-ui.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devguide.e107.org/plugin-development/installation-and-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
