# Tools

Overview
Defining Tools
Registering Tools
Building Tools

# Overview

Sometimes, your business may need additional functionality that isn't provided by Nova. For this reason, Nova allows you to build custom tools and add them to the Nova sidebar. Nova tools are incredibly customizable, as they primarily consist of a single-file Vue component that is totally under your control. Within your Vue component, you are free to make HTTP requests to any controller within your application.

# Defining Tools

Custom tools may be generated using the nova:tool Artisan command. By default, all new tools will be placed in the nova-components directory of your application. When generating a tool using the nova:tool command, the tool name you pass to the command should follow the Composer vendor/package format. So, if we were building a price tracker tool, we might run the following command:

php artisan nova:tool acme/price-tracker

When generating a tool, Nova will prompt you to install the tool's NPM dependencies, compile its assets, and update your application's composer.json file. All custom tools are registered with your application as a Composer "path" repository.

Nova tools include all of the scaffolding necessary to build your tool. Each tool even contains its own composer.json file and is ready to be shared with the world on GitHub or the source control provider of your choice.

# Registering Tools

Nova tools may be registered in your application's NovaServiceProvider. Your service provider contains a tools method, which returns an array of tools. To register your tool, simply add it to the list of tools returned by this method. For example, if you created a Nova tool named acme/price-tracker, you may register the tool like so:

use Acme\PriceTracker\PriceTracker;

/**
 * Get the cards that should be listed in the Nova sidebar.
 *
 * @return array
 */
public function tools()
{
    return [
        new PriceTracker,
    ];
}

# Building Tools

Each tool generated by Nova includes its own service provider and "tool" class. Using the price-tracker tool as an example, the tool class will be located at src/PriceTracker.php. The tool class must be registered with your application's NovaServiceProvider as previously noted.

The tool's service provider is also located within the src directory of the tool, and is registered in your tool's composer.json file so that it will be auto-loaded by the Laravel framework.

# Authorization

If you would like to only expose a given tool to certain users, you may chain the canSee method onto your tool's registration. The canSee method accepts a Closure which should return true or false. The Closure will receive the incoming HTTP request:

use Acme\PriceTracker\PriceTracker;

/**
 * Get the tools that should be listed in the Nova sidebar.
 *
 * @return array
 */
public function tools()
{
    return [
        (new PriceTracker)->canSee(function ($request) {
            return false;
        }),
    ];
}

# Routing

Often, you will need to define Laravel routes that are called by your tool. When Nova generates your tool, it creates a routes/api.php routes file. If needed, you may use this file to define any routes your tool requires.

All routes within this file are automatically defined inside a route group by your tool's ToolServiceProvider. The route group specifies that all routes within the group should receive a /nova-vendor/tool-name prefix, where tool-name is the "kebab-case" name of your tool. So, for example, /nova-vendor/price-tracker. You are free to modify this route group definition, but take care to make sure your Nova tool will co-exist with other Nova packages.

# Routing Authorization

Your Nova tool is generated with an Authorize middleware. This middleware automatically determines that the authenticated user can "see" the tool before it processes any requests to routes within your tool's route group; however, you are free to modify this middleware if needed.

Your Nova tool class contains a renderNavigation method. This method should return the view that renders your tool's sidebar links. Of course, a default navigation view will be created for you when the tool is generated; however, you are free to customize this view as needed:

/**
 * Build the view that renders the navigation links for the tool.
 *
 * @return \Illuminate\View\View
 */
public function renderNavigation()
{
    return view('price-tracker::navigation');
}

# Assets

When Nova generates your tool, resources/js and resources/sass directories are generated for you. These directories contain your tool's JavaScript and Sass stylesheets. The primary files of interest in these directories are: resources/js/components/Tool.vue and resources/sass/tool.scss.

The Tool.vue file is a single-file Vue component that contains your tool's front-end. From this file, you are free to build your tool however you want. Your tool can make HTTP requests using Axios, which is available globally. In addition, the moment.js and underscore.js libraries are globally available.

# Registering Assets

Your Nova tool class contains a boot method. This method is executed when the tool is registered and available. By default, this method registers your tool's compiled assets so that they will be available to the Nova front-end:

/**
 * Perform any tasks that need to happen on tool registration.
 *
 * @return void
 */
public function boot()
{
    Nova::script('price-tracker', __DIR__.'/../dist/js/tool.js');
    Nova::style('price-tracker', __DIR__.'/../dist/css/tool.css');
}

JavaScript Bootstrap & Routing

Your component is bootstrapped and front-end routes are registered in the resources/js/tool.js file. You are free to modify this file or register additional components here as needed.

# Compiling Assets

Your Nova tool contains a webpack.mix.js file, which is generated when Nova creates your tool. You may build your tool using the NPM dev and prod commands:

// Compile your assets for local development...
npm run dev

// Compile and minify your assets...
npm run prod

In addition, you may run the NPM watch command to auto-compile your assets when they are changed:

npm run watch

Nova utilizes the free icon set Heroicons UI (opens new window) from designer Steve Schoger (opens new window). Feel free to use these icons to match the look and feel of Nova's built-in ones.

← Themes Metrics →