Syntax Untangler Files

Syntax Untangler readme file

Revision date: August 13, 2015

***
*** Server Requirements
***

Any industry-standard LAMP (Linux/Apache/MySQL/PHP) server will probably do. Syntax Untangler 2.0 was originally developed in a pretty conservative, locked-down shared-hosting environment that had Apache 2.0, PHP 5.1.6, and MySQL 5.0.77. Slightly older versions of those software would probably also allow Syntax Untangler to work as-is.

***
*** How to Upgrade from version 2.3 or earlier to version 2.4
***

1. Replace all the Web server files with their newest versions included in the 2.4 release. You may delete all files dating from the 2.3 release that are no longer included in the 2.4 release.

2. Use your PHP database administrative tool to run the following MySQL queries to update your database:
ALTER TABLE `questions` ADD `allowSkip` ENUM('T','F') NOT NULL DEFAULT 'F' AFTER `questionID`;
INSERT INTO `feedbackTypes` (`feedbackTypeID`, `feedbackType`, `sortOrder`) VALUES (12, 'Already did that part correctly.',12);

3. If you prefer to update your serverSettings.php file manually instead of replace it with the new version and then manually re-configure the new version with your preferred settings, these are the manual changes to make:
Line 2: define('VERSION','2.4');
Line 44: define ('COUNT_OF_FEEDBACK_TYPES',12); 

4. Log in into your admininistor account in the S.U. Instructor Tools Web application, and add default values for the new feedback type "Already did that part correctly." See step #8 below for suggested texts to use.

***
*** How to Upgrade from version 2.2 or earlier to version 2.3
***

In addition to the usual task of replacing all the Web server files with these new ones (and note that some old files were removed from use), you must do the following:

1. In your MySQL database, drop the old `feedbackTypes` table and use both the table-creation and table data-insertion queries in the file "untangler.sql" to create and populate the new table.

2. Run this MySQL query to update your `units` table structure:
ALTER TABLE `units` ADD `stripEdgePunctuation` ENUM( 'T', 'F' ) NOT NULL DEFAULT 'T';

3. Log in into your admininistor account in the S.U. Instructor Tools Web application, and add default values for the new feedback types. See step #8 below for suggested texts to use.
 

***
*** How to Install from Scratch
***

1. Create a blank MySQL database on your Web server

2. Import the file /untangler.sql into your blank database.

3. Edit the /serverSettings.php file to match your server file locations.

4. Follow the instructions in the comments in serverSettings.php to create a separate settings file in some secure location on your Web server that contains your MySQL connection information to the database you just created. Ideally a "secure location" is someplace outside your httpdocs folder, i.e., not accessible to an attacker approaching from the Web.

5. Place all the Syntax Untangler files in an appropriate spot on your Web server except, of course, for the following:
- /ReadMe.txt
- /untangler.sql

6. Use a browser to surf to the .../instructor/ page of the site you just created.

7. Create yourself a Syntax Untangler instructor account that will be the owner of the system-wide default text messages used in the Syntax Untangler game. This should not be an account that will ever be used by an actual instructor to create their own S.U. content.

8. Log in with that "admin" account and create an empty dummy unit, just so that you can see the "Set Default Feedback Messages" and "Set Default Mechanical Instructions" buttons. Suggested values for default message texts are:

Type: Successful completion of entire question
Text: Correct!

Type: Got a correct answer in a multi-part question.
Text: You got part of the answer, keep going!

Type: Completed this unit.
Text: Great! You completed this unit!

Type: Selection's left edge is correct
Text: You found where it starts!

Type: Selection's right edge is correct
Text: You found where it ends!

Type: Selection is correct, but for a different tag.
Text: Well, that would be right for a different tag.

Type: Selection contains no parts of any answer
Text: Your selection did not include any part of an answer.

Type: Selection contains at least part of one answer.
Text: Almost: that covers at least part of one answer.

Type: Selection is too big. Spans more than one answer.
Text: Your selection includes more than one answer. Take care to separately identify each part.

Type: Next question.
Text: Next question ->

Type: Forgot to select a tag first
Text: Please choose a tag before tagging any words.

Type: Already did that part correctly.
Text: Correct again. Look elsewhere for other correct answers.


Mechanical Instructions

Highlight: Click and drag in the text - or double-click - to select your answer(s).
Tag: Click a tag. Then highlight the corresponding answer in the text.

9. Look in the database and edit the appropriate spot in /serverSettings.php to record what the userID is of the "admin" account you just set up. This is how SU knows that that the above messages should be used system-wide as default texts when an instructor doesn't specify their own texts.

10. All done. Start using it!