OpenWetWare:Software/Projects/Lab Notebooks/Overview

=Overview=

=Introduction=

The most recent version of the OWW Lab Notebook will be deployed this week. The Lab Notebook is currently under active development. This version is based upon a model created by Austin Che. A number of people have been providing input to this effort. Prototype versions are already in use.

=Design Model=

The Lab Notebook design assumes that an individual researcher or student needs to track one or more discrete projects over a period of days, weeks, or months.

Representing Projects
Entering notes and findings for projects has been performed using two different models.

Entry by Project
In the first model, each project is represented as a single document. New entries for the project are made within the document. As each new project entry is added, a date label is included. An existing OWW extension, the Dynamic Page List (DPL), is used to create chronological reports across all of the projects.

Entry by Date
In a second model, the project and entry pages are reversed. In this model, entries are made in discreet entries for each calendar day. Within the daily entry pages, content for each project is entered in sections. Each section is labeled with the project name that findings or notes are to be entered. The DPL is used to create summary pages for each project. The project entries are linked to the summary page; clicking on the entries brings the user to the daily entries.

Initial Data Entry Model
Our initial focus is to complete work on the second model, where data is entered by date and displayed by project.


 * BC 09:51, 10 January 2008 (CST): This is fine with me, primary organization by date is likely to be more familiar to new adopters. I think it is important however to develop this in a manner that will allow us to switch to a system whereby entries can be made equally easily by date or project.  While most people are likely to have a preferred method of entering content, it's very useful to be able to add an entry identically regardless of whether you are on a "date page" or a "project page".


 * Currently, the content of the project is not editable since the page is derived by using the Dnamic Page List (DPL) to create the list of entries for each project. From each Project, each Entry can be edited by clicking on the link at the top of it.


 * We can add another link to the current entry page on each project so a user can immediately click to edit the page.


 * The pages used to reformat the original Entries (shadow pages) into entries that can be displayed within the Project Pages will all contain a link to the "ShadowEntry" category. This category has a message indicating that the pages are not editible.

Project Pages
Each project will be viewable as a separate Mediawiki page. The Project Page display is based upon a templated call to the DPL. The DPL uses a Mediawiki technique referred to as 'transcluding' to display portions of each Date Entry. Only the sections of a Date Page associated with each individual project will be displayed within each Project Page.

The Project Page is an editable page. However, it contains a reference to a template wich calls the DPL. This call gathers pages containing the "ShadowEntry" category. These pages must be within the designated namespace (currently User) and must contain at least one reference to the Project being displayed.

Calendar View
A calendar view will be located on the Lab Notebook front page. A user can access date entries independent of the Lab Notebook projects by clicking on the entry for a specific date. Individual entries are made for multiple projects within separate daily entry pages. The main page of the Lab Notebook is the jumping off-point for all activity. All daily pages are always accessible. Since this uses MediaWiki, all edits and revisions of the pages are always online.


 * BC 09:58, 10 January 2008 (CST): A downstream issue to consider with the calendar view is how the list of dates on the front page will be generated. Will it automatically display the next one year, three years?  Or will the user be responsible for controlling the date range displayed?  Not important yet though I think but wanted to flag it.


 * : I agree. As we discussed, the next stage is to move to a model where either "project-priorit" or "date_priority" will be supported equally by moving to individual entries for each Lab Notebook update. Currently, the OWW Lab Notebook gather multiple entries per page. As we move to a more semantic-web-based model (via Semantic MediaWiki), this will become a new option. We need to do it in a way that both provides improved flexibility and backward compatibility.


 * As for the date entries, there's alreadysome of flexibility in it. I've included an optional calendar that is set up to create new entries on any displayable date. The current OWW Calendar extension does not provide for moving to the next or previous month. We need to use a more flexible calendar to do this.

Date Entry Pages
Individual date entry pages are created only when a specific date is selected. On the first day of the lab notebook's use, there will be no date entries.

Date Entry Format
The format of the individual date entries will be up to the Lab Notebook user. Each new page will use an optional "model" file to seed the format of the page. This is not a MediaWiki template. Instead, it is a named Mediawiki page containing a pre-populated format. This page can contain Mediawiki templates. It can contain MediaWiki text with as little as a single MediaWiki template.


 * BC 09:58, 10 January 2008 (CST): Austin's code to automatically put "Yesterday | Today | Tomorrow" links at the top of all date pages could be included in this template.


 * I'll add this code.

=Using the OWW Lab Notebook=

This is a "use-case"-like model of how users will interact with their Lab Notebooks. Each currently implemented component will be differentiated from festures not yet implemented.

Enabling a User's Lab Notebook
A new option has been added to the "Misc" tab in the User Preferences page. The new control is a checkbox. Clicking it will enable the lab Notebook.

By checking the "Enable Lab Notebook" box, a new entry for "My Lab Notebook" on the "Personal Navigator" at the top right of each OWW page.

In addition to enabling the navigator link, an internal flag will be set allowing all OWW Lab Notebook features to be enabled.

If the "Enable Lab Notebook" is unchecked after the Labe Notebook hs been enabled, all exsting OWW Lab Notebook pages will still be accessible. No data will be destroyed as a result of disabling the OWW Lab Notebook.

My Lab Notebook
My Lab Notebook: Link to permit OWW user to open the Lab Notebook (not yet implemented)==

The user will see the 'My Lab Notebook" link at the left-hand top of OWW page. When an OWW user chooses to enable the Lab Notebook, the link will be displayed as the last entry on the "personal navigator", just after the "log out" link.

Per a suggestion from one reviewer, this will not initially be enabled.


 * Jason R. Kelly I think we should roll this out with a beta-test group (still on the main site) but not have this link pop up on everyones toolbar just yet.


 * This is an option. The default is that it is disabled.


 * BC 10:00, 10 January 2008 (CST): Once we are ready to roll this out more widely, there should be a link to the users preferences put on their User page when their account is created.


 * I agree. If the Lab Notebook is created by another action, the option should automatically be set as well. It's not clear how this would be done yet.

Navigating to Lab Notebook Main page
Click on "My Lab Notebook" to go to the "Lab Notebook Main Page" (not yet implemented)== The "Lab Notebook Main Page" will be a designated page within the OWW user's personal namespace. As is the case with both the user's "My Talk" and "User Page", the "Lab Notebook Main Page" will be prefixed with the "User:[UserName]" tag. Each "Entry Page" and "Project Page" will be created within the same page-space. This allows all OWW User's Lab Notebooks to be managed in a consistent manner.

Creating New Projects
You can create multiple projects on the notebook's main page. To do this, thee is a textbox with a button to the right of it.

The user will enter a project name in the text box and click the button. The user's specified "Bsse Project" page will be used to fill in the contents of the new project. There is no editing of the new Project's content currently required.

Upon creating a new Project, the new Project will appear on the user's main OWW Lab Notebook page.

If a Project's page is deleted, the Entries labelled for that project will still be present. In other words, no entries are deleted as a result of ANY action including the deletion of a Project.

It may be convenient to provide another "non-project" which would contain a list of all entries in all pages that are not associated with a specific project. The DPL does allow for this as long as a list of all projects can be created.

Base Project
The Base Project is the content used to create a new Project with. This is not a template but it can contain templates. The model is that a user can modify the way all Projects are created.

The Base Project page is created for the user when a new OWW Lab Notebook is created. The original content is based upon the system default.


 * BC 10:04, 10 January 2008 (CST) How do we want this to work? I assume that in the early version we'll need to edit the notebook's main page and enter a new project name in a list?  Is that vision that eventually there would just be a text box to enter a new project name and a button to add the new project?


 * This is the way it has been implemented.

Lab Notebook Calendar
The calendar will allow you to see all of the dates for the month.

Currently, the calendar only displays the current month. The OWW Calendar extension does not allow for displaying last and next month or changing the year. These features are highly desirable. There is another MediaWiki Calendar that does allow for this kind of interaction. It will be evaluated for future use.

The format for all dates will be "YYYY/MM/DD". Both Month and Date entries are not zero-padded. Example:


 * January 9, 2008: 20008/1/9

Selecting a New Date Entry
Clicking on a date in the calendar will either create a new Entry for the specified date or or go the existing Entry for the specifed date. In either case, the user will be redirected to the specified entry.

Creating New Date Entries
A simple template is used to identify the content in the entry page for each project.

Updating Projects
Saving the page will update each project with the entries just created. Projects are not meant to contain the dated entries. Instead, the pages are gathered for display by the DPL.

Since the Project page is a standard MediaWiki page, it can be edited as any other page. However, the editing is restricted to the areas of the page where Date Entries are not being displayed.

The Date Entries on each OWW page are re-created each time the Project page is opened. The Project can be thought of as a list or view of entries with additional editable content.

Opening or closing the page will not capture the current Date Entries.

Project View
On the main Lab Notebook page, the projects will all display all activity by date for that notebook.

Lab Notebook Search
We will be adding a search button that will only search the contents of the lab notebook rather than all OWW pages.

To do this, the current MediaWiki SpecialSearch.php can be subclassed to create a new set of methods. The showMatchers method contains the loop where results returned from the search engine are output. For each valid search result, the showHit method is called.

A modified version of the showHit method can be replaced in the derived class. This version of showHit would check to see if the reference page of the result to be included in the result list matched a page within the user's lab notebook. If it did, the result will be printed. If not, the result is skipped.

To call this search, a modified version of the current search dialog can be added as a separate version of the current search box. The new box would call a new Special page that would include a call to use the derived class rather than the original Special Search class.

This would mean that the new SpecialLnSearch.php module would contain the entry point, the definition for the new class, and a single method, showHit. The new showHit method would check to see if the returned result was inside of the current user's Lab Notebook pages.

There will be no modification to the current core search files required to implement this change.

The MonoBook.php skin file will need to be modified to include the new Search box. This seach box will only be displayed if the user has enabled the Lab Notebook.

The amount of work required to make this change will not be large. The code to check for the page is a comparison of the root of the page title. The actual page file can be obtained from a class already created to support the Lab Notebook. The UI modification should be limited to adding the new search box below the current one with conditional code added to check for the user's "enablelabnotebook" option in the User.php object.

The result page will not indicate that the search is any different than a regular search.

Lab Notebook Backup
We will provide a single-button export to allow users to save a copy of the Lab Notebook notebook outside of OWW.

Backup will be clear to implement if we do continue to use a hierarchy for all Lab Notebook pages rooted in a single page such as the current design.

Templates used within the pages to be backed up can be collected along with the pages and stored in the XML export file if we choose to use the MediaWiki Export format for backups.

For image files, it's possible to create a zip file that would contain the root of the images directory where all images referenced from within the Lab Notebook are stored.

The specific format to be used is still not determined. However, the MediaWiki Export format represents the most simple format from within the system to implement.


 * BC 10:07, 10 January 2008 (CST): I gather the options here are -


 * MySQL dump of the user's lab notebook "namespace" and files


 * A MySQL dump may be overkill. It would be difficult to re-import a SQL dump of a Lab Notebook into another instance of Mediawiki.


 * Nicely formatted pdf document with text and images.


 * This method would allow for capturing all of the images and text


 * PDF-ifying a document will "flatten" the content almost like printing it to paper


 * The resulting PDF file cannot be imported into another system.


 * Any other options?


 * The MediaWiki standard is to create a single XML file containing a the contents of the pages.


 * The XML file can technically be imported into any MediaWiki server.


 * This would have to be done by a Sysop or Bureaucrat: these options are not generally allowed for users.


 * Pictures would also have to be extracted along with the MediaWiki export.


 * Current;y there is no automatic way to import pictures into MediaWiki.


 * Each picture would have to be uploaded manually.


 * Using Austin's Dewikify program, we can also convert the user's Lab Notebook to HTML.


 * This would allow for upload to a web server or local modification of the content with a text editor or HTML editor.

WYSIWYG Support
The Lab Noebook will optionally allow full WYSIWYG editing using the FCKEDIT extension.


 * Users can customize the style with which project pages are formatted. For instance, for your class, you may want a specific way to view the content or to automatically link the entries to a category tag for your class.


 * The same will hold for the daily Entries. A Base Project Page will be used to insure that Project and Entry pages will be consistently formatted. Every new Daily Entry will start out with the same content before the user edits it.

Private Wikis vs. OWW
Lab notebooks can be equally easily be stored in a sub-wiki or the main OWW wiki. To ensure the content is searchable and integrated with the OWW community, we will initially integrate all lab notebooks into the main wiki. The Lab Notebook will be rooted in the User:[UserName] page range that the User's personal pages already use.

Toolbox
The Toolbox is the left=hand column box of links located below the Search box. The contents of this list are programmable within Mediawiki. The Lab Notebook will contain an optional list of links related to navigation within the OWW Lab Notebook. This list will only be displayed when a user is vieing one of the OWW Lab Notebook pages. We can also customize the Toolbox the user has access to when working with the Lab Notebok. If you have specific documents, such as assignments, to post for the class, the custom toolbox will be present when they are using pages tagged as part of the Lab Notebook.


 * Jason R. Kelly 18:09, 9 January 2008 (CST): What exactly is the 'toolbox'?

"Canned" Toolbox for Labs
The Toolbox is the left-hand navigation box located directly below the Search box. Using an existing OWW mediaWiki extension. The links listed in the Toolbox can be configured in a number of ways. OWW can globally set the content of this list as a default. Alternatively, a user can modify the Toolbox. Another option may be to pre-set the content of the Toolbox to meet the requirements of a set of users in the same Lab or for a Laboratory class.


 * Jason R. Kelly 18:06, 9 January 2008 (CST):I don't know what this means exactly, but in general I am against things that let one "superuser" group do things other lesser users can't do on the main site. This applies to students/teachers.  Courses on OWW have been just as vandalism-free as the rest of the site (w/o lowering students' edit access).  Students might even be more trustworthy than the avg community member, since they've got a grade hanging in the balance ;)


 * This was not included for vandalism-related purposes. It was anticipated that for some labs, it may be desirable to have all users at least have the option of sharing a common set of links related to either their area of investigation or to the subject material being covered in the lab.


 * This has not been implemented and will not be until it is required.

=OWW Lab Notebook Page Layout=

Lab Notebook Main Page
The Main Page will be created witin the user's "page space".

Lab Notebook Project Pages
Project pages will all be created beneath the Lab Notebook Main Page

Lab Notebook Projects Pages
Each Project pages will be created beneath the Lab Notebook Main Page

Lab Notebook Daily Entry Pages
Each Project pages will be created beneath the Lab Notebook Main Page

Lab Notebook Individual Daily Entry Pages
Each Project pages will be created beneath the Lab Notebook Enries Page. The pages will all use a date as part of the title using the format YYYY/MM/DD with no leading zeroes. Only valid dates will be allowed. This means there currently can be only one entry per day.