Difference between revisions of "Adding new views"

From EPrints Documentation
Jump to: navigation, search
(Linking in your view)
 
(47 intermediate revisions by 7 users not shown)
Line 1: Line 1:
Browse views provide a way for visitors to your site to discover relevant content without a specific item in mind (for example, browsing all the content associated with a particular topic). Visitors arriving directly at the page for a specific item in the repository (for example, via a search engine) may also use the views to discover other related content. There are two default views in EPrints - '''By Year''' and '''By Subject'''. This guide describes how to add additional views to your repository.
+
[[Category:Manual]]
 +
[[Category:Browse Views]]
 +
 
 +
 
 +
Browse views provide a way for visitors to your site to discover relevant content without a specific item in mind (for example, browsing all the content associated with a particular topic). Visitors arriving directly at the page for a specific item in the repository (for example, via a search engine) also use views you have defined to discover related content.  
 +
 
 +
There are two default views in EPrints - '''By Year''' and '''By Subject'''. This guide describes how to add additional views to your repository.
 +
Instead with this link you can read a [http://wiki.eprints.org/w/Views.pl complete list of all options] avaible for views.
  
 
__TOC__
 
__TOC__
  
===Adding a new view===
+
===The basics===
 
 
This section describes how to quickly add a new view to your repository.
 
  
Open the views configuration file in a text editor:
+
The views for your repository are defined in the views configuration file:
  
 
  /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl
 
  /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl
  
Find the browse_views configuration setting:
+
Open this file and find the browse_views configuration setting:
  
 
  $c->{browse_views} = [
 
  $c->{browse_views} = [
 
         {
 
         {
 
                 id => "year",
 
                 id => "year",
 +
                fields => "-date;res=year",
 
                 ...
 
                 ...
 
         },
 
         },
 
         {
 
         {
 
                 id => "subjects",
 
                 id => "subjects",
 +
                fields => "subjects",
 
                 ...
 
                 ...
 
         },
 
         },
 
  ];
 
  ];
  
Each view is defined using a special (Perl*) syntax: the view definition consists of a pair of curly braces (''note the comma after each closing brace'') enclosing a list of property/value pairs (note ''the comma'' after each line).
+
The views are defined using a special (Perl) syntax: the view definition consists of a pair of curly braces (''note the comma after each closing brace'') enclosing a list of property/value pairs (note ''the comma'' after each line).
 +
 
 +
The key part of the view definition is the '''fields''' property. This names the metadata field (or fields) that EPrints will use to construct the view. For example, for the '''By Year''' view, EPrints groups the records in the repository according to their '''date''' (note that the '''res=year''' suffix tells EPrints to only consider the year part), and constructs a Web page for each date listing the records. Similarly, the '''Browse by Subjscts''' view, groups the records according to the ''subjects'' they have been assigned to (a record may appear in more than one group!).
 +
 
 +
Both the '''Browse by Year''' and '''Browse by Subject''' views are constructed using the values of a single field ('''date''' and '''subjects''' respectively).
 +
 
 +
It is also possible to construct a view using the ''combined'' values of two or more fields (eg. group records by author '''and''' editor), or even using a sequence of two or more fields (eg. group records by journal title '''and then''' by volume number).
 +
 
 +
===Worked example: browse by organisational structure===
 +
 
 +
By default, EPrints has a ''divisions'' metadata field which allows authors to associate their deposits with the divisions (units, faculties, schools, departments, institutes, centres..) that were involved in producing their item (for example, the author's department, and the departments of any co-authors). This worked example allows visitors to browse the repository content by division.
  
* Those familiar with Perl will recognise the browse_views setting as a reference to an array of hash references.
+
Open the views configuration file:
  
'''Example 1 Browse by organisational structure'''
+
/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl
  
By default, EPrints has a ''divisions'' metadata field which allows authors to associate their deposits with the divisions (units, faculties, schools, departments, institute, centre..) that were involved in producing their item (for example, the author's department, and the departments of his co-authors). To allow visitors to the repository to browse the content by division, add the following definition to the browse_views setting:
+
Add the following definition to the browse_views setting:
  
 
  $c->{browse_views} = [
 
  $c->{browse_views} = [
Line 49: Line 66:
 
  ];
 
  ];
  
'''Example 2 Browse by type'''
+
Save the file and generate the new view pages (this will also re-generate any existing views defined in the views configuration file):
 
 
Every deposit in EPrints has a type (article, book, thesis...). To allow visitors to browse your repository content by type, add the following definition to the browse_views setting:
 
 
 
{
 
        id => "types",
 
        fields => "type",
 
        order => "-date/title",
 
        hideempty => 1,
 
},
 
 
 
After adding a new view definition, save the file generate the new view pages:
 
  
 
  bin/generate_views ARCHIVEID --verbose
 
  bin/generate_views ARCHIVEID --verbose
 
(this will also re-generate any existing views defined in the views configuration file).
 
 
====Testing new views====
 
  
 
Open the view page in a Web browser:
 
Open the view page in a Web browser:
Line 72: Line 74:
 
  http://your.repository.url/view/
 
  http://your.repository.url/view/
  
The view page lists all the available views. You should see your new views on the list.
+
The view page lists all the available views. You should see your new views on the list:
  
[[Image:View_page.png]]
+
[[Image:View_page2.png|frame|none|The view page lists available views]]
  
'''Naming your view
+
'''Fixing the undefined phrase warning''' The new view may appear on the views page with an ''undefined phrase'' warning (you may also notice a similar warning message when running generate_views):
 
 
Your new view may appear on the views page with an ''undefined phrase'' warning:
 
  
 
  ["viewname_eprint_divisions" not defined]
 
  ["viewname_eprint_divisions" not defined]
  
(you may also notice a similar warning message when running generate_views).
+
Each view you create needs to be assigned a ''human-readable'' name, which EPrints will use on the view Web pages.
 
 
Each view you create needs to be assigned a name, which EPrints will use to display the view.
 
  
 
Edit the language-specific phrases file for view names:
 
Edit the language-specific phrases file for view names:
  
  /opt/eprints3/archives/devel/cfg/lang/en/phrases/views.xml
+
  /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/views.xml
  
Add an appropriate phrase which describes your new view, for example:
+
Add an appropriate phrase which describes the new view, for example:
  
 
  <epp:phrase id="viewname_eprint_divisions">Division</epp:phrase>
 
  <epp:phrase id="viewname_eprint_divisions">Division</epp:phrase>
  
Reload the phrase files:
+
Save the phrases file and regenerate the view pages:
  
  bin/epadmin reload ARCHIVEID
+
  bin/generate_views ARCHIVEID --verbose
  
====Linking in your view====
+
===Example view definitions===
  
'''Example 1 Add your view to the navigation bar
+
====Browse by type (3.3.8)====
  
Open the site template:
+
Every deposit in EPrints has a type (article, book, thesis...). To allow visitors to browse your repository content by type, add the following definition to the browse_views setting:
  
  /opt/eprints3/archives/devel/cfg/lang/en/templates/default.xml
+
  {
 +
    id=>"doctype",
 +
    menus => [
 +
    {
 +
      fields => [ "type" ],
 +
    },],
 +
    order=>"-date",
 +
},
 +
 
 +
====Browse by author====
  
Find the navigation bar:
+
===Example views (combined fields)===
  
<pre>
+
====Browse by author and editor====
<ul class="ep_tm_menu"> ... <li><a href="{$config{base_url}}/view/subjects">Browse by Subject</a></li></ul>
 
</pre>
 
  
Add a link to your new view:
+
===Example views (multiple fields)===
  
<pre>
+
====Browse by journal title, then by volume====
<ul class="ep_tm_menu"> ... <li><a href="{$config{base_url}}/view/subjects">Browse by Subject</a></li><li><a href="{$config{base_url}}/view/divisions">Browse by Division</a></li></ul>
 
</pre>
 
  
Reload the template:
+
This example lets visitors browse the journals items in your repository have been published in, and then volumes within each journal.
  
  bin/epadmin reload ARCHIVEID
+
  {
 +
        id=>"journal_volume",
 +
        fields=>"publication,volume",
 +
        order=>"-date/title",
 +
        hideempty => 1,
 +
},
  
'''Example 2 Add link to views page
+
[[Image:Browse_by_journal.png|border]]
  
Rather than link directly to each view, you may prefer to add a Browse option to the navigation bar which
+
[[Image:Browse_by_journal_volume.png|border]]
  
[[Image:Browse_by_navbar.png]]
 
  
===Advanced views===
 
  
====Multiple field views====
+
===Linking in your view===
  
Division->Author
+
You now need to add a link to your repository pages which takes visitors directly to your new view, or to the views page from where they can access all available views.
  
Journal->ISSN
+
[[Image:Browse_by_navbar.png]]
  
 
====Generating CVs etc====
 
====Generating CVs etc====
Line 141: Line 147:
 
===Views as collections===
 
===Views as collections===
  
discover related content
 
  
There are two ways in which visitors to your repository may discover relevant content - searching
+
===New options in EPrints 3.1===
 +
 
 +
====subfield no longer supported====
 +
 
 +
The subfield option is no longer supported in EPrints 3.1.
 +
 
 +
====new_column_at====
 +
 
 +
This is an array of integers representing the number of items in a view list before another column is added.  For example:
 +
 
 +
[ 10 ]
 +
 
 +
This would have one column of values until there were 11, then there would be 2 columns.
 +
 
 +
[ 10, 10 ]
 +
 
 +
This would have one column if there were ten or less values, two columns if there were between eleven and twenty (ten + ten) values, and three columns for all other cases.
 +
 
 +
[ 0, 0 ]
 +
 
 +
This would always have three columns.
 +
 
 +
Add one to the number of integers in the array and you get the maximum number of columns.  The value of each integer defines the point at which that column becomes full, and more values cause an 'overflow' into the next column.
 +
 
 +
====variations====
 +
 
 +
This controls the various ways in which a browse view can be subheaded.  It consists of a list of strings.  Each string is the name of a non-compound metadata field (or the keyword DEFAULT, for an unsubheaded list), optionally followed by a semi-colon and a comma separated list of options.  E.G:
 +
 
 +
variations => [
 +
  "creators_name;first_letter",
 +
  "type",
 +
  "DEFAULT"
 +
],
  
Visitors to your repository can take advantage
+
See [[views.pl]] for the list of options.

Latest revision as of 12:55, 14 October 2015


Browse views provide a way for visitors to your site to discover relevant content without a specific item in mind (for example, browsing all the content associated with a particular topic). Visitors arriving directly at the page for a specific item in the repository (for example, via a search engine) also use views you have defined to discover related content.

There are two default views in EPrints - By Year and By Subject. This guide describes how to add additional views to your repository. Instead with this link you can read a complete list of all options avaible for views.

The basics

The views for your repository are defined in the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Open this file and find the browse_views configuration setting:

$c->{browse_views} = [
       {
               id => "year",
               fields => "-date;res=year",
               ...
       },
       {
               id => "subjects",
               fields => "subjects",
               ...
       },
];

The views are defined using a special (Perl) syntax: the view definition consists of a pair of curly braces (note the comma after each closing brace) enclosing a list of property/value pairs (note the comma after each line).

The key part of the view definition is the fields property. This names the metadata field (or fields) that EPrints will use to construct the view. For example, for the By Year view, EPrints groups the records in the repository according to their date (note that the res=year suffix tells EPrints to only consider the year part), and constructs a Web page for each date listing the records. Similarly, the Browse by Subjscts view, groups the records according to the subjects they have been assigned to (a record may appear in more than one group!).

Both the Browse by Year and Browse by Subject views are constructed using the values of a single field (date and subjects respectively).

It is also possible to construct a view using the combined values of two or more fields (eg. group records by author and editor), or even using a sequence of two or more fields (eg. group records by journal title and then by volume number).

Worked example: browse by organisational structure

By default, EPrints has a divisions metadata field which allows authors to associate their deposits with the divisions (units, faculties, schools, departments, institutes, centres..) that were involved in producing their item (for example, the author's department, and the departments of any co-authors). This worked example allows visitors to browse the repository content by division.

Open the views configuration file:

/opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/views.pl

Add the following definition to the browse_views setting:

$c->{browse_views} = [
       {
               id => "year",
               ...
       },
       {
               id => "subjects",
               ...
       },
       {
               id => "divisions",
               fields => "divisions",
               order => "-date/title",
               hideempty => 1,
       },
];

Save the file and generate the new view pages (this will also re-generate any existing views defined in the views configuration file):

bin/generate_views ARCHIVEID --verbose

Open the view page in a Web browser:

http://your.repository.url/view/

The view page lists all the available views. You should see your new views on the list:

The view page lists available views

Fixing the undefined phrase warning The new view may appear on the views page with an undefined phrase warning (you may also notice a similar warning message when running generate_views):

["viewname_eprint_divisions" not defined]

Each view you create needs to be assigned a human-readable name, which EPrints will use on the view Web pages.

Edit the language-specific phrases file for view names:

/opt/eprints3/archives/ARCHIVEID/cfg/lang/en/phrases/views.xml

Add an appropriate phrase which describes the new view, for example:

<epp:phrase id="viewname_eprint_divisions">Division</epp:phrase>

Save the phrases file and regenerate the view pages:

bin/generate_views ARCHIVEID --verbose

Example view definitions

Browse by type (3.3.8)

Every deposit in EPrints has a type (article, book, thesis...). To allow visitors to browse your repository content by type, add the following definition to the browse_views setting:

{
   id=>"doctype", 
   menus => [ 
   { 
     fields => [ "type" ], 
   },], 
   order=>"-date",
},

Browse by author

Example views (combined fields)

Browse by author and editor

Example views (multiple fields)

Browse by journal title, then by volume

This example lets visitors browse the journals items in your repository have been published in, and then volumes within each journal.

{
       id=>"journal_volume",
       fields=>"publication,volume",
       order=>"-date/title",
       hideempty => 1,
},

Browse by journal.png

Browse by journal volume.png


Linking in your view

You now need to add a link to your repository pages which takes visitors directly to your new view, or to the views page from where they can access all available views.

Browse by navbar.png

Generating CVs etc

Linking items back to views

Views as collections

New options in EPrints 3.1

subfield no longer supported

The subfield option is no longer supported in EPrints 3.1.

new_column_at

This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 10 ]

This would have one column of values until there were 11, then there would be 2 columns.

[ 10, 10 ]

This would have one column if there were ten or less values, two columns if there were between eleven and twenty (ten + ten) values, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

Add one to the number of integers in the array and you get the maximum number of columns. The value of each integer defines the point at which that column becomes full, and more values cause an 'overflow' into the next column.

variations

This controls the various ways in which a browse view can be subheaded. It consists of a list of strings. Each string is the name of a non-compound metadata field (or the keyword DEFAULT, for an unsubheaded list), optionally followed by a semi-colon and a comma separated list of options. E.G:

variations => [
 "creators_name;first_letter",
 "type",
 "DEFAULT"
],

See views.pl for the list of options.