====== Plugin functions ======
This page documents the GetSimpleCMS functions available from ''admin/inc/plugin_functions.php''.\\
The ones you will most commonly need as a plugin/ theme developer are:
<code>register_plugin, add_action, add_filter, createSideMenu, createNavTab, register_script, queue_script, register_style, queue_style</code>

The following functions are mostly used by GS internally:
<code>get_scripts_frontend, get_scripts_backend, get_styles_frontend, get_styles_backend, read_pluginsxml, create_pluginsxml, cdn_fallback, change_plugin</code>
===== add_action =====
**Signature**
<code>add_action($hook_name, $added_function[, $args])</code>

**Description**\\ 
Hooks ''$added_function'' in the function queue to be executed at ''$hook_name''.

**Parameters**
  * ''$hook_name'', the name of the hook to add ''$added_function'' to. See [[plugins:hooks_filters|core hooks list]]
  * ''$added_function'', the function you want to execute at ''$hook_name''
  * ''$args'' (optional), additional arguments you can supply to the ''$added_function''

===== exec_action =====
**Signature** 
<code>exec_action($hook_name)</code>
**Description**\\ 
Registers a hook at the line where it is called. Other plugins can then execute a function in that hook by using ''add_action($hook_name,'their_function');''

**Parameters**
  * ''$hook_name'', the name of the hook to execute

===== createSideMenu =====
**Signature**
<code>createSideMenu($id, $txt[, $action=null, $always=true])</code>

**Description**\\
Adds a sidebar link item to the sidebar with ''$id'' as id. 

**Parameters:**
   *''$id'', the id of the sidebar to output the link in
   *''$txt'', the text of the sidebar item
   *''$action'' //(optional)//, the action parameter in the link's query string. Eg, "edit" will generate a link like ''load.php?id=myplugin&action=edit''
   *''$always'' //(optional)//, set to true if the sidebar item should be loaded on every admin page with a sidebar.
===== createNavTab =====
**Signature**
<code>createNavTab($tabname, $id, $tabtitle[, $action=null])</code>

**Parameters:**
  * ''$tabname'', the 'page type' of the tab to be created.
  * ''$id'', the ID of the plugin page, as retrieved in the URL as ''load.php?id=plugin_id''.
  * ''$tabtitle'', the title displayed on the nav tab.
  * ''$action'' (optional)

===== register_plugin =====
**Signature**
<code>register_plugin($id, $name[, $ver=null, $auth=null, $auth_url=null, $desc=null, $type=null, $init=null])</code>

**Description**\\
Registers a plugin in the ''$plugin_info'' list. \\ 

**Parameters**
  * ''$id'', the unique ID of the plugin
  * ''$name'', the display name of the plugin
  * ''$ver'' //(optional)//, the version of the plugin
  * ''$auth'' //(optional)//, the author of the plugin
  * ''$auth_url'' //(optional)//, the plugin's or author's website
  * ''$desc'' //(optional)//, the plugin's short description
  * ''$type'' //(optional)//, the plugin's page type (can be a built-in page type or custom defined)
  * ''$init'' //(optional)//, the function to run on plugin page load

===== add_filter =====
**Signature**
<code>add_filter($filter_name, $added_function)</code>

**Description**\\
Provides the ability to filter/modify content passed to ''$added_function''.\\ The (filtered) content is provided to ''$added_function'' as parameter and **must** be returned at the end of the function. \\ 

**Parameters**
  * ''$filter_name'', the name of the filter to hook into. Use one of the [[plugins:hooks_filters|built-in filters]], or one defined by a plugin.
  * ''$added_function'', the name of a function to execute on ''$filter_name''.
===== exec_filter =====
**Signature**
<code>exec_filter($filter_name[, $data = array()])</code>

**Description**\\
Allows filtering content passed as ''$data''. Functions called in ''add_function'' will have access to the ''$data'' parameter.\\ 
These functions //must// return the modified data.

**Parameters**\\
  * ''$filter_name'', the name of the filter. Other developers can add their filters by calling ''add_filter($filter_name, 'their_function');''
  * ''$data'' //(optional)//, the data to be passed through the filter (an array of parameters). Defaults to null.
===== change_plugin =====
**Signature**
<code>change_plugin($name[, $active = null])</code>

**Description**\\ 
Toggles the state of a plugin (active/ inactive). Pass ''$active'' to force activation.\\ 

**Parameters**
  * ''$name'', the name of the plugin to (de)activate.
  * ''$active'' //(optional)//, if specified, will always activate plugin with id ''$name''.

===== read_pluginsxml =====
**Signature**
<code>read_pluginsxml()</code>

**Description**\\
Reads in the ''plugins.xml'' file and populates the ''$live_plugins'' array with activated plugins

===== create_pluginsxml =====
**Signature**
<code>create_pluginsxml([$force = false])</code>

**Description**\\
Reads in each plugin and creates the ''plugins.xml'' file, if it does not exist, or if ''$force'' is ''true''.

**Parameters**\\
   * ''$force'' //(optional)// force recreating the ''plugins.xml'' file

===== register_script =====
**Signature**
<code>register_script($handle, $src, $ver[, $in_footer=FALSE])</code>

**Description**\\
Registers a script in the global ''$GS_scripts''.

**Parameters**\\
   * ''$handle'', a unique identifier for the script
   * ''$src'', path to the script
   * ''$ver'', the script's version
   * ''$in_footer'' //(optional)//, whether the script should be loaded in the page footer. In the document head by default.
===== deregister_script =====
**Signature**
<code>deregister_script($handle)</code>

**Description**\\
Removes the identified script completely from the ''$GS_scripts'' global.

**Parameters**
   * ''$handle'', the unique identifier of the script as registered with ''register_script''
===== queue_script =====
**Signature**
<code>queue_script($handle, $context)</code>

**Description**\\
Queue a script to be outputted in the front- or backend (depending on ''$context''), or pass 1 to load in both.

**Parameters**\\
   * ''$handle'', the style's unique identifier as registered with ''register_style''
   * ''$context'', pass "GSBACK" or "GSFRONT" constant as parameter, depending on where you want the script loaded
===== dequeue_script =====
**Signature**
<code>dequeue_script($handle, $context)</code>

**Description**\\
Removes a script queued with ''register_script'' from the script queue (effectively un-loading it).

**Parameters**
   *''$handle'', identifier of the script as registered with ''register_script''.
   *''$context'', pass in either "GSBACK" or "GSFRONT", depending on where the script should be dequeued.
===== get_scripts_frontend =====
**Signature**
<code>get_scripts_frontend([$footer=FALSE])</code>

**Description**\\
Outputs script tags for all scripts queued in the GSFRONT context. Is called once in the theme header, and once in the footer.

**Parameters**\\
   *''$footer'' //(optional)//, Whether to load scripts registered with ''register_script'' where the ''$in_footer'' parameter is either false or true. False by default.
===== get_scripts_backend =====
**Signature**
<code>get_scripts_backend([$footer=FALSE])</code>

**Description**\\
Outputs script tags for all scripts queued in the GSBACK context. Is called once in the admin header, and once in the footer.

**Parameters**\\
   *''$footer'' //(optional)//, Whether to load scripts registered with ''register_script'' where the ''$in_footer'' parameter is either false or true. False by default.
===== cdn_fallback =====
**Signature**
<code>cdn_fallback($script)</code>

**Description**\\
Ouputs a local cdn fallback link. Only works when ''GSNOCDN=false''.

**Parameters**\\
   * ''$script'', the script to fall back for
===== register_style =====
**Signature**
<code>register_style($handle, $src, $ver, $media)</code>

**Description**\\
Registers a stylesheet in the global ''$GS_styles''.

**Parameters**\\
   * ''$handle'', a unique identifier for the script
   * ''$src'', path to the style
   * ''$ver'', the style's version
   * ''$media'', sets the media attribute on the HTML ''<link>'' tag, e.g. 'screen', 'all', 'print', etc.
===== queue_style =====
**Signature**
<code>queue_style($handle[, $context=1])</code>

**Description**\\
Queue a style to be outputted in the front- or backend (depending on ''$context''), or pass 1 to load in both.

**Parameters**\\
   * ''$handle'', the style's unique identifier as registered with ''register_style''
   * ''$context'' //(optional but advised)//, usually you would pass "GSBACK" or "GSFRONT" as parameter, depending on where you want the style loaded. By default: loads it in both contexts.
===== dequeue_style =====
**Signature**
<code>dequeue_style($handle, $context)</code>

**Description**\\
Removes a style queued with ''queue_style'' from the stylesheet queue (effectively un-loading it).

**Parameters**
   *''$handle'', identifier of the style as registered with ''register_style''.
   *''$context'', pass in either "GSBACK" or "GSFRONT", depending on where the style should be dequeued.
===== get_styles_frontend =====
**Signature**
<code>get_styles_frontend()</code>

**Description**\\
Loops through the ''$GS_styles'' global and outputs all styles queued with ''queue_style''\\
where the queueing ''$context'' is "GSFRONT", on front-end pages.


===== get_styles_backend =====
**Signature**
<code>get_styles_backend()</code>

**Description**\\
Loops through the ''$GS_styles'' global and outputs all styles queued with ''queue_style''\\ 
where the queueing ''$context'' is "GSBACK", on admin pages.