Editing Generic Reporting Framework (section)

==For Developers==

GitHub: https://github.com/eprintsug/reports

===Returning Report Bullet Points (v1.1+ only)===
By default, any problems that are identified by the report's 'validate_dataobj' function are displayed as bullet points for that item in the report. However, if you wish to display bullet points for an item which does not report any problems when validating, a new 'bullet_points' function may be defined, e.g.

<pre>
sub bullet_points
{
        my( $self, $eprint ) = @_;

        my $repo = $self->{repository};

        my @bullets;

        foreach my $creator( @{ $eprint->value( "creators" ) } )
        {
                if( EPrints::Utils::is_set( $creator->{orcid} ) )
                {
                        push @bullets, 
                                EPrints::XML::to_string( $repo->html_phrase( 
                                       "creator_with_orcid", 
                                       creator => $repo->xml->create_text_node(EPrints::Utils::make_name_string( $creator->{name} ) ),
                                       orcid => $repo->xml->create_text_node( $creator->{orcid} ) 
                                ) );
                }
                else
                {
                        push @bullets, 
                                EPrints::XML::to_string( $repo->html_phrase( 
                                       "creator_no_orcid", 
                                       creator => $repo->xml->create_text_node(EPrints::Utils::make_name_string( $creator->{name} ) ) 
                                 ) );
                }
        }

        return @bullets;
}

</pre>

The 'bullet_points' function should then be called from ajax_eprint when generating the report's JSON data, e.g. 

<pre>
sub ajax_eprint
{
        my( $self ) = @_;

        my $repo = $self->repository;

        my $json = { data => [] };

        $repo->dataset( "eprint" )
        ->list( [$repo->param( "eprint" )] )
        ->map(sub {
                (undef, undef, my $eprint) = @_;

                my $frag = $eprint->render_citation_link;
                push @{$json->{data}}, {
                        datasetid => $eprint->dataset->base_id,
                        dataobjid => $eprint->id,
                        summary => EPrints::XML::to_string( $frag ),
                        problems => [ $self->validate_dataobj( $eprint ) ],
                        bullets => [ $self->bullet_points( $eprint ) ],
                };
        });
        print $self->to_json( $json );
}

</pre>

===Returning Report Colours (v1.1+ only)===
Version 1.0 of the Generic Reporting Framework plugin, can only display two colours for records displayed in the report. When validating a record using the a report plugin's 'validate_dataobj' function, if an array of problems is returned the item is displayed with a red bar, and if none are returned the item is displayed with a green bar.

To return other colours, define a 'get_state' function which should return a string representing a hex encoded colour. E.g.

<pre>
sub get_state
{
        my( $self, $eprint ) = @_;

        my $repo = $self->{repository};

        if( $eprint->hasProblem() )
        {
            return "#E19141"; #orange
        }
        else
        {
            return undef;
        }
}
</pre>

The 'get_state' function should then be called from ajax_eprint when generating the report's JSON data, e.g.

<pre>
sub ajax_eprint
{
        my( $self ) = @_;

        my $repo = $self->repository;

        my $json = { data => [] };

        $repo->dataset( "eprint" )
        ->list( [$repo->param( "eprint" )] )
        ->map(sub {
                (undef, undef, my $eprint) = @_;
                
                my $frag = $eprint->render_citation_link_staff;
                push @{$json->{data}}, {
                        datasetid => $eprint->dataset->base_id,
                        dataobjid => $eprint->id,
                        summary => EPrints::XML::to_string( $frag ),
                        problems => [ $self->validate_dataobj( $eprint ) ],
                        state => $self->get_state( $eprint ),
                };
        });

        print $self->to_json( $json );
}
</pre>

===Custom Reports (v1.1+ only)===
For a report to display in the 'Custom Reports' tab of the splash page, its custom property must be set. E.g.

<pre>
#from within the local archive level
$c->{plugins}{"Screen::Report::REF_CC"}{params}{custom} = 1;
</pre>

===Custom Export Fields (v2.0+ only)===

To specify which fields should appear in the custom export box for a specific report plugin, include an 'export_conf' parameter in the plugin's configuration that defines an ID for locating configuration relating to exports. E.g.

<pre>
#in the report plugin's 'sub new' constructor
$self->{export_conf} = 'hefce_report';
</pre>

The export fields themselevs should then be defined at the local archive configuration level, using this 'export_conf' ID. 

Export fields are described using a hash of 1 or more arrays, allowing fields to be grouped under a particular heading. Note, that as per a search config, fields of other datasets may be defined also, providing the dataset has a connection with the parent dataset (e.g. document fields can be defined within an eprint context as documents.fieldname). E.g.

<pre> 
$c->{hefce_report}->{exportfields} = {
        ref_core => [ qw(
                eprintid
                documents.content
                type
                title
                abstract
                creators
                publisher
                divisions
                dates
                id_number
                isbn
                issn
                official_url                                            
        )],
        ref_rioxx => [ qw(
                rioxx2_free_to_read
                rioxx2_license_ref
                rioxx2_coverage
                rioxx2_source
                rioxx2_subject
                rioxx2_dateAccepted
                rioxx2_publication_date
                rioxx2_apc
                rioxx2_project
                rioxx2_version
                rioxx2_version_of_record
        )],
        ref_exceptions => [ qw(
                hoa_compliant
                hoa_problems
                hoa_ref_pan
                hoa_ex_dep
                hoa_ex_dep_txt
                hoa_ex_acc
                hoa_ex_acc_txt
                hoa_ex_tec
                hoa_ex_tec_txt
                hoa_ex_oth
                hoa_ex_oth_txt
        )],
};
</pre>

For each of the fields defined above a checkbox will be displayed in the Report's 'Export Options' box. Some of these may be selected by default, by defining an "exportfield_defaults" value, also at the local archive configuration level, E.g.

<pre>
$c->{hefce_report}->{exportfield_defaults} = [ qw( eprintid documents.content type title creators dvisisions dates hoa_compliant hoa_problems ) ];
</pre>

Finally, functions may be defined that allow fields to be displayed in a bespoke manner. These functions are also defined at the local archive level via use of the 'export_conf' ID, with each field mapping on to a function. The functions take the DataObj and Report plugin as parameters. E.g.

<pre>
$c->{hefce_report}->{custom_export} = {
        hoa_compliant => sub {
                my( $dataobj, $plugin ) = @_;

                my $compliance = "Compliant";

                my @problems = $plugin->validate_dataobj( $dataobj );
                if( scalar( @problems ) > 0 )
                {
                        $compliance = "Not Compliant";
                }
                $compliance = "Compliant pending open access" if defined $plugin->get_state( $dataobj );
                return $compliance;
        },
        creators => sub {
                my( $dataobj ) = @_;

                my @creator_names;
                my $creators = $dataobj->get_value( "creators" );
                foreach my $c ( @{$creators} )
                {
                        push @creator_names, EPrints::Utils::make_name_string( $c->{name} );
                }
                return join( ";", @creator_names );
        },
</pre>

===Custom Report Search Configuration (v2.0+ only)===

Custom reports allow users to generate reports via a search config. This is stored in a report plugin parameter call "sconf" and is by default defined as "report":

<pre>
$self->{sconf} = "report";
</pre>

With default report config is defined as follows, matching the format used by search configs such as the Advanced Search:

<pre>
$c->{search}->{report} =
{
        search_fields => [
                { meta_fields => [ "title" ] },
                { meta_fields => [ "creators_name" ] },
                { meta_fields => [ "date" ] },
                { meta_fields => [ "subjects" ] },
                { meta_fields => [ "type" ] },
                { meta_fields => [ "divisions" ] },
                { meta_fields => [ "publication" ] },
        ],
        order_methods => {
                "byyear"         => "-date/creators_name/title",
                "byyearoldest"   => "date/creators_name/title",
                "byname"         => "creators_name/-date/title",
                "bytitle"        => "title/creators_name/-date"
        },
        default_order => "byyear",
        show_zero_results => 1,
};
</pre>

Bespoke search configurations can be defined, by overriding the 'sconf' parameter. E.g.

<pre>
#in the report plugin's 'sub new' constructor
$self->{sconf} = 'hefce_report';
</pre>

And then a corresponding search configuration may be defined at the local archive level. E.g.

<pre>
$c->{search}->{hefce_report} =
{
        search_fields => [
                { meta_fields => [ "title" ] },
                { meta_fields => [ "creators_name" ] },
                { meta_fields => [ "date" ] },
                { meta_fields => [ "hoa_date_acc" ] },
                { meta_fields => [ "subjects" ] },
                { meta_fields => [ "type" ] },
                { meta_fields => [ "ispublished" ] },
                { meta_fields => [ "divisions" ] },
                { meta_fields => [ "publication" ] },
        ],
        order_methods => {
                "byyear"         => "-date/creators_name/title",
                "byyearoldest"   => "date/creators_name/title",
                "byname"         => "creators_name/-date/title",
                "bytitle"        => "title/creators_name/-date"
        },
        default_order => "byyear",
        show_zero_results => 1,
};
</pre>


===Custom Report Header (v2.1+ only)===

The compliance information in the report header (the compliance bar visualisation and the percentage) can be removed by setting the 'show_compliance' value for a report. E.g.

<pre>
#in the report plugin's 'sub new' constructor
$self->{show_compliance} = 0;
</pre>

The word 'outputs' in the report header to show how many items are included in the report, may be customised by setting the 'labels' value. E.g.

<pre>
#in the report plugin's 'sub new' constructor
$self->{labels} = {
                outputs => "users"
        };
</pre>

Only the 'outputs' value can be changed at present, with the value stored in a 'labels' hash for any future changes that may be applied.


===Grouping and Sorting (v3.0+ only)===

To specify grouping and sorting parameters, first a key must be defined as a report plugin parameter, that allows the grouping and sorting configuration to be uniquely identified: 

<pre>
$self->{sort_conf} = 'eprint_report';
$self->{group_conf} = 'eprint_report';
</pre>

At the local archive level sorting configurations may be defined like so: 

<pre>
$c->{eprint_report}->{sortfields} = {
        "byname" => "creators_name/-date/title",
        "byyear" => "-date/creators_name/title",
        "bytitle" => "title/creators_name/-date",
        "bydivision" => "divisions/creators_name/-date",
};
</pre>

Sorting configurations can be defined using the same format as used by any search configuration in the repository.

Grouping configurations may be defined as follows:

<pre>
$c->{eprint_report}->{groupfields} = [ qw(
        divisions
        subjects
        type
        date;res=year;reverse_order=1
)];
</pre>

Much like the 'menus' and 'variations' when configuring Browse Views, further options may be passed for each group, with separated by a semi-colon. 

* 'reverse_order=1': reverses the ordering of the groups, e.g. dates will be presented from newest to oldest, rather than oldest to newest.
* 'truncate': truncates the field value by the number of characters specified (e.g. 'creators_name;truncate=1' will only use the creator's first initial).
* 'res': This only applies to 'date' fields, applying a resolution for the date, e.g. 'date;res=year' (see [[Date_field]] for more information).

===HTML Export Templates (v3.0+ only)===
To customise the look and feel of an HTML report export, a number of parameters may be defined at the local archive configuration level:

<pre>
$c->{plugins}{"Export::Report::HTML"}{params}{title_phrase} = "eprint_report_title";
$c->{plugins}{"Export::Report::HTML"}{params}{custom_class} = "eprint_report";
$c->{plugins}{"Export::Report::HTML"}{params}{template} = "eprint_report";
</pre>

Setting the 'title_phrase' will apply a custom phrase as the title of the HTML report.

Setting the 'custom_class' parameter, will result in the value being added as a class attribute to the various HTML elements that make up the report, allowing for easier CSS customisation.

The 'template' parameter is used to specify the name of a template XML file that the report should use instead of default.xml. 

===Export Virtual Report Fields (v3.0+ only)===
The list of fields to be included in a report export, may now also include virtual report fields. These fields do not need to be defined anywhere else in the dataset configuration.

To define a virtual report field, first include it in the list of the 'exportfields', e.g.

<pre>
$c->{eprint_report}->{exportfields} = {
        eprint_report_core => [ qw(
                eprintid
                title
                virtual_field_foo
        )]
};
</pre>

For the field to be exported successfully, we must define a function that generates a value to be included in the export. E.g.

<pre>
$c->{eprint_report}->{custom_export} = {
        virtual_field_foo => sub {
                my( $dataobj, $plugin ) = @_;
                return "My exported value";       
        }
};
</pre>

To return values over multiple rows in the multiline CSV export, we can simply return an array of the values we want to return.

The export functions (which may also be used to override existing fields in the dataset), receive both the dataobject and the report plugin as parameters, which may be used when generating the value that is to be exported.

===Set Export Field Checkbox Ordering (v3.1+ only)===
The fields which may be included in an export are displayed as columns of checkboxes, as defined by the 'exportfields' value, e.g.:

<pre>
$c->{my_report}->{exportfields} = {
        eprint_core => [ qw(
                eprintid
                title
                abstract
        )],
        eprint_metadata => [ qw(
                publication
                divisions               
                subjects
        )]
};
</pre>

The order in which these columns are displayed may be set by providing a list of the keys of this hash, e.g.:

<pre>
$c->{my_report}->{exportfield_order} = [ qw( eprint_core eprint_metadata )];
</pre>

In both these examples the value 'my_report' used as a key to find the right bit of configuration can be defined in the report's 'export_conf' parameter, e.g.:

<pre>
$self->{export_conf} = 'my_report';
</pre>

===Set Available Export Plugins (v3.1+ only)===
The ordering and presence of export plugins presented in the 'Export Options' box at the top of a report screen, may be configured for each report, e.g.

<pre>
$c->{eprint_report}->{export_plugins} = [ qw( Export::Report::CSV Export::Report::HTML Export::Report::JSON )]; #set the CSV export to appear at the top of the select element
</pre>

In the above example, the value 'eprint_report' used as a key to find the configuration can be defined in the report's 'export_conf' parameter, e.g.:

<pre>
$self->{export_conf} = 'eprint_report';
</pre>