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