# Edocman Lite – Backend Administration Guide (English)

This guide covers all backend (WordPress admin) features of the Edocman Lite plugin:

- [Configuration](#1-configuration)
- [Categories](#2-categories)
- [Documents](#3-documents)

---

## 1. Configuration

**Menu path:** Edocman Lite → Configuration

The Configuration page controls how the plugin stores and accepts documents.

### Settings

| Field | Default | Description |
|---|---|---|
| **Documents Path** | `{wp-root}/edocman` | Absolute path on the server where uploaded document files are stored. Click **Reset** to restore the default value. A warning is shown if the directory is not writable. |
| **Hierarchical Folders** | Off | When enabled, documents are placed in sub-folders that mirror the category hierarchy (e.g. `edocman/legal/contracts/file.pdf`). |
| **Allowed File Types** | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, zip, rar | Tick each file extension that users are permitted to upload. |
| **Maximum File Size (MB)** | 10 | The largest file that can be uploaded (in megabytes). The upper limit is set by your server's `upload_max_filesize` PHP setting. |

### Version information

The bottom of the page shows the installed plugin version. Edocman Lite checks for updates from WordPress.org every 12 hours; if a newer version exists, a notice is shown at the top of the page with a download link.

### Saving

Click **Save Configuration** to apply any changes.

---

## 2. Categories

**Menu path:** Edocman Lite → Categories

Categories let you organise documents into a hierarchy. The list shows all categories in tree order (child categories are indented under their parent).

### 2.1 Categories List

| Column | Description |
|---|---|
| **Title** | Name of the category. Indented entries are child categories. |
| **Description** | Short excerpt of the category description. |
| **Status** | ✅ Published / ❌ Unpublished |
| **Date** | Date the category was created. |

**Row actions** (appear when you hover over a category title):

- **Edit** — opens the edit form for that category.
- **Delete** — permanently deletes the category (with a confirmation dialog).

**Search:** Use the search box at the top to filter categories by keyword.

**Add New:** Click the **Add New** button (top-right) to create a new category.

---

### 2.2 Add / Edit Category

The add and edit forms share the same fields:

| Field | Required | Description |
|---|---|---|
| **Title** | ✅ Yes | Display name of the category. |
| **Parent Category** | No | Select a parent to nest this category under another. Choose `-- None (Root Category) --` for a top-level category. |
| **Folder Name** | When hierarchical folders are on | Physical folder name used to store documents (letters, numbers, hyphens and underscores only). This field only appears when **Hierarchical Folders** is enabled in Configuration. |
| **Description** | No | Rich-text description of the category (full WordPress editor). |
| **Image** | No | Thumbnail image URL. Click **Select Image** to choose from the Media Library. |
| **Ordering** | No | Integer used to sort categories. Lower numbers appear first. |
| **Published** | No | Tick to make the category visible on the frontend. |

#### Folder Name / Path Preview (Hierarchical Folders only)

When **Hierarchical Folders** is enabled, a live path preview is displayed above the Folder Name input:

```
Full Path:    /parent-folder/my-folder
Parent Path:  /parent-folder           (read-only, set by the selected Parent Category)
Folder Name:  [my-folder_______]       ← editable
```

As you change the Parent Category or type a Folder Name, the Full Path preview updates in real time. The hidden `path` field is submitted with the form and stored in the database.

> **Note:** Changing the folder name of an existing category does **not** automatically move files already stored in the old folder. Files already uploaded will need to be moved manually.

#### Buttons

| Button | Action |
|---|---|
| **Save & Close** | Save the category and return to the categories list. |
| **Apply** | Save the category and remain on the edit form. |
| **Cancel** | Discard changes and return to the categories list. |

---

## 3. Documents

**Menu path:** Edocman Lite → Documents

Documents are the files managed by the plugin. Each document can have one **Main Category** (which determines where the file is stored) and any number of **Additional Categories**.

### 3.1 Documents List

| Column | Description |
|---|---|
| **Title** | Name of the document. |
| **File** | Original file name with a file-type icon. |
| **Size** | Formatted file size (e.g. 1.2 MB). |
| **Downloads** | Number of times the document has been downloaded. |
| **Status** | ✅ Published / ❌ Unpublished |
| **Date** | Date the document was created. |

**Row actions** (appear on hover):

- **Edit** — opens the edit form.
- **Delete** — deletes the document and its associated file (with confirmation).

#### Filtering and Search

- **Category filter** — select a category from the dropdown and click **Filter** to show only documents in that category.
- **Search box** — type a keyword and click **Search Documents** to filter by document title.

#### Bulk Actions

Select one or more documents using the checkboxes, choose an action from the **Bulk Actions** dropdown, then click **Apply**:

| Action | Description |
|---|---|
| **Delete** | Permanently delete the selected documents and their files. |
| **Publish** | Set the selected documents to Published. |
| **Unpublish** | Set the selected documents to Unpublished. |

---

### 3.2 Add / Edit Document

**Add New:** Click the **Add New** button (top-right) on the Documents List page.

| Field | Required | Description |
|---|---|---|
| **Title** | ✅ Yes | Display name of the document. |
| **Main Category** | No | Single-select dropdown. The document file is uploaded into this category's folder. This category is stored with `is_main_category = 1` in the database. |
| **Additional Categories** | No | Multi-select list (hold **Ctrl** or **Cmd** to pick several). These categories are stored with `is_main_category = 0`. The Main Category is excluded automatically. |
| **Document File** | ✅ On add | The file to upload. Only file types enabled in Configuration are accepted. On the edit form, upload a new file to replace the existing one; leave empty to keep the current file. |
| **Short Description** | No | Brief plain-text summary displayed in document list views. |
| **Description** | No | Full rich-text description (WordPress editor). |
| **Thumbnail Image** | No | Image URL for the document thumbnail. Click **Select Image** to choose from the Media Library. |
| **Ordering** | No | Integer used to sort documents. Lower numbers appear first. |
| **Published** | No | Tick to make the document visible on the frontend (default: checked). |

#### How file storage works

When **Hierarchical Folders** is **off**, the file is saved in the `documents/` sub-folder inside the configured Documents Path:

```
{Documents Path}/documents/myfile.pdf
```

The `filename` column in the database stores the relative path:

```
documents/myfile.pdf
```

When **Hierarchical Folders** is **on** and a Main Category is selected, the file is stored in that category's folder:

```
{Documents Path}/legal/contracts/myfile.pdf
```

The `filename` column stores:

```
legal/contracts/myfile.pdf
```

By default, `{Documents Path}` is `{WordPress root}/edocman` (e.g. `/var/www/html/edocman`). This relative path is sufficient to locate the file — no category database join is needed at download time.

#### Buttons

| Button | Action |
|---|---|
| **Save & Close** | Save the document and return to the documents list. |
| **Apply** | Save the document and remain on the edit form. |
| **Cancel** | Discard changes and return to the documents list. |

---

## Quick Reference — Admin Menu Structure

```
Edocman Lite
├── Documents       → list, add, edit, delete documents
├── Categories      → list, add, edit, delete categories
└── Configuration   → plugin settings
```

---

## Common Tasks

### Add a new top-level category
1. Go to **Edocman Lite → Categories**.
2. Click **Add New**.
3. Enter a **Title**.
4. Leave **Parent Category** as `-- None (Root Category) --`.
5. If Hierarchical Folders is on, enter a **Folder Name** (e.g. `reports`).
6. Click **Save & Close**.

### Add a sub-category
1. Go to **Edocman Lite → Categories**.
2. Click **Add New**.
3. Enter a **Title**.
4. Select the parent category in the **Parent Category** dropdown.
5. If Hierarchical Folders is on, enter a **Folder Name** for this sub-level.
6. Click **Save & Close**.

### Upload a new document
1. Go to **Edocman Lite → Documents**.
2. Click **Add New**.
3. Enter a **Title**.
4. Choose a **Main Category** (optional but recommended).
5. Optionally select **Additional Categories**.
6. Click **Choose File** next to **Document File** and select the file.
7. Fill in any additional fields (description, thumbnail, etc.).
8. Ensure **Published** is ticked if the document should be immediately visible.
9. Click **Save & Close**.

### Publish documents uploaded by frontend users
Documents submitted via the frontend `[edocman_lite_upload_document]` shortcode are saved with **Published = No** (pending review).

1. Go to **Edocman Lite → Documents**.
2. Locate the unpublished document (look for the ❌ status icon).
3. Click **Edit**, tick **Published**, and click **Save & Close**.

   — or —

   Select one or more unpublished documents, choose **Publish** from **Bulk Actions**, and click **Apply**.

### Delete a document
- **Single:** Hover over the document title and click **Delete**.
- **Bulk:** Select documents using the checkboxes, choose **Delete** from **Bulk Actions**, and click **Apply**.

> ⚠️ Deletion is permanent. The physical file on the server is also removed.
