Difference between revisions of "Views.pl"

From EPrints Documentation
Jump to: navigation, search
(Option avaible for the views config)
(Option avaible for the views config)
Line 11: Line 11:
 
   ];
 
   ];
  
(be careful about commas and semicolons). The order of the view determine the order in which they appear in the http://repoid/view/ page.
+
(be careful about commas and semicolons). The order of the browse definitions determines the order in which these will appear in the http://repoid/view/ page.
  
 
Each browse definition is a collection of attributes, given as
 
Each browse definition is a collection of attributes, given as
  
     attribute_id => value,
+
     attribute1 => value1,
 +
    attribute2 => value2,
 +
    ...
  
(again, the ''value'' should end by a comma). The ''value'' can be a ''string'' enclosed by quotation marks (") or by apostrophes ('); an ''array'' which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ]; or a ''hash'' which is a list of attribute&endash;value pairs enclosed into curly brackets. Thus the browse view definition is an array of hashes.
+
(again, the ''value'' should end by a comma). The ''value'' can be  
 +
*''string'' enclosed by quotation marks (") or by apostrophes (');  
 +
*''array'' which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ]; or  
 +
*''hash'' which is a list of attribute&endash;value pairs enclosed into curly brackets.  
 +
Thus the browse views definition is an array of hashes.
  
 
===Basic attributes===
 
===Basic attributes===
Line 23: Line 29:
 
====id (mandatory)====
 
====id (mandatory)====
  
This is the ID by which you will refer to this view. For example, this is the value of the ''browse_link'' attribute in [[eprint_fields.pl]].
+
String, this is the ID by which you will refer to this view. For example, this is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:
 +
 
 +
    id => 'divisions',
  
 
====fields (deprecated)====
 
====fields (deprecated)====
Line 35: Line 43:
 
   nolink => 1,
 
   nolink => 1,
  
then this view won't appear in the outmost eprints.org/view/ browse directory.
+
then this view won't appear in the outmost http://repoid/view/ browse page.
  
 
====max_menu_age====
 
====max_menu_age====
  
Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds before, it is regenerated.
+
Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds ago, it is regenerated.
  
 
====max_list_age====
 
====max_list_age====
  
Defaults to 86400 (one day in seconds). If the list in this menu was generated more than than many seconds before, it is regenerated.
+
Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
  
 
====allow_null, new_column_at, hideempty, render_menu====
 
====allow_null, new_column_at, hideempty, render_menu====
  
These define the default values of the same attributes in all [[#menus|menus]]. I.e, if not defined otherwise, they take this as the default value.
+
These define the default values of the same attributes in all [[#menus|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view.
  
 
====order====
 
====order====

Revision as of 11:24, 13 July 2009

Option avaible for the views config

This link is an 'How to' about views with examples.

The general form of views definition is

 $c->{browse_views} = [
   { <first browse definition> },
   { <second browse definition> },
   ...
   { <last browse definition> },
 ];

(be careful about commas and semicolons). The order of the browse definitions determines the order in which these will appear in the http://repoid/view/ page.

Each browse definition is a collection of attributes, given as

   attribute1 => value1,
   attribute2 => value2,
   ...

(again, the value should end by a comma). The value can be

  • string enclosed by quotation marks (") or by apostrophes (');
  • array which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ]; or
  • hash which is a list of attribute&endash;value pairs enclosed into curly brackets.

Thus the browse views definition is an array of hashes.

Basic attributes

id (mandatory)

String, this is the ID by which you will refer to this view. For example, this is the value of the browse_link attribute in eprint_fields.pl. Example:

   id => 'divisions',

fields (deprecated)

This attribute describes the field(s) by which the view is built. It has been replaced by the more general menus attribute.

nolink

When this is set to 1 by adding

 nolink => 1,

then this view won't appear in the outmost http://repoid/view/ browse page.

max_menu_age

Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds ago, it is regenerated.

max_list_age

Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.

allow_null, new_column_at, hideempty, render_menu

These define the default values of the same attributes in all menus. I.e, if not defined otherwise there, they take this as the default value in this view.

order

menus

An array of menu descriptions (see below). Each menu is a refinement of the previous ones. In each menu, as minimum, you should give the fields which are used to define the menu. Thus a menus definition looks like

 menus => [
    { <first menu definition> },
    { <second menu definition which is the refinement of the first> },
    { <third level menu definition> },
 ],

If there is only one menu definition, then the browse will be flat, otherwise you'll get links to the next level.

Options in menus

fields

allow_null

If the fields value is undefined, the entry does not show up in the generated view. To allow these undefined values to be there as well, set

 allow_null => 1,

Be beware: the title of the undefined entries will be the ugly UNDEFINED. You can redefine this to something else in the system.xml file.

hideempty

If a category is empty, don't show it as an entry. Default value: show all entries, even if they contain no entries. Example:

   hideempty => 1,

Standard

heading_level

include

subheadings

Extra feature

citation

nocount

nohtml

noindex

nolink

New features

render_menu

The name of a config element which defines a function with an alternate way to render the menu page for a view. For an example, try looking in lib/defaultcfg/cfg.d/views_render_menu_example.pl

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

The following options are available:

reverse Reverses the order in which the groupings are shown. Default is the ordervalue for that field (usually alphanumeric). Useful for dates as you may want the highest values first.
filename Changes the filename of the view variation. The default is the name of the metadata field used, so if two variations use the same metadata field with different options, this is needed.
filename=different_filename
first_value If a field is multiple, only use the first value. Otherwise each item will appear once for each value.
first_initial If using a name, truncate the given name to the first initial. This will make items like "Les Carr" and "Leslie Carr" appear together. Note it will also make "John Smith" and "Jake Smith" appear together too, showing that you really never can win.
first_letter The same as 'truncate=1'
truncate Use the first X characters of a value to group by. truncate=4 may be useful for dates as it will group by the first four digits (the year) only.
truncate=4
tags Useful for fields like keywords where values may be separated by commas or semi-colons. The value is split on these two characters ( , and ; ) and a heading is created for each.
cloud Creates a tag cloud. Sets jump to 'plain', cloudmax to 200, cloudmin to 80 and no_separator, then resizes the jump-to links according to frequency of use.
cloudmax The % size of the largest tag in a tag cloud.
cloudmin The % size of the smallest tag in a tag cloud.
jump
 jump=plain

Turns of the 'jump to' text before the list of subheading navigation links.

no_seperator (sic) Turns of the separator between each subheading navigation link (by default a vertical bar symbol).
string Uses values 'as is'. No ordervalues, no phrases.
hideup (since 3.1.1) Defaults to "0". If set to "1" this hides the "up to parent" link (often you want to hide this on .include files)
render_fn Name of a function to render this groupings list of items. For an example, see views_render_items_example.pl