jFlash Multilingual Web-Based Flashcard System ---------------------------------------------- I. Introduction So what is jFlash? jFlash is a multilingual, web-based flashcard system based on open web standards, PHP, and XML. It consists of two principal software modules: 1) A PHP system for indexing and delivering flashcard content. 2) A Javascript application that parses out and presents a set flashcards represented in XML. A "deck" of cards in jFlash in defined in an XML document. After one or more decks have been created, index.php can be changed to dynamically create indexes of which decks exist in a given directory. A user selects a deck and then the Javascript flashcard application begins. A variety of flashcards are presented to the user along with a number of statistics for this study session, an answer form, and a few buttons to interact with the flashcard program. Once the user has demonstrated that they can answer all cards in a given deck correctly at least once, the user may start the deck over or return to the index. From there, the process begins again. II. Running jFlash A. Requirements jFlash has been designed to have fairly minimal, but modern requirements: 1. Web server Requirements jFlash requires a PHP-enabled web server with DOM XML support. This generally implies PHP 4.3 and higher. Please let me know if it works for you on any earlier versions. jFlash has been tested on Apache 2.0.48 and PHP 4.3.4. 2. Web Browser Requirements jFlash requires a web-browser with good Javascript and CSS support. It was initially developed under Mozilla Firebird (0.7) and then (painfully) ported to Microsoft Internet Explorer 6.0. It is unknown if jFlash works on Opera, Safari, Galeon, etc. If you test/fix jFlash for operation on any of these browsers, please submit the patches to me. B. Installation To install jFlash, simply unpack the jFlash archive into a directory of your choosing. I'm assuming that since your reading this file, you have completed this step already. Next, move this directory to someplace your PHP-enabled web-server will be able to serve it from and then navigate to this directory using your web-browser. If the installation was successful you will now be rewarded by seeing the jFlash flashcard system lesson index. C. Operation Click on a lesson. A new page will be displayed containing a jFlash flashcard, its answer dialog, and a series of buttons. The jFlash flashcard consists of a card number in the upper-right hand corner; the question number, question total and mode in the upper left; the actual flashcard content in the very middle; the score in the lower left; and finally the correct and incorrect answer totals in the lower right hand corner. Each flashcard in the "deck" has its own card number. This is the number that is displayed in the upper right. Because the deck is shuffled each time you enter a lesson, this number jumps around non-sequentially each time an answer is given. The question number in the upper right displays how many questions out of how many total questions in the deck have been answered. This number will only increment when a correct answer is given as when an incorrect answer is given, that card is reshuffled back into the deck automatically. The mode can either be "normal" or "ask answers as questions," the latter also being known as "reverse" mode. The former is the default, in which questions are asked and then matched against the answers that are given for each card definition in a deck. Reverse mode, on the other hand asks the answers and expects the user to enter the question text as the answer. This is very useful for verifying that one has learned something as a two-way association. The middle of the flashcard usually contains the current flashcard question. It may also display a hint in smaller text above the question when the "Toggle Hint" button is pressed or "[end of deck]" when the current lesson's deck of cards has been exhausted. The score is updated for each correct answer given. The individual score value of a flashcard is calculated by taking 100 and dividing it by the total number of cards. Each time a flashcard is answered incorrectly, its score value is divided in half. The correct and incorrect answer totals in the lower right hand corner update for each question answered. By watching these counters, one receive feedback for whether an answer given was correct or not. Once a flashcard is displayed, one gives their answer by interacting with the answer form. Depending on how the flashcard was setup, this form may either be represented as a multiple choice question or a text-input. field. In either case, the user also has two buttons "Answer" and "Toggle Hint." If the form is drawn as a multiple choice form, the user indicates their answer by selecting one from the many presented and clicking the "Answer" button. The flashcard area will then update its information fields and present a new card. If the form is drawn as a text-input field, the user indicates their answer by typing it in exactly and clicking the "Answer" button. Again, the flashcard area will update. If the "Toggle Hint" button is clicked, a hint will appear as small text above the question text within the flashcard. This hint will automatically disappear once an answer is given, or if the user clicks upon "Toggle Hint" again. Below this answer area there are more buttons for that perform different functions. They are labeled "Skip and Show Answer" "Start Over" and "Ask Answers" respectively. The "Skip and Show Answer" button scores the user for an incorrect answer, but presents the user with the correct answer in the center panel of the flashcard area. The user can then click the "Continue" button that appears in the answer area to continue on to the next card. This function should be used when the answer, or even a guess for the answer, is not known. The "Start Over" button resets all the scores to zero and reshuffles the deck. Use this function to restart the lesson without returning to the lesson index screen. The "Ask Answers" button resets the scores to zero and reshuffles the deck, but more importantly it asks the answer and accepts only the correct question as the correct answer. At the bottom of the visual is a link to return to the lesson list. Click this screen to return to the initial jFlash screen. That's all you need to know to use the software! III. Customizing the Application A. Writing New Lessons jFlash has been authored with ease of creating and managing lessons and flashcard decks in mind. Creating a new flashcard deck is easy, all one needs to do is edit a simple XML file. A lesson collection is nothing more than a directory full of these XML flashcard decks. The XML files are parsed and emitted in unicode (UTF-8), so it is preferred if the files are created in a unicode compatible editor. All XML files begin with the following XML processing instruction header, followed and terminated by the tag. Inside the tag, there are three types of tags that may be defined: , , and . There should The tag contains the title of the flashcard deck. There should only be one tag per flashcard deck. The tag defines how many multiple-choice options should be given if a card is defined as accepting a multiple-choice answer. A good guideline is to offer one multiple choice answer for every 4 cards in the deck, with perhaps a minimum of three choices and perhaps a maximum of ten. The tag encloses the actual "meat" of a card definition. The card tag itself can take two options--"forward" and reverse--and may contain up to three tags: , , and . The "forward" and "reverse" options define which answer form style is presented to the user when the system is in normal mode ("forward" asking mode) or "reverse" mode. You may either set these options to "multiple" or "exact" for multiple-choice or fill in the blank exact text input modes respectively. The contents of the tag contains the text that will be presented to the user as a question. If the user presses the "Toggle Hint" button, this text will appear above the question text; both in normal ("forward") and "reverse" mode. The tag defines the answer to the question. Here is an example XML deck that contains two cards: Antonyms 2 hot Like a Minnesotan Winter cold addition to take away subtraction B. Customizing the Look And Feel You have two choices for customizing the look and feel of the application. One is easy, the other is more difficult. The first and easiest option is to simply edit the jFlash.css style-sheet and manipulate the colors, fonts, and image definitions. Eventually, documentation and examples will exist on which identities change what on the final rendered output. The last and more difficult way is to change the actual HTML source as defined in jFlash.php. The two functions to look at are sendLesson() and sendLessonList(). If you go this route, good luck ;-) IV. Miscellaneous Information A. Included Lessons jFlash was created to help me and my classmates learn the incredible amount of Japanese vocabulary that we must take from our class text _An Integrated Approach to Intermediate Japanese_ by Akira Miura & Naomi Hanaoka McGloin. Included at the time of the writing of this document is material from Chapter 5 from this text. Submissions of other flashcard sets would be greatly appreciated, and I would be happy to host them. B. Other Notes I believe this software to be useful to a great many people. If you have suggestions, comments, or contributions please write me an e-mail! V. Copyright Information This software is protected by the LGPL, and the copyright notice is as follows. Please write the address below, or visit http://www.gnu.org/copyleft/lesser.html for more information. jFlash: Multilingual Web-Based Flashcard Software Copyright (C) 2004 Jordan Husney This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA $Id: README,v 1.2 2004/01/28 04:49:33 jordanh Exp $