View source with raw comments or as raw
   1/*  Part of ClioPatria SeRQL and SPARQL server
   2
   3    Author:        Jan Wielemaker
   4    E-mail:        J.Wielemaker@cs.vu.nl
   5    WWW:           http://www.swi-prolog.org
   6    Copyright (C): 2010, University of Amsterdam,
   7		   VU University Amsterdam
   8
   9    This program is free software; you can redistribute it and/or
  10    modify it under the terms of the GNU General Public License
  11    as published by the Free Software Foundation; either version 2
  12    of the License, or (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public
  20    License along with this library; if not, write to the Free Software
  21    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  22
  23    As a special exception, if you link this library with other files,
  24    compiled with a Free Software compiler, to produce an executable, this
  25    library does not by itself cause the resulting executable to be covered
  26    by the GNU General Public License. This exception does not however
  27    invalidate any other reasons why the executable file might be covered by
  28    the GNU General Public License.
  29*/
  30
  31:- module(cliopatria, []).
  32
  33/** <module> ClioPatria hooks
  34
  35This module declares the _hooks_ an application  may define to extend or
  36modify some of ClioPatria's  behaviour.   Hooks  are =multifile= defined
  37predicates that -typically- have no default   definition. Code using the
  38hook typically first calls the hook. If   the  hook succeeds the task is
  39considered  done.  Otherwise  some  default  action  is  performed.  For
  40example, a property myprefix:componentName can be   added  as a property
  41that provides a label using this code:
  42
  43    ==
  44    :- use_module(cliopatria(hooks)).
  45
  46    rdf_label:label_property(myprefix:componentName).
  47    ==
  48
  49The example below adds an item to =Help= popup of ClioPatria:
  50
  51    ==
  52    :- use_module(cliopatria(hooks)).
  53    :- use_module(library(http/http_dispatch)).
  54
  55    cliopatria:menu_item(help/about, 'About').
  56
  57    :- http_handler(root(about), about, []).
  58
  59    about(Request) :-
  60	<generate the about page>
  61    ==
  62*/
  63
  64:- multifile
  65	menu_item/2,
  66	menu_label/2,
  67	menu_popup_order/2,
  68
  69	rdf_label:label_property/1,
  70	bnode_label//1,			% +Resource
  71	display_link//2,		% +RDFObject, +Options
  72	resource_link/2,		% +URI, -URL
  73
  74	list_resource//2,		% +URI, +Options
  75
  76	user_preference_db/2,		% ?Property, ?Value
  77	user_preference_default/2,	% ?Property, ?Value
  78
  79	page_body//1,			% +Body
  80	page_body//2,			% +Style, +Body
  81	server_address//0,
  82	logo//0,
  83
  84	predicate_order/2,		% +P, -Order
  85	context_graph/2,		% +R, -RDF
  86	context_graph/3,		% +R, -RDF, +Options
  87	context_predicate/2,		% +R, -Pred
  88	node_shape/3,			% +R, -Shape, +Options
  89	bag_shape/3.			% +Members, -Shape, +Options
  90
  91
  92		 /*******************************
  93		 *	     THE MENU		*
  94		 *******************************/
  95
  96%%	menu_item(?Item, ?Label)
  97%
  98%	This hook adds an item to the ClioPatria menu. Item is a term of
  99%	the form [rank=]popup/item, where _popup_   denotes  the name of
 100%	the popup menu and _item_ is a  (new)   item  to be added to the
 101%	popup. The _item_ is the handler-identifier  of the HTTP handler
 102%	that implements the item  (see   http_handler/3).  Label  is the
 103%	label displayed. _rank_ defines the   position inside the popup.
 104%	The built-in items are numbered 100,200,...
 105%
 106%	For example, if we want to add   a  new item to the *Repository*
 107%	menu after *|Load from library|* that   crawls  LOD data, we can
 108%	use the following code:
 109%
 110%	==
 111%	:- use_module(cliopatria(hooks)).
 112%	:- use_module(library(http/http_dispatch)).
 113%
 114%	:- handler(cliopatria('crawl_lod_form'), crawl_lod_form, []).
 115%
 116%	cliopatria:menu_item(400=repository/crawl_lod_form, 'Crawl LOD').
 117%
 118%	crawl_lod_form(Request) :-
 119%		...
 120%	==
 121%
 122%	@see The menu_label/2 and menu_popup_order/2 hooks provide
 123%	further control over the menu.
 124%	@see cp_menu:menu_item/2 implements the default menu.
 125
 126%%	menu_label(+Id, -Label)
 127%
 128%	This hook allows for dynamic   or redefined (e.g., multilingual)
 129%	labels.  It  is   called   both    for   popup-identifiers   and
 130%	item-identifiers.
 131
 132%%	menu_popup_order(+Id, -Location:integer)
 133%
 134%	This hook controls the order of the popup-item of ClioPatria's
 135%	menu.
 136
 137
 138		 /*******************************
 139		 *		LABELS		*
 140		 *******************************/
 141
 142%%	rdf_label:label_property(?Property)
 143%
 144%	True if the value of  Property   can  be  used to (non-uniquely)
 145%	describe an object to the user.   This  hook provides additional
 146%	facts to cp_label:label_property/1.
 147
 148%%	bnode_label(+Resource)//
 149%
 150%	HTML-write DCG rule that produces an HTML description for the
 151%	given RDF blank node.  See cp_label:bnode_label//1.
 152
 153%%	display_link(+RDFObject)//
 154%
 155%	HTML-write DCG rule that produces an   HTML  description for the
 156%	given RDFObject (a resource  or   literal)  with  an appropriate
 157%	link. This predicate is called by the RDF browser to present RDF
 158%	triples.
 159
 160%%	resource_link(+URI, -URL)//
 161%
 162%	URL is the link created by rdf_link//1 for URI. The default
 163%	opens the ClioPatria `local view'.
 164%
 165%	@see	cpa_browse:list_resource/1 is the handler addressed by the
 166%		default link.
 167%	@see	cp_label:resource_link/2 calls the hook.
 168
 169
 170		 /*******************************
 171		 *	    LOCAL VIEW		*
 172		 *******************************/
 173
 174%%	list_resource(+URI, +Options)//
 175%
 176%	This  hook  is  called   by  cpa_browse:list_resource//2,  which
 177%	display the `local view' page for a   resource. This can be used
 178%	to create a different page for   describing a resource and still
 179%	using overall infrastructure such as rdf_link//1.
 180
 181
 182		 /*******************************
 183		 *   USER/SESSION PREFERENCES	*
 184		 *******************************/
 185
 186%%	user_preference_db(?Property:atom, ?Value:rdf_object) is nondet.
 187%
 188%	Query properties for the current   user/session.  This mechanism
 189%	allows code to access information about the user/session without
 190%	committing to a particular  implementation.   The  predicate and
 191%	values are compatible with RDF to   allow  implementing the user
 192%	database in RDF, typically using the OpenID as subject.
 193
 194%%	user_preference_default(?Property:atom, ?Value:rdf_object) is nondet.
 195%
 196%	Provides defaults for the user_preference/2.
 197%
 198%	@see user_preference_db/2
 199
 200
 201		 /*******************************
 202		 *	       SKINS		*
 203		 *******************************/
 204
 205%%	page_body(+Body)// is semidet.
 206%%	page_body(+Style, +Body)// is semidet.
 207%
 208%	Emit the body of  the  page.  This   can  be  used  to provide a
 209%	different skin for ClioPatria. The Style argument is passed from
 210%	reply_html_page/3. The file skin(cliopatria) defines the overall
 211%	skin and first calls  cliopatria:page_body//2,   if  this  fails
 212%	cliopatria:page_body//1 and if  this  fails   too  it  uses  the
 213%	default page.
 214
 215%%	server_address//
 216%
 217%	HTML-write DCG rule that writes the   address  of the server. If
 218%	you want to maintain its  normal   position  in the page layout,
 219%	this should create an element of class =address= using the class
 220%	=cliopatria=.
 221
 222%%	logo//
 223%
 224%	Logo placed left of the menu-bar.  Must   be  an object that has
 225%	`float:left` style.
 226
 227
 228		 /*******************************
 229		 *	    RDF BROWSING	*
 230		 *******************************/
 231
 232%%	predicate_order(+Pred, -Order) is semidet.
 233%
 234%	Define the order in which predicates appear in the local view.
 235%	The Order is an integer. The system ordering is defined by
 236%	cpa_browse:p_order/2. Predicates that are not explicitly ordered
 237%	are placed at the end of the table an ordered alphabetically.
 238%
 239%	Predicates that have order `0' are _deleted_ from the table.
 240
 241%%	context_graph(+R, -RDF, +Options) is semidet.
 242%
 243%	@deprecated Use context_graph/3.
 244
 245%%	context_graph(+R, -RDF, +Options) is semidet.
 246%
 247%	This hook redefines the context graph   shown by the RDF browser
 248%	for the resource R. RDF is  a   list  of rdf(S,P,O) triples that
 249%	describe the context. Typically only   object-triples  are used,
 250%	although that is not a requirement.
 251%
 252%	@see	This predicate hooks cpa_browse:context_graph/3.  Please
 253%		visit the soure to learn about available building
 254%		blocks.
 255
 256%%	context_predicate(+Subject, -Predicate) is nondet.
 257%
 258%	True when rdf(Subject, Predicate, _)  must   be  included in the
 259%	context graph for Subject.
 260
 261%%	node_shape(+URI, -Shape, +Options) is semidet.
 262%
 263%	Compute the desired shape for a GraphViz node representing URI.
 264%
 265%	@param URI is the resource for which to determine the shape
 266%	@param Shape is a list Name(Value) for parameters given to
 267%	       GraphViz.
 268%	@param Options provides additional guidance. Currently it
 269%	       may provide start(StartURI) to indicate the graph is a
 270%	       context node for the resource StartURI.
 271%	@see   http://www.graphviz.org/doc/info/shapes.html
 272
 273%%	node_shape(+Bag, -Shape, +Options) is semidet.
 274%
 275%	Compute the desired properties for a table used to display a bag
 276%	of resources.  Shape options include:
 277%
 278%	  - max(Max)
 279%	  Only show the first Max members of the bag.  Default is 5.
 280%	  - shape(Shape)
 281%	  Basic shape
 282%	  - style(Style)
 283%	  Style options
 284%	  - max_label_length(Chars)
 285%	  Truncate labels that have more then Chars characters.
 286%
 287%	@param Bag is a list of member resources