# Cards
# Overview
Cards are similar to resource tools, but are small, miniature tools that are typically displayed at the top of your dashboard, resource index, or resource detail screens. In fact, if you have used Nova metrics, you have already seen Nova cards. Custom Nova cards allow you to build own, metric-sized tools.
# Defining Cards
Cards may be generated using the nova:card Artisan command. By default, all new cards will be placed in the nova-components directory of your application. When generating a card using the nova:card command, the card name you pass to the command should follow the Composer vendor/package format. So, if we were building a traffic analytics card, we might run the following command:
php artisan nova:card acme/analytics
When generating a card, Nova will prompt you to install the card's NPM dependencies, compile its assets, and update your application's composer.json file. All custom cards are registered with your application as a Composer "path" repository.
Nova cards include all of the scaffolding necessary to build your card. Each card 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 Cards
Nova cards may be registered in your resource's cards method. This method returns an array of cards available to the resource. To register your card, add your card to the array of cards returned by this method:
use Acme\Analytics\Analytics;
/**
* Get the cards available for the resource.
*
* @param \Illuminate\Http\Request $request
* @return array
*/
public function cards(Request $request)
{
return [new Analytics];
}
# Card Options
Often, you will need to allow the consumer's of your card to customize run-time configuration options on the card. You may do this by exposing methods on your card class. These methods may call the card's underlying withMeta method to add information to the card's metadata, which will be available within your Card.vue component. The withMeta method accepts an array of key / value options:
<?php
namespace Acme\Analytics;
use Laravel\Nova\Card;
class Analytics extends Card
{
/**
* The width of the card (1/3, 1/2, or full).
*
* @var string
*/
public $width = '1/3';
/**
* Indicates that the analytics should show current visitors.
*
* @return $this
*/
public function currentVisitors()
{
return $this->withMeta(['currentVisitors' => true]);
}
/**
* Get the component name for the card.
*
* @return string
*/
public function component()
{
return 'analytics';
}
}
After registering your custom card, don't forget to actually call any custom option methods you defined:
(new Acme\Analytics\Analytics)->currentVisitors()
# Building Cards
Each card generated by Nova includes its own service provider and "card" class. Using the analytics card as an example, the card class will be located at src/Analytics.php.
The card's service provider is also located within the src directory of the card, and is registered in your card'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 card to certain users, you may chain the canSee method onto your card's registration. The canSee method accepts a Closure which should return true or false. The Closure will receive the incoming HTTP request:
use Acme\Analytics\Analytics;
/**
* Get the cards available for the resource.
*
* @param \Illuminate\Http\Request $request
* @return array
*/
public function cards(Request $request)
{
return [
(new Analytics)->canSee(function ($request) {
return false;
}),
];
}
# Routing
Often, you will need to define Laravel routes that are called by your card. When Nova generates your card, it creates a routes/api.php routes file. If needed, you may use this file to define any routes your card requires.
All routes within this file are automatically defined inside a route group by your card's CardServiceProvider. The route group specifies that all routes within the group should receive a /nova-vendor/card-name prefix, where card-name is the "kebab-case" name of your card. So, for example, /nova-vendor/analytics. You are free to modify this route group definition, but take care to make sure your Nova card will co-exist with other Nova packages.
Routing Authorization
When building routes for your card, you should always add authorization to these routes using Laravel gates or policies.
# Assets
When Nova generates your card, resources/js and resources/sass directories are generated for you. These directories contain your card's JavaScript and Sass stylesheets. The primary files of interest in these directories are: resources/js/components/Card.vue and resources/sass/card.scss.
The Card.vue file is a single-file Vue component that contains your card's front-end. From this file, you are free to build your card however you want. Your card can make HTTP requests using Axios, which is available globally. In addition, the moment.js and underscore.js libraries are globally available.
# Card Properties
Your card's Card.vue component receives a card Vue prop. This property provides access to any card options that may be available:
const currentVisitors = this.card.currentVisitors;
# Registering Assets
Your Nova card's service provider registers your card's compiled assets so that they will be available to the Nova front-end:
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
$this->app->booted(function () {
$this->routes();
});
Nova::serving(function (ServingNova $event) {
Nova::script('{{ component }}', __DIR__.'/../dist/js/card.js');
Nova::style('{{ component }}', __DIR__.'/../dist/css/card.css');
Nova::translations(__DIR__.'/../resources/lang/en/card.json');
});
}
JavaScript Bootstrap & Routing
Your component is bootstrapped and registered in the resources/js/card.js file. You are free to modify this file or register additional components here as needed.
# Compiling Assets
Your Nova resource card contains a webpack.mix.js file, which is generated when Nova creates your card. You may build your card 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
← Assets Dashboards →