Exporting data from your models

Para allows you to implement exporters in your admin panel.

1. Configure which component you want to allow exporting from
2. Create and configure the exporter

Exporting to CSV

For the demonstration, we'll create an export of the users in CSV format.

1. Configure the component

Inside your config/components.rb :

component :users, :crud, model_type: 'User',
                         exporters: ['UsersExporter']

In our users component main page, we'll get a button to export to CSV

2. Create and configure the exporter

Generate the exporter from the command line :

rails generate para:exporter user csv

An exporter file will be created at : app/exporters/users_exporter.rb

Note : If this is your first exporter, since the app/exporters folder has just been created, you'll need to reboot your rails server for the exporters folder to be added to your autoload paths.

Then configure the exporter at app/exporters/csv/users_exporter.rb :

class UsersExporter < Para::Exporter::Csv
  # Define the export file name, here it'll be : "users-export.csv"
  def name
    'users-export'
  end

  private
    
  # Define which fields to export in your CSV
  def fields
    [:id, :name, :email, :created_at]
  end
end

Note that the exporter automatically inherits from the Para::Exporter::Csv parent class. This allows to easily create Excel-compatible CSVs defining only the file name and the fields to export.

If you need more flexibility for your export, commented methods are provided in the generate Exporter file that you can use to have complete control over the CSV generation.

Configuring exporter name

Exporters use are ActiveModel::Naming to easily handle translations. To change the exporter name, you need to create the following key in your translations :

activemodel.models.<your_exporter_name>

So for our UsersExporter you'd define :

activemodel:
  models: 
    users_exporter: "Users export"

Exporting to other formats

To export to other formats, you can use the same generator, with the desired format (JSON, XLS or other).

For example, if you want to export your users in JSON format :

rails generate para:exporter user json

You'll then configure the file in app/exporters/users_exporter.rb :

class UsersExporter < Para::Exporter::Base
  def name
    'users'
  end

  def extension
    '.json'
  end
    
  # Define your custom JSON exporting logic here
  def generate
    resources.as_json(only: [:id, :name, :email, :created_at]).to_json
  end
end

Linking to the exporter from your component

CRUD components automatically show exporters for a given component available as a button or a dropdown in the main table view of the component. For other cases, where you want to create a link to access the export form, you'll need to add the link manually to your views.

The URL to access the desired export form can be accessed through the component#path method, like the following : component.path(namespace: :exports, exporter: 'YourExporterClassName').

Since exporters are run in background and to allow the UI to work as needed, you'll need to add some specific attributes to your link to allow Para's async job tracker interface to work : the [data-remote] and [data-job-tracker-button] attributes.

For a basic link with an upload icon and a button appearance, the could would look like :

= link_to @component.path(namespace: :exports, exporter: 'UsersExporter'), class: 'btn btn-lg btn-primary', remote: true, data: { :'job-tracker-button' => true } do
  = fa_icon 'upload'
  Export data