Improve data column mapping docs (#340)

* Improve data column mapping docs

* indent

* use correct config handle

---------

Co-authored-by: Ryan Mitchell <[email protected]>

Author: duncanmcclean

README.md

@@ -58,9 +58,83 @@ The configuration file, found in `config/statamic/eloquent-driver.php` is automa
 
 For each of the repositories, it allows you to determine if they should be driven by flat-files (`file`) or Eloquent (`eloquent`). Some repositories also have additional options, like the ability to override the model used.
 
-### Mapping Entry data
-
-If you want to map fields from your blueprints to columns with the same handle in your blueprint, set `entries.map_data_to_columns` to true. When adding new columns in a migration we recommend resaving all Entries so that column data is filled: `Entry::all()->each->save()`.
+### Using dedicated columns for data
+
+> Note: This feature is currently only available for Entries.
+
+By default, the Eloquent Driver stores all data in a single `data` column. However, it is possible to store fields in their own columns. 
+
+1. First, you'll need to enable the `map_data_to_columns` option in the `entries` section of the configuration file:
+
+    ```php
+    // config/statamic/eloquent-driver.php
+    
+    'entries' => [
+        'driver' => 'file',
+        'model' => \Statamic\Eloquent\Entries\EntryModel::class,
+        'entry' => \Statamic\Eloquent\Entries\Entry::class,
+        'map_data_to_columns' => false,
+    ],
+    ```
+
+2. Create a new migration to add the columns to the `entries` table:
+    ```bash
+    php artisan make:migration add_columns_to_entries_table
+    ```
+    
+    ```php
+    public function up()
+    {
+        Schema::create('entries', function (Blueprint $table) {
+            $table->string('description')->nullable();
+            $table->json('featured_images')->nullable();
+        });
+    }
+    ```
+    
+    You should ensure that the column names match the field handles in your blueprints. You should also ensure the column type matches that of the fieldtype. As a general rule of thumb, here are some common mappings:
+
+   * Text fields should be stored as `string` columns.
+   * Relationship fields should be stored as `json` columns. (Unless `max_items` is set to `1`, in which case it should be stored as a `string` column.)
+   * Number fields should be stored as `integer` or `decimal` columns.
+
+3. Run the migration:
+    ```bash
+    php artisan migrate
+    ```
+
+4. If you're adding `json` or `integer` columns, you will need to provide your own `Entry` model in order to set the appropriate casts. You can do this by creating a new model which extends the default `Entry` model:
+    ```php
+    <?php
+    
+    namespace App\Models;
+    
+    class Entry extends \Statamic\Eloquent\Entries\EntryModel
+    {
+        protected $casts = [
+            // The casts from Statamic's base model...
+            'date'      => 'datetime',
+            'data'      => 'json',
+            'published' => 'boolean',
+    
+            // Your custom casts...
+            'featured_images' => 'json',
+        ];
+    }
+    ```
+    
+    If you're using UUIDs as your entry IDs (which is the default if you imported existing entries into the database), you should extend the `Statamic\Eloquent\Entries\UuidEntryModel` class instead:
+    
+    ```php
+    class Entry extends \Statamic\Eloquent\Entries\UuidEntryModel
+    ```
+
+5. If you have existing entries, you will need to re-save them to populate the new columns. You can do this by pasting the following snippet into `php artisan tinker`:
+    ```php
+    \Statamic\Facades\Entry::all()->each->save();
+    ```
+
+6. And that's it! Statamic will now read and write data to the new columns in the `entries` table, rather than the `data` column.
 
 ## Upgrading