Custom Resources

1. # Getting Started
2. # Model and Controller
3. # Admin Views
4. # Index
5. # Add
6. # Edit
7. # Show
8. # Delete
9. # TypeRocket REST API
10. # Override Controller

#Getting Started

Custom resources are the way you access and manage custom database tables.

To get started, you will be creating a custom resource named "Test". When making your custom resource, it is crucial it does not share the same name as a post type or taxonomy.

Now, in your main business logic add the following code:

$parent_page = tr_resource_pages('Test')->setIcon('line-chart');

If you like, you can use TypeRocket migrations to manage your custom tables.

php galaxy make:migration add_tests_table

Here is the database table schema. Add it to your migration.

-- Description: Tests Migration 
-- >>> Up >>>  
CREATE TABLE `{
Pro Only Feature
prefix
Pro Only Feature
}tests` (  
  `id` int(11) unsigned NOT NULL AUTO_INCREMENT,  
  `name` varchar(255) DEFAULT NULL,  
  PRIMARY KEY (`id`)  
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;  
-- >>> Down >>>  
DROP TABLE IF EXISTS `{
Pro Only Feature
prefix
Pro Only Feature
}tests`;

Then run the migration.

php galaxy migrate up

#Model and Controller

php galaxy make:model -c base Test

This will create the model and controller needed to manage your custom resources.

#Admin Views

In the resources folder, create a new folder named pages to house the admin views. Next, create a folder in resources/pages named tests. Finally, create four files: index.php, show.php, edit.php and add.php.

#Index

Let us get started building out a complete resource.

#Actions

In the TestController you just created return a view for the admin for the index page.

public function index() {
    return tr_view('tests.index');
}

#View

For the index page you might want to use a table. In the index.php view add the following code:

<?php
$table = tr_table();
$table->setColumns([
    'name' => [
        'sort' => true,
        'label' => 'Name',
        'actions' => ['edit', 'view', 'delete']
    ],
    'id' => [
       'sort' => true,
       'label' => 'ID'
    ]
], 'name');
$table->render();

#Add

Let us make the resource capable of creating new items.

#Actions

In the TestController return a view for the admin for the add page.

public function add() {
    $form = tr_form('test');  
    $button = 'Add';  
  
    return tr_view('tests.form', compact('form', 'button'));
}

Next, save the data we pass over from the view using the create method.

public function create(Test $test)
{ 
	$test->name = tr_request()->getFields('name');  
	$test->save();  
	tr_response()->flashNext('Test created!');  
	return tr_redirect()->toPage('test', 'index');
}

#Views

In the form.php view add the following code:

<?php
/** @var \App\Elements\Form $form */
echo $form->save($button)->setFields(
    $form->text('Name')
);

#Edit

Let us make the resource capable of editing items.

#Actions

In the TestController return a view for the admin for the edit page.

public function edit( Test $test ) {
    $form = tr_form($test);  
	$button = 'Update';
	  
	return tr_view('tests.form', compact('form', 'button'));
}

Next, save the data we pass over from the view using the update method.

public function update(Test $test)
{
    $test->name = tr_request()->getFields('name');  
	$test->save();  
	tr_response()->flashNext('Test updated!');  
	return tr_redirect()->toPage('test', 'edit', $test->getID());
}

#Show

Let us make the resource capable of being viewed.

#Actions

public function show(Test $test)
{
    return tr_view('tests.show', ['test' => $test] );
}

#View

<h3><?php echo esc_html($test->name); ?></h3>

#Delete

Let us make a resource capable of being deleted.

#Actions

public function destroy(Test $test)
{
    $test->delete();
	return tr_response()->flashNext('Test deleted!', 'warning');
}

If you plan to use a delete view page as well, add a method called delete().

#View

You usually will not need the delete view. However, in some cases, it makes sense to have a page for deleting an item. For example, maybe you want a user to confirm their decision by clicking a checkbox before moving forward.

First, create a new method called delete().

public function delete($id)
{
    $form = tr_form('test', 'destroy', $id);
    return tr_view('tests.delete', ['form' => $form] );
}

To have a delete view create one last view file called delete.php.

echo $form->open();
echo $form->checkbox('Delete Record')->setText("I'm sure I want to delete this record");
echo $form->submit('Delete');
echo $form->close();

Next, update your index view file and turn off AJAX for the delete method.

<?php
$table = tr_table();
$table->setColumns([
    'name' => [
        'sort' => true,
        'label' => 'Name',
        'actions' => ['edit', 'view', 'delete'],
        'delete_ajax' => false // disable AJAX
    ],
    'id' => [
       'sort' => true,
       'label' => 'ID'
    ]
], 'name');
$table->render();

Finally, modify the destroy() method.

public function destroy($id)
{
    $delete = tr_request()->getFields('delete');  
  
	if($delete) {  
	    $test->delete();  
	    tr_response()->canRedirect()->flashNext('Test deleted!', 'warning');  
	    return tr_redirect()->toPage('test', 'index');  
	}  
	  
	tr_response()->flashNext('Test not deleted!', 'error');  
	return tr_redirect()->toPage('test', 'delete', $test->getID());
}

#TypeRocket REST API

If you want to use the TypeRocket REST with your Form classes use the useRest() method. For example, you might update your edit actions Form object to use the TypeRocket REST API:

public function edit(Test $test)  
{  
    $form = tr_form($test)->useRest();
    $button = 'Update';  
  
    return tr_view('tests.form', compact('form', 'button'));  
}

For security, custom resources using the REST API are only accessible to admin users. If you wish to change the security settings for custom resources using the REST API register a custom middleware group using the same name as your custom resource. In the example we have been using, test would be the name of the group.

If you encounter issues, the TypeRocket REST API requires strict adherence to the controller action naming scheme: showRest, create, update, and destroy.

Also, be sure your custom resources do not share the name of a post type or taxonomy as the REST API is shared with them. For example, if you create a custom resource named post the REST API will update the post post type and not your custom resource.

#Override Controller

You can override the controller used by using shorthand.

tr_resource_pages('Test@\App\Controllers\TestController');

Or, your class if you are making a plugin.

tr_resource_pages('Test@\MyPlugin\TestController');

If you want to access your custom resource using the TypeRocket REST API used by the Form classes useRest() method, you may need to register your resource if you are not using the standard controller naming convention. To register a custom resource use the Registry::addCustomResource() method.

\TypeRocket\Register\Registry::addCustomResource('test', [
    'controller' => '\MyPlugin\TestController', // Controller class
]);