# Admin-UI (User Interface)

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

## Introduction

The Admin-UI (Admin User Interface) is .....

{% hint style="info" %}
TODO: explain what it is and what it does
{% endhint %}

### Advantages of the Admin-UI

:thumbsup: The advantages of using the new [Admin-UI](https://devguide.e107.org/plugin-development/admin-ui) are numerous - including, but not limited to:

* No need to code in the HTML or the process of reading or writing to your database.
* Consistent interface with the rest of Admin Area
* Users can select which fields from your database table they wish to view - based on your predefined list.
* The Media-Manager is integrated into the system.
* Easily add drag and drop sorting/re-ordering to your plugin.
* Easily add batch functionality such as deleting, copying, featurebox creation, sitelink creation, userclass modification, etc.
* Easily add inline editing to your data.
* Easily add tabs to keep your plugin's admin-area well organized.

{% hint style="info" %}
:thumbsup: **TIP:** The [Plugin Builder](https://devguide.e107.org/plugin-development/plugin-builder) is very useful tool to use for the Admin-UI as it will generate most of the new code for the Admin-UI of your plugin.
{% endhint %}

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

### **File structure**

Below you can find the basic file structure of of the **admin\_config.php** file. This file serves the Admin-UI to the administrators. 

{% hint style="warning" %}
 It is strongly recommended to use **admin\_config.php** as the filename! 
{% endhint %}

```php
<?php

require_once("../../class2.php");
if (!getperms("P"))
{
	e107::redirect('admin');
	exit;
}


class plugin_blank_admin extends e_admin_dispatcher
{

	protected $menuTitle 	= 'blank Menu';
	protected $modes 		= array(...);
	protected $adminMenu 	= array(....);

	// optional
	protected $adminMenuAliases = array(...);
}
 

class plugin_blank_admin_ui extends e_admin_ui
{
	protected $pluginTitle 	= "...";
	protected $pluginName 	= '_blank';
	protected $table 		= "blank"; 
	protected $listQry 		= "";
	protected $listQry 		= "";
	protected $listOrder	= 'blank_id DESC';
	protected $listGroup	= 'somefield';  
	protected $pid 			= "blank_id";

	// optional
	// protected $perPage 			= 20;
	// protected $batchDelete 		= true;
	// protected \$sortField		= 'somefield_order';
	// protected \$sortParent      	= 'somefield_parent';
	// protected \$treePrefix      	= 'somefield_title';
	// protected $editQry 			= "SELECT * FROM #blank WHERE blank_id = {ID}";
	

	protected  $fields = array(...)


	//required - default column user prefs
	protected $fieldpref = array(...);
	protected $prefs = array(...);

	// optional
	public function init()
	{

	}
	
	
	public function customPage()
	{

	}

	public function beforePrefsSave($new_data, $old_data)
	{

	}
}

class plugin_blank_admin_form_ui extends e_admin_form_ui
{
	
	function blank_type($curVal, $mode) 
	{
		$frm = e107::getForm();
		
		$types = array('type_1'=>"Type 1", 'type_2' => 'Type 2');
		
		if($mode == 'read')
		{
			return vartrue($types[$curVal]).' (custom!)';
		}

		if($mode == 'batch') // Custom Batch List for blank_type
		{
			return $types;
		}

		if($mode == 'filter') // Custom Filter List for blank_type
		{
			return $types;
		}

		return $frm->select('blank_type', $types, $curVal);
	}
	
}

new plugin_blank_admin();
require_once(e_ADMIN."auth.php");
e107::getAdminUI()->runPage();

require_once(e_ADMIN."footer.php");
```

## Classes, methods, variables

{% hint style="warning" %}
This section will summarize the various options which may be used while utilizing the Admin-UI class.&#x20;

**Please note that the documentation for this section is a work-in-progress.** \
Thank you for your patience!
{% endhint %}

### class plugin\_blank\_admin&#x20;

extends e\_admin\_dispatcher

#### $modes

...

####

### class plugin\_blank\_admin\_ui&#x20;

extends e\_admin\_ui

#### $fields

Database fields are defined by the `$fields` value in the Admin-UI class.&#x20;

*Example:*

```php
protected $fields = array(
	
	'myfield_id'  => array(
   		"title" 	=> "My Title", 
   		"type"		=> "text", 
   		"data"		=> "str", 
   		"width"		=> "auto", 
   		"inline"	=>	true
   	),

   // .....
);
```

| Key        | Format            | Description                                           |
| ---------- | ----------------- | ----------------------------------------------------- |
| title      | string            | Field Title                                           |
| type       | string            | Type of Field                                         |
| data       | string            | Data Type                                             |
| width      | string            | width of the column (List View)                       |
| inline     | boolean \| string | Enable or disable inline editing.                     |
| help       | string            | Popup helper text (tooltip)                           |
| readParms  | array             | Parameters specific to the 'list' mode.               |
| writeParms | array             | Parameters specific to the 'edit' and 'create' modes. |

#### type

| Type                   | Description                                                                            |
| ---------------------- | -------------------------------------------------------------------------------------- |
| text                   | text box                                                                               |
| number                 | text box (number)                                                                      |
| checkbox               | checkbox (0 or 1 is returned)                                                          |
| icon                   | icon (from media manager)                                                              |
| textarea               | text area (text only)                                                                  |
| boolean                | radio buttons with enable/disable                                                      |
| bbarea                 | right text area (html)                                                                 |
| dropdown               | dropdown list (ie. `<select></select>` )                                               |
| userclass              | drop-down list of userclasses                                                          |
| userclasses            | checkboxes for multiple userclasses                                                    |
| datestamp              | date / time text box                                                                   |
| user                   | user selection text box. (type 3 letters to find/search)                               |
| hidden                 | hidden field                                                                           |
| ip                     | text field with ip decoding                                                            |
| email                  | text field for email addresses                                                         |
| url                    | text field for urls (becomes clickable in list mode)                                   |
| password               | password field (with optional generator)                                               |
| image                  | Media-manager image selection tool for a single image                                  |
| images                 | Media-manager image selection tool for multiple images                                 |
| file                   | Media-manager file selection tool for a single file                                    |
| files                  | Media-manager file selection tool for multiple files                                   |
| media                  | Media-Manager selection tool for images, mp4, youtube and gylphs. (requires type=json) |
| method                 | custom method                                                                          |
| lanlist                | drop-down list of installed languages                                                  |
| language               | drop-down list of all languages                                                        |
| templates              | Dropdown list of templates (from a template file)                                      |
| null (without quotes)  | Ignore this field and do not save it's data                                            |
| false (without quotes) | Hide this field but save it's data if a posted key value is found.                     |

#### data

| Value             | Description                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| str               | Posted data is converted to string before saving to the database                                       |
| safestr           | Posted data is run through a filter (using `filter_var(FILTER_SANITIZE_STRING)`) and thus strips HTML. |
| int               | Posted data is converted to integer before saving to the database                                      |
| array             | Posted data is converted to an e107 array format. (use `e107::unserialize()` to decode)                |
| json              | Posted data is converted to json format before saving to the database                                  |
| false (no quotes) | Posted data from this field is not saved to the database                                               |

#### readParms (list mode)

| Key    | Value                                          | Field-type               | Comments                |
| ------ | ---------------------------------------------- | ------------------------ | ----------------------- |
| thumb  | (integer)                                      | image                    | Set the thumbnail width |
| url    | (string)  e\_url.php key value or a field key. | number, text, tags, null | Wrap value in a link    |
| target | (string) blank \| dialog                       | number, text, tags, null | Target for 'url' above. |

#### writeParms (create/edit mode)

| Key          | Value                                                                           | Field-type                           | Comments                                                                              |
| ------------ | ------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |
| pre          | (html)                                                                          | (all)                                | Render html just before the field                                                     |
| post         | (html)                                                                          | (all)                                | Render html just after the field                                                      |
| media        | (string)                                                                        | bbarea                               | Sets the media-owner category to be used by the media-manager                         |
| video        | 0 or 1                                                                          | image                                | Show video selector tab in media-manager                                              |
| path         | 'plugin' or null                                                                | image                                | When set to 'plugin', images will be stored in the 'plugin' folder within e107\_media |
| glyphs       | 0 or 1                                                                          | icon                                 | Show glyph selector tab in media-manager                                              |
| size         | large, xlarge, xxlarge, block-level                                             | text, url, email, textarea, dropdown | Set the size (width) of input field                                                   |
| optArray     | (array of key=>value pairs)                                                     | dropdown, checkboxes                 | Set the keys/values to be used in the dropdown or checkboxes.                         |
| placeholder  | (string)                                                                        | text, url, email, textarea           | Placeholder text                                                                      |
| pattern      | (regexp)                                                                        | text, url, email                     | Regular expression validation                                                         |
| type         | date or datetime                                                                | datestamp                            | Choose between date or date and time                                                  |
| readonly     | 0 or 1                                                                          | datestamp                            | Make element read-only                                                                |
| auto         | 0 or 1                                                                          | datestamp                            | Insert current date/time automatically                                                |
| label        | yesno                                                                           | boolean                              | Change "Enabled" and "Disabled" to "Yes" and "No".                                    |
| inverse      | 0 or 1                                                                          | boolean                              | Invert the values of 0 and 1. ie. "Disabled" = 1 and "Enabled" = 0.                   |
| enabled      | (string)                                                                        | boolean                              | Alternate text to replace "Enabled"                                                   |
| disabled     | (string)                                                                        | boolean                              | Alternate text to replace "Disabled"                                                  |
| classlist    | <p>public, guest, nobody, member, admin, main, classes<br>(comma separated)</p> | userclass                            | Set which userclasses should be displayed.                                            |
| tdClassLeft  | (string)                                                                        | (all)                                | Set the css class for the left-side table cell.                                       |
| tdClassRight | (string)                                                                        | (all)                                | Set the css class for the right-side table cell.                                      |
| trClass      | (string)                                                                        | (all)                                | Set the css class for the table row.                                                  |
| nolabel      | 0 or 1                                                                          | (all)                                | Hide the left table cell                                                              |

## Creating a tree structure

The Admin-UI allows to automatically create a tree structure based on parent/child relationship tables.  In order to add a tree structure, add the following code:

```php
protected $sortField  = 'field1';
protected $sortParent = 'field2';
protected $treePrefix = 'field3';
```

In this case:

* `field1` represents the field which determines the order (for example an ID field).&#x20;
* `field2` represents the field which is the parent&#x20;
* `field3` represents the field which is the child

### Examples

{% hint style="info" %}
Examples can be found in the forum and download plugin.
{% endhint %}

```php
protected $sortField  = 'download_category_order';
protected $sortParent = 'download_category_parent';
protected $treePrefix = 'download_category_name';
```