PageRenderTime 32ms CodeModel.GetById 2ms app.highlight 18ms RepoModel.GetById 1ms app.codeStats 0ms

/readme.html

https://github.com/xiongchiamiov/IMathAS
HTML | 260 lines | 242 code | 18 blank | 0 comment | 0 complexity | 192479b6e26b74bca7a1aef96298c8da MD5 | raw file
  1<html>
  2<head>
  3<title>IMathAS</title>
  4<style type="text/css">
  5ul li {
  6	margin-top: .3em;
  7}
  8ol li {
  9	margin-top: .3em;
 10}
 11h1 {
 12	color: #00f;
 13}
 14h2,h3,h4 {
 15	color: #00c;
 16}
 17</style>
 18<body>
 19<h1>IMathAS</h1>
 20<p>Version: 1.8.   Released November 9, 2009 <br/>
 21See <a href="changelog.html">Change Log</a> for detailed change history.  The most recent version of
 22the code is available via SVN at <a href="http://code.google.com/p/imathas/">Google Code</a></p>
 23
 24<h3>What is IMathAS</h3>
 25<p>IMathAS is an Internet Mathematics Assessment System. It is primarily a 
 26web-based math assessment tool for delivery and automatic grading of math homework 
 27and tests. Questions are algorithmically generated and numerical and math expression
 28answers can be computer graded. Beyond that, IMathAS includes learning management tools, 
 29including posting of announcements, text files, and attachments, as well as discussion 
 30forums and a full gradebook. In postings and assessments, IMathAS allows accurate display 
 31of math and graphs, with simple calculator-style math entry and point-and-click graph 
 32creation.   It is most similar to (and inspired by) <a href="http://webwork.math.rochester.edu/">WebWork</a> 
 33and <a href="http://wims.unice.fr/">WIMS</a>, and similar to commercial and publisher-produced systems 
 34like iLrn, MathXL, WebAssign, etc.</p>
 35
 36<p>IMathAS was written by <a href="http://www.pierce.ctc.edu/dlippman">David Lippman</a> (c) 2006-2009, 
 37with with partial support from the
 38<a href="http://www.sbctc.ctc.edu/College/_g-elchome.aspx">WA State E-Learning Council</a>, the 
 39<a href="http://www.transitionmathproject.org/">Transition Math Project</a>, and 
 40<a href="http://www.pierce.ctc.edu">Pierce College</a>.  It is distributed under
 41the <a href="http://www.gnu.org/copyleft/gpl.html">GPL</a>.  See the <a href="license.txt">license.txt</a> file distributed with IMathAS for more details
 42and credits for components attributed to others.</p>
 43
 44<h3>Features</h3>
 45<h4>IMathAS was built on three primary philosophies:</h4>
 46<ul>
 47<li><b>Math</b>:  The system was designed for Math assessment; no effort was made for the system to be multi-purpose.</li>
 48<li><b>Sharing</b>:  The system was setup to encourage sharing of questions within a system and outside.  Questions are grouped into
 49    question libraries, and are not tied directly to a specific assessment.  Unless marked Private, questions can be used by
 50    anyone on the system, or used as a template for writing new questions.  Assessments and course setups can be copied
 51    between users with permission.  Export and Import allows the 
 52    sharing of question sets between systems.  Also, macro libraries allow for the expansion of IMathAS's question language.  
 53    Users with expertise in a field can develop macro extensions, and share them with other users.</li>
 54<li><b>Ease of Install</b>:  The system uses standard PHP and MySQL.  It requires no special compilation options or installation
 55    of external programs.</li>
 56</ul>
 57
 58<h4>Core Features include:</h4>
 59<ul>
 60<li>Display:</li>
 61	<ul>
 62	<li>Rich Math and Graph display, using standards-based MathML and SVG, powered
 63	    by Peter Jipsen's <a href="http://www1.chapman.edu/~jipsen/svg/asciisvg.html">ASCIIsvg</a> and
 64	    <a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMathML</a>, or using image fallbacks</li>
 65	<li>Rich Text Editor with built-in Math and Graph support for text items displayed in a course and forum posts</li>
 66	<li>Alternate display options for screenreaders and browsers without needed support</li>
 67	</ul>
 68<li>Assessment:</li>
 69	<ul>
 70	<li>Question types including:</li>
 71		<ul>
 72		<li>Functions, with answers like "sin(x)"</li>
 73		<li>Numbers, compared to a given tolerance</li>
 74		<li>Calculated Numbers, like 5/3 or 2^5</li>
 75		<li>Multiple-Choice</li>
 76		<li>Multiple-Answer</li>
 77		<li>Matching</li>
 78		<li>String</li>
 79		<li>Essay (not computer graded)</li>
 80		<li>Numerical Matrix</li>
 81		<li>Calculated Matrix</li>
 82		<li>Interval</li>
 83		<li>Calculated Interval</li>
 84		<li>N-tuples</li>
 85		<li>Drawing / Graphing</li>
 86		<li>File Upload</li>
 87		<li>Multipart</li>
 88		</ul>
 89	<li>Multiple display options and assessment settings, including an option for practice sets, and
 90	    due date exceptions for individual students</li>
 91	<li>Algorithmically generated questions, with a relatively simple-to-use question language 
 92	    (loosely based on PHP) with many built-in randomizers and display macros</li>
 93	<li>Group assessments</li>
 94	<li>Expandable question language, by installing additional macros</li>
 95	</ul>
 96<li>Other Course Management Features:</li>
 97	<ul>
 98	<li>Post text items, uploaded files, or web links to the classroom</li>
 99	<li>Discussion Forums, optionally gradable </li>
100	<li>Full gradebook with support for online and offline grades and flexible grading schemes</li>
101	</ul>
102<li>Administration:</li>
103	<ul>
104	<li>Flexible administration:  IMathAS can be centrally administered, 
105	    or teachers can be given rights to create their own courses</li>
106	<li>Teachers can be grouped by school or other division, with one or more group administrators</li>
107	<li>Courses can have one or more teachers</li>
108	</ul>
109<li>Mash-ups:</li>
110	<ul>
111	<li>Experimental support for <a href="http://www.imsglobal.org/community/forum/categories.cfm?catid=44">BasicLTI</a>, both as a consumer and producer</li>
112	<li>Google gadget for listing messages and forum posts</li>
113	</ul>
114</ul>
115
116<h4>Details</h4>
117For details on how the system works, look over the <a href="help.html">Help File</a> or view
118<a href="http://www.imathas.com/support.html">training and support</a> resources.
119
120<h3>Why a new system</h3>
121<p>You may be wondering why another system, when excellent systems already exist.</p>
122
123<p>For my purposes, WebWork and WIMS were too difficult to install (since I don't have direct 
124access to my school's webserver).  I didn't want to use commercial or publisher produced systems
125because I don't want students with used books to incur additional cost.</p>
126
127
128<h3>Installation</h3>
129<p>
130<ol>
131<li>Download IMathAS, extract it, and copy the files to your webserver.</li>
132<li>Alternatively, if you have shell access to your server, enter the directory you want IMathAS in,
133    and checkout the code from SVN:  <i>svn checkout http://imathas.googlecode.com/svn/trunk/</i>.   
134    Using SVN greatly simplifies upgrading.</li>
135<li>If your web host requires that you create databases through the web panel, create a database
136    and database user for IMathAS now.  If you have a username/password with database
137    creation priviledges, you can wait and use it later in the install process.</li>
138<li>Open a browser and access install.php.  This script will write the config.php file, change directory
139    permissions, copy distribution files, and set up the database.  At the end of the install you
140    will be given the opportunity to install a small set of example questions.  <i>Note</i>: 
141    If you are running on a Windows server, you may need to set directory permissions manually.</li>
142<li>Log into IMathAS.  If you didn't change the
143    initial imathas user settings when running install.php, log in as 'root' with password 'root'. 
144    If you did not change the inital imathas user settings, click the "Change Password"
145    link now to change the password to something substantial.  Alternatively, you can
146    go into the Admin page, create a new user with Admin rights, then delete the 'root'
147    admin.</li>
148<li>Edit loginpage.php and infoheader.php if desired.  If you plan to use the new instructor account 
149    request page, edit newinstructor.php</li>
150</ol>
151</p>
152
153<h3>Installation Issues/Troubleshooting</h3>
154<p>
155<ul>
156<li>If you receive an 500 access error trying to access install.php, try deleting the .htaccess file in the
157    IMathAS root directory.  This file is used to give some advice to the web server about file compression 
158    and file types, but could potentially cause problems depending on the server configuration</li>
159</ul>
160</p>
161
162
163<h3>Upgrading</h3>
164<p>If you are upgrading from IMathAS 1.6 or later, access update.php to install any new database changes
165and learn about any other changes necessary.  If you are upgrading from a version earlier
166than 1.6, you'll need to manually apply changes from the upgrade.txt file.
167</p>
168
169<h3>System Requirements</h3>
170<h4>Versions</h4>
171<p>PHP 5 and MySQL 4+ are recommended, and required from some features.  
172Most of the system will work with PHP 4.2+
173and MySQL 3.23, but future compatibility is not guaranteed.</p>
174<p>PHP with GD2 and Freetype are recommended for best image-based graph support</p> 
175
176<h4>Server Requirements</h4>
177<p>An installation serving 3500+ students 
178with 100+ concurrent users has operated well on a commercial shared web server.</p>
179
180<h4>Security</h4>
181<p>IMathAS uses a standard databased-stored sessions-based system.  If a user does
182not log out, the session is cleared from database after 24 hours.</p>
183
184<p>Questions (written by teachers) are passed through an interpreter that only allows 
185authorized functions to be used.  Student answers are evaluated client-side using
186JavaScript, and are never evaled server-side.</p>
187
188<h3>Install Notes</h3>
189<p>
190The install.php script automatically handles the following install steps.  They're 
191listed here in case anything goes wrong:
192<ul>
193<li>Change permissions (chmod) of the following directories to allow the webserver process
194    to write to the directories: 
195    	<ul>
196	<li>assessment/libs</li>
197	<li>assessment/qimages</li>
198	<li>admin/import</li>
199	<li>course/files</li>
200	<li>filter/graph/imgs</li>
201	</ul>
202	<br/>
203    <i>Note</i>: If you are running on a Windows server, you may need to set directory permissions manually. <br/>
204    <i>Note</i>: For security, the admin/import directory should not be web-readable.  A .htaccess file is included to
205       prevent access.  If your server doesn't obey .htaccess files, you may need to do additional tweaking. </li>
206<li>Rename (in the main directory):
207	<ul>
208	<li>config.php.dist to config.php</li>
209	<li>infoheader.php.dist to infoheader.php</li>
210	<li>loginpage.php.dist to loginpage.php</li>
211	<li>newinstructor.php.dist to newinstructor.php</li>
212	</ul></li>
213<li>Edit config.php.  Change these options to your liking:</li>
214	<ul>
215	<li>$dbserver:  The address of your database server.  Probably www.yoursite.edu or localhost</li>
216	<li>$dbname:  The name of the IMathAS database</li>
217	<li>$dbusername:  The username of the IMathAS database user.</li>
218	<li>$dbpassword:  The password for the IMathAS database user.  Choose something really complicated</li>
219	<li>$installname: The name of your installation, for personalization.</li>
220	<li>$longloginprompt:  How you want to prompt new students for a username</li>
221	<li>$loginprompt:  How you want to prompt students for a username</li>
222	<li>$loginformat:  Enforce a format requirement on the username</li>
223	<li>$emailconfirmation:  If set to true, new users will have to respond to an email sent by the system 
224	    before being able to enroll in any classes</li>
225	<li>$sendfrom:  An email address to send confirmation and notification emails from.</li>
226	<li>$imasroot:  The web root of the imathas install (ie, http://yoursite.edu $imasroot)</li>
227	<li>$mathimgurl: An absolute path or full url to a Mimetex CGI installation, for math image fallback</li>
228	<li>$colorshift:  Whether icons should change colors as due date approaches.  I thought this was cute, 
229	    but others might find it annoying</li>
230	<li>$smallheaderlogo: Text or an HTML image tag for a small (120 x 80) logo to display at the top right of
231	    course pages</li>
232	<li>$allownongrouplibs:  Whether non-admins should be allowed to create non-group libraries.  
233		On a single-school install, set to true; for larger installs that plan to
234		use the Groups features, set to false</li>
235	<li>$allowcourseimport:  Whether anyone should be able to import/export questions and libraries from the
236	    course page.  Intended for easy sharing between systems, but the course page
237	    is cleaner if turned off.</li>
238	<li>$allowmacroinstall:  Whether admins should be able to install macro files.  Macros files hold a large 
239	    security risk, and should only be installed from trusted sources.  For a single-admin system, it is 
240	    recommended that you leave this as false, and change it when you need to install a macro</li>
241	<li>$sessionpath:  change the session file path different than the default.
242	    This is usually not necessary unless your site is on a server farm, or 
243	    you're on a shared server and want more security of session data</li>
244	<li>$mathchaturl:  a URL to the live chat server.  Leave unchanged to use the local install's
245	    server.  Comment out to disable the chat server.  You can also use a different install to
246	    offload chat on a different server</li>
247	<li>$enablebasiclti:  Set to true to enable use of IMathAS as a BasicLTI producer.</li>
248	<li>$AWSkey,$AWSsecret,$AWSbucket:  To allow students and teachers to upload files through
249	    the text editor, and to enable file upload questions, this specifies an Amazon S3
250	    key, secret, and bucket to use for file storage.  Local storage is not yet implemented.</li>
251	</ul>
252<li>Run the dbsetup.php script (access http://yoursite.edu $imasroot/dbsetup.php), or send it 
253    to your system administrator and ask them to run it, if you don't have creation access
254    to the database server.  Alternatively, have your system administrator create a database and database user,
255    and use these names in the config.php file before running dbsetup.php.  This script sets up the necessary database user, database, and tables for IMathAS.</li>
256
257</ul>
258</p>
259</body>
260</html>