SelectRelationField and FieldWithRelation

changelog.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.2
+
+### Added
+
+- `SelectRelationField`
+- `FieldWithRelation`
+
+## 1.0.1
+
+### Added
+
+- Default option on `FieldWithOptions`
+- `beforeSave` method on `Field`

docs/fields.md

@@ -3,9 +3,9 @@
 Fields are the way to bring power to your model attributes.  
 Many are available and all are customizable to your needs.
 
-## API
+## Usage
 
-Each field can be attached to you model via the `getCrudFields` method on your `Crudable` model.
+Each field can be attached to your model via the `getCrudFields` method on your `Crudable` model.
 And each of them share the same base API and some have their own additionnal API.
 
 ```php
@@ -17,99 +17,153 @@ public function getCrudFields()
 }
 ```
 
-### Attaching
+## Attach fields
 
-The minimum working code is (rules are facultatives):
+The minimum working code is:
 ```php
-TextField::handle('your-attribute', 'your-rules')
+TextField::handle('your-attribute')
 // or
-new TextField('your-attribute', 'your-rules')
+new TextField('your-attribute')
 ```
 
-### Customizing
-
-Once declared, you can use the Field API to declare your modifiers.
-
-- Declaring Rules: `withRules(array|string $rules)`:  
-They're your field validation rules and they are the same as Laravel Validation.
-
-- Customize the label: `withLabel(string $lavel)`:  
-Allows you to customize the label that'll be displayed on the form. By default, if your identifier is `title` it will be displayed `Title`.
-
-- Customize the placeholder: `withPlaceholder(string $placeholder)`:  
-Allows you to customize the placeholder displayed on the input form. By default, it's empty.
-
-- Customize the help message: `withHelp(string $help)`:  
-Allows you to customize the help message displayed above on the input form. By default, it's empty.
-
-- Display or not in the table: `displayInColumns(bool $state)`:  
-Enable or disable the field on the entries table. Defaults to `true`.
+You can pass your rules as second parameter:
+```php
+TextField::handle('your-attribute', 'required|min:3')
+```
 
 ## Fields reference
 
 ### TextField
 
 It's a basic `<input type="text" />`.  
 
-View: `fields/text.blade.php`
+View: `fields/text.blade.php`  
+Extends: `Field`  
+Trait: -  
 
 ### TextareaField
 
 It's a basic HTML textarea.  
 
-View: `fields/textarea.blade.php` 
+View: `fields/textarea.blade.php`  
+Extends: `Field`  
+Trait: -  
 
 ### RadioField
 
 Simple HTML radio.  
 
-View: `fields/radio.blade.php` 
-
-Methods: 
-
-- `withOptions(array $options)`  
-When called, `in:...options` validation rule is added.
+View: `fields/radio.blade.php`  
+Extends: `Field`  
+Trait: `FieldWithOptions`  
 
+Additional API:
 ```php
-RadioField::handle('status')->withOptions([0 => 'Draft', 1 => 'Live']);
+$field = RadioField::handle('status');
+
+// Add radio options as an array. Takes care to add validation rules.
+// The second parameter is the default value but it can be null.
+$field->withOptions([0 => 'Dra`ft', 1 => 'Live'], 1);
 ```
 
 ### EmailField
 
 Same as [TextField](#textfield) but takes care of the email contained.  
 
 View: `fields/email.blade.php` 
+Extends: `Field`  
+Trait: -  
 
 ### TinymceField
 
 Same as [TextareaField](#textareafield) but produces a WYSIWYG via [TinyMCE 4](https://www.tinymce.com/).  
-To use it you should read [Fields with assets](#fields-with-assets).  
+To use it you should read [Fields with assets](#publishing-assets).  
 
-View: `fields/tinymce.blade.php` 
+View: `fields/tinymce.blade.php`  
+Extends: `Field`  
+Trait: -  
 
 ### FileUploadField
 
 File upload field. You can specify extensions authorized, max filesize, upload path and storage disk.  
 Once added this field will add `enctype="multipart/form-data"` to the entry form.  
 By default; this field value is not displayed in the entries table.  
 
-View: `fields/fileupload.blade.php` 
+View: `fields/fileupload.blade.php`  
+Extends: `Field`  
+Trait: `FieldHandleUpload`  
+
+Additional API:
+```php
+$field = FileUploadField::handle('illustration');
+
+// Only accept this mimes.
+// Default: empty
+$field->withTypes('jpeg,png');  
+
+// Set the maximum file size (in kB)
+// Default: empty
+$field->withMaxSize(1024 * 1024);  
+
+// Set the upload destination folder on the disk.
+// Default: 'uploads'
+$field->uploadToPath('uploaded-illustrations');
 
-Methods: 
+// Set the disk that'll store uploads. Configure them in "config/filesystems.php".
+// Default: 'public'.
+$field->uploadToDisk('disk-name');
+```
 
-- `withTypes(string $types)`  
-It's similar to the laravel validation rule 'mimes' and can be used to restrict the file to the given extensions.
+### SelectRelationField
 
-- `withMaxSize(int $size)`  
-It's similar to the laravel validation rule 'max' and can be used to restrict the maximum file size (given in kB).
+This field adds a select input based on an existing model relation.  
+For example, a Post model belongs to a Category model:  
+```php
+SelectRelationField::handle('category_id')->withRelation('category')
+```
 
-- `uploadToPath(string $path)`  
-It's the uploaded file destination. Ex: /uploads`.  
+View: `fields/select-relation.blade.php`  
+Extends: `Field`  
+Trait: `FieldWithRelation`  
+
+Additional API:
+```php
+$field = SelectRelationField::handle('category_id');
 
-- `uploadToDisk(string $disk)`  
-It's the storage disk used for the uploaded file. Defaults to `public`.
+// The relation to use. The parameter is the name of the relation used in the model.
+// Default: empty
+$field->withRelation('category');  
+```
+
+## Customize fields
+
+Once declared, you can use the Field API to declare your modifiers.
+
+```php
+$field = TextField::handle('title');
+
+// Attach some additional validation rules
+// Default: empty
+$field->withRules('required|min:3');
+
+// Change the displayed label for this tield
+// Default: Capitalized attribute name
+$field->withLabel('The title');
+
+// Set an input pladeholder
+// Default: empty
+$field->withPlaceholder('Ex: Hello world');
+
+// Set a custom help message
+// Default: empty
+$field->withHelp('This is the title of your post');
+
+// Show this field on the entries table ?
+// Default: true
+$field->displayInColumns(true);
+```
 
-## Fields with assets
+## Publishing assets
 
 Some fields such as [TinymceField](#tinymcefield) comes with custom assets.  
 

docs/routes_and_controllers.md

@@ -1,3 +1,122 @@
 # Routes and controllers
 
-Coming soon.
+Each `Crudable` model is managed by a `CrudManager` instance.
+
+## Usage
+
+By default, the `CrudManager` is automatically and basicly configured.  
+This configuration comes from the `getCrudManager` on the `Crudable` trait, but you can override it.
+
+In your model:  
+```php
+use Crudable;
+
+public function getCrudManager()
+{
+    $manager = CrudManager::make($this);
+
+    // Configuration of your manager.
+
+    return $manager;
+}
+```
+
+## Configuration
+
+Many methods are available to configure the way your `Crudable` model is managed.
+
+### Controller
+
+```php
+$manager->setController('ModelController');
+```
+
+All actions will use the `ModelController` located in the namespace `App\Http\Controllers`.
+
+### Routes
+
+By default all you model crud routes are:
+
+- [Route URI] => [Route name]
+- model/index => model.index
+- model/create => model.create
+- model/store => model.store
+- model/edit/{id} => model.edit
+- model/update/{id} => model.update
+- model/delete/{id}/{csrf} => model.delete
+
+Where the 'model' value is the model name, ex: `Post` => 'posts, `Category` => 'categories', ...
+
+You can change all crud routes URI prefix like this:  
+```php
+$manager->setUriPrefix('admin/posts');
+```
+
+You also can change the custom prefix for the named routes:
+```php
+$manager->setNamePrefix('admin.posts');
+```
+
+### Name
+
+By default the name of the crud is the name of the model, but you can configure it like this:
+```php
+$manager->setName('Post');
+```
+
+The name is used to display a title on the table and the form.
+
+### Entries per page
+
+You can customize entries displayed per page like this:
+```php
+$manager->setPerPage(50);
+```
+
+By default, 25 entries are displayed per page.
+
+## Register routes
+
+All `Crudable` model comes with a static `registerRoutes` method. 
+
+Once routes and controller are configured, you can bind you crud model routes in your routes file like this:  
+```php
+// routes/web.php
+Model::registerRoutes();
+```
+
+## API
+
+The `CrudManager` instance comes with many public method.
+
+```php
+$manager = $model->getCrudManager();
+
+// Returns the number of entries per page
+// => 25
+$manager->getPerPage();
+
+// Returns the name of the CRUD
+// => 'Model'
+$manager->getName();
+
+// Returns the controller
+// => 'ModelController'
+$manager->getController();
+
+// Returns URL for a route
+// => 'model/store'
+$manager->getActionRoute('store');
+
+// Returns needed method for a route
+// => 'POST'
+$manager->getActionMethod('store');
+
+// Returns the URI prefix
+// => 'model/'
+$manager->getUriPrefix();
+
+// Returns the routes name prefix
+// => 'model.'
+$manager->getNamePrefix();
+```