Description v 4.0
--------------------------------------------------------------------------------

An advanced mutiple choice quiz plugin for Buzztouch.
This plugin supports a few features that the free Buzztouch plugin does not.

The text views for the question and answers are dynamically sized. This means
that the text view size is based on the amount of text inside of it. The view size
changes when going from one question to the next. With this plugin you no longer
need to worry about the amount of text in your quiz, or the font size.

This plugin uses a scroll view to display the questions and answers. Because the
text views can resize them selves there is no guarantee that the questions and
answers will fit on the screen. A scroll view is used to make sure the app user
can see the entire question.

In the free quiz plugin the question text and question image are in the same view
(or box). This plugin uses separate views for the question text and image.
The plugin will also dynamically insert and remove the image view based on
whether or not each individual question has an image or not.

Supports device rotation. When the device is rotated the views will resize
themselves to fit the screen. This includes the image view. Up to 4 different
image sizes can be used depending on the device (iPhone or Ipad) and its
orientation (portrait or landscape).

The plugin uses a feature called Autolayout. Autolayout is new in iOS 6 and will not work with
older versions if iOS. Some older devices are supported so long as they have been
upgraded to use iOS 6.

Game Center integration is built into the control panel.

Share scores via Email, Twitter, and Facebook. Enable sharing from the contral panel.

Advanced screen data section now allows you to store your quiz data locally on the device.
The option to store data online is still there.

Select between 2 and 20 answer boxes. Want to make a true/false quiz? Just set
the 'Number of Answer Boxes' in the control panel to two.


iOS Project
--------------------------------------------------------------------------------
iOS 6 +
This plugin uses a feature called Autolayout which is only supported in iOS 6 and above.
Set Deployment Target to 6 or higher
Required:
Mac with OSX 10.7.4 (Lion) or higher.
Xcode 4.3+
GameKit.framework



Files included are:
NAD_advanced_quiz.h
NAD_advanced_quiz.m


Android Project
--------------------------------------------------------------------------------
Buzztouch 3.0

Files included:
NAD_advanced_quiz.java
NAD_advanced_quiz.xml


Setting up the Nav bar
------------------------
In your control panel under Core->Allow/Prevent rotation select 'All devices allow rotations'.
Then hit save.


Change log
-----------------------
v1.0 Original
v1.1 Added some text to the Readme.
     Removes _autolayoutTrace from .m file to avoid Apple rejection.
     Added image of CP to the screen shots. screen-3.png
v1.2 Select the number of answer boxes from inside the control panel. Between 2-5.
          Added 'Hide from Search Results' to the control panel.
v1.3       Added UIAlert to twitter and fb sharing in case the end user is not logged into those accounts.
          Removed timer from final label when the timer is disabled from the CP.
          Added background audio option to CP.
          Added require login option to CP.
v1.4       Fixed crash when question text is left blank.
          Fixed issue with timer disapearing.
          Fixed issue with 5th answer button having no background color.
          Added optional explanation screen.
          Added option to disable vertical scroll bar.
          Added question # to the Nav Bar title (ex. 1 of 4).
          Added ability to set the top bar background color.
          Added ability to set score font color.
          Added ability to set timer font color.
          Added ability to reset the timer after each question.
v1.5       Fixed issues with sounds playing at the wrong times.
v1.6      Added percent field to score result
          Added passed field to score result
          Added simple text based explanation screen based on alert view.
v1.7      Changed it so that the number of answer boxes can change from question to question.
v1.8      Fixed issue with the number of answer boxes not being backward compatible.
v1.9      Fixed deprecations in Game Center due to changes in iOS 7
v2.0       Fixed issue with advanced screend data not cacheing properly.
v2.1       Replaced BT version 2 files.
v2.2 Put the (global) number of answer boxes field back into the control panel
          A previous upgrade moved the location of number of answer boxes to
          the child items. This broke some active apps. This fix is for the control panel only.
v2.3       Fixed issue with errant button showing up in the right navbar.
          Fixed issue with control panel not accepting Finished Screen input.
v2.4      Expands the number of answer boxes to 20.          
v2.5       Fixes broken parts from v2.4 update. Specifically with new answer boxes and image.
v2.6       Adds Android version.
v2.7 Fixed animation isssue in iOS version.
v2.8 Added new screenshot subfolders for btgo upgrade. Fix control panel div error.
v2.9 Refactoring of iOS code.
v3.0 Fixes problem with question number not showing up.
Fixes problem with crash related to facebook sharing.
v3.1 Fixes blank screen issue with xcode 6 and iOS 8 (major fix)
v4.0 Updated for new buzztouch 4.0

JSON Data
------------------------
{
"itemId": "4089C9AE47419BEBD8A8E29",
"itemType": "NAD_advanced_quiz",
"itemNickname": "quiz 1a",
"navBarTitleText": "quiz 1",
"navBarBackgroundColor": "666666",
"navBarStyle": "solid",
"navBarRightButtonTapTransitionType": "flip",
"number_of_answers": "",
"number_of_questions": "4",
"randomize_question_order": "0",
"show_correct_answers": "1",
"show_incorrect_answers": "1",
"delay_between_questions": "1",
"button_color_correct": "#00FF00",
"button_color_incorrect": "#FF0000",
"show_timer": "1",
"show_score_box": "1",
"points_per": "1",
"passing_score": "90",
"corner_radius": "8",
"reset_timer": "0",
"disable_vert_scroll_bar": "0",
"topBar_backg_color": "#FFFFFF",
"question_background_color": "#FFFFFF",
"button_color_answers": "#FFFFFF",
"exp_transition_type": "fade",
"enableGameCenter": "1",
"GCleaderBoardID": "LeaderBoardID",
"GCAchievmentID": "AchievmentID",
"GCAchievmentPoints": "50",
"GCAchievmentBannerTitle": "Good Job",
"GCAchievmentBannerMessage": "You Win",
"share_via_email": "1",
"emailScoreSubject": "Hey there",
"emailScoreMessage": "This is my quiz score",
"share_via_tmFB": "1",
"tmFBText": "Hey There this is my quiz score",
"tmFBImageName": "appIcon.png",
"tmFBURL": "http://myapp.com",
"share_via_tmTWT": "1",
"tmTWTText": "Hey There, This is my quiz score.",
"tmTWTImageName": "appIcon.png",
"tmTWTURL": "http://myapp.com",
"finished_screen_nickname": "menu",
"show_reward": "1",
"reward_screen_nickname": "menu",
"text_just": "left",
"font_color_timer": "#000000",
"font_color_score": "#000000",
"font_color_question": "#000000",
"font_color_answers": "#000000",
"font_size_questions_small": "15",
"font_size_answers_small": "18",
"font_size_questions_large": "25",
"font_size_answers_large": "30",
"correct_sound": "purr.mp3",
"incorrect_sound": "glass.mp3",
"sound_effect_finished": "finished.mp3",
"sound_effect_reward": "reward.mp3",
"backgroundColor": "#666666",
"includeAds": "0",
"hideFromSearch": "1",
"loginRequired": "0",
"hideTabBarWhenScreenLoads": "0"
}


Required Fields
-------------------------------------------------------------------------------------
1. Finished screen needs to be filled in so that the app knows which screen to open when the quiz is done and the continue button is pressed.
2. Number of Questions needs to be filled in. The number of questions can be less than or equal to the amount of quiz questions entered into the plugin.




Adding quiz Data:
-------------------------------------------------------------------------------------
Quiz data can be stored in a separate text file.
This text file needs to be in VALID JSON format. Use JSONlint.com to verify your files.
Quiz data text files are then stored locally in your project, by dragging and dropping
the file into the BT_Docs folder of your iOS project. The file name is then entered into
the control panel. The corresponding JSON field is "dataURL":"".
Or, the quiz data text file can be stored online. Enter the URL into the control panel.
Please verify that your app can access your online file.


{
"childItems": [
{
"itemId": "",
"itemType": "",
"questionText": "",
"number_of_answers": "",
"correctAnswerText": " ",
"incorrectText1": " ",
"incorrectText2": "",
"incorrectText3": "",
"incorrectText4": "",
"incorrectText5": "",
"incorrectText6": " ",
"incorrectText7": "",
"incorrectText8": "",
"incorrectText9": "",
"incorrectText10": "",
"incorrectText11": " ",
"incorrectText12": "",
"incorrectText13": "",
"incorrectText14": "",
"incorrectText15": "",
"incorrectText16": " ",
"incorrectText17": "",
"incorrectText18": "",
"incorrectText19": "",
"incorrectText20": "",
"isImageIncluded": "",
"ImageNameIphonePortrait": "",
"IphonePortraitHeight": "",
"IphonePortraitWidth": "",
"ImageNameIphoneLandscape": "",
"IphoneLandscapeHeight": "",
"IphoneLandscapeWidth": "",
"ImageNameIpadPortrait": "",
"IpadPortraitHeight": "",
"IpadPortraitWidth": "",
"ImageNameIpadLandscape": "",
"IpadLandscapeHeight": "",
"IpadLandscapeWidth": "",
"exp_screen_enable": "1",
"exp_screen_text": "Hey there",
"exp_screen_nickname": ""
},
{
"itemId": "",
"itemType": "",
"questionText": "",
"number_of_answers": "",
"correctAnswerText": " ",
"incorrectText1": " ",
"incorrectText2": "",
"incorrectText3": "",
"incorrectText4": "",
"incorrectText5": "",
"incorrectText6": " ",
"incorrectText7": "",
"incorrectText8": "",
"incorrectText9": "",
"incorrectText10": "",
"incorrectText11": " ",
"incorrectText12": "",
"incorrectText13": "",
"incorrectText14": "",
"incorrectText15": "",
"incorrectText16": " ",
"incorrectText17": "",
"incorrectText18": "",
"incorrectText19": "",
"incorrectText20": "",
"isImageIncluded": "",
"ImageNameIphonePortrait": "",
"IphonePortraitHeight": "",
"IphonePortraitWidth": "",
"ImageNameIphoneLandscape": "",
"IphoneLandscapeHeight": "",
"IphoneLandscapeWidth": "",
"ImageNameIpadPortrait": "",
"IpadPortraitHeight": "",
"IpadPortraitWidth": "",
"ImageNameIpadLandscape": "",
"IpadLandscapeHeight": "",
"IpadLandscapeWidth": "",
"exp_screen_enable": "1",
"exp_screen_text": "Hey there",
"exp_screen_nickname": ""
},
{
"itemId": "",
"itemType": "",
"questionText": "",
"number_of_answers": "",
"correctAnswerText": " ",
"incorrectText1": " ",
"incorrectText2": "",
"incorrectText3": "",
"incorrectText4": "",
"incorrectText5": "",
"incorrectText6": " ",
"incorrectText7": "",
"incorrectText8": "",
"incorrectText9": "",
"incorrectText10": "",
"incorrectText11": " ",
"incorrectText12": "",
"incorrectText13": "",
"incorrectText14": "",
"incorrectText15": "",
"incorrectText16": " ",
"incorrectText17": "",
"incorrectText18": "",
"incorrectText19": "",
"incorrectText20": "",
"isImageIncluded": "",
"ImageNameIphonePortrait": "",
"IphonePortraitHeight": "",
"IphonePortraitWidth": "",
"ImageNameIphoneLandscape": "",
"IphoneLandscapeHeight": "",
"IphoneLandscapeWidth": "",
"ImageNameIpadPortrait": "",
"IpadPortraitHeight": "",
"IpadPortraitWidth": "",
"ImageNameIpadLandscape": "",
"IpadLandscapeHeight": "",
"IpadLandscapeWidth": "",
"exp_screen_enable": "1",
"exp_screen_text": "Hey there",
"exp_screen_nickname": ""
}
]
}


Image Data: (IMPORTANT!!!)
--------------------------------------------------------------------------------------
Image files can only be stored locally inside of your project.
This plugin has no function for fetching your images online.

Drag and drop all image files into the BT_Images folder of your iOS project.

Images are assigned to individual questions. The plugin will figure out the proper
screen layout (image or no image) for you, so long as the JSON quiz image data
fields are filled out properly.

To include an image with question set the "isImageIncluded": "", field to 1, like so:
"isImageIncluded": "1",

Set this field to 0 or leave it blank to leave out the image.

If you set the "isImageIncluded": "", field to 1, then all of the following fields MUST be
given some value.

"isImageIncluded": "1",
"ImageNameIphonePortrait": "P538280.png",
"IphonePortraitHeight": "332",
"IphonePortraitWidth": "280",
"ImageNameIphoneLandscape": "P538440.png",
"IphoneLandscapeHeight": "521",
"IphoneLandscapeWidth": "440",
"ImageNameIpadPortrait": "P538700.png",
"IpadPortraitHeight": "829",
"IpadPortraitWidth": "700",
"ImageNameIpadLandscape": "P538980.png",
"IpadLandscapeHeight": "1161",
"IpadLandscapeWidth": "980"


The following fields are used for the image file names. Each field corresponds to
a certain device and/or orientation.
"ImageNameIphonePortrait": "",
"ImageNameIphoneLandscape": "",
"ImageNameIpadPortrait": "",
"ImageNameIpadLandscape": "",


The size of each image MUST be explicitly declared in height and width fields.

For instance, the image name P538980.png has a width of 980 pixels and a height of
1161 pixels. These dimensions need to be included in the JSON data.

"ImageNameIpadLandscape": "P538980.png",
"IpadLandscapeHeight": "1161",
"IpadLandscapeWidth": "980"


These fields have a maximum width based on the device or orientation.
There is no maximum height, but the height field still needs to be filled in.
This plugin supports up to four different image dimension sizes.
iPhone Portrait:
-Max width is 280 pixels
-Max height is any greater than > 0
iPhone Landscape
-Max width is 440 pixels
-Max height is any greater than > 0
iPad Portrait:
-Max width is 700 pixels
-Max height is any greater than > 0
iPad Landscape:
-Max width is 980 pixels
-Max height is any greater than > 0

You can re-use images so long as the width requirements are not violated,
and the image size is explicitly declared for each divice orientation.

Like so:
This configuration will only show a 280 width image for all devices
and orientations:

"isImageIncluded": "1",
"ImageNameIphonePortrait": "P538280.png",
"IphonePortraitHeight": "332",
"IphonePortraitWidth": "280",
"ImageNameIphoneLandscape": "P538280.png",
"IphoneLandscapeHeight": "332",
"IphoneLandscapeWidth": "280",
"ImageNameIpadPortrait": "P538280.png",
"IpadPortraitHeight": "332",
"IpadPortraitWidth": "280",
"ImageNameIpadLandscape": "P538280.png",
"IpadLandscapeHeight": "332",
"IpadLandscapeWidth": "280"

or:
This configuration is will take the largest image and shrink to a specific
size for each device and orientation. This is good for saving space inside
of your application. .PNG files only, no JPEG for this configuration.

"isImageIncluded": "1",
"ImageNameIphonePortrait": "P538980.png",
"IphonePortraitHeight": "332",
"IphonePortraitWidth": "280",
"ImageNameIphoneLandscape": "P538980.png",
"IphoneLandscapeHeight": "521",
"IphoneLandscapeWidth": "440",
"ImageNameIpadPortrait": "P538980.png",
"IpadPortraitHeight": "829",
"IpadPortraitWidth": "700",
"ImageNameIpadLandscape": "P538980.png",
"IpadLandscapeHeight": "1161",
"IpadLandscapeWidth": "980"


Image Notes:
.PNG is the preferred image format. JPG can be used but is not supported as well
in iOS.
If using .PNG files make sure the files are NOT 'interlaced'. iOS will not accept
interlaced png files.
The same image can be used in different questions. Only one copy of that image file
needs to be stored on the device.

Images for Android:
You only need to add the image name to the landscape portion (large and small) in the control panel.
The plugin will use the input in the Landscape fields for both landscape and portrait orientation in the app. The Android app does not reference the portrait orientation in the control panel.


Retina Displays
-------------------------------------------------------------------------------------
Be sure to include a second set of images for retina devices.
If you are using an image like p538980.png with dimension 980x1161. Then include
a larger copy of that image with dimensions 1960x2322 in your project.
Name this file the same as the original but with the @2x added to the end of the file name.
Like this: [email protected]
There is no need to enter this additional information into the control
panel or your quiz bank files. The iOS operating system will take care of using
the correct file.

Explanation Screens
------------------------------------------------------------------------------------
The explanation screen is a pop up view controller that shows up after the quiz user answers a question.
This popup allows you to provide a detailed explanation of the question and answer set after each question is answered.
For your explanation screen you can use one of three html based plugins.
1. The htmlDoc plugin. Usefull for storing the html file locally in the project. Does not refresh.
2. The Custom URL plugin. Usefull for using a remote document. Always refreshes when it loads. Does not cache the document locally.
3. The Custom HTML plugin. Comes with its own document editor.
(hint: The dataURL from the Custom HTML plugin can be used in the Custom URL plugin)

Required: For whichever plugin you choose to use, set the Nav Bar Style to solid.
The Nav Bar contains the back button, which is needed to get back into the quiz.

Recommended settings for the html plugin/ explanation screen.

In the Nav Bar section:
Nav Bar Title - any - Recommended
Nav Bar Background color - NOT recommended.
Nav Bar Style - Solid - Required.
Nav Bar Right button type - NOT recommended.

In the Document Behavior Section:
Show Browser Back Button - NOT recommended.
Show Browser Refresh Button - NOT recommended.
Show Launch in Native App Button - NOT recommended.
Show email Document Link - any
Force Refresh - depends on the plugin. Do not use with the HTML Doc plugin.
Detect Phone/Address Links - NOT recommended.
Prevent scrolling - any
Hide Vertical Scroll Bar - any
Hide Horizontal Scroll bary - any
Prevent scroll bounce - any
Prevent All interation - yes - Recommended.

In the Audio section
Background Audio - NOT recommended. Set the background audio in the quiz plugin, but leave it alone in the explanation doc.

//end recommended settings section.


Adding Sounds
-------------------------------------------------------------------------------------
Sound files cannot be downloaded from a URL. They must be stored locally in the
project.
Drag and drop all sound files into the BT_sounds folder.
BT_loadConfigDataViewController.m

Some sounds to use here.
dl.dropboxusercontent.com/u/2452503/buzztouch_screen_shots/sounds.zip

To add a sound of you own to the project, add the following code to the file:
BT_loadConfigDataViewController.m
around line 402:

[appDelegate.soundEffectNames addObject:@"mySound.mp3"];

mySound.mp3 being the name of the sound file that you want to use.
Be sure to drag this file into your project.

Enter a file name for a sound into the following fields.
"correct_sound":"",
"incorrect_sound":"",
"sound_effect_finished":"",
"sound_effect_reward":"",

These fields can be left blank. In which case no sound is played for that
specific event.


Background Patterns
---------------------------------------------------------------------------------
Patterns are small 'tile-able' images. Enter the pattern file name in your CP.
Then drag and drop you pattern file into your BT_images folder inside of Xcode.
Be sure to include an additional retina image, using the same file name but
with @2x added to the end of the name.
Free Patterns:
tileabl.es
subtlepatterns.com/
Example site:
www.bobmccune.com/2011/03/08/ios-101-pattern-images/