Merge pull request #15 from tattersoftware/pages

Pages

Author: MGatner

.github/workflows/analyze.yml

@@ -46,7 +46,7 @@ jobs:
         uses: actions/cache@v2
         with:
           path: ${{ steps.composer-cache.outputs.dir }}
-          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
           restore-keys: ${{ runner.os }}-composer-
 
       - name: Create PHPStan cache directory

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,21 @@ 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/new** - Basic Dropzone form
+* **files/upload** - Accepts AJAX 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 +70,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

@@ -0,0 +1,24 @@
+<?php namespace Tatter\Files\Config;
+
+/**
+ * Class Registrar
+ *
+ * Provides a basic registrar class for testing BaseConfig registration functions.
+ */
+
+class Registrar
+{
+	/**
+	 * Override database config
+	 *
+	 * @return array
+	 */
+	public static function Pager()
+	{
+		return [
+			'templates' => [
+				'files_bootstrap' => 'Tatter\Files\Views\pager',
+			],
+		];
+	}
+}

src/Commands/MaintainFiles.php

@@ -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');