1/* Part of ClioPatria SeRQL and SPARQL server 2 3 Author: Jan Wielemaker 4 E-mail: J.Wielemaker@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 All rights reserved. 10 11 Redistribution and use in source and binary forms, with or without 12 modification, are permitted provided that the following conditions 13 are met: 14 15 1. Redistributions of source code must retain the above copyright 16 notice, this list of conditions and the following disclaimer. 17 18 2. Redistributions in binary form must reproduce the above copyright 19 notice, this list of conditions and the following disclaimer in 20 the documentation and/or other materials provided with the 21 distribution. 22 23 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 24 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 25 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 26 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 27 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 28 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 29 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 30 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 31 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 33 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34 POSSIBILITY OF SUCH DAMAGE. 35*/ 36 37:- module(cliopatria, []). 38 39/** <module> ClioPatria hooks 40 41This module declares the _hooks_ an application may define to extend or 42modify some of ClioPatria's behaviour. Hooks are =multifile= defined 43predicates that -typically- have no default definition. Code using the 44hook typically first calls the hook. If the hook succeeds the task is 45considered done. Otherwise some default action is performed. For 46example, a property myprefix:componentName can be added as a property 47that provides a label using this code: 48 49 == 50 :- use_module(cliopatria(hooks)). 51 52 rdf_label:label_property(myprefix:componentName). 53 == 54 55The example below adds an item to =Help= popup of ClioPatria: 56 57 == 58 :- use_module(cliopatria(hooks)). 59 :- use_module(library(http/http_dispatch)). 60 61 cliopatria:menu_item(help/about, 'About'). 62 63 :- http_handler(root(about), about, []). 64 65 about(Request) :- 66 <generate the about page> 67 == 68*/ 69 70:- multifile 71 menu_item/2, 72 menu_label/2, 73 menu_popup_order/2, 74 75 rdf_label:label_property/1, 76 bnode_label//1, % +Resource 77 display_link//2, % +RDFObject, +Options 78 resource_link/2, % +URI, -URL 79 80 list_resource//2, % +URI, +Options 81 82 user_preference_db/2, % ?Property, ?Value 83 user_preference_default/2, % ?Property, ?Value 84 85 page_body//1, % +Body 86 page_body//2, % +Style, +Body 87 server_address//0, 88 logo//0, 89 90 predicate_order/2, % +P, -Order 91 context_graph/2, % +R, -RDF 92 context_graph/3, % +R, -RDF, +Options 93 context_predicate/2, % +R, -Pred 94 node_label/4, % +R, +Lang, +MaxLen, -Label 95 node_shape/3, % +R, -Shape, +Options 96 bag_shape/3, % +Members, -Shape, +Options 97 edge_shape/3. % +P, -Shape, +Options 98 99 100 /******************************* 101 * THE MENU * 102 *******************************/ 103 104%! menu_item(?Item, ?Label) 105% 106% This hook adds an item to the ClioPatria menu. Item is a term of 107% the form [rank=]popup/item, where _popup_ denotes the name of 108% the popup menu and _item_ is a (new) item to be added to the 109% popup. The _item_ is the handler-identifier of the HTTP handler 110% that implements the item (see http_handler/3). Label is the 111% label displayed. _rank_ defines the position inside the popup. 112% The built-in items are numbered 100,200,... 113% 114% For example, if we want to add a new item to the *Repository* 115% menu after *|Load from library|* that crawls LOD data, we can 116% use the following code: 117% 118% == 119% :- use_module(cliopatria(hooks)). 120% :- use_module(library(http/http_dispatch)). 121% 122% :- handler(cliopatria('crawl_lod_form'), crawl_lod_form, []). 123% 124% cliopatria:menu_item(400=repository/crawl_lod_form, 'Crawl LOD'). 125% 126% crawl_lod_form(Request) :- 127% ... 128% == 129% 130% @see The menu_label/2 and menu_popup_order/2 hooks provide 131% further control over the menu. 132% @see cp_menu:menu_item/2 implements the default menu. 133 134%! menu_label(+Id, -Label) 135% 136% This hook allows for dynamic or redefined (e.g., multilingual) 137% labels. It is called both for popup-identifiers and 138% item-identifiers. 139 140%! menu_popup_order(+Id, -Location:integer) 141% 142% This hook controls the order of the popup-item of ClioPatria's 143% menu. 144 145 146 /******************************* 147 * LABELS * 148 *******************************/ 149 150%! rdf_label:label_property(?Property) 151% 152% True if the value of Property can be used to (non-uniquely) 153% describe an object to the user. This hook provides additional 154% facts to cp_label:label_property/1. 155 156%! bnode_label(+Resource)// 157% 158% HTML-write DCG rule that produces an HTML description for the 159% given RDF blank node. See cp_label:bnode_label//1. 160 161%! display_link(+RDFObject)// 162% 163% HTML-write DCG rule that produces an HTML description for the 164% given RDFObject (a resource or literal) with an appropriate 165% link. This predicate is called by the RDF browser to present RDF 166% triples. 167 168%! resource_link(+URI, -URL)// 169% 170% URL is the link created by rdf_link//1 for URI. The default 171% opens the ClioPatria `local view'. 172% 173% @see cpa_browse:list_resource/1 is the handler addressed by the 174% default link. 175% @see cp_label:resource_link/2 calls the hook. 176 177 178 /******************************* 179 * LOCAL VIEW * 180 *******************************/ 181 182%! list_resource(+URI, +Options)// 183% 184% This hook is called by cpa_browse:list_resource//2, which 185% display the `local view' page for a resource. This can be used 186% to create a different page for describing a resource and still 187% using overall infrastructure such as rdf_link//1. 188 189 190 /******************************* 191 * USER/SESSION PREFERENCES * 192 *******************************/ 193 194%! user_preference_db(?Property:atom, ?Value:rdf_object) is nondet. 195% 196% Query properties for the current user/session. This mechanism 197% allows code to access information about the user/session without 198% committing to a particular implementation. The predicate and 199% values are compatible with RDF to allow implementing the user 200% database in RDF, typically using the OpenID as subject. 201 202%! user_preference_default(?Property:atom, ?Value:rdf_object) is nondet. 203% 204% Provides defaults for the user_preference/2. 205% 206% @see user_preference_db/2 207 208 209 /******************************* 210 * SKINS * 211 *******************************/ 212 213%! page_body(+Body)// is semidet. 214%! page_body(+Style, +Body)// is semidet. 215% 216% Emit the body of the page. This can be used to provide a 217% different skin for ClioPatria. The Style argument is passed from 218% reply_html_page/3. The file skin(cliopatria) defines the overall 219% skin and first calls cliopatria:page_body//2, if this fails 220% cliopatria:page_body//1 and if this fails too it uses the 221% default page. 222 223%! server_address// 224% 225% HTML-write DCG rule that writes the address of the server. If 226% you want to maintain its normal position in the page layout, 227% this should create an element of class =address= using the class 228% =cliopatria=. 229 230%! logo// 231% 232% Logo placed left of the menu-bar. Must be an object that has 233% `float:left` style. 234 235 236 /******************************* 237 * RDF BROWSING * 238 *******************************/ 239 240%! predicate_order(+Pred, -Order) is semidet. 241% 242% Define the order in which predicates appear in the local view. 243% The Order is an integer. The system ordering is defined by 244% cpa_browse:p_order/2. Predicates that are not explicitly ordered 245% are placed at the end of the table an ordered alphabetically. 246% 247% Predicates that have order `0' are _deleted_ from the table. 248 249%! context_graph(+R, -RDF, +Options) is semidet. 250% 251% @deprecated Use context_graph/3. 252 253%! context_graph(+R, -RDF, +Options) is semidet. 254% 255% This hook redefines the context graph shown by the RDF browser 256% for the resource R. RDF is a list of rdf(S,P,O) triples that 257% describe the context. Typically only object-triples are used, 258% although that is not a requirement. 259% 260% @see This predicate hooks cpa_browse:context_graph/3. Please 261% visit the soure to learn about available building 262% blocks. 263 264%! context_predicate(+Subject, -Predicate) is nondet. 265% 266% True when rdf(Subject, Predicate, _) must be included in the 267% context graph for Subject. 268 269%! node_label(+URI, +Lang, +MaxLen, -Label) is semidet. 270% 271% Compute a label for URI in the given language, truncating the 272% label to MaxLen characters. 273 274%! node_shape(+URI, -Shape, +Options) is semidet. 275% 276% Compute the desired shape for a GraphViz node representing URI. 277% 278% @param URI is the resource for which to determine the shape 279% @param Shape is a list Name(Value) for parameters given to 280% GraphViz. 281% @param Options provides additional guidance. Currently it 282% may provide start(StartURI) to indicate the graph is a 283% context node for the resource StartURI. 284% @see http://www.graphviz.org/doc/info/shapes.html 285 286%! bag_shape(+Bag, -Shape, +Options) is semidet. 287% 288% Compute the desired properties for a table used to display a bag 289% of resources. Shape options include: 290% 291% - max(Max) 292% Only show the first Max members of the bag. Default is 5. 293% - shape(Shape) 294% Basic shape 295% - style(Style) 296% Style options 297% - max_label_length(Chars) 298% Truncate labels that have more then Chars characters. 299% 300% @param Bag is a list of member resources 301 302%! edge_shape(+Triple, -Shape, +Options) is semidet. 303% 304% Compute the desired attributes for a GraphViz edge representing 305% the predicate Triple. 306% 307% @param Triple is the triple for which to determine the shape 308% @param Shape is a list Name(Value) for parameters given to 309% GraphViz. 310% @param Options provides additional guidance. Currently it 311% may provide start(StartURI) to indicate the graph is a 312% context node for the resource StartURI.