==NAME The Microlibrary mimicrokernel== ==DESCRIPTION== This script runs a web-service thru the Open Library (OL) API, stores data send by the web-service into files and generate XHTML to display data in a very simple page. The microlibrary is made to manage everything to generate a book-shelf page, using your data from Open Library. For more informations and How To, please see http://goo.gl/k375R ===The Self Shelf Swap Project=== This first implementation is a physical object (books) swaping/sharing system. Our Library project is to create an online index which could make (in next version) possible to : ; Inform :retrieve informations about registered documents ; Locate :know where documents are physically based and if you can loan it ) ; Create :register an account & create your own Library DataBase ; Share :share it with other users. Our desire is to provide a private Libraries Network in an IRL spirit, a Library of Libraries ("meta-libraries"), physically based (shelfs). We don't want to provide downloadable documents. That's why our project is named "Self Shelf Swap". It's first implementation will be Bibliothek. ===How does-it do the job ?=== ; '''The lists''' :List are considered like thematic shelfes of your library. First the microlibrary mimicrokernel calls the Properties Reader, that will parse our open_library_lists file, and return an array if list ids. This array is passed as an argument to the build_the_list_request() subroutine of the Curl Requester, that will build '''and''' get the list requests. For each list id, we get a RDF flux containing books URI. Flux are stored into your hard drive by passing the RDF flux, the list id and the "list" flag (to specify that we manage lists) to the store_RDF_flux() of the RDF Tool. ; '''The books''' :Next, for each list, we load the file on disk thru the parse_RDF_file() subroutine, passing the list id as an argument. We get many data thru the get_list_element() subroutine of RDFTool, that will get all books data. For more information about this part, see the RDFTool documentation. ; '''The View''' :The Web Displayer was and is still scattered everywhere. And will be remplaced soon by a more decent system (AKA MVC). Now, at 0.02 version it's a little bit better cause we put any view item in a buffer for later usage. See you soon... ===HOW TO SET UP YOUR MICROLIBRARY=== ====INTERACT WITH OPEN LIBRARY AND GENERATE YOUR DATABASE==== To deploy and install your microlibrary, you need a GNU/Linux environment or any Perl friendly system. Dime and a shoestring has been only tested on Debian or Ubuntu. Feel free to test it on other platforms and give us feedback... Install every dependencies. You can follow the DEPENDENCIES section of this documentation and test it by running the microlibrary.pl script. To run this script, just open a terminal, go to the dime_and_a_shoestring. Fix the $ENV{HOME} environment variable that should target the 'lib' directory containing the microlibrary.pl script. Set the $reload_mode and the $log_mode flags to '1', let the $html_mode and $sad_deps_mode to '0'. Now type into your terminal : $ perl microlibrary.pl The script should start and send querries to microlibrary. This can take some time. We wait to receive the response of every querry before to send another one. Once every querries have been send, a kind of database is stored into your hard drive in /home/foo/bar/dime_and_a_shoestring/database/book/$ /list/$ =head3 MAKE A VERY SIMPLE WEB SITE Now turn the $reload_mode and the $log_mode flags to '0'. As your database is on your own disk now you don't even need to send request to Open Library again. You will only re-run the script with $reload_mode activated each time you add a list/shelf, a book, or update informations into OL. Set the $html_mode to '1'. Your microlibrary is ready, to be used from a browser you just need to deploy it on your public server (don't forget to update the $ENV{HOME} variable). ==CONFIGURATION AND ENVIRONMENT== ===Flags for modes=== All the flags for modes should be configurated from the /properties/modes.properties file. ; '''Reload OL data mode''' :We will use the Open Library database and list feature to constitute the shelfes of a very simple library : lists are thematic shelfes, and your set of lists under a OL account is a Microlibrary. Soon, we will provide more powerful features. You can turn of the interraction with the OL API by giving the value of 0 to the $reload_mode scalar. Data will be read from the files stores on your harddrive. Script with "$reload_mode = 1" must have been run at least once to generate files on your hard drive. ; '''Display log mode''' :In development and debug environment you must most of the time use our "log mode" that will display useful informations when processing. Don't forget to turn it of ( $log_mode = 0) in production environment cause it will display logs into you web pages. We will soon replace this by a more descent and classical LogForPerl logger. ; '''Browser simulation mode''' :Maybe it is bad-named. Simulate a browser querry on the main script. It generates a query string ("?lib=lib_name") when you're working from console. It should be used to reload the datas from open-library for a particular user. You should set the $nick scalar to select wich library will be reload. Experience makes us learn that you should avoid to use this mode in terminal work, near of deploiement time, and prefer a clean and reasonable debug direclty from your browser. That's why the 'Browser debug mode has been made' ! ; '''Display XHTML tags mode''' :This is the mode for production environment. It generate your data into XHTML tags ( $html_mode = 1 ). Data are stored into a temporary buffer, that will be soon print when asked by a browser. It can also be used into console for debug, combinated with the browser simulation mode. ; '''SAD dependencies mode''' :This is the Simple And Dirty dependencies logger ( $sad_deps_mode = 1 ), that will display all needed dependencies. Only works when dependencies are used (to confirm ?) Don't forget to turn it of ( $sad_deps_mode = 0 ) in production environment cause it will display logs into you web pages :(. ; '''Browser debug mode''' :Will simply display useful debug things into the browser into an independant fixed
that will not smashed the delicate display of your pages and gives you performances stuffs and other techs goodies. MUST be turned off in production environment. It has been proved that's it's better to test as soon as possible into a browser. In early development time you can use the browser debug mode but it's more sure to switch to a real browser as soon as possible. Browser debug mode is good for terminal kiddies. ==DEPENDENCIES== ===Self Shelf Swap dependencies=== Microlinrary comes with : Data::CURL::CurlRequester - Data:Properties::PropertiesReader - Data::RDF::RDFTool Tools::DependanciesViewer - View::WebDisplayer ===CPAN dependencies=== We use these CPAN modules : Data::Dumper - Encode::Encoder - File::Basename - IO::File - Module::ScanDeps - Net::Curl::Simple - Properties - XML::Simple Time::HiRes This will at least need these following CPAN modules to work : local::lib - Log::Simplest - Merror - RDF::Redland - Test::Simple ==SUBROUTINES / METHODS== ; '''print_generic_footer()''' :It seems to be self explanatory, but what is not is it should be located into View::WebDisplayer, not here, but I've been too lazy to move it :(, it will be made into our next *smart* version, soon available in 2027. ==ARGUMENTS== I would like it could take parameters in command line mode, just like : $ perl microlibrary.pl --reload ... to force the reload mode to be activated for ALL lists and books $ perl microlibary.pl --reload --name foo ... will reload only the lists and books of a user. 'foo' will be supposed to be a valid Open Library user name, listed into our open_library_lists.properties file. Even better, if this user don't exist, it could be created : $ User 'foo' don't exist, should I create it ? (yes / no) ... and add it into the properties file. Will load all the user's lists, put it the properties files and make all the stupid work that you don't want to do. Out in 2054 !!! ==BUGS AND LIMITATIONS== The Microlibrary mimicrokernel 0.01 version has been an exercice for learning perl and is not recommended for re-use. Even if we try to make it better for the 0.02 version (it's really better), lots of work should be done to reach the perfect 0.03 version and the wonderful mythical 1.0 version. ===Hard coded things and configuration stuff=== Some hard coded things and configuration stuff should be into properties files. See # See https://bugs.launchpad.net/bibliothek-project/+bug/856571 ===Non-portability=== The Microlibrary is not cross-platform and has been tested ONLY on Debian-like GNU/Linux systems. At this day, we didn't try to deploy it on MS Windows, but feel free to help us if you want ! ===Scattering view !!!=== This is the most S.A.D. thing about the microlibrary... View is scattered everywhere, there is nothing to do than do re-do it correctly !!! ===Dependancies section=== This section could be ported to a meta.yaml file ==AUTHOR== Self Shelf Swap - Simon Foutaiz - 2011-05-24 ==CURRENT MAINTAINER== my ( $firstname = "seb", $lastname = "feugere", $provider = "gmail"); print $firstname . "." . $lastname . "@" . $provider . "." .com; ==VERSION== This is version 0.02, well known as a Dime And A Shoestring II ==COPYRIGHT AND LICENSE== Copyright 2011 Self Shelf Swap. This library is free software. You can redistribute it and/or modify it under the same terms as Perl himself.