Tutorial.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package MyLibrary;
2  
3 =head1 NAME
4  
5 MyLibrary tutorial - an overview of how to use the MyLibrary modules
6  
7 =head1 DESCRIPTION
8  
9 This tutorial gives the reader an overview of how to use the MyLibrary modules. It is only an introduction. The reader is expected to understand the principles of basic object-oriented Perl programming.
10  
11 By the end of the tutorial the reader should be able to: create sets of facets, create sets of terms, create sets of librarians, create sets of location types, create sets of resources, classify librarians and resources with terms, work with sets of resources assoicated with particular sets of terms, output the resources' titles, descriptions and locations, create a freetext index of MyLibrary content, harvest OAI repositories and cache the content in a MyLibrary database.
12  
13  
14 =head2 Initialization
15  
16 To include MyLibrary into your scripts you "use" it:
17  
18 # include the whole of MyLibrary
19 use MyLibrary::Core;
20  
21 This will enable all the necessary modules. You can use selected modules if you so desire. This will save you a bit of RAM and compile time, but not a whole lot. For example:
22  
23 # include just selected modules
24 use MyLibrary::Facet;
25 use MyLibrary::Term;
26  
27 Make your life easy. Just include the whole of MyLibrary. See MyLibrary::Core's pod for more information.
28  
29  
30 =head2 Configuration
31  
32 Each installation of the MyLibrary modules is configured, by default, to work against at least one MyLibrary instance. This instance was created during the make process. When you include MyLibrary::Core, the default instance will be read from and written to.
33  
34 If you want to read and write to a different instance of MyLibrary, then you will need to use the MyLibrary::Config methods to specify the database options for that instance.
35  
36  
37 =head2 Facets
38  
39 One of the first things you will want to do with any MyLibrary instance is create a set of facets.
40  
41 Facets are a set of broad classification headings. Most instances of MyLibrary will contain some sort of Subjects facet to denote the "aboutness" of items. Other possible facets include Formats or Audiences. Formats could denote the physical manifestations of information resources. Audiences might denote who are the intended users of information resources.
42  
43 Here are a number of ways to create and manipulate facet objects:
44  
45 # create a facet object
46 $facet = MyLibrary::Facet->new;
47
48 # set the facet's name and note
49 $facet->facet_name('Subjects');
50 $facet->facet_note('The "aboutness" of items');
51
52 # save the facet to the database
53 $code = $facet->commit;
54 if ($code ne 1) { die 'commit failed' }
55
56 # get the facet's id; think "database key"
57 $id = $facet->facet_id;
58
59 # get the facet's name and note
60 $name = $facet->facet_name;
61 $note = $facet->facet_note;
62
63 # get a specific facet based on an id
64 $facet = MyLibrary::Facet->new(id => 1);
65
66 Given the methods outlined above, you could use the following code to create, save, retrieve, and then display a facet:
67  
68 # configure
69 $name = 'Formats';
70 $note = 'The physical manifestation of resources';
71
72 # create, save, retrieve, and display
73 $facet = MyLibrary::Facet->new;
74 $facet->facet_name($name);
75 $facet->facet_note($note);
76
77 # save
78 $facet->commit;
79 $id = $facet->facet_id;
80
81 # retrieve
82 $facet = MyLibrary::Facet->new(id => $id);
83
84 # display
85 print ' ID: ' . $facet->facet_id . "\n";
86 print 'Name: ' . $facet->facet_name . "\n";
87 print 'Note: ' . $facet->facet_note . "\n";
88
89 You will often want to get a list of all the facets in your system in order to facilitate browsable interfaces to your collection of resources. The get_facets method is used for this purpose. Since get_facets returns an array of objects, you can now loop through the array and process each item. This is how you might display them:
90  
91  
92 # create a list of all the facets in the system
93 @facets = MyLibrary::Facet->get_facets;
94
95 print "ID\tName\t(Note)\n";
96 foreach $f (@facets) {
97  
98 print $f->facet_id . "\t" .
99 $f->facet_name . "\t(" .
100 $f->facet_note . ")\n"
101
102 }
103
104 Read the scripts named manage-facets.pl and subroutines.pl to see an example of how to manage sets of facets from a terminal-based interface. For more information read the pod of MyLibrary::Facets.
105  
106  
107 =head2 Terms
108  
109 Terms are a set of narrower classification headings, and each term is associated with one and only one facet -- its parent. Terms are expected to be the controlled vocabulary of your MyLibrary implementation, and consequently they are expected to be assigned to one or more information resources. Terms might include Astronomy, Music, or Mathematics, and these terms may have a parent facet named Subjects. Other terms might be Book, Journal, or Image, and these terms might be associated with a facet called Formats. Still other examples include Catalog, Dictionary, or Encyclopedia, and could associated with a facet named Research Tools.
110  
111 The methods of MyLibrary term objects are very similar to the methods of facet objects:
112  
113 # create a term object
114 $term = MyLibrary::Term->new;
115
116 # set the term's name and note
117 $term->term_name('Dictionary');
118 $term->term_note('A list of word definitions');
119
120 # create a facet named Research Tools
121 $facet = MyLibrary::Facet->new;
122 $facet->facet_name('Research Tools');
123 $facet->facet_note('Traditional library objects like dictionaries.');
124 $facet->commit;
125
126 # associate (join) this term to that facet
127 $term->facet_id($facet->facet_id);
128
129 # save the term to the database
130 $code = $term->commit;
131 if ($code ne 1) { die 'commit failed' }
132
133 # get the term's id; think "database key"
134 $id = $term->term_id;
135
136 # get the term's name and note
137 $name = $term->term_name;
138 $note = $term->term_note;
139
140 # get a specific term based on its id
141 $term = MyLibrary::Term->new(id => 1);
142  
143 Given the methods outlined above, you could use the following code to create, save, retrieve, and then display relevant term data:
144  
145 # configure
146 $term_name = 'Sophomores';
147 $term_note = 'Students in the second year of college';
148 $facet_name = 'Audiences';
149 $facet_note = 'People who use your services';
150
151 # create a term
152 $term = MyLibrary::Term->new;
153 $term->term_name($term_name);
154 $term->term_note($term_note);
155  
156 # create a facet
157 $facet = MyLibrary::Facet->new;
158 $facet->facet_name($facet_name);
159 $facet->facet_note($facet_note);
160 $facet->commit;
161  
162 # join and save
163 $term->facet_id($facet->facet_id);
164 $term->commit;
165
166 # get and display
167 $id = $term->term_id;
168 $term = MyLibrary::Term->new(id => $id);
169 $facet = MyLibrary::Facet->new(id => $term->facet_id);
170 print ' ID: ' . $term->term_id . "\n";
171 print ' Name: ' . $term->term_name . "\n";
172 print ' Note: ' . $term->term_note . "\n";
173 print 'Parent: ' . $facet->facet_name . "\n";
174  
175 Like the facets, you will often want to get a list of all the terms in your system in order to facilitate some sort of browse function. The get_terms method is used for this purpose:
176  
177 # get all the terms
178 @terms = MyLibrary::Term->get_terms;
179 foreach $term (@terms) { print 'Term: ' . $term->term_name . "\n" }
180  
181 Creating a list of sorted terms involves creating a list of term ids and calling the sort method denoting the sorting field, usually name:
182  
183 # get all terms
184 @terms = MyLibrary::Term->get_terms;
185  
186 # print
187 foreach $t (@terms) { print 'Term: ' . $t->term_name . "\n" }
188
189 # create a list of term ids
190 foreach $t (@terms) { push @term_ids, $t->term_id }
191
192 # get a sorted list of term id
193 @terms = MyLibrary::Term->sort(term_ids => [@term_ids],
194 type => 'name');
195  
196 # print, again
197 foreach $t (@terms) {
198
199 $term = MyLibrary::Term->new(id => $t);
200 print 'Term: ' . $term->term_name . "\n";
201
202 }
203
204 After terms have been assigned to MyLibrary resource objects a number of other useful term methods present themselves, but they are outlined in a later section named "Terms and resources revisited".
205  
206 Read the scripts named manage-terms.pl and subroutines.pl to see how you can manage sets of terms from a terminal-based interface. For more detail read the MyLibrary::Term pod.
207  
208  
209 =head2 Librarians
210  
211 Question: What do libraries have that Yahoo and Google don't have? Answer: Librarians -- people who are willing and able to address the information needs of others. That is why librarian objects are a part of MyLibrary.
212  
213 Think of librarian objects as information resources with the characteristics of people: name, address, telephone number, and URL of home page. In libraries librarians usually have subject specialties, and that is why it is possible to "catalog" librarians with facet/term combinations.
214  
215 The setting and getting of MyLibrary librarian objects works like this:
216  
217 # create a librarian
218 $librarian = MyLibrary::Librarian->new;
219
220 # give the librarian characteristics
221 $librarian->name('Fred Kilgour');
222 $librarian->email('kilgour@oclc.org');
223 $librarian->telephone('1 (800) 555-1212');
224 $librarian->url('http://oclc.org/~kilgour/');
225
226 # create an astronomy term as a child of the subjecs facet
227 $term = MyLibrary::Term->new;
228 $term->term_name('Astronomy');
229 $term->term_note('Studying the stars');
230 $facet = MyLibrary::Facet->new(name => 'Subjects');
231 $term->facet_id($facet->facet_id);
232 $term->commit;
233
234 # associate (join) the librarian with astronomy
235 $librarian->term_ids(new => [$term->term_id]);
236
237 # save the librarian
238 $librarian->commit;
239
240 # get the librarian
241 $id = $librarian->id;
242 $librarian = MyLibrary::Librarian->new(id => $id);
243
244 # display basic information about the librarian
245 print ' ID: ', $librarian->id, "\n";
246 print ' Name: ', $librarian->name, "\n";
247 print ' Email: ', $librarian->email, "\n";
248 print 'Telephone: ', $librarian->telephone, "\n";
249 print 'Home page: ', $librarian->url, "\n";
250
251 # display each of their associated subject areas
252 @term_ids = $librarian->term_ids;
253 foreach $id (@term_ids) {
254
255 $term = MyLibrary::Term->new(id => $id);
256 print ' Term: ', $term->term_name, "\n";
257
258 }
259  
260 Just like everything else, you might want to pull all of the librarians out of the system. The class method get_librarians is used for this purpose. It returns an array of librarian objects:
261  
262 # get all librarians
263 @librarians = MyLibrary::Librarian->get_librarians;
264
265 # print each librarian's name and email address
266 foreach $l (@librarians) { print $l->name . ' <' . $l->email . ">\n" }
267  
268 Question: Who are you going to call? Answer: The Librarian. By creating a set of facet/term combinations and associating them with information resources you can effectively group like things together. By associating the same facet/term combinations to librarians you can begin to make connections between information resources and librarians. Thus, when displaying lists of information resources, consider adding the associated librarian's name and contact information to the list.
269  
270 For more detail regarding librarian objects read the MyLibrary::Librarian pod.
271  
272  
273 =head2 Location types
274  
275 The world of information resources is made up of many different types. For example there are books, journals, and websites. To complicate matters, things like the same books or journals can be manifested in physical or digital form. Heck, the book or journal could even exist in a number of physical forms such as a codex or microfiche or maybe even a film. Because of these things a single information resource may have many different locations and each of these locations may be of different types: call numbers, URL's, buildings, etc. Because all information resources have some sort of location will need to create at least one location type in your MyLibrary implementation.
276  
277 Location types are just labels for different types of locations. For example, almost all MyLibrary implementations will have a location type such as Internet Resource, or URL. If the information resources in your MyLibrary implementation includes books -- physical, every-day books -- then another location type for your implementation might be Call Numbers. Suppose you have an electronic journal and one URL associated with the journal is a pointer to the content and another URL points to a help file. In this case you might want to have an additional location type such as Help Location.
278  
279 Here are an example of how you might implement a simple Internet resource location type:
280  
281 # create a location type
282 $location_type = MyLibrary::Resource::Location::Type->new;
283
284 # give it characteristics
285 $location_type->name('URL');
286 $location_type->description('A type of Internet resource');
287
288 # save it and get its id
289 $location_type->commit;
290 $id = $location_type->location_type_id;
291
292 # get a location by an id and display its data
293 $location_type = MyLibrary::Resource::Location::Type->new(id => $id);
294 print ' ID: ' . $location_type->location_type_id . "\n";
295 print ' Type: ' . $location_type->name . "\n";
296 print ' Note: ' . $location_type->description . "\n";
297  
298 Like most of the other modules, MyLibrary::Resource::Location::Type provide a class method for getting everything. In this case it is all_types, and it returns an array of location type ids:
299  
300 # get all location types
301 @location_types = MyLibrary::Resource::Location::Type->all_types;
302
303 # display them
304 foreach $l (@location_types) {
305
306 $location = MyLibrary::Resource::Location::Type->new(id => $l);
307 print 'Type: ' . $location->name . "\n";
308
309 }
310  
311 You can also create a location type object by calling it by name, but the name must exist in the underlying database. To do this you supply the name parameter to the new method:
312  
313 # get the location type object named URL
314 $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
315
316 # print
317 print ' Location type ID: ' . $location_type->location_type_id . "\n";
318 print 'Location type name: ' . $location_type->name . "\n";
319 print 'Location type note: ' . $location_type->description . "\n";
320
321 Because information resources are manifested in many ways, and since each of these ways are usually associated with different types of "addresses" (such as URLs or call numbes) MyLibrary provides as means of creating and listing such types.
322  
323 See the terminal-based program called location-types.pl as well as the pod for MyLibrary::Resource::Location::Type for more detail.
324  
325  
326 =head2 Resources
327  
328 Now the fun really begins.
329  
330 With the exception of the librarians, all of the previous sections essentially described how to create sets of controlled vocabularies. Facets. Terms. Location types. You are now ready to create lists of information resources, describe them, classify them, and save them to the underlying database. Once you have built your collection you are expected to write reports against it implementing various services such as: browse, search, What's New?, Find More Like This One, most popular, most useful, export subsets to a file, send subsets as email, create RSS feeds, etc. In today's world of changing user expectations it is not only about collections. It is more about the effective combination of collections and services.
331  
332 MyLibrary resource objects include methods for setting and getting the objects' characteristics, and these characteristics are a superset of the basic fifteen Dublin Core elements. There is an implicit one-to-one relationship between the basic Dublin Core element names and many of the MyLibrary resource object methods/objects, listed below:
333  
334 1. contributor --> MyLibrary::Resource->contributor
335 2. coverage --> MyLibrary::Resource->coverage
336 3. creator --> MyLibrary::Resource->creator
337 4. date --> MyLibrary::Resource->date
338 5. description --> MyLibrary::Resource->note
339 6. format --> MyLibrary::Resource->format
340 7. identifier --> MyLibrary::Resource::Location
341 8. language --> MyLibrary::Resource->language
342 9. publisher --> MyLibrary::Resource->publisher
343 10. relation --> MyLibrary::Resource->relation
344 11. rights --> MyLibrary::Resource->rights
345 12. source --> MyLibrary::Resource->source
346 13. subject --> MyLibrary::Resource->subject
347 14. title --> MyLibrary::Resource->name
348 15. type --> MyLibrary::Resource->type
349  
350 This mapping makes it relatively easy to store Dublin Core-based descriptions of information resources into a MyLibrary implementation. The items described in OAI-PMH data repositories come immediately to mind.
351  
352 As a simple example of setting and getting values of MyLibrary resource objects, let's set and get a link to a fictional electronic version of The Adventures of Huckleberry Finn:
353  
354 # create a resource object
355 $resource = MyLibrary::Resource->new;
356
357 # describe it
358 $resource->creator('Mark Twain');
359 $resource->format('ebook');
360 $resource->language('en');
361 $resource->name('The Adventures of Huckleberry Finn');
362 $resource->note('This is a coming of age story.');
363 $resource->subject('young adult reading');
364 $resource->type('text/html');
365
366 # give it a URL
367 $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
368 $resource->add_location(location => 'http://library.org/finn.html',
369 location_type => $location_type->location_type_id);
370  
371 # save it
372 $resource->commit;
373  
374 # get it
375 $id = $resource->id;
376 $resource = MyLibrary::Resource->new(id => $id);
377
378 # output the data
379 print ' Author: ' . $resource->creator . "\n";
380 print ' Format: ' . $resource->format . "\n";
381 print ' Language: ' . $resource->language . "\n";
382 print ' Title: ' . $resource->name . "\n";
383 print ' Description: ' . $resource->note . "\n";
384 print ' Subject: ' . $resource->subject . "\n";
385 print ' MIME type: ' . $resource->type . "\n";
386  
387 # get the url; assume there is only one
388 @locations = $resource->resource_locations;
389 print ' URL: ' . $locations[0]->location . "\n";
390  
391 With the exception of the location attributes, this should be pretty straight-forward. (Remember, information resources can have more than one location and more than one location type. This is why setting and getting the location of resource objects is not as simple as the other attributes.)
392  
393 While the procedure outlined above is functional, it is not necessarily complete. It does not take advantage of your facet/term combinations. Let's assume you have a facet called Subjects. Let's also assume you have the terms American Literature and Young Adult Reading assigned to the Subjects facet. Given this you can use the related_terms method to classify a resource with these terms. Very, very important! To get the terms back out you again use the related_terms method. It returns an array of term ids (keys):
394  
395 # get the facet id for subjects
396 $facet = MyLibrary::Facet->new(name => 'Subjects');
397 $facet_id = $facet->facet_id;
398
399 # create the subject term amerian literature
400 $term = MyLibrary::Term->new;
401 $term->term_name('American Literature');
402 $term->term_note('Writings of the New World');
403 $term->facet_id($facet_id);
404 $term->commit;
405 $american_literature = $term->term_id;
406
407 # create the subject term young adult reading
408 $term = MyLibrary::Term->new;
409 $term->term_name('Young Adult Reading');
410 $term->term_note('Literature for the middle schoolers');
411 $term->facet_id($facet_id);
412 $term->commit;
413 $young_reading = $term->term_id;
414
415 # get huck finn and assume there is only one matching record
416 @resources = MyLibrary::Resource->new(
417 name => 'The Adventures of Huckleberry Finn');
418 $resource = $resources[0];
419 $resource->related_terms(new => [$american_literature, $young_reading]);
420 $resource->commit;
421  
422 # output the data
423 print ' Author: ' . $resource->creator . "\n";
424 print ' Format: ' . $resource->format . "\n";
425 print ' Language: ' . $resource->language . "\n";
426 print ' Title: ' . $resource->name . "\n";
427 print ' Description: ' . $resource->note . "\n";
428 print ' Subject: ' . $resource->subject . "\n";
429 print ' MIME type: ' . $resource->type . "\n";
430  
431 # get the url; assume there is only one
432 @locations = $resource->resource_locations;
433 print ' URL: ' . $locations[0]->location . "\n";
434  
435 # get the related terms
436 @related_terms = $resource->related_terms;
437 foreach $rt (@related_terms) {
438
439 # print the term name
440 $term = MyLibrary::Term->new(id => $rt);
441 print ' Term : ' . $term->term_name . "\n";
442
443 }
444
445 Read manage-resources.pl, subroutines.pl to learn how to implement these ideas in a terminal-based environment. See the pod of MyLibrary::Resource for more detail because there are many more methods to be found there.
446  
447 A Zen Master once said, "Collections without services are useless, and services without collections are empty." Use MyLibrary to create a collection of information resources, and then use MyLibrary to provide services against the collection. Both are necessary in order to meet the expectations of today's users of libraries.
448  
449  
450 =head2 Terms and resources revisited
451  
452 Once you have created sets of MyLibrary resources and associated them with sets of MyLibrary terms you can exploit a couple more term methods to query your MyLibrary database.
453  
454 You can use the MyLibrary::Term class method called related_resources to create a list of resources associated with a term. For example, suppose you have a term named Astronomy, then you could use the following code to list the names and descriptions of all those resources:
455  
456 # require the necessary modules
457 use MyLibrary::Term;
458 use MyLibrary::Resource;
459  
460 # get the id for the astronomy term, assume there is only one
461 @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
462 $term = MyLibrary::Term->new(id => @terms[0]->term_id);
463 $astronomy = $term->term_id;
464  
465 # create astronomy resources, #1 of 3
466 $resource = MyLibrary::Resource->new;
467 $resource->name('Stars amoung us');
468 $resource->note('No, not movie stars');
469 $resource->related_terms(new => [$astronomy]);
470 $resource->commit;
471  
472 # resource #2 of 3
473 $resource = MyLibrary::Resource->new;
474 $resource->name('Guiding lights');
475 $resource->note('Soap operas and beyond');
476 $resource->related_terms(new => [$astronomy]);
477 $resource->commit;
478  
479 # resource #3 of 3
480 $resource = MyLibrary::Resource->new;
481 $resource->name('My Guide the the Galaxy');
482 $resource->note('As if the Hitchhikers was not good enough');
483 $resource->related_terms(new => [$astronomy]);
484 $resource->commit;
485  
486 # get all astronomy resources through the term
487 $term = MyLibrary::Term->new(id => $astronomy);
488 @resource_ids = $term->related_resources;
489
490 # display information about the resources
491 foreach $id (@resource_ids) {
492
493 $resource = MyLibrary::Resource->new(id => $id);
494 print ' Name: ' . $resource->name . "\n";
495 print ' Note: ' . $resource->note . "\n\n";
496
497 }
498  
499 The suggested_resources method allows you to set and get lists of resource ids determined to be particularly useful. Think recommendations. For example, suppose there is a resource called Most Cool Astronomy Site. Suppose also it is determined that this particular site lives up to its name and when displaying lists of astronomy resources you would like to highlight this one in particular. To do this you would first use the suggested_resources method set this value:
500  
501 # get the id for astronomy; assume there is only one astronomy-like term
502 @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
503 $term = MyLibrary::Term->new(id => @terms[0]->term_id);
504 $astronomy = $term->term_id;
505  
506 # create an astronomy resource
507 $resource = MyLibrary::Resource->new;
508 $resource->name('Most Cool Astronomy Site');
509 $resource->related_terms(new => [$astronomy]);
510
511 # save and get its id (key)
512 $resource->commit;
513 $id = $resource->id;
514
515 # get the astronomy term
516 $term = MyLibrary::Term->new(id => $astronomy);
517
518 # denote our resource as a suggested item for astronomy, and save
519 $term->suggested_resources(new => [$id]);
520 $term->commit;
521  
522 You can then list all the resources associated with a term and then specify which ones are recommended:
523  
524 # get the id for astronomy; assume there is only one astronomy-like term
525 @terms = MyLibrary::Term->get_terms(field => 'name', value => 'Astronomy');
526 $term = MyLibrary::Term->new(id => @terms[0]->term_id);
527
528 # get all astronomy resource ids and suggestion ids
529 @resources = $term->related_resources(sort => 'name');
530 @suggestions = $term->suggested_resources;
531  
532 # process each resource
533 foreach $r (@resources) {
534
535 # get the resource and print its name
536 $resource = MyLibrary::Resource->new(id => $r);
537 print ' Name: ' . $resource->name;
538
539 # loop through each suggestion
540 foreach $s (@suggestions) {
541
542 # compare suggestion and resource ids
543 if ($s == $r) {
544
545 # specify this as suggested resource
546 print ' (suggested)';
547 last;
548
549 }
550
551 }
552
553 print "\n";
554
555 }
556  
557 You will often want work with entire sets or subsets of resources from your MyLibrary implementation, and the get_resources method is used for this purpose. Once you get the set of resources you are expected to loop through them and extract the ones you really need. Here is a simple way to get all the resources as objects and print their names:
558  
559 # get all resources and display
560 @resources = MyLibrary::Resource->get_resources;
561 foreach $resource (@resources) { print $resource->name . "\n" }
562  
563 You can do the same thing, but return a sorted list
564  
565 # get a sorted list, by name, of resources
566 @resources = MyLibrary::Resource->get_resources(sort => 'name');
567 foreach $resource (@resources) { print $resource->name . "\n" }
568
569 Besides the basic Dublin Core elements, MyLibrary allows you to assign additional attributes to resources. The first of note is foreign key through the fkey method. This is intended to store things like OCLC numbers, catalog record numbers, or OAI identifiers in MyLibrary resource objects. By combining the fkey values with things like URL it is often possible to link to back to some other list of information resources. You set and get fkey values just like most of the other attributes:
570  
571 # create a resource
572 $resource = MyLibrary::Resource->new;
573
574 # set the name and fkey value
575 $resource->name('Tom Sawyer Rides Again');
576 $resource->fkey('123457');
577 $resource->commit;
578
579 # print it
580 print ' Foreign key: ' . $resource->fkey . "\n";
581
582 The lcd ("lowest common denominator") method is intended to denote information resources that are useful to anybody, not restricted to any MyLibrary term. For example, most librarians will believe the catalog is a tool useful for everybody for every discipline. A general encyclopedia and dictionary are other examples. Denote a resource as a "lowest common denominator" resource like this:
583  
584 # create and denote a resource as an "lcd" resource
585 $resource = MyLibrary::Resource->new;
586 $resource->name('Library catalog');
587 $resource->lcd(1);
588 $resource->commit;
589  
590 To get a list of all the resource objects denoted as lowest common denominator resources, use the class method lcd_resources:
591  
592 # get all "lcd" resources and display
593 @lcd_resources = MyLibrary::Resource->lcd_resources;
594 print "These resources are useful to everyone:\n";
595 foreach $r (@lcd_resources) { print "\t" . $r->name . "\n" }
596  
597 Through the qsearch_prefix, qsearch_suffix, and qsearch_redirct methods you are able to reverse engineer many Internet search engines. Take a simple Google search for the word cat, http://www.google.com/search?q=cat. This URL can be divided into at least three parts: 1) the root (http://www.google.com/), 2) a prefix (search?q=), 3) the query itself (cat), and 4) an optional suffix (null in this example).
598
599 You might use this code to create a resource for Google and add a search prefix to it:
600  
601 # create a resource describing Google
602 $resource = MyLibrary::Resource->new;
603 $resource->name('Google');
604 $resource->note('A very popular Internet index');
605
606 # get the location type of URL
607 $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
608 $type_id = $location_type->location_type_id;
609
610 # give the resource a URL
611 $resource->add_location(location => 'http://www.google.com/',
612 location_type => $type_id);
613
614 # add a quick search prefix and save
615 $resource->qsearch_prefix('search?q=');
616 $resource->commit;
617 $id = $resource->id;
618  
619 # begin echoing results
620 $resource = MyLibrary::Resource->new(id => $id);
621 print ' Title: ' . $resource->name . "\n";
622 print ' Note: ' . $resource->note . "\n";
623
624 # get the location; assume there is only one
625 @locations = $resource->resource_locations;
626
627 # echo more results
628 print ' URL: ' . $locations[0]->location . "\n";
629 print ' Prefix: ' . $resource->qsearch_prefix . "\n";
630
631 Now suppose you have some sort of HTML form that accepts text input. Using the qsearch_redirect method the input can be transformed into a URL to search the resource. Something like this:
632  
633 # get a query
634 $query = 'foobar';
635
636 # get the Google resource; assume there is only one
637 @resources = MyLibrary::Resource->new(name => 'Google');
638 $resource = $resources[0];
639
640 # get the location; assume there is only one
641 @locations = $resource->resource_locations;
642 $root_url = $locations[0]->location;
643
644 # build a URL to search
645 $url = $resource->qsearch_redirect(resource_id => $resource->id,
646 qsearch_arg => $query,
647 primary_location => $root_url);
648
649 # display in an HTML snippet
650 print "<a href='$url'>Click here</a> to search Google for '$query'.\n";
651  
652 Take this technique a step further. Suppose your MyLibrary implementation contains records from your library catalog. Suppose each MyLibrary resource record includes an fkey value pointing to the full record in the catalog. Suppose that you also have a MyLibrary record describing your catalog, and that record is complete with a qsearch_prefix and optional qsearch_suffix values. Using the qsearch_redirect method you could display brief records on a Web page and link back to the full record in your library catalog by using the fkey value as the qsearch_arg attribute.
653  
654  
655 =head2 Implementing search
656  
657 This section outlines a method for making the content of your MyLibrary implementation searchable.
658  
659 MyLibrary is essentially a relational database application. As such, searching the database requires queries be converted into SQL. By definition these SQL queries must specify what fields to search. Unfortunately people expect to perform freetext queries against sets of content, not necessarily fielded searches. Moreover, people increasingly expect relevancy ranked output as well as output sorted by this, that, and the other thing. For these reasons you are encouraged to use an intermediary indexing application to implement searchability instead of querying the database directly.
660  
661 Making your MyLibrary content searchable through an intermediate indexer uses this process:
662  
663 1. Write a report against MyLibrary.
664 2. Feed the report to the indexer.
665 3. Index the report.
666 4. Provide a Perl interface to search the index.
667 5. Search results are integers -- MyLibrary database keys.
668 6. Use the keys to get data from MyLibrary.
669 7. Reformat the data for display and return it to the user.
670  
671 Swish-e is a good indexer. Simple, fast, and it comes with a Perl API. This will be the indexer in this example, but something like Plucene would work just as well.
672  
673 The first step is to write a report against the MyLibrary database. Swish-e expects its input to look much like HTML. The following code outputs a very simple report containing only the titles and notes of every resource in a MyLibrary instance. The report is in a form swish-e expects:
674  
675 # require
676 use MyLibrary::Resource;
677
678 # first, get all of the resource ids
679 @resource_ids = MyLibrary::Resource->get_ids;
680
681 # process each id
682 foreach $resource_id (@resource_ids) {
683
684 # get a resource
685 $resource = MyLibrary::Resource->new(id => $resource_id);
686
687 # get its id, title, and note
688 $id = $resource->id;
689 $title = $resource->name;
690 $note = $resource->note;
691
692 # build the report
693 $output = '';
694 $output .= '<html>';
695 $output .= '<head>';
696 $output .= "<meta name='title' content='$title' />";
697 $output .= "<meta name='note' content='$note' />";
698 $output .= '</head>';
699 $output .= '<body>';
700 $output .= "<h1>$title</h1>";
701 $output .= "<p>$note</p>";
702 $output .= '</body>';
703 $output .= '</html>';
704
705 # output a swish-e header
706 print "Path-Name: $id\n";
707 print "Content-length: " . scalar(length $output) . "\n";
708 print "Document-Type: HTML*\n";
709 print "\n";
710
711 # output the report
712 print "$output";
713
714 }
715  
716 The next step is to build a configuration file telling swish-e what to look for in the report. In our case the configuration needs to know about the title and note, and the configuration could be this simple:
717  
718 # define fields to index and make searchable
719 MetaNames title note
720 PropertyNames title note
721
722 # define the location and name of the resulting index
723 IndexFile ./mylibrary.idx
724  
725 Finally, you need to run your report generator and pipe the output to swish-e specifying the configuration file. You can do this from the command line. Assuming your report generator is called mylibrary2swish.pl and your swish-e configuration file is called mylibrary2swish.cfg, then the command might look like this:
726  
727 ./mylibrary2swish.pl | swish-e -c ./mylibrary2swish.cfg -S prog -i stdin
728  
729 The result should be a two files, mylibrary.idx and mylibrary.idx.prop. These files are your swish-e index and you should be able to search them from the command line using the swish-e binary. Remember, you only included name and note in your output so only those fields will be searched. Also, queries will only return ids, not words.
730  
731 The next step is to provide the ability to search the index. As queries are accepted the swish-e Perl API is used to search the index. Queries return MyLibrary keys, and these keys are used to look up the values of resources:
732
733 # require the necessary modules
734 use MyLibrary::Resource;
735 use SWISH::API;
736
737 # define the location of your index
738 $INDEX = './mylibrary.idx';
739
740 # get the input
741 print "Enter a query. ";
742 chop (my $query = <STDIN>);
743
744 # search the index
745 $swish = SWISH::API->new($INDEX);
746 $results = $swish->Query($query);
747 $hits = $results->Hits;
748
749 # branch according to the number of hits
750 if ($hits) {
751
752 print "Your search ($query) returned $hits hit(s).\n\n";
753 $counter = 0;
754
755 # process each result
756 while ($result = $results->NextResult) {
757
758 # get the id (key)
759 $id = $result->Property("swishdocpath");
760
761 # get the resource, title, and note
762 $resource = MyLibrary::Resource->new(id => $id);
763 $title = $resource->name;
764 $note = $resource->note;
765
766 # increment the counter
767 $counter++;
768
769 # print the result
770 print "$counter. $title - $note\n\n";
771
772 }
773
774 }
775
776 else {
777
778 print "No hits. Sorry.\n";
779
780 }
781  
782 This section has outlined the most basic of search interfaces. Your reports sent to swish-e will want to be much more verbose.
783  
784 For more information see index-resources.pl, index-resources.cfg, resources2swish.pl, and search.pl that came with the distribution. These files implement a more full-featured, terminal-based program for search.
785  
786  
787 =head2 MyLibrary and OAI
788  
789 Because the MyLibrary database so closely resembles the basic Dublin Core elements, and because OAI requires data repositories to support Dublin Core, it is almost trivial to harvest the content of OAI repositories and cache it to a MyLibrary database.
790  
791 The following script does just that, and in a nutshell here is how it works:
792  
793 1. Define the repository to harvest.
794 2. Create a facet called Formats, if it doesn't exist.
795 3. Create a term called Images, if it doesn't exist.
796 4. Create a location type called URL, if it doesn't exist.
797 5. Harvest all the records from the repository.
798 6. Loop through each harvested record.
799 7. Create a MyLibrary resource object.
800 8. Fill the resource with attributes.
801 9. Save the resource.
802 10. Go to Step #6 'till done.
803  
804
805 # include the necessary modules
806 use MyLibrary::Core;
807 use Net::OAI::Harvester;
808
809 # define the repository
810 $repository = 'http://infomotions.com/gallery/oai/index.pl';
811
812 # check for a facet called Formats
813 $facet = MyLibrary::Facet->new;
814 if (! MyLibrary::Facet->get_facets(value => 'Formats', field => 'name')) {
815
816 # create it
817 $facet->facet_name('Formats');
818 $facet->facet_note('Types of physical items embodying information.');
819 $facet->commit;
820 print "\nThe facet Formats was created.\n";
821
822 }
823
824 else {
825
826 # already exists
827 $facet = MyLibrary::Facet->new(name => 'Formats');
828 print "\nThe facet Formats already exists.\n";
829
830 }
831
832 # remember this facet id
833 $facetID = $facet->facet_id;
834
835 # check for a term named Images
836 $term = MyLibrary::Term->new;
837 if (! MyLibrary::Term->get_terms(value => 'Images', field => 'name')) {
838
839 # create it
840 $term->term_name('Images');
841 $term->term_note('These are things like photographs or paintings.');
842 $term->facet_id($facetID);
843 $term->commit;
844 print "The term Images was created.\n";
845
846 }
847
848 else {
849
850 # it already exists
851 $term = MyLibrary::Term->new(name => 'Images');
852 print "The term Images already exists.\n";
853
854 }
855
856 # remember this term id
857 $imageTermID = $term->term_id;
858
859 # check for a location type called URL
860 $location_type = MyLibrary::Resource::Location::Type->new;
861 if (! MyLibrary::Resource::Location::Type->new(name => 'URL')) {
862
863 # create it
864 $location_type->name('URL');
865 $location_type->description('A type of Internet resource.');
866 $location_type->commit;
867 print "The location type URL was created.\n";
868 }
869
870 else {
871
872 # it already exists
873 $location_type = MyLibrary::Resource::Location::Type->new(name => 'URL');
874 print "The location type URL already exists.\n";
875
876 }
877
878 # remember the location type id
879 $location_type_id = $location_type->location_type_id;
880
881 # create a harvester and get the data
882 $harvester = Net::OAI::Harvester->new('baseURL' => $repository);
883 $records = $harvester->listAllRecords('metadataPrefix' => 'oai_dc');
884
885 # process each record
886 while ($record = $records->next) {
887
888 $FKey = $record->header->identifier;
889 $metadata = $record->metadata;
890 $name = $metadata->title;
891 @description = $metadata->description;
892 $description = join (' ', @description);
893 $location = $metadata->identifier;
894 print "$name...";
895
896 # check to see if it already exits
897 if (! MyLibrary::Resource->new(fkey => $FKey)) {
898
899 # create it
900 $resource = MyLibrary::Resource->new;
901 $resource->name($name);
902 $resource->note($description);
903 $resource->fkey($FKey);
904 $resource->related_terms(new => [$imageTermID]);
905 $resource->add_location(location => $location,
906 location_type => $location_type_id);
907 $resource->commit;
908 print "added (", $resource->id, ").\n";
909
910 }
911
912 else {
913
914 # already got it
915 print "already exists.\n";
916
917 }
918
919 }
920
921 # done
922 print "\nDone\n";
923 exit;
924  
925 While this was the longest example in this tutorial, this particular OAI to MyLibrary interface is very rudimentary. See the script named images2mylibrary.pl from the distribution to see how you can harvest OAI sets. See doaj2mylibrary.pl to see how you can more accurately classify incoming resources based on set names. The really enterprising reader will figure out ways to read the incoming Dublin Core subject fields and create facet/term combinations accordingly.
926  
927  
928 =head1 Summary
929  
930 Unlike version 2.x of MyLibrary, version 3.x is more like a toolbox and less like a turn-key application. Developers are expected to read and write values to the MyLibrary database, manipulate these values to create sets of information services.
931  
932 The examples above point to terminal-based scripts implementing the described concepts. The distribution comes with another set of scripts implementing these ideas using a Web-based interface. They use all of the concepts outlined above but they are CGI scripts implemented in a more graphical interface.
933  
934 Use MyLibrary in conjunction with other Perl modules. In a more traditional library you might consider reading sets of MARC records to create a sort of online catalog. Provide an SRU interface to your indexed content and then transform the XML returned from the SRU server into email messages or RSS feeds. Create CGI scripts that return Javascript that simply write to the document window. Then call these CGI scripts from within HTML <script> elements. This will enable HTML authors to incorporate MyLibrary content into their pages. You might harvest data from various but similar OAI repositories to create subject-specific collections. Index the collection and provide an interface to it. You might create Web-based input screens allowing authors to submit information about publications thus implementing a sort of institutional repository. Use your imagination. Think a bit outside the box.
935  
936 When you've got a hammer everything looks like a nail. While MyLibrary is not necessarily a perfect hammer, it can address many of the needs in libraries to create, maintain, and distribute classified lists of information resources. The key to success is discovering ways to re-purpose these lists meeting the expressed needs of library users.
937  
938 =head1 AUTHOR
939  
940 Eric Lease Morgan <emorgan@nd.edu>
941  
942 =cut
943  
944 1; # return true or die