Skip to content

Overview

Jump to bottom
Michelle Lewis edited this page Aug 12, 2015 · 4 revisions

Everything you need to know to start using MyTCG-f3! Since it's built on top of the Fat-Free Framework, you would also benefit greatly from reading through the F3 docs!

Quick Start

This Quick Start guide will show you how to set up a simple "Hello World" page in MyTCG-f3.

1. Create a new View file app/views/hello.htm

<p>Hello, {{ @name }}.</p>

2. Create a Controller for your View app/controllers/local/HelloController.php

<?php
namespace Controllers\Local;

use Template;

class HelloController extends Controller {

public function index()
{
	$this->f3->set('name','World'); // stores "World" in the @name variable

	$this->f3->set('content','app/views/hello.htm'); // loads the hello.htm view
	echo Template::instance()->render('app/templates/default.htm'); // loads the default.htm layout
}

3. That's it! Navigate to http://yourtcg.com/hello in your browser. You should see "Hello, World." printed to the screen.

File Structure (and MVC) Explained

The files and code within MyTCG-f3 are organized in an MVC-like structure. If you're not familiar with MVC, this may be a bit disorienting at first! But this is important because it allows you to organize your code in a logical, modular way, which ultimately makes everything much easier to maintain in the long run.

File Tree Overview

  • app
    • controllers - All application logic
      • core - Default MyTCG-f3 controllers
      • local - Custom and/or extended controllers
    • models - All database logic
      • core - Default MyTCG-f3 models
      • local - Custom and/or extended models
    • plugins - All plugin files
    • templates - HTML for your website layout and email templates
    • views - HTML and content for each view (or page) of your website
    • www - Static pages that don't require custom database or application logic
  • assets - Static asset files (css, js, images)
    • css
    • js
    • img
  • storage
    • backups - Backups of your database are stored here
    • logs - Your players' logs are stored here
    • jig - Jig database
      • games - Game configuration and data
  • tmp - Temporary storage and cache for your website
  • vendor - PHP libraries used by MyTCG-f3 (F3, Swift Mailer)
  • bootstrap.php - Handles the default routing behaviors of MyTCG-f3
  • config.ini - Customize and configure your MyTCG-f3 instance here
  • index.php - Loads and runs your MyTCG-f3 website

Essential Concepts

The only areas that are really important to understand in order to use MyTCG-f3 are the following:

  1. config.ini
  2. Templates
  3. Views
  4. Controllers
  5. WWW

config.ini

This is your configuration file. It's very much the same as the original MyTCG "settings.php" file, so if you're a MyTCG veteran it should look familiar. Updating the options in your config.ini is the first thing you'll want to do when starting a MyTCG-f3 project, so take a moment to go through it and familiarize yourself!

These configuration settings are "global" variables - meaning they're always available to use or reference from any part of your project. You can reference them using the following syntax:

$f3->get('var');

Check out the official documentation on F3 variables to learn more!

Templates

Templates contain the HTML for your website layouts - ie. the stuff that usually goes into your "header.php" and "footer.php" files. The following templates are included with MyTCG-f3:

  • default.htm - The layout for your website
  • admin-default.htm - The layout for your admin control panel
  • admin-login.htm - The layout for the admin login page

If you want to create unique layouts for specific pages, you can add them here and load them via your controllers!

MyTCG-f3 templates are powered by the F3 template language. Definitely take a moment to read through their documentation - it's very quick and easy to learn, and will make your markup look super neat and tidy!

Email Templates

Within the templates directory is a sub-directory called emails - which (surprise!) contains the templates for the HTML emails sent from MyTCG-f3. You can customize these emails, and even create new email templates here.

Emails are handled by the Swift Mailer library, which is included in MyTCG-f3 by default. MyTCG-f3 also ships with a wrapper for the Swift Mailer library, which handles much of the configuration, and also automatically converts your HTML emails into their plain-text equivalents for multi-part support (TLDR; this allows you to use pretty HTML emails without getting flagged as SPAM).

You can use the following code to send an email from MyTCG-f3:

$mailer = new Mailer;
$message = $mailer->message()
->setSubject('My Email Subject')
->setFrom(array('[email protected]'))
->setTo(array('[email protected]'))
->setReplyTo(array('[email protected]'))
->setBody(Template::instance()->render('app/templates/emails/my-email-template.htm'), 'text/html')
;
$mailer->send($message)

Views

Views contain the HTML and content for each page of your website. You can process code and/or pass data to be used in your views via controllers, or create a quick static page by adding your view file to the www directory (see below for more on controllers and www files).

Like templates, the F3 template language is also available to use in your views.

Controllers

Your controllers are your application logic - ie. tasks such as form processing, session handling, and authentication. Controllers are also responsible for passing data to your views, and loading the appropriate views/templates for the requested route. If you like creating custom content, you'll likely spend a lot of time here!

In most frameworks, you need to define routes (routes are basically URLs for your various website pages), and then point those routes to the appropriate controller and/or view to process the request. In MyTCG-f3, the routing logic is automatically handled for you, so all you need to do is create your controllers and views.

For example, if you wanted to create a page that loads when someone visits the /members URI, you would just need to create a file called MembersController.php in your app/controllers/local directory containing the following code:

<?php
namespace Controllers\Local; // Tells the script that we are making a custom (local) controller

use Controllers\Core\Controller; // Tells the script that we want to use the default MyTCG-f3 base Controller
use Models\Core\Members; // Tells the script to use the core Members model for "new Members(...)" in the code below
use Template; // Tells the script to use the Fat-Free Framework template language to display the page

class MembersController extends Controller {

public function index()
{
	/****************
	Stores a reference to the "members" table in the $members variable.
	****************/
	$members = new Members($this->db);

	/****************
	Stores a list of all members in a new F3 variable called "members".
	This "members" variable is now available to use in the "members.htm" view referenced below.
	****************/
	$this->f3->set('members',$members->all());

	/****************
	Loads the "members.htm" view into the "content" area of the template,
	then loads the "default.htm" layout template.
	****************/
	$this->f3->set('content','app/views/members.htm');
	echo Template::instance()->render('app/templates/default.htm');
}

}

This code creates a class called MembersController (note that it must match the route name, be capitalized, and end with -Controller) that extends the base Controller class (which just contains some baseline code that's used for all controllers).

Within the MembersController class, we've created an index() function - this contains all of the code that we want to execute when someone visits /members.

Keep in mind that index() is a special controller function, and is always used for code at the top-most level of your route (ie. in this case, /members).

If we also wanted to create a sub-route to /members/hiatus, we would create a new function within the same MembersController class called hiatus():

public function hiatus()
{
	//some code to get Hiatus members

	$this->f3->set('content','app/views/members-hiatus.htm');
	echo Template::instance()->render('app/templates/default.htm');
}

This automatically makes the /members/hiatus route available on your website, runs some code when someone visits the page (ie. to grab Hiatus members from the database, most likely) and loads the contents of the "members-hiatus.htm" view into the "default.htm" layout template.

If you're a MyTCG-f3 beginner, you should definitely take a look at the controllers that are already included with MyTCG-f3 to familiarize yourself with the controller structure and the many use cases!

WWW

Controllers are a great way to keep your application logic separate from your view logic - which otherwise would inevitably result in some unsightly spaghetti code. However, sometimes controllers may seem a bit over-kill when you just want to get a simple static page up and running.

If a page doesn't require any complex application logic or database interaction, you can just add the view file to the www directory. This will automatically activate a route with a matching name (ie. an info.htm file within the www directory would create an /info route) and allows you to skip controllers altogether.

Note that all files within the www directory will automatically load within the default.htm layout template.

Clone this wiki locally