Difference between revisions of "Views.pl"

From EPrints Documentation
Jump to: navigation, search
(Options in ''menus'')
(Basic attributes)
Line 25: Line 25:
 
Thus the browse views definition is an array of hashes.
 
Thus the browse views definition is an array of hashes.
  
===Basic attributes===
+
==Basic==
  
 
{| border="1" cellpadding="4" cellspacing="0"
 
{| border="1" cellpadding="4" cellspacing="0"
Line 41: Line 41:
 
new_column_at
 
new_column_at
 
render_menu
 
render_menu
|These define the default values of the same attributes in all [[#Options in menus|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view. "Hideempty" is used when rendering the view list: namely, if set to 1 then the "UNDEFINED" value won't show up in the bottom list.
+
|These define the default values of the same attributes in all [[#Options in menus|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view. "Hideempty" is also used when rendering the [[#View list options|view]] list.
 
|- valign="top"
 
|- valign="top"
 
|menus
 
|menus
|An array of ''[[#Options in menus|menu descriptions]]''. Each ''menu'' is a refinement of the previous ones. In each menu, as minimum, you should give the field(s) which are used to define that level. Thus the ''menus'' definition looks like
+
|An array of ''[[#Options in menus|menu descriptions]]''. Each ''menu'' is a refinement of the previous ones, and last menu points to the [[#View list options|view list(s)]]. In each menu, as minimum, you should give the field(s) which are used to define entries at that level. The menus definition looks like
 
 
 
   menus => [
 
   menus => [
 
     { <first menu definition> },
 
     { <first menu definition> },
Line 51: Line 50:
 
     { <last level> },
 
     { <last level> },
 
   ],
 
   ],
 
+
You must have at least one menu level.
From the last level you will be directed to the ''view list''.
 
|- valign="top"
 
|order
 
|This defines how the items in the view list (at the lowest level) are ordered. Thr format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values vill be reverse sorted by 'bar'. More than 2 fiedls can be specified.
 
|-
 
|- valign="top"
 
|hideup
 
|Don't show the "up one level" link in the list page. You can set this attribute for the menus separately.
 
|- valign="top"
 
|variations
 
|An array of strings describing different rendering of the items at the lowest level (the ''list''). See [[#Variations|variations]].
 
 
|- valign="top"
 
|- valign="top"
 
|template
 
|template
Line 72: Line 60:
 
   nolink => 1,
 
   nolink => 1,
 
then this view won't appear in the outmost <nowiki>http://repoid/view/</nowiki> browse page.
 
then this view won't appear in the outmost <nowiki>http://repoid/view/</nowiki> browse page.
 +
|- valign="top"
 +
| 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.
 +
|}
 +
 +
 +
==View list options==
 +
There are options which determine how the last page in the view chain should look like.
 +
 +
{| border="1" cellpadding="4" cellspacing="0"
 +
|- valign="top"
 +
|order
 +
|This defines how the items in the view list (at the lowest level) are ordered. The format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values will be reverse sorted by 'bar'. More than 2 fields can be specified. Example:
 +
  order => "-date/title",
 +
|- valign="top"
 +
|hideup
 +
|Don't show the "up one level" link in the list page. You ''must'' set this attribute for each menu separately, it is not inherited.
 +
|- valign="top"
 +
|hideempty
 +
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
 +
|- valign="top"
 +
|nocount
 +
|If set, the "Number of items" line at the top of the page is omitted.
 +
|- valign="top"
 +
|notimestamp
 +
|If set, the "This list was generated on" line at the bottom of the list is omitted.
 +
|- valign="top"
 +
|variations
 +
|An array of strings describing different rendering of the items at the ''list''. For datails see [[#Variations|variations]]. Example:
 +
    variation => [ "creators_name;first_letter",
 +
        "type", "DEFAULT", ],
 
|- valign="top"
 
|- valign="top"
 
|layout
 
|layout
|Possible values are: orderedlist, unorderedlist, paragraph
+
|Possible values are  
 +
*paragraph (default)
 +
*orderedlist
 +
*unorderedlist
 +
Determines how items in the list (or sublist) is rendered. In the first case each item is a paragraph by itself. In the other cases items are rendered as an ordered (unordered) list.
 
|- valign="top"
 
|- valign="top"
 
|citation
 
|citation
|Default value: 'default'
+
|The citation style defined in archives/<REPOID>/cfg/citations/eprint/ which is used to render each item. Example:
|- valign="top"
+
  citation => 'screen',
| 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.
 
 
|- valign="top"
 
|- valign="top"
 
|max_list_age
 
|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.
 
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
 
 
|}
 
|}
  

Revision as of 12:14, 16 July 2009

Options 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 => value pairs enclosed into curly brackets.

Thus the browse views definition is an array of hashes.

Basic

id (mandatory) String, this is the ID by which you will refer to this view, and also the name of the top directory in http://yourrepo/view/. 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.
hideempty

allow_null new_column_at 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. "Hideempty" is also used when rendering the view list.
menus An array of menu descriptions. Each menu is a refinement of the previous ones, and last menu points to the view list(s). In each menu, as minimum, you should give the field(s) which are used to define entries at that level. The menus definition looks like
 menus => [
    { <first menu definition> },
    { <second level menu> },
    { <last level> },
 ],

You must have at least one menu level.

template Define an alternate template for all pages in this view. The template page should be a proper xml file in the repoid/cfg/lang/<langid>/templates/ directory. The best way is to copy the default.xml file and edit it according to taste.
 template => 'view_template',
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.


View list options

There are options which determine how the last page in the view chain should look like.

order This defines how the items in the view list (at the lowest level) are ordered. The format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values will be reverse sorted by 'bar'. More than 2 fields can be specified. Example:
 order => "-date/title",
hideup Don't show the "up one level" link in the list page. You must set this attribute for each menu separately, it is not inherited.
hideempty Do not list the empty (undefined) entry in the list. This property inherits to the menus.
nocount If set, the "Number of items" line at the top of the page is omitted.
notimestamp If set, the "This list was generated on" line at the bottom of the list is omitted.
variations An array of strings describing different rendering of the items at the list. For datails see variations. Example:
   variation => [ "creators_name;first_letter", 
       "type", "DEFAULT", ],
layout Possible values are
  • paragraph (default)
  • orderedlist
  • unorderedlist

Determines how items in the list (or sublist) is rendered. In the first case each item is a paragraph by itself. In the other cases items are rendered as an ordered (unordered) list.

citation The citation style defined in archives/<REPOID>/cfg/citations/eprint/ which is used to render each item. Example:
 citation => 'screen',
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.

Options in menus

fields An array of field identifiers. Items in all fields are merged together. For example, to define a list of those those who are either authors or editors or both, use the definition
   fields => [ "creators_id", "editors_id" ],

Even if there is a single field, you must use square brackets, such as

   fields => [ "subjects" ],
Important! All fields must have the same type - i.e. you cannot mix titles and authors, say.

You can also add extra rendering info to the field name, without the "render_" prefix. For example, to make a date have resolution year, you would write

   fields => [ "date;res=year" ],

or, ordering authors by their given names rather than by their family names:

   fields => [ "creators_name;order=gf" ],

You can add ";quiet" to the field name to force non-existing values to appear as empty space rather than the ugly "UNDEFINED" (see the allow_null property below). You can find the available rendering properties of different fields in the Metadata section.

allow_null The undefined value among the possible values of the fields does not show up in the generated view. To allow the undefined value to appear as well, set
 allow_null => 1,

Beware: the title of the undefined entries will be the ugly UNDEFINED. You might consider to use the ";quiet" rendering option for field names.

hideempty If a category is empty, don't show it as an entry. Default value: show all entries, even if they contain no entries. Used only in menus, not at the lower level (list).

Example:

   hideempty => 1,
reverse_order If set, then the ordering of items in this menu is reversed. Example:
   reverse_order => 1,
mode Possible values: sections and default (default). When defined as sections then grouping can be defined by the following data:
  • grouping_function (group by first character if not defined)
  • group_sorting_function (how to sort members of a group)
  • group_range_function
  • open_first_section the front page should show the first section

See below.

hideup When set to 1, don't show the "move one level up" link at the top of the page.
render_menu The configuration parameter which renders this menu. This should be a string, and also you should define a routine with the same name. For example if you write
   render_menu => 'render_view_menu_3col_boxes',

then this menu will be rendered by the routine which is defined in views_render_menu_example.pl as

 $c->{render_view_menu_3col_boxes} = sub
 {
      ...
 }

See there for hints how to tweak your own routine.

new_column_at Used in menus (not lists) and in default mode. This is an array of integers representing the number of items in a view list before another column is added. For example:
[ 11 ]

The menu is rendered as a single column data if there are less than 11 entries, then there would be 2 columns.

[ 11, 21 ]

This would have one column if there were ten or less values, two columns if there are twenty or less, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

[ 2, 3 ]

This would have one column for a single data, two columns for two, and three columns for three or more data.

Add one to the number of integers in the array and you get the maximum number of columns. The entries are evenly distributed in the columns.

Variations

Variations is an array of string, such as

[ "creators_name;first_letter",
  "type",
  "DEFAULT",
]

The variation "DEFAULT" is the default one, it is always a good practice to include it in the list. If no variation is given, "DEFAULT" is used.

A variation consists of a field name, followed by zero, one or more options separated by commas. An option is either a single attribute, or an attribute, an equal sign, and the value of the attribute. Thus

   "creators_name;truncate=4,hideup"

sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

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

Phrases

Standard

heading_level

include

subheadings

Extra feature

nocount

nohtml

noindex