Clean meta for release

Author: MGatner

README.md

@@ -6,14 +6,14 @@ File uploads and management, for CodeIgniter 4
 1. Install with Composer: `> composer require tatter/files`
 2. Migrate the database: `> php spark migrate -all`
 2. Seed the database: `> php spark db:seed "Tatter\Files\Database\Seeds\FileSeeder"`
-3. Start managing files: https://[yourdomain.com]/files
+3. Start managing files: https://example.com/files
 
 ## Features
 
 The Files module is a self-contained set of routes and functions that adds uploading and
 CRUD controls to any project. It uses [DropzoneJS](https://www.dropzonejs.com) for
-drag-and-drop uploads, and supports a number of extensions for directing files to other
-locations (WIP).
+drag-and-drop uploads, and supports a number of extensions for generating file thumbnails
+and exporting files to various destinations.
 
 ## Installation
 
@@ -41,14 +41,20 @@ writable/files/*
 ## Configuration (optional)
 
 The library's default behavior can be altered by extending its config file. Copy
-**bin/Files.php** to **app/Config/** and follow the instructions
+**examples/Files.php** to **app/Config/** and follow the instructions
 in the comments. If no config file is found in **app/Config** the library will use its own.
 
 ## Usage
 
 Default routes:
 * **files/index** - If user is allowed `mayList()` then shows all files, otherwise tries to fall back to the current logged in user
-* **files/user** - Shows files for a single user; if no user ID is supplied it defaults to the current logged in user
+* **files/user/{userId}** - Shows files for a single user; if no user ID is supplied it defaults to the current logged in user
+* **files/thumbnail/{fileId}** - Displays the thumbnail for a file
+
+CRUD:
+* **files/upload** - Accepts upload requests from Dropzone
+* **files/delete/{fileId}** - Removes a file
+* **files/rename/{fileId}** - Accepts POST data to rename a file
 
 Available formats:
 * **?format=cards** - Default view with thumbnail on responsive layout
@@ -63,3 +69,51 @@ group for global file access.
 
 By default the **files/** routes are available as soon as the module is installed. In most
 cases you will want to use Route Filters to restrict some or all of the routes.
+
+## Extending
+
+**Controllers/Files.php** is the heart of the module, using cascading options to choose
+which files to display when. This controller has a `setData()` method to allow you to
+intercept this process to provide your own settings at any point. Simply extend the
+controller to your own and then provide whatever changes you would like, followed
+by the `display()` method. E.g.:
+
+```
+<?php namespace App\Controller;
+
+class WidgetFiles
+{
+	public function index($widgetId)
+	{
+		$this->setData([
+			'format' => 'cards',
+			'files'  => model(WidgetModel::class)->getFiles($widgetId),
+			'layout' => 'manage',
+		]);
+
+		return $this->display();
+	}
+}
+
+```
+
+These are the default options for `setData()`, but you may also supply anything else you
+need in your view:
+
+* `source` - The name of the controller method making the call
+* `layout` - The view layout to use (see **Config/Files.php**)
+* `files` - An array of Files to display
+* `selected` - Files to pre-select (for the `select` format)
+* `userId` - ID of a user to filter for Files`
+* `username` - Display name of the user for the default layout title
+* `ajax` - Whether to process the request as an AJAX call (skips layout wrapping)
+* `search` - Search term to filter Files
+* `sort` - File sort field
+* `order` - File sort order
+* `format` - Display format for files (cards, list, select, or your own!)
+* `perPage` - Number of items to display per page
+* `page` - Page number (leave `null` for default Pager handling)
+* `pager` - `Pager` instance to handle pagination
+* `access` - Whether the files can be modified, "manage" or "display"
+* `exports` - Destinations a File may be sent to (see `Tatter\Exports`)
+* `bulks` - Bulk destinations for a group of Files (see `Tatter\Exports`)

bin/Files.php

@@ -0,0 +1,54 @@
+<?php namespace Config;
+
+/***
+*
+* This file contains example values to alter default library behavior.
+* Recommended usage:
+*	1. Copy the file to app/Config/Files.php
+*	2. Change any values
+*	3. Remove any lines to fallback to defaults
+*
+***/
+
+class Files extends \Tatter\Files\Config\Files
+{
+	/**
+	 * Directory to store files (with trailing slash)
+	 *
+	 * @var string
+	 */
+	public $storagePath = WRITEPATH . 'files/';
+
+	/**
+	 * Layouts to use for general access and for administration
+	 *
+	 * @var array<string, string>
+	 */
+	public $layouts = [
+		'public' => 'Tatter\Files\Views\layout',
+		'manage' => 'Tatter\Files\Views\layout',
+	];
+
+	/**
+	 * View file aliases
+	 *
+	 * @var string[]
+	 */
+	public $views = [
+		'dropzone' => 'Tatter\Files\Views\Dropzone\config',
+	];
+
+	/**
+	 * Default display format; built in are 'cards', 'list', 'select'
+	 *
+	 * @var string
+	 */
+	public $defaultFormat = 'cards';
+
+	/**
+	 * Path to the default thumbnail file
+	 *
+	 * @var string
+	 */
+	public $defaultThumbnail = 'Tatter\Files\Assets\Unavailable.jpg';
+}

examples/Files.php

@@ -14,7 +14,7 @@ class Files extends BaseConfig
 	/**
 	 * Layouts to use for general access and for administration
 	 *
-	 * @var string[]
+	 * @var array<string, string>
 	 */
 	public $layouts = [
 		'public' => 'Tatter\Files\Views\layout',

bin/Unavailable.png renamed to examples/Unavailable.png

@@ -4,9 +4,9 @@
 $routes->group('files', ['namespace' => '\Tatter\Files\Controllers'], function ($routes)
 {
 	$routes->get('/', 'Files::index');
-	$routes->get('index/(:any)', 'Files::index/$1');
+	$routes->get('user', 'Files::user');
 	$routes->get('user/(:any)', 'Files::user/$1');
-	//$routes->get('delete/(:num)',    'Files::delete/$1');
+	$routes->get('delete/(:num)',    'Files::delete/$1');
 	$routes->get('thumbnail/(:num)', 'Files::thumbnail/$1');
 
 	$routes->post('upload', 'Files::upload');

src/Commands/MaintainFiles.php

@@ -213,26 +213,6 @@ public function user($userId = null)
 		return $this->display();
 	}
 
-	/**
-	 * Lists selectable files for a form (AJAX).
-	 *
-	 * @param string|integer|null $userId Optional user to filter by
-	 *
-	 * @return RedirectResponse|string
-	 */
-	public function select($userId = null)
-	{
-		$this->setData(['format' => 'select']);
-
-		// If a list of File IDs was passed then pre-select them
-		if ($ids = $this->request->getVar('selected'))
-		{
-			$this->setData(['selected' => explode(',', $ids)]);
-		}
-
-		return $userId ? $this->user($userId) : $this->index();
-	}
-
 	//--------------------------------------------------------------------
 
 	/**
@@ -611,6 +591,7 @@ protected function setDefaults(): self
 	{
 		return $this->setData([
 			'source'   => 'index',
+			'layout'   => 'public',
 			'files'    => null,
 			'selected' => explode(',', $this->request->getVar('selected') ?? ''),
 			'userId'   => null,

src/Config/Files.php

@@ -1,4 +1,4 @@
-<?= $this->extend(config('Files')->layouts['public']) ?>
+<?= $this->extend(config('Files')->layouts[$layout ?? 'public']) ?>
 <?= $this->section('main') ?>
 
 	<div class="row">