Tutorial: Adding Fields to Users/Characters/Etc - Revision history

Preimpression: Finishing up for the day.

2020-10-31T20:38:48Z

Finishing up for the day.

Preimpression: Switching to Characters from User and discussing the Model.

2020-10-31T19:44:11Z

Switching to Characters from User and discussing the Model.

Show changes

Preimpression: Finishing up Migrations. Starting Existing-File-Edits.

2020-10-31T18:38:02Z

Finishing up Migrations. Starting Existing-File-Edits.

Preimpression at 23:13, 8 October 2020

2020-10-08T23:13:38Z

Junijwi: added category

2020-09-04T04:48:03Z

added category

Preimpression: /* The Parts of the Process */

2020-08-21T15:05:29Z

The Parts of the Process

Preimpression: /* The Parts of the Process */

2020-08-21T14:53:37Z

The Parts of the Process

Preimpression: Initial creation and began Migrations portion.

2020-08-21T14:49:45Z

Initial creation and began Migrations portion.

New page

One of the best parts about Lorekeeper is how customizable it is. Beyond Extensions, you can go in and add entire new columns to the database to store new information that's custom to your site or to the extension you might be working on.

This tutorial will cover the basics of adding new fields to Users, though you can implement the same logic in adding fields to items, characters, etc.

==The Parts of the Process==
Before you get into the code, you should understand the files and terms you'll be working with.
<br />

* '''Migrations:''' Migrations are used to directly affect the columns of the database. This isn't used for putting data into the database, but instead to make new columns, tables, etc. Found in: ''database/migrations''
* '''Views:''' Views are the files holding the HTML code that you see. Laravel uses a '''[https://laravel.com/docs/5.8/blade blade]''' system, which essentially means that each page you see when you load your site is actually a bunch of files fitted together, like a knife block. This allows a certain amount of customization and more importantly, allows you to reuse code in numerous locations or ways. This is how so many pages have similar sidebars - the sidebar isn't included in its entirety on every page. Found in: ''resources/views''
* '''Forms:''' This is what your users or admins will see when they want to edit the information in the database. It's important to note that without the back-end information (such as if you just put a text box on a page,) forms will do nothing. Found in: ''resources/views''
* '''Routes:''' When you navigate to a page in your browser, the site looks at the URL and then looks at the route to see where to go next, unlike static websites where you'd go to, say, ''index.html'' and see the page that's ''index.html'' in the root directory. Routes work by (usually) going to a function in a controller. GET routes are getting the information from the site in order to display it, while POST routes are sending the information from a form back to the controller to be handled. Found in: ''routes''
* '''Controllers:''' Controllers receive and give data. There are two main function types: GET and POST. GET generally gets information from the database and puts it together for the user to see it. This is how views are called and accessed. POST is generally used to put data into the database. Laravel has a naming convention for these for function names: GET functions generally begin with all-lowercase ''get'' (eg. getSettings, getNotifications) while POST functions usually begin with all-lowercase ''post'' (eg. postPassword, postEmail.) ''Fun fact: This method of naming functions/variables with a lowercase word and then capitalized words in programming is called camelCase.'' Found in: ''app/Http/Controllers''
* '''Services:''' Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service. Found in: ''app/Services''
* '''Models:''' Models directly relate to the table in the database. We won't need to make a new model for this, since we'll just be editing an existing table, but we will need to edit one slightly. Found in: ''app/Models''

'''Here's an analogy:'''

You begin your job by picking up a package of spices [the '''data'''] at the POST office [a '''form''']. You look at your directions ['''the link on a form'''] and go along the route ['''route'''] to the restaurant worker ['''controller''']. The package is given to the chef ['''service'''], who puts the spices ['''data'''] into the appropriate cabinets [columns in the '''database'''] in the appropriate room [table in the '''database'''.] Later, when requested by the customer [page load on a '''GET route'''], the restaurant worker ['''controller'''] gets the ingredients and puts them together. They then put the food on the plate ['''view'''] and place it on the table for the customer [you!]
<br />

== Starting Out: Migrations ==
Before you even begin coding, you should have determined some things:

# What information do you want added?
## Is it nullable - can it be completely empty/blank?
## Does it have a default value?
# What form does this information take? Is it a short text input that should only be a few words? A full WYSIWYG (What You See Is What You Get) input? A boolean (True/false?)
# Does this need to be in a new table or does it fit in one of the existing tables? ''This tutorial will only cover existing tables.''

I recommend looking at existing migrations if there's anything similar to the field you want to add.

Migrations have a specific way to be created in a console command! I always recommend testing on a local server (like WAMPserver or XAMPP) before you mess with the database on your live server. I also recommend looking at the [https://laravel.com/docs/5.8/migrations documentation] - it's my go to when I need to add something. It makes it easier if you include the table in the migration command, though you are able to affect multiple tables in one migration if you so desire.

Go into your console commands (I use Putty for my server and Git Bash for my local, but I've seen other users use Sourcetree or VSC directly.)
php artisan make:migration add_nickname_to_users_table --table=users
It's good to make the title (add_nickname_to_users_table) as descriptive as possible whilst being succinct, but remember: this will be part of the file name for the migration file. Once you hit enter, it might take a minute to create, but it will give a nice verification saying something like:
Created Migration: 2020_08_21_104400_add_nickname_to_users_table
Now you can navigate to your ''database/migrations'' folder and see a fresh new file! If you used the form I suggested, it'll look pretty much exactly like this, but maybe with different colours:<syntaxhighlight lang="php" line="1">
<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class AddNicknameToUsersTable extends Migration
{
/**
* Run the migrations.
*
* @return void
*/
public function up()
{
Schema::table('users', function (Blueprint $table) {
//
});
}

/**
* Reverse the migrations.
*
* @return void
*/
public function down()
{
Schema::table('users', function (Blueprint $table) {
//
});
}
}
</syntaxhighlight>The two existing functions are important! ''up()'' is what gets set up when you run artisan migrate later, while ''down()'' is what's run if you ever need to roll the migration back.

I'll get back to this tutorial later.

@@ Line 161: / Line 161: @@
 <br />
-== Setting It Up ==
+==Setting It Up==
 I always need to plan things out before I can get going. Some things you'll want to make sure to decide pretty early on, using nicknames as an example:
-* Can users edit their character's nicknames?
+*Can users edit their character's nicknames?
-* Do only characters get nicknames or can MYOs also have them?
+*Do only characters get nicknames or can MYOs also have them?
-* Do characters get created with nicknames?
+*Do characters get created with nicknames?
-* Do MYOs get created with nicknames?
+*Do MYOs get created with nicknames?
-* Should nicknames be included in the Character Masterlist?
+*Should nicknames be included in the Character Masterlist?
-* Where else should nicknames be visible?
+*Where else should nicknames be visible?
-* Do you have any Accessors you'd like to include this? (Things like displayName etc)
+*Do you have any Accessors you'd like to include this? (Things like displayName etc)
 For the purposes of this tutorial, I'll go over all of these.
@@ Line 176: / Line 176: @@
 ===Model===
-==== Fillable ====
+====Fillable====
 To start off, you'll want to add 'nickname' to the Model so that Laravel will understand that the column exists and can be edited.
 If you navigate to <code>app/Models/Character</code> there will be a file called <code>Character.php</code>. Open this up and take it all in. Go to <code>protected $fillable</code> and add <code>, 'nickname'</code> after <code>'trade_id'</code> or whatever you might have there. It doesn't matter where it's put, as long as it's there, separated from the one before (or after) it with a comma.
@@ Line 182: / Line 182: @@
 Adding the column to <code>fillable</code> means that Laravel will understand that it's a part of the database that you want users, admins, etc to be able to edit.
-==== Accessor ====
+====Accessor====
 If you want the nickname to be displayed in any fun way, you can add an Accessor. Accessors are set in functions that are named like so: <code>getDisplayNameAttribute()</code>. To view the returned value from this function, you would use <code>{!! $character->displayName !!}</code> on a page that <code>$character</code> is defined on.
 I'll simply add the nickname to a character's display name - the <code>getDisplayNameAttribute()</code> function.
@@ Line 199: / Line 199: @@
 When it mentions <code>$this</code> , that is referring to the model in question - the Character model. When the character has a nickname set, it will be added in parentheses behind the name, after the link. So a character named Julius with the nickname Jules will appear as <code>Julius (Jules).</code>
-==== Validation Rules ====
+====Validation Rules====
 Also, you may want to add some validation rules for the nickname!
 I've added the following to $createRules, $updateRules, and $myoRules since I think both characters and MYOs should be able to have nicknames, and they should be allowed to be added during character creation.
   'nickname' => 'nullable|between:3,25',
 This allows the field to be nullable and also makes it only valid between 3 and 25 characters. This can be used in conjunction with the 191 string length we set up in our migration, though it should never be larger than the max length you used for the column! If it is and a user attempts a super-long nickname, the database will yell at them about truncation and you will have unhappy, confused users.
-== Setting Nicknames on New Characters/MYOs. ==
+==New Characters/MYOs==
-For the user to edit their own nickname, you will need the following:
+For nicknames to be set upon character and MYO creation, you'll have to look at the following:
-* The '''form''' added to the <code>resources/views/characters/edit_profile.blade.php</code> file. For this, I want users to be able to edit from the Edit Profile page.
+*The '''form''' already exists in the <code>resources/views/admin/masterlist/create_character.blade.php</code> file.
-* Sometimes: The '''route''' set up for the form. This would be in <code>routes/lorekeeper/members.php</code> - only logged in members can view and edit these! We will use the profile editing route for this, so you don't have to worry.
+*The '''route''' is already set up, since we're using an existing form!
-* The controller set up for the form. For editing via the Settings page, this would be in <code>app/Http/Controllers/</code>
+*The '''controller''', <code>app/Http/Controllers/Admin/Characters/CharacterController.php</code>
 [[Category:Community Tutorials]]

← Older revision		Revision as of 23:13, 8 October 2020
Line 1:		Line 1:
		+	== '''INCOMPLETE TUTORIAL!''' ==
	One of the best parts about Lorekeeper is how customizable it is. Beyond Extensions, you can go in and add entire new columns to the database to store new information that's custom to your site or to the extension you might be working on.		One of the best parts about Lorekeeper is how customizable it is. Beyond Extensions, you can go in and add entire new columns to the database to store new information that's custom to your site or to the extension you might be working on.

@@ Line 7: / Line 7: @@
 <br />
-; '''Migrations:'''
+;'''Migrations:'''
-: Migrations are used to directly affect the columns of the database. This isn't used for putting data into the database, but instead to make new columns, tables, etc.
+:Migrations are used to directly affect the columns of the database. This isn't used for putting data into the database, but instead to make new columns, tables, etc.
-: Found in: ''database/migrations''
+:Found in: ''database/migrations''
-; '''Views:'''
+;'''Views:'''
-: Views are the files holding the HTML code that you see. Laravel uses a '''[https://laravel.com/docs/5.8/blade blade]''' system, which essentially means that each page you see when you load your site is actually a bunch of files fitted together, like a knife block. This allows a certain amount of customization and more importantly, allows you to reuse code in numerous locations or ways. This is how so many pages have similar sidebars - the sidebar isn't included in its entirety on every page.
+:Views are the files holding the HTML code that you see. Laravel uses a '''[https://laravel.com/docs/5.8/blade blade]''' system, which essentially means that each page you see when you load your site is actually a bunch of files fitted together, like a knife block. This allows a certain amount of customization and more importantly, allows you to reuse code in numerous locations or ways. This is how so many pages have similar sidebars - the sidebar isn't included in its entirety on every page.
-: Found in: ''resources/views''
+:Found in: ''resources/views''
-; '''Forms:'''
+;'''Forms:'''
-: This is what your users or admins will see when they want to edit the information in the database. It's important to note that without the back-end information (such as if you just put a text box on a page,) forms will do nothing.
+:This is what your users or admins will see when they want to edit the information in the database. It's important to note that without the back-end information (such as if you just put a text box on a page,) forms will do nothing.
-: Found in: ''resources/views''
+:Found in: ''resources/views''
-; '''Routes:'''
+;'''Routes:'''
-: When you navigate to a page in your browser, the site looks at the URL and then looks at the route to see where to go next, unlike static websites where you'd go to, say, ''index.html'' and see the page that's ''index.html'' in the root directory.   Routes work by (usually) going to a function in a controller. GET routes are getting the information from the site in order to display it, while POST routes are sending the information from a form back to the controller to be handled.
+:When you navigate to a page in your browser, the site looks at the URL and then looks at the route to see where to go next, unlike static websites where you'd go to, say, ''index.html'' and see the page that's ''index.html'' in the root directory.   Routes work by (usually) going to a function in a controller. GET routes are getting the information from the site in order to display it, while POST routes are sending the information from a form back to the controller to be handled.
-: Found in: ''routes''
+:Found in: ''routes''
-; '''Controllers:'''
+;'''Controllers:'''
-: Controllers receive and give data. There are two main function types: GET and POST. GET generally gets information from the database and puts it together for the user to see it. This is how views are called and accessed. POST is generally used to put data into the database. Laravel has a naming convention for these for function names: GET functions generally begin with all-lowercase ''get'' (eg. getSettings, getNotifications) while POST functions usually begin with all-lowercase ''post'' (eg. postPassword, postEmail.)
+:Controllers receive and give data. There are two main function types: GET and POST. GET generally gets information from the database and puts it together for the user to see it. This is how views are called and accessed. POST is generally used to put data into the database. Laravel has a naming convention for these for function names: GET functions generally begin with all-lowercase ''get'' (eg. getSettings, getNotifications) while POST functions usually begin with all-lowercase ''post'' (eg. postPassword, postEmail.)
-: ''Fun fact: This method of naming functions/variables with a lowercase word and then capitalized words in programming is called camelCase.''
+:''Fun fact: This method of naming functions/variables with a lowercase word and then capitalized words in programming is called camelCase.''
-: Found in: ''app/Http/Controllers''
+:Found in: ''app/Http/Controllers''
-; '''Services:'''
+;'''Services:'''
-: Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service.
+:Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service.
-: Found in: ''app/Services''
+:Found in: ''app/Services''
-; '''Models:'''
+;'''Models:'''
-: Models directly relate to the table in the database. We won't need to make a new model for this, since we'll just be editing an existing table, but we will need to edit one slightly.
+:Models directly relate to the table in the database. We won't need to make a new model for this, since we'll just be editing an existing table, but we will need to edit one slightly.
-: Found in: ''app/Models''
+:Found in: ''app/Models''
@@ Line 42: / Line 42: @@
 <br />
-== Starting Out: Migrations ==
+==Starting Out: Migrations==
 Before you even begin coding, you should have determined some things:
-# What information do you want added?
+#What information do you want added?
-## Is it nullable - can it be completely empty/blank?
+##Is it nullable - can it be completely empty/blank?
-## Does it have a default value?
+##Does it have a default value?
-# What form does this information take? Is it a short text input that should only be a few words? A full WYSIWYG (What You See Is What You Get) input? A boolean (True/false?)
+#What form does this information take? Is it a short text input that should only be a few words? A full WYSIWYG (What You See Is What You Get) input? A boolean (True/false?)
-# Does this need to be in a new table or does it fit in one of the existing tables? ''This tutorial will only cover existing tables.''
+#Does this need to be in a new table or does it fit in one of the existing tables? ''This tutorial will only cover existing tables.''
 I recommend looking at existing migrations if there's anything similar to the field you want to add.
@@ Line 98: / Line 98: @@
 I'll get back to this tutorial later.

@@ Line 29: / Line 29: @@
 ; '''Services:'''
-: Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service.  Found in: ''app/Services''
+: Services usually handle the actual placing of data into the database. While sometimes people will code the data->database handling in the Controller, it's usually better praxis to have this handling in the Service.
 ; '''Models:'''

@@ Line 1: / Line 1: @@
-== '''INCOMPLETE TUTORIAL!''' ==
+=='''INCOMPLETE TUTORIAL!'''==
 One of the best parts about Lorekeeper is how customizable it is. Beyond Extensions, you can go in and add entire new columns to the database to store new information that's custom to your site or to the extension you might be working on.
@@ Line 44: / Line 44: @@
 ==Starting Out: Migrations==
 Before you even begin coding, you should have determined some things:
@@ Line 56: / Line 58: @@
 Migrations have a specific way to be created in a console command! I always recommend testing on a local server (like WAMPserver or XAMPP) before you mess with the database on your live server. I also recommend looking at the [https://laravel.com/docs/5.8/migrations documentation] - it's my go to when I need to add something. It makes it easier if you include the table in the migration command, though you are able to affect multiple tables in one migration if you so desire.
-Go into your console commands (I use Putty for my server and Git Bash for my local, but I've seen other users use Sourcetree or VSC directly.)
   php artisan make:migration add_nickname_to_users_table --table=users
-It's good to make the title (add_nickname_to_users_table) as descriptive as possible whilst being succinct, but remember: this will be part of the file name for the migration file. Once you hit enter, it might take a minute to create, but it will give a nice verification saying something like:
+It's good to make the title (add_nickname_to_users_table) as descriptive as possible whilst being succinct, but remember: this will be part of the file name for the migration file.
   Created Migration: 2020_08_21_104400_add_nickname_to_users_table
 Now you can navigate to your ''database/migrations'' folder and see a fresh new file! If you used the form I suggested, it'll look pretty much exactly like this, but maybe with different colours:<syntaxhighlight lang="php" line="1">
@@ Line 94: / Line 100: @@
+     }
+}
-</syntaxhighlight>The two existing functions are important! ''up()'' is what gets set up when you run artisan migrate later, while ''down()'' is what's run if you ever need to roll the migration back.
+</syntaxhighlight>The two existing functions are important! ''<code>up()</code>'' is what gets set up when you run <code>php artisan migrate</code> later, while ''<code>down()</code>'' is what's run if you ever need to roll the migration back. If you'll be working with multiple tables at once, it's generally good practice to have the down() be in reverse order of the <code>up()</code> - at least, when you're working with foreign keys!
-I'll get back to this tutorial later.
+=== Model ===
 [[Category:Community Tutorials]]