Skip to content

Commit bbe4652

Browse files
author
Liran Cohen
committed
Update README.md
1 parent 64dcd1a commit bbe4652

File tree

1 file changed

+254
-31
lines changed

1 file changed

+254
-31
lines changed

‎README.md‎

Lines changed: 254 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,282 @@
1-
# Laravel Custom Fields.
2-
## Add custom fields to your Laravel models.
3-
The purpose of this package is to allow you, the user, to add custom fields to Laravel models.
4-
This is done by the use of a few models (by default they are called `Custom Fields` and `Custom Field Responses`) and traits which allow you to relate them to the models already in your application.
1+
# Laravel Custom Fields
2+
3+
Laravel Custom Fields is a package that allows you to add custom fields to any Laravel model and associate responses to those fields with other models.
4+
5+
[![Latest Stable Version](https://poser.pugx.org/givebutter/laravel-custom-fields/v/stable)](https://packagist.org/packages/givebutter/laravel-custom-fields) [![Total Downloads](https://poser.pugx.org/givebutter/laravel-custom-fields/downloads)](https://packagist.org/packages/givebutter/laravel-custom-fields) [![License](https://poser.pugx.org/givebutter/laravel-custom-fields/license)](https://packagist.org/packages/givebutter/laravel-custom-fields)
56

67
## Installation
7-
`composer require givebutter/laravel-custom-fields`
88

9-
This package publishes a few migrations. To run these in their default configuration, simply run `artisan migrate` after installation.
10-
*You can customize the table names using config options. More on that later.*
9+
To get started, add the `givebutter/laravel-custom-fields` package to your `composer.json` file and update your dependencies:
10+
11+
```bash
12+
composer require givebutter/laravel-custom-fields
13+
```
14+
15+
Publish the migration:
16+
```bash
17+
php artisan vendor:publish --provider="Givebutter\LaravelCustomFields\LaravelCustomFieldsServiceProvider" --tag="migrations"
18+
```
19+
20+
Run the migration:
21+
```bash
22+
php artisan migrate
23+
```
1124

12-
## An Example App
13-
For the purposes of the documentation, lets use the example of a Survey taking app. Administrators might use a backend to create `Surveys` full of questions and end users might then fill out those surveys, generating `SurveyResponses`.
25+
*You can customize the table names using configuration options. More on that later.*
1426

15-
## Adding Custom Fields
16-
To add basic custom field support, We'll simply pull in the `HasCusomFields` trait at the top of our `Survey` model.
27+
## An example - Survey App
28+
For the purposes of the documentation, lets use the example of a Survey building app. Administrators might use a backend to create `Surveys` full of questions and end users might then fill out those surveys, generating `SurveyResponses`.
29+
30+
## Preparing your models
31+
32+
### Adding custom fields
33+
34+
To add basic custom field support, simply add the `HasCusomFields` trait at the top of your model:
35+
36+
```php
37+
use Illuminate\Database\Eloquent\Model;
38+
use Givebutter\LaravelCustomFields\Traits\HasCusomFields;
39+
40+
class Survey extends Model
41+
{
42+
use HasCusomFields;
43+
44+
// ...
45+
}
46+
```
47+
48+
### Adding custom field responses
49+
50+
Next, we add support to store custom field responses. We'll simply pull in the `HasCusomFieldResponses` trait at the top of our `SurveyResponse` model.
51+
52+
```php
53+
use Illuminate\Database\Eloquent\Model;
54+
use Givebutter\LaravelCustomFields\Traits\HasCusomFieldResponses;
55+
56+
class SurveyResponse extends Model
57+
{
58+
use HasCusomFieldResponses;
59+
60+
// ...
61+
}
62+
```
63+
64+
## Basic usage
65+
66+
### Creating fields
67+
68+
You can add a field to a model like this:
1769

18-
We then have the ability to add a field to a survey simply by running
1970
```php
2071
$survey->customFields()->create([
21-
'title' => `favorite_album`,
22-
`description` => `What is your favorite album.`
72+
'title' => `What is your name?`,
2373
`type` => `text`
2474
]);
2575
```
2676

27-
## Custom Field Types
77+
Each field can contain the following. More on these later:
78+
79+
`title` : The title / question of your custom field.
80+
`description` : The description of your field. Useful for providing more context to user filling out fields.
81+
`type` : The type of field you're creating. Available types are outlined in the next section.
82+
`required` : A boolean representing whether a field is required or not.
83+
`answers` : An array of acceptable values for fields that have user-selection.
84+
85+
### Creating field responses
86+
87+
To store a response on a field, you can do this:
88+
89+
```php
90+
$field->responses()->create([
91+
'value' => 'John Doe'
92+
]);
93+
```
94+
95+
### Retrieving fields
96+
97+
To retrieve custom fields, use the `customFields` relation:
98+
99+
```php
100+
$survey->customFields()->get();
101+
```
102+
103+
### Retrieving field responses
104+
105+
To retrieve the responses on a field, use the `responses()` relation:
106+
107+
```php
108+
$field->responses()->get();
109+
```
110+
111+
## Custom field types
28112
Custom fields may be any of 5 types:
29113

30-
- `text` : Free entry fields which are stored as strings. Try to use these for simple inputs as they have a max-length of 256 characters.
31-
- `textarea` : Free entry fields which are stored as text columns. Use these for longer bits of text that may not fit within 256 characters.
32-
- `radio` : These are multi-select fields, which require you to pass and `answers` property.*
33-
- `select`: These are multi-select fields, which require you to pass and `answers` property.*
34-
- `checkbox`: Boolean fields.
35-
- `number` : Free entry fields stored as integers.
114+
- `text` : Free entry fields which are stored as strings. Use these for simple inputs as they have a max-length of 255 characters.
115+
- `textarea` : Free entry fields which are stored as text columns. Use these for longer bits of text that may not fit within the `text` field.
116+
- `radio` : These are multi-select fields, which require you to pass an `answers` property.*
117+
- `select` : These are multi-select fields, which require you to pass an `answers` property.*
118+
- `checkbox` : Boolean fields.
36119

37-
In the future we may provide front-end scaffolding for these fields, but for now, that's up to you.
120+
In general, these field types correspond to their respective HTML elements. In the future we may provide front-end scaffolding for these fields, but for now, that's up to you.
38121

39-
* *The `select` and `checkbox` field types require you to fill the `answers` property on the field. This is a simple array of strings, which are valid responses for the field. For example:
122+
*The `radio` and `select` field types require you to fill the `answers` property on the field. This is a simple array of strings, which are valid responses for the field. For example:
40123

41124
```php
42125
$survey->customFields()->create([
43-
'title' => 'favorite_album',
44-
'description' => 'What is your favorite album.'
126+
'title' => 'What is your favorite color?',
45127
'type' => 'select',
46-
'answers' => ['Lil Wayne - Tha Carter II', 'Gang Starr - Moment of Truth'],
128+
'answers' => ['Red', 'Green', 'Blue', 'Yellow'],
129+
]);
130+
```
131+
132+
## Validating responses
133+
134+
135+
### Validation helpers
136+
137+
In most cases, you'll want to validate responses to your custom fields before saving them. You can do so by calling the `validateCustomFields()` function on your model:
138+
139+
```php
140+
141+
$responses = [
142+
'1' => "John Doe",
143+
'2' => "Blue"
144+
];
145+
$survey->validateCustomFields($responses);
146+
```
147+
148+
You can also pass in a `Request` object:
149+
150+
```php
151+
use Request;
152+
153+
class FooController extends Controller {
154+
155+
public function index(Request $request)
156+
{
157+
$validation = $survey->validateCustomFields($request);
158+
159+
// ...
160+
}
161+
162+
}
163+
```
164+
165+
```html
166+
<form>
167+
<input type="text" name="custom_fields[]" />
168+
</form>
169+
```
170+
When using a `Request` object, the input key should be an array of values
171+
172+
173+
174+
### Implicit validation rules
175+
176+
The 5 supported field types described above automatically have the following validation rules applied to them:
177+
178+
- `text` : `string|max:255`
179+
- `textarea` : `string`
180+
- `radio` : `string|max:255|in:answers`
181+
- `select`: `string|max:255|in:answers`
182+
- `checkbox`: `in:0,1`
183+
184+
*Important: when using checkboxes, it is important you POST unchecked boxes as well, otherwise your response data may be incomplete.*
185+
186+
### Required fields
187+
188+
Because of how common they are, required fields have native support in this package. To mark a field as required, simply set `required` to true when creating a custom field.
189+
190+
```php
191+
$survey->customFields()->create([
192+
'title' => 'Do you love Laravel?',
193+
'type' => 'radio',
194+
'answers' => ['Yes', 'YES'],
195+
'required' => true
47196
]);
48197
```
49198

50-
## Adding Custom Field Responses
51-
Adding custom field response support is basically the same as adding field support. We'll simply pull in the `HasCusomFieldResponses` trait at the top of our `SurveyResponses` model.
199+
### Custom validation rules
52200

53-
We then have the ability to add a response to a given survey like so:
201+
Along with the built in validation rules, you can apply your own rules to the any custom field. For example, if you wanted to validate a field was an integer between 1 and 10, you could do the following:
54202

55203
```php
56-
$favoriteAlbumField->responses()->create([
57-
'value' => 'Lil Wayne - Tha Carter II'
204+
$survey->customFields()->create([
205+
'title' => 'Pick a number 1-10',
206+
'type' => 'text',
207+
'validation_rules' => 'integer|min:1|max:10'
58208
]);
59209
```
210+
211+
Remember, the `validation_rules` supports any of the [available validation rules](https://laravel.com/docs/6.x/validation#available-validation-rules) in Laravel.
212+
213+
214+
### Validation Rule Sets
215+
-> nah?
216+
In some cases, it's easier and more practical to define validation rules sets. For example, in our Survey app, if we wanted to offer a
217+
218+
## Saving Responses
219+
220+
To store responses to custom fields, just call `saveCustomFields()` and pass in an array of values
221+
222+
The `saveCustomFields` function can take in a Request or array.
223+
224+
```php
225+
$surveyResponse->saveCustomFields(['
226+
227+
']);
228+
```
229+
230+
If you're submitting a form request, you can easily:
231+
232+
```php
233+
Use App\...
234+
$surveyResponse->saveCustomFields($request->input);
235+
```
236+
237+
## Querying responses
238+
239+
You can query for responses on any field by using the `WhereCustomField()` scope. The function takes in the field object and the value you're looking for. To learn more about query scopes visit [this link](https://laravel.com/docs/6.x/eloquent#query-scopes).
240+
241+
For example, if you wanted to find all `SurveyResponses` with a `large` T-shirt size, perform the following query:
242+
243+
```php
244+
Use App\Models\SurveyResponse;
245+
Use App\Models\SurveyResponse;
246+
247+
$field =
248+
249+
SurveyResponse::WhereCustomField($field, 'large')->get();
250+
```
251+
252+
## Ordering
253+
254+
You can change the order of custom fields on a model by using the `order` function. Pass in either an array or `Collection` of ids. The index position of the field represent the order position of it.
255+
256+
```php
257+
$survey->orderCustomFields([2, 4, 5]); // Field with id 2 will be ordered first.
258+
```
259+
260+
You can also manually change the value of the `order` column:
261+
262+
```php
263+
$field->order = 3;
264+
$field->save();
265+
```
266+
267+
By default, custom fields are returned in ascending order when retrieved via the relation:
268+
```php
269+
$survey->customFields()->get(); // Returned in ascending order.
270+
```
271+
272+
## Configuration
273+
274+
To publish the configuration file, run the following command:
275+
```bash
276+
php artisan vendor:publish --provider="Givebutter\LaravelCustomFields\LaravelCustomFieldsServiceProvider" --tag="config"
277+
```
278+
279+
The configuration file should now be published in `config/custom-fields.php`. The available options and their usage are explained inside the published file.
280+
281+
## License
282+
Released under the [MIT](https://choosealicense.com/licenses/mit/) license. See [LICENSE](LICENSE.md) for more information.

0 commit comments

Comments
 (0)