# 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](/plugin-development/admin-ui.md) 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](/plugin-development/plugin-builder.md) 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="/pages/-M8L7UlhkmSR6OQuNPAr" %}
[Plugin Builder](/plugin-development/plugin-builder.md)
{% 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';
```


---

# 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/admin-ui.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.