diff --git a/README.md b/README.md index d7446b4..ea1c755 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,27 @@ Created for personal use, and is not well documented or tidy. Feel free to use / QForm for Laravel does a bunch of html form stuff, making use of Laravel components - Create most types of html inputs with a single component -- Make use of the QForm::init() set of tools either by itself or with a component to easily access a models data, create form name attributes with prefix etc, and deal with error display and old() for you. +- Make use of the QForm::new() set of tools either by itself or with a component to easily access a models data, create form name attributes with prefix etc, and deal with error display and old() for you. - Customize template - In the provided base Bootstrap 4 template, it makes some attempts to provide labelling, error and other accesibility features. +```php +$form = Qform::new()->model(User::first())->text('forms.edit_user'); +``` +```html +{{ $form->input('name')->render(['type' => 'text']) }} +{{ $form->input('email')->render(['type' => 'email']) }} +{{ $form->input('level')->render(['type' => 'select', 'variables' => [0 => 'User', '1' => 'Admin']]) }} +``` + +- The input will automatically look for errors and old values based on value given by input() +- The input will look to array or model given by model() to get input value +- The input will automatically look to the given text for input label and guide text, eg. text('forms.edit_user') as above, in the case of input('name') will look to 'forms.edit_user.name' for the translation. Or if you give a table via table() such as table('users') it will look to 'columns.users.name'. It looks for text first, then table. You may also pass an array of key to text to text(). + ## Warnings 1. Doesn't play nice when array inputs such as select have muliple options that resolve to false (not strict) -2. QForm::init() expects that you will have your translations arranged in a certain way, using key translations, +2. QForm::new() expects that you will have your translations arranged in a certain way, using key translations, a columns.php translation file arranged with table name as key and array of column names as follows ```php 'users' => [ @@ -46,11 +59,15 @@ and a forms.php (or any name you choose, this is optional) arranged in the same ... Other forms ``` -For example you have a signup form and a login form. Preparing a QForm via `$form = QForm::init(NULL, 'forms.login')->table('users')` means it will first look to forms.login for the column text, then columns.users. +For example you have a signup form and a login form. Preparing a QForm via `$form = QForm::new()->text('forms.login')->table('users')` means it will first look to forms.login for the column text, then columns.users. # Setup +## Composer + +composer require corbinjurgens/qform + ## Manual Installation Copy the following to main composer.(in the case that the package is added to packages/corbinjurgens/qform) @@ -112,78 +129,102 @@ Array input, ie. anything that has, or can have multiple options Using components with the QForm tools is the intended usage of this package -### Basics - In your template or controller, create a form. See the warning section above for an example of the translation files that this would be pointing to ```html @php // Initiate the $form either in your template, or from the controller - // To edit an item, pass a model as the first parameter, or if your form will never edit, just pass null. Personally I usually share form between create and edit and pass a new model when creating - // For second parameter point to a translation, pass an array of translations, or leave it empty. Pass table with ->table() to point to a table in tables.php translation file - $form = QForm::init($user, 'forms.permissions')->table('users'); + // To edit an item, pass a model as the via model(), or if your form will never edit, just pass null or do not call. Personally I usually share form between create and edit and pass a new model when creating + // For text() point to a translation, pass an array of translations, or leave it empty. Pass table with ->table() to point to a table in tables.php translation file + $form = QForm::new()->model($user)->text('forms.permissions')->table('users'); @endphp {{-- Shift current column to 'name' and pass it to the form. The form will automatically look to the model for the 'name' value and fill the input, and look to translation files first for forms.permissions.name, then users.name --}} - +`` +{{-- Or --}} +{{ $form->input('name')->render(['type' => 'text']) }} @php( $form->input('level') ) {{-- In the previous input, I shifted current input as I passed it to :form, but you can also shift separately, then access. -Normally, $form->text() would look for the current inputs text, so first it would look to forms.permissions.level, then users.level. But because I passed a value to it, its looking to the same root, just different key to get :variables (See Introduction section for example of translation files) +Normally, $form->getText() would look for the current inputs text, so first it would look to forms.permissions.level, then users.level. But because I passed a value to it, its looking to the same root, just different key to get :variables (See Introduction section for example of translation files) --}} - + + + +{{-- Or --}} +{{ $form->render(['variables' => $form->getText('levels'), 'type' => 'radio']) }} + {{-- Normally this would look to forms.permissions.notifications, then users.notifications, - but by passing a translation pointer, or array of columns to text_shift() I am telling it to look elsewhere for the 'notifications' text (and guide text) - WARNING: text_shift() and value_shift() functions persist between input shifts so you must either pass null again, or call hard_reset() to clear + but by passing a translation pointer, or array of columns to textShift() I am telling it to look elsewhere for the 'notifications' text (and guide text) + WARNING: textShift() and dataShift() functions persist between input shifts so you must either pass null again, or call hardReset() to clear --}} - + +{{-- Or --}} +{{ $form->input('notifications')->textShift('forms.admin')->render(['type' => 'checkbox']) }} +``` + +## Freely + +You can use QForm tools without using a component. This makes creating your inputs id, name and value easy, saving you a lot of repition + +```html +@php( $form = QForm::new()->model($user)->text('forms.permissions')->table('users') ) + +@php( $form->input('name') ) +