====== Plugin functions ======

These are functions which can be used from within plugins' files.

====== register_plugin() ======

This function is used to register plugin in Instant Update's Plugin System (further: IUPS). It accepts two arguments, first is Plugin ID, which is actually file name of main plugin file, and second is array of plugin data.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type   ^ description                           ^
| $plugin_id | string | Plugin ID, name of plugin's main file |
| $data      | array  | Array with plugin data                |

===== Example =====

<code php>
//set plugin id as file name of plugin
$plugin_id = basename(__FILE__);

//some plugin data
$data['name'] = "IU Footer ad";
$data['description'] = "Advertise Instant Update in the footer of your website.";
$data['author'] = "Instant Update team";
$data['url'] = "http://www.instant-update.com/";

//register plugin to IUPS
if (function_exists('register_plugin')) {
	register_plugin($plugin_id, $data);
}
</code>

====== add_hook() ======

This function is used to attach plugin function to IUPS. It accepts two arguments, first is [[plugins:hooks|hook name]] and second is name of the function you want to attach to the hook.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type   ^ description                           ^
| $where     | string | Name of the hook (chosen from the [[plugins:hooks|list of hooks]]) you want to attach function to |
| $function  | string | Name of the function you want to attach to hook |

===== Example =====

<code php>
if (function_exists('add_hook')) {
	add_hook('iu_page_footer','iufooterad_add2footer');
	add_hook('below_dashboard','iufooterad_add2dash');
}
</code>

====== add_navigation_menu_item() ======

Function to add navigation menu item to the [[usage:auto_menus|automatically generated menus]]. All items added via this function will be added right before last menu item added by Instant Update's [[usage:auto_menus|automatic menus]].

This function can be used only in plugin functions which are attached to following hooks: [[hooks#iu_navigation_menu|iu_navigation_menu]]

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type   ^ description                           ^
| $text      | string | Text which will be linked |
| $link      | string | Linking URL |

===== Example =====

<code php>
function nav_link() {
	add_menu_item("Google", "http://www.google.com/");
}
</code>

====== add_menu_item() ======

Function to add navigation menu item to the menus used in Instant Update administration.

This function can be used only in plugin functions which are attached to following hooks: [[hooks#below_dashboard|below_dashboard]], [[hooks#above_dashboard|above_dashboard]], [[hooks#main_nav|main_nav]]

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type    ^ required ^ default value  ^ description                           ^
| $text      | string  | yes      | //NULL//       | Text which will be linked             |
| $link      | string  | yes      | //NULL//       | Linking URL                           |
| $mode      | const.  | no       | IU_LINK_NORMAL | How to open link. Possible values: **IU_LINK_NORMAL** for normal links,\\ **IU_LINK_POPUP** for small popup links and **IU_LINK_BIGPOPUP** for full screen popups.  |
| $title     | string  | no       | Instant Update | Title of popup window. Used only if **$mode** is set to //IU_LINK_POPUP// or //IU_LINK_BIGPOPUP// |
| $width     | integer | no       | 500            | Width of popup window. Used only if **$mode** is set to //IU_LINK_POPUP//  |
| $height    | integer | no       | 250            | Height of popup window. Used only if **$mode** is set to //IU_LINK_POPUP// |

===== Example =====

<code php>
function iufooterad_add2dash() {
	if (iu_is_admin()) {
		add_menu_item("Configure footer Ad", "plugins/iu-footer/iu-footer-config.php", IU_LINK_POPUP, "Footer AD administration", 500, 450);
	}
}
</code>

====== iu_is_admin() ======

This function accepts no arguments and returns TRUE or FALSE if currently logged in user is [[usage:access_levels|administrator user]] or not, respectively.

//Exists from version: 3.0//

===== Variables =====

//NONE//

===== Example =====

<code php>
function iufooterad_add2dash() {
	if (iu_is_admin()) {
		add_menu_item("Configure footer Ad", "plugins/iu-footer/iu-footer-config.php", IU_LINK_POPUP, "Footer AD administration", 500, 450);
	}
}
</code>

====== iu_is_loggedin() ======

This function accepts no arguments and returns TRUE or FALSE if current web site visitor is logged in into Instant Update administration panel or not, respectively.

//Exists from version: 3.0//

===== Variables =====

//NONE//

===== Example =====

<code php>
function plugin_function() {
	if (iu_is_loggedin()) {
		echo "You are logged in :)";
	}
	else {
		echo "You are not logged in :(";
	}
}
</code>

====== GetSettingsValue() ======

This function returns value of a setting in MySQL database. If there is no such setting in MySQL database, it'll return FALSE.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type   ^ description                             ^
| $setting  | string | Name of the setting which value you want |

===== Example =====

<code php>
if (!GetSettingsValue('iu_footer_url')) { $iu_footer_url = 'http://www.instant-update.com/'; }
else { $iu_footer_url = GetSettingsValue('iu_footer_url'); }
</code>

====== RemoveSetting() ======

This function removes a setting in MySQL database. If there is no such setting in MySQL database, it'll return FALSE.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type   ^ description                                 ^
| $setting  | string | Name of the setting which you want to remove |

===== Example =====

<code php>
if (isset($_GET['uninstall']) && iu_is_admin()) {
	RemoveSetting('iu_footer_url');
	RemoveSetting('iu_footer_image_alt');
	RemoveSetting('iu_footer_image');
	RemoveSetting('iu_footer_image_align');
	RemoveSetting('iu_footer_image_target');
	RemoveSetting('iu_footer_active');
	die("<p>IU footer Ad data removed! Now you can remove folder iu-footer from your plugins directory!</p>");
}
</code>

====== WriteSettingsValue() ======

This function updates setting value in MySQL database. If there is no such setting in MySQL database, it'll create it.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type    ^ required ^ default value  ^ description                                       ^
| $setting   | string  | yes      | //NULL//       | Name of the setting which value you want to write |
| $value     | string  | yes      | //NULL//       | Value of the setting which will be written        |
| $type      | string  | no       | text           | Setting type: **text** for a text box, **radio** for a radio button\\ or **select** for a drop down list |
| $offer     | string  | no       | 500            | Offered values, divided with pipe. Used only if **$type** is set to //radio// or //select//  |

===== Example =====

<code php>
if (GetSettingsValue('iu_footer_image_target') == false) {
	WriteSettingsValue('iu_footer_image_target', '_blank','select','_blank|_self|_top');
}
</code>

====== CreateSettingFormField() ======

This function returns HTML code of HTML form field based on setting type in MySQL database.

//Exists from version: 3.0//

===== Variables =====

^ variable   ^ type    ^ required ^ default value  ^ description                                       ^
| $setting   | string  | yes      | //NULL//       | Name of the setting which HTML form field you want to display  |
| $delimiter | string  | no       | //SPACE//      | Value of the divider with which offered values will be divided.\\ Used only if **type** of the setting is //radio//        |
| $updating  | boolean | no       | TRUE           | Whether current value will be shown in HTML form field (TRUE) or not (FALSE)        |

===== Example =====

<code php>
echo CreateSettingFormField('iu_footer_active','<br />');
</code>