Building Quizzes with SQuiz3

To start all kinds of items find the SQuiz menu on top of the WordPress menu.

2016-08-17 09_49_16-SQuiz Menu

Select New SQuiz Item. The form will open and you must input the basic data. That is:

  1. a title
  2. item type and template
  3. button labels ( bottom of the page )
  4. decide if you want to randomize questions, show review at end (only quizzes), time limit and passing score.

2016-08-17 09_53_46-Edit SQuiz Item Type and Template

After that you have to save the quiz otherwise you cannot add questions.

You should have already created some questions for your quiz, otherwise you must do that now.

Adding Questions

2016-08-10 15_03_48-Edit SQuiz Item-question_map

Questions on the left side are available, on the right already assigened to this quiz. Simply drag questions to the right to add them, click the remove button in the upper right corner to remove them from the list.

You can filter the available questions by category and type. Every update of this list will be saved dynamically by AJAX.

In case of polls you can add more than one question, but this don’t has any effect to the frontend: Only the first question will be available for the visitor.

Ending

You can add some information and text add the end. Use following placeholders to insert information:

  • {passing score} : Predefined passing score
  • {result score} : Predefined passing score
  • {correct} : Correct answered questions
  • {question count} : Overall question count
  • {question answered} : Answered questions by user
  • {time} : Time user needed to complete the quiz

2016-08-17 10_58_36-Edit SQuiz Item Quiz ending

If you leave this empty, nothing will be displayed after voting.

An optional review button will be added automatically if you check ‘Show Review’ in quiz options

Installation

SQuiz3 and sk-library Installation

The download archive contains to plugins: SQuiz3 and sk-library.
You must install both within the wordpress plugin panel. Activate first sk-library and then SQuiz3. Activation process of SQuiz3 will install the necessary database tables.

SQuiz 3 contains an update checker so that you will be informed about plugin or library updates.

IMPORTANT

For all purchasers of WP SQuiz in older versions (2.x): You MUST deactivate and delete the SQuiz and SQuiz User Plugin. Old and new Version are not compatible.

Deleting the old version don’t affect the database so that you can import old quizzes to the new plugin. An update script will be available soon.

 

Templates

SQuiz 3 uses the TWIG template engine. Most outputs are generated by the template engine so that you are able to customize it by creating your own templates.

Quiz items will get the template parameter through settings in the quiz edit page.

Templates for emails send from Evaluation area can be selected in the options menu on the result detail page.

All templates are located in /SQuiz/templates, quiz item templates have own folders with multiple template files for each layout part. A full set for quizzes look like this:

2016-08-16 12_33_17-squiz3-standard-template

If you want to build your own you have not to create each template part. All parts you omit will be searched in /standard. Learn more about Template Overloading.

Basically contain templates simple html code. Every dynamic output generated by php is enclosed with double curly braces {{ my_var }}.

Every programatically stuff is enclosed in curly braces and percent signs. For example:

<div class="squiz_checkbox_container">
    <input type="checkbox" name="quizdata[question_{{ item.id }}_{{ question.id }}]"
               id="quizdata_question_{{ item.id }}_{{ answer.id }}"
               data-question="{{ question.id }}"
               data-answer="check"
               class="squiz_checkbox squiz_hide" value="{{ answer.id }}" />
    <label for="quizdata_question_{{ item.id }}_{{ answer.id }}" class="squiz_label squiz_label_checkbox">
        {{ answer.text|raw }}
    </label>
</div>

This is the answer_checkbox template. You can make a copy into a new folder and change everything in this template but you must include the dynamic outputs as seen in the example above. If there is something missing like data-question tag or name tag of the input field the quiz item won’t work.

As you can see in the label tag there is as content answer.question and divided by a pip a modifier ‘raw’. This causes the text is displayed as is – html code will be put out  as html and not as text.

Be careful: Do not customize basic templates delivered with this plugin.The next update will override your changes. Make a copy of an email template respectively copy a folder and make your additions or changes there.

More about Twig can be found here.

Shortcodes

There are two shortcodes available:

  1. ([) squiz id=3(]) and
  2. ([) squiz-topten id=3 count=10 month=2 year=2016 show_user=1(])

1.) This is the basic shortcode to display all kinds of items and it takes no other arguments than the item (quiz) id. It will display the item using the predefined template.

2.) To display a list of participations use this shortcode whereby following arguments are allowed:

  • id = the item id
  • count = integer number of entries to display
  • month = integer the month of participation
  • year = the full year of participation
  • show_user = integer (0/1) show the user name or not (=0)

You can omit every argument except the id. Default values will be:

count = 10
show_user = 1
month and year = 0 (show all)

To display the list the template named top_ten.twig is used.

Discover more about Templates and Template Overloading.

 

New Features

As we said, there are a lot of new features in SQuiz 3. See them here in detail:

New Items: Polls and Surveys

First to say there are two new item types: surveys and polls. They are slightly different from quizzes. Polls could have only one choice question (btw. you can add more but they won’t be visible), surveys have only a aggregated evaluation. You drill down to a single users participation. Beside that polls show up only if the user not already voted (today) this poll, otherwise the result is shown directly.

2016-08-12 19_34_09-SQuiz 3 –poll result

Surveys in opposite to quizzes can’t have a review at end.

New Question Types: Plain Text and Cloze Text

We added a plain text question where the user must type word by word – character by character exactly what you defined in the question editor. But more important is the usage of this type in surveys. There user can input free text as they like.

The new cloze text question type will enhance your quizzes. You can write long texts with so much gaps as you need. The user input will be compared character by character for each gap and the user gets only his point if all gaps are correctly filled in.

Rewritten: Review Mode

The review mode is completely rewritten and enhanced. If you set ‘Show Review’ to ‘on’ in the quiz editing page users get at the end a review button. By clicking this they can go through the complete list of questions, see their answers and the correct ones and additionally an explanation (but only if you wrote one).

2016-08-16 13_17_19-PHP Quiz – Review - Skurrilewelt

New: Explanations

Questions now can have an explanation text. This text will be used in reviews to explain the question in detail (if you want that)

2016-08-16 13_12_06-PHP Quiz - Review – Skurrilewelt

New: Templates

The quiz, survey or poll output on the screen is generated by the template engine Twig. The plugin contains a set of three templates for the three item types.

Customizing this is easier as you think: In most cases a new css file with a few styles is enough to create your unique look. Therefor it is sufficient to create a new template folder (yes: empty!) and the stylesheet in another specified folder. Ready with that. The template engine loads missing templates from the standard folder – you must not care about that. For more information please read the docs.

Better: Item editing

A new question section in the quiz editing view facilitates the selection of questions and improves clarity. Questions and associated filter buttons are colored, additionally you filter by category as combined filters.

Editing answers is also improved: you get to edit responses the visual editor so that now HTML and media files possible answer content.

2016-08-10 15_03_48-Edit SQuiz Item-question_map

Statistics and Evaluation

The stats section is completely renewed. All item types have their specific evaluation.

Quizzes are well organized in a accordion and in there a  sortable table with pagination and filter with the participations. Every participation can be viewed in a details version and gives you information about all questions a user answered, if he has passed or not and so on. You can mail this detail view directly to the user if you like.

All tables and evaluations can be exported with a single click to csv. You can choose between export of a filtered list or the complete result list.

2016-08-12 07_59_21-Statistics Quiz

2016-08-12 08_03_43-Statistics Export Options

Quiz evaluation can be drilled down to a single user participation. You can see a complete review of a single quiz on one page. Additionally you can send a copy of that via email to the user.

2016-08-17 08_04_42-Statistics singel quiz user details

As you see above you can choose between two export options:

Popup and Mail

The popup will give you the html markup as seen on this page. The mail option sends an email build on choosen template ( see Templates ) to the specified email address. If a logged in user makes a quiz his data will be available here otherwise you have to input data manually.

If you have any suggestions about new features please leave a comment.

Overview

System requirements

Frontend

  • Modern html5 browser
  • Cookies enabled
  • Javascript enabled

Backend / Server

  • Client with modern browser, javascript and cookies
  • MySQL database (mandantory for wordpress also)
  • PHP 5.4 or newer
  • WordPress 4.5.x or newer (older versions maybe also ok but we offer no support for them)

Features

  • Three item types: Quiz, Survey and Poll
  • Five question types: Single choice, multiple choice, order, cloze and free text.
  • Template engine and templates for all items. Template overloading and fallback for missing elements.
  • Randomizing questions as option per item.
  • Detailed evaluation and statistics with multiple export options.
  • Detailed quiz review for end user after completing a quiz.
  • Database time control for quizzes with time limit.
  • Internal session management to manage page reloads on all items.
  • Full visual WordPress editor for questions and answers.
  • Questions can be assigned to categories.
  • Multiple filter for questions on edit quiz pages.
  • Save deleting of quiz items and questions: SQuiz will check if questions are in use or quizzes are part of any evaluation or statistic.

The difference between quiz, survey and poll can be found mainly in the evaluation. Only quiz evaluation has the possibility to drill down to single user participation. Poll and survey  participations are only visible as aggregated data.

Another restriction with polls is that you can have only one choice question. Additionally a hashed ip is saved in an internal session for participation so that a visitor only can vote once a day. When reloading the page the result will shown up.

Basically SQuiz starts an internal session based on a client cookie if a visitor starts a quiz, survey or poll. So user must accept cookies to participate, otherwise quizzes wont work. The cookie only contains a single number – this is the id to the internal session. There is no security issue, neither for the visitors nor for the system. The session will be deleted if it has expired (one day) or if the cookie on the client is missing.

All this is necessary to save a visitors state. If he reloads the page while playing a quiz the quiz will continue exactly where it was before reloading. So he don’t lost answered questions when he unintentionally reloads the page or the browser gets stuck at any point. In case of polls this should avoid multiple participations by one visitor.

Customizing basic layout and styles is easy. You only have to override parts of a template with your own template and add a new stylesheet file. Please read more about Templates and Template Overloadiung.

Building Polls with SQuiz3

Start with New Squiz Item from the SQuiz menu.

2016-08-17 09_49_16-SQuiz Menu

The form will open and you must input the basic data. That is:

  1. a title
  2. item type and template
  3. There is only one nav button necessary: the Start Button. You should label it with ‘vote’ or something like that. ( bottom of the page )
  4. decide if you want to randomize questions or have a time limit.

Review at the end, passing score, randomize questions and time limit are obviously not suitable. Leave them off or 0.

After that you have to save the poll otherwise you cannot add the question.

Polls could have only ONE question. This question MUST be of type choice otherwise you won’t see anything.

You should have already created a question for your poll , otherwise you must do that now. You can use the same questions as for the quizzes and surveys. User votes will be aggregated in evaluation.

Add Questions

see Build Quizzes

Ending

Polls should have a overview about all votes at the end. You can use the placeholder

  • {poll participations} : Number of counted votes
  • {poll result} : The result diagramm

all others are not suitable.

2016-08-17 10_58_36-Edit SQuiz Item Poll ending

If you leave this empty, nothing will be displayed after voting.

Building Surveys with SQuiz3

Start with New Squiz Item from the SQuiz menu.

2016-08-17 09_49_16-SQuiz Menu

The form will open and you must input the basic data. That is:

  1. a title
  2. item type and template
  3. button labels ( bottom of the page )
  4. decide if you want to randomize questions or have a time limit.

Review at the and and a passing score is obviously not suitable. I don’t know if a time limit makes sense because the survey will end automatically if time has elapsed.

After that you have to save the survey otherwise you cannot add questions.

You should have already created some questions for your survey , otherwise you must do that now. You can use the same questions as for the quizzes and polls. Difference will be in evaluation. No answer will be considered as correct, every answer will be counted and listed aggregated in the evaluation.

2016-08-17 10_50_16-Statistics Survey Aggregation

Adding Questions

Surveys are different from quizzes because there are no correct answers. To get Questions were the user can choose more than one answer you have to mark all possible answers as correct.

To get a single choice question (such as true / false) leave all correct checkboxes unchecked – the user can only select one answer.

Further information about adding answers here.

Ending

Add some text to say goodbye to your visitor or let him know some statistics. Use the placeholder as described on top of this box.

2016-08-17 10_58_36-Edit SQuiz Item Quiz ending

This is an example for a quiz ending but you can use the placeholders similar to that.

SQuiz 3

Hello out there.

We are proudly present the completely new written WordPress Quiz Plugin SQuiz 3. Development is nearly finished, now we run intensive tests and do a little bit finishing.

There are a lot of new features and a better user interface. This version gives you three types of squiz items:

  • Quiz
  • Survey
  • Poll

and five types of questions:

  • Single Choice
  • Multiple Choice
  • Order
  • Cloze
  • Text

Statistic and evaluation is now enhanced, with filterable tables, export functions and diagrams.

The frontend uses the TWIG templating engine. You can create as much templates as you need, to let the layout follow your quiz or survey. SQuiz uses the template overloading mechanism, so that you only need to customize the parts you really need.

Because of the completely rewritten engine this is installed as a new plugin and NOT as update. The database structure differs so that you can not use old questions and answers out of the box.

The codecanyon.com review process will start soon.

Are you interested in SQuiz3

You must select an option
If available, would you purchase SQuiz3?

Template Overloading

The frontend is driven by the template engine Twig. Examples and docs can be found here: http://twig.sensiolabs.org/documentation.
All templates can be found in \[plugin_dir]\templates, every template group in his own directory.

If you want to create your own, create for a new folder (name without umlauts, white spaces and special characters, only [a-z 0-9 -_]).
From now on you can access this new template in the SQuiz edit screen (right sidebar Templates) and you can assign it to a quiz.
You must not but you can copy and customize template parts from the standard, poll or survey folder.

Additionally you must create a style sheet file in \[plugin_dir]\assets\css which must be named like this:

squiz_frontend_[template directory name].css

As you can see, that the template directory name must follow the rules for valid unix filenames.

This stylesheet will be loaded after the standard stylesheet, so that you can overwrite the standard styles as you like. Btw. the standard frontend stylesheet will be loaded even if you use another template for a certain quiz. Missing template files (in your custom template folder) will be searched in standard so that is a kind of overloading mechanism. You can overload or customize some parts of a template and you can skip other parts if they are okay for you.

With version 3.0.0 stylesheet overloading affects all quizzes, polls or surveys grouped on one page together. That means if you have a page with two items (even if they are from different type) the overloaded stylesheet will affect both.

To avoid this you have to use an unique id or class for the new template and group all styles to this class or id. Best would be to set a class for the main container and use this in your stylesheet

<div class="squiz_container my_new_template" id="squiz_{{ item.id }}">
.my_new_template.squiz_container {
   width: 100%;
   position: relative;
   height: auto;
   overflow: hidden;
   border:3px solid #a35;
}