LimeSurvey Manual - User contributions [en]

Project ideas for GSOC 2011

2011-03-28T16:45:57Z

Ttielu:

__TOC__

=Welcome=

Welcome Google Summer of Code Student aspirants (:razz:)

This page lists project ideas developed by the LimeSurvey Community. These tend to be areas that will get the most support as projects since they have been developed by people who know the project and what it needs the most. '''However''', if you have your own idea for a project discuss your awesome idea with us in our [http://www.limesurvey.org/en/forum forums], [https://lists.sourceforge.net/lists/listinfo/limesurvey-developers mailing list] or at [http://www.limesurvey.org/en/support/live-chat #limesurvey on irc.freenode.net]. Then submit your proposal. Good Luck (:biggrin:)

----

=Project ideas=

==Central participants database (User panel)==

Develop a central 'participants' database for LimeSurvey that can be used as a central registry of participants between surveys. The database should allow
* adding/removing of users along with flexible data to store related information for users
* simple copying of user-information to individual survey token tables
* ability to link user entries with survey responses if the linked survey was not unanimous (UUIDs?)
* ability for survey participants to register in the panel
* ability to update the flexible user data from collected results
* a 'do not email' blacklist to allow people to automatically unsubscribe
* data ownership features for multi-user systems - allow different LimeSurvey users to 'own' different participants

'''Skills'''

Database and PHP coding

'''Difficulty'''

Moderate to high - the coding would be relatively simple, but will entail complex relationships

'''Probable mentors'''

Jason Cleeland

----

==Port the LimeSurvey front-end to CodeIgniter==

LimeSurvey is still written using old procedural code. We want to take the next step into the future and use a MVC-framework name CodeIgniter and port the whole application to this new framework. However proting the whole application is too much for one students. That is why we will split the task into smaller ones. This particular task deals with porting the front-end of LimeSurvey to CodeIgniter - this means all the parts that can be seen by the average survey participant:
*Survey taking
*Public statistics
*Central landing page

During the rewrite you will be prompted also to encapsulate certain functions to objects where easily doable and it makes sense - we do not want you to rewrite everything. Since you are only working on a certain part of LimeSurvey and other students will port the back-end (=administration) of LimeSurvey you will be required to coordinate your coding with the other students.

'''Skills'''

OOP experience in PHP and experience with a PHP framework like CakePHP or CodeIgniter are definately a must. You should get busy with LimeSurvey as early as possible. Students can raise their chance to get accepted by showing off according knowledge about LimeSurvey inner workings.

'''Difficulty'''

If you fulfill the requirements above the difficulty in this task is to gradually modernize an application with a modern coding approach while resisting the natural urge to rewrite everything at once. Our mantra to modernizing the application is that the framework is just laying the new fundaments while the fance walls can be built later. So we lay the fundament first and make it stable, then we build new walls (See also [[LimeSurvey roadmap|the LimeSurvey roadmap]] )

'''Probable mentors'''

Carsten Schmitz (c_schmitz)

Thibault le Meur (tlemeur)

----

==Port the LimeSurvey back-end (administration) to CodeIgniter==

LimeSurvey is still written using old procedural code. We want to take the next step into the future and use a MVC-framework name CodeIgniter and port the whole application to this new framework. However porting the whole application is too much for one student. That is why we will split the task into smaller ones. This particular task deals with porting the backend of LimeSurvey to CodeIgniter - this means all the parts that can be seen by an administration user.

During the rewrite you will be prompted also to encapsulate certain functions to objects where easily doable and it makes sense - we do not want you to rewrite everything. Since you are only working on a certain part of LimeSurvey and another student will port the front-end (=administration) of LimeSurvey you will be required to coordinate your coding with the other student.

'''Skills'''

OOP experience in PHP and experience with a PHP framework like CakePHP or CodeIgniter are definately a must. You should get busy with LimeSurvey as early as possible. Students can raise their chance to get accepted by showing off according knowledge about LimeSurvey inner workings.

'''Difficulty'''

If you are a very good PHP coder (and fit the demanded skills above) then the main difficulty in this task is the sheer size of it. The administration consists of a great number of different screens and functions which need to be ported. If you don't manage to port all of it then at least the unported parts still have to be working - still best would be if you manage to do the whole administration.

Also the difficulty in this task is to gradually modernize an application with a modern coding approach while resisting the natural urge to rewrite everything at once. Our mantra to modernizing the application is that the framework is just laying the new foundation while the fancy walls can be built later. So we lay the foundation first and make it stable (your task in the administration), then we build new walls (See also [[LimeSurvey roadmap|the LimeSurvey roadmap]] )

'''Probable mentors'''

Carsten Schmitz (c_schmitz)

Thibault le Meur (tlemeur)

----

==Implement a modular authentication framework==

The idea is to design and implement a modular authentication "framework" for LimeSurvey as well as some authentication modules. The Authentication framework will define the API each authentication plugin must (or may) implement and propose basic methods that can be used by plugins (for instance how to store the plugins parameters in DB, how to display a form using the survey template). A plugin will be responsible to implement, for each particular authentication backend, specific methods (some mandatory, some optionnal) such as: user authentication, user provisionning, user rights, ...

Currently authentication is only used for the survey-administration GUI and not the participants interface (tokens are used for this). With the new authentication framework it will be possible to define several authentication backends and use some of them for participants-authentication.

The generic authentication framework must define the following services:
* User authentication: this interface must return the identity of the authenticated user if authentication is successful.
** Authentication may not always be based on a simple user/password form, so the proposed framework must be generic enough to enable authentication based on other schemes (using any numbers or interaction-pages between the server and the end-user or any other contextual parameter such as Referrer, session variable...
* User provisionning:
** when activated on the survey administration interface, an authentication module might be able to create a newly authenticated user into the LimeSurvey internal DB (which is required for setting the user rights on the platform). The newly created user can be assigned a default profile or a per-user profile (queried from an external database).
** when activated on the participants interface, the authentication module will provision the token table of the correspoding survey // alternatively the general-purpose cross-survey participants-database as described in the above GSoC idea.

The already existing authentication schemes will be ported to the new framework (internal-DB and Web server authentication delegation) and at least a new one will be implemented (openID, CAS, Shibboleth).

'''Skills'''

PHP, SQL, CodeIgniter, Authentication protocols (openID, CAS, LDAP-bind, ...)

'''Difficulty'''

Medium

'''Probable Mentors'''

lemeur (Thibault Le Meur)

'''Want to know more'''

Please read the [http://docs.limesurvey.org/tiki-index.php?page=GSOC+2010++Authentication+framework#FAQ FAQ about this project]

----

== Rewrite and extend the conditions in LimeSurvey==

[[File:addNewCondition1.png]]

Rewrite the conditions engine that will let survey administrators design, store and evaluate conditions. Conditions must be implemented in such a way that they can be used in several features such as question branching (survey logic), assessments, quotas, ...

This projects will at least end up with:
* A working GUI to design complex conditions:
** several atomic conditions can be combined by AND or OR logical operators and will support for grouping conditions with parentheses
** an atomic condition representation can be

<syntaxhighlight lang="php" enclose="div"><left operand> <operator> <right operand></syntaxhighlight>
** an atomic condition editor will implement
*** several operators (equality, inequality, string-comparisons, numerical-comparisons, regexp),...
*** meta operators surch as 'Not displayed'
** left and right operands can be answers from previous questions, or a static values. It should be extensible so that we are able in the future to use more complex operand such as the result of a specific function (for instance the sum of some previous integer questions)
* A working DB storage backend using a string in [http://en.wikipedia.org/wiki/Reverse_Polish_Notation RPN] (Reverse Polish Notation) to describe each condition
* The evaluation of conditions for the question branching feature.

'''Skills'''

PHP, CodeIgniter, JQuery and User Interface Design Skills

'''Difficulty'''

High

'''Probable Mentors'''

Thibault Le Meur (lemeur)

Carsten Schmitz

'''Want to know more'''

Discussion about the [http://docs.limesurvey.org/tiki-index.php?page=GSOC+2010+Condition+engine LS2 conditions engine] is an interresting start. Note however that the task will be easier this year because of the existing conditions engine and the stable database layout of LS1.

----

==Custom Report Generation==

The task is to make a module which will generate custom reports. Module should be able to do these things(at least) :-
*Creating various types of reports i.e. using tables, pie charts, graphs and bar-charts to name few.
*The resulting charts and other illustrations should be easy to read and understand, and should include the ability to export into standard office suites.
*Reports can be general or survey specific.
**General in the sense that it should show basic findings of a general survey graphically like number of users completing the survey, average time taken to complete the survey, average number of correct responses etc.
**Survey specific results should also be addressed properly e.g. how many users choose first option as there answer of a particular question, how many users didn't answer a specific question etc.

'''Skills'''

OOP experience in PHP and experience with a PHP framework like CakePHP or CodeIgniter, jQuery. Strong mathematical background will help!

'''Difficulty'''

Moderate

'''Probable mentors'''

Carsten Schmitz (c_schmitz)

----

==Adding new questions/subquestions and groups dynamically==

Currently in LimeSurvey once a survey is activate we can not
*Add or delete groups
*Add or delete questions
*Add or delete subquestions or change their codes

The idea is to cover these shortcomings. And in addition, all those participants who have already taken that survey must also be notified about the changes.

'''Skills'''

Experience with a PHP framework like CakePHP or CodeIgniter and knowledge of inner working of LimeSurvey is must!

'''Difficulty'''

Moderate

'''Probable mentors'''

Carsten Schmitz (c_schmitz)

----

==Extend the use of assessments==

[http://docs.limesurvey.org/Assessments&structure;=English+Instructions+for+LimeSurvey Assessments] are used a lot at Limesurvey but currently this feature only covers very basic needs. Users have asked for some additional assessment features, unfortunately most of them can't be implemented until we start saving assessment results at the database instead of calculating assessment scores at runtime.

So the first step is to extend the database layout of Limesurvey and add a new table for storing assessment results. Once this is done advanced features can be implemented such as:
* Export assessment results when exporting survey data
* Include assessment results at confirmation emails
* Extend statistics to include information about assessment results such as max score, min score, mean score, standard deviation, ...
* Connect [http://docs.limesurvey.org/Quotas&structure;=English+Instructions+for+LimeSurvey quotas] and assessments so that assessment results can be used to screen users at the beginning of a survey.
* Enable assessment scores at [http://docs.limesurvey.org/Setting+conditions&structure;=English+Instructions+for+LimeSurvey conditions] so that a condition like "''Show question X if <assessment_score1> > 10''"

'''Skills'''

PHP, MySQL, CodeIgniter, JQuery and some basic User Interface Design Skills

'''Difficulty'''

Medium

'''Probable Mentors'''

Carsten Schmitz (c_schmitz)

----

=='''NEW''' Rebuild the database frontend using CodeIgniter==

During last years GSoC, a database frontend was developed using CakePHP. Limesurvey has since decided to switch to the CodeIgniter framework. As such, last years work needs to be ported to CodeIgniter.

All documentation from last year is available at [[Database Storage Engine Project|here]] aswell as the source of the developed CakePHP modules which can be found [https://limesurvey.svn.sourceforge.net/svnroot/limesurvey/source/limesurvey20/limesurvey-dev/app/plugins/ here] - the plugins market with dbse.

The final project has to comply with the API developed last year, changes have to be discussed.

'''Skills'''

PHP, SQL, Object oriented programming & design patterns, CodeIgniter, CakePHP

'''Difficulty'''

Medium, Main challenges will be database abstraction and automatic generation of sql code out of survey structures.

'''Probable Mentors'''

Maarten Tielemans (ttielu)

Pieter-Jan Speelmans (MrP001)

----

==Idea template==

Describe the idea here in general terms

'''Skills'''

Explain what sort of coding skills would be needed for a student to implement this project

'''Difficulty'''

Explain the level of difficulty involved

'''Probable Mentors'''

Put your name (and tag) here if you are willing to mentor a student for this idea

----

=More information=

==Getting started==

[[GSoC getting started|Check out our 'Get started' page]] for setting up the development environment, coding standards, and all the other important stuff that you need to know before the real fun begins!

==Frequently Asked Questions==

Check out [[GSoC FAQ|our GSoC FAQ page.]]

Project ideas for GSOC 2011

2011-03-28T16:45:56Z

Ttielu:

Database Storage Engine Project M3 Class diagram

2010-08-11T13:44:21Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes documenting the [[Database Storage Engine Project|Database Storage Engine]] with a class diagram. This will make it easier for future developers to make changes to the database system. This milestone is closely linked to the [[Database Storage Engine Project M2 API|API]] milestone since the controllers will have to implement this API.

= Todo=
*Identify the important classes and define the data-classes for the system (done)
*Define the structure of the database designs (done)

= Diagrams=

There are three big parts in the diagrams: the enginefactory, the components and the model classes. Packages used in the diagrams will not result in namespaces.

== Model classes==

[[File:models.png]]

== Components==

[[File:components.png]]

This also contains the DbseObserver components, which can be used to register classes implementing the DbseObserver interface.

== Engine factory==

[[File:enginefactory.png]]

This also contains the DbseObserver interface, which can be implemented.

== Question types==

A list of question types can be found at:

[[Database Storage Engine Project M1 Database Design|#Mappings_for_QuestionType_classes_to_table_columns]]

Methods for these classes will be documented when they are implemented.

Database Storage Engine Project M3 Class diagram

2010-08-11T13:43:29Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes documenting the [[Database Storage Engine Project|Database Storage Engine]] with a class diagram. This will make it easier for future developers to make changes to the database system. This milestone is closely linked to the [[Database Storage Engine Project M2 API|API]] milestone since the controllers will have to implement this API.

= Todo=
*Identify the important classes and define the data-classes for the system (done)
*Define the structure of the database designs (done)

= Diagrams=

There are three big parts in the diagrams: the factory part, the controllers and the general classes. Packages used in the diagrams will not result in namespaces.

== Model classes==

[[File:models.png]]

== Components==

[[File:components.png]]

This also contains the DbseObserver components, which can be used to register classes implementing the DbseObserver interface.

== Engine factory==

[[File:enginefactory.png]]

This also contains the DbseObserver interface, which can be implemented.

== Question types==

A list of question types can be found at:

[[Database Storage Engine Project M1 Database Design|#Mappings_for_QuestionType_classes_to_table_columns]]

Methods for these classes will be documented when they are implemented.

Database Storage Engine Project M3 Class diagram

2010-07-08T09:48:39Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes documenting the [[Database Storage Engine Project|Database Storage Engine]] with a class diagram. This will make it easier for future developers to make changes to the database system. This milestone is closely linked to the [[Database Storage Engine Project M2 API|API]] milestone since the controllers will have to implement this API.

= Todo=
*Identify the important classes and define the data-classes for the system
*Define the structure of the database designs

= Diagrams=

There are three big parts in the diagrams: the factory part, the controllers and the general classes. Packages used in the diagrams will not result in namespaces.

== General classes==

[[File:general.png]]

== Controllers==

[[File:controllers.png]]

== Engine factory==

The engine classes (like the one in the DBSESF package) are trivial classes (one for each type of table).

[[File:eninefactory.png]]

== Exceptions==

The exceptions classes. They will have a message which will describe the exception.

[[File:exceptions.png]]

== Question types==

A list of question types can be found at:

[[Database Storage Engine Project M1 Database Design|#Mappings_for_QuestionType_classes_to_table_columns]]

Methods for these classes will be documented when they are implemented.

Database Storage Engine Project M2 API

2010-07-02T18:02:09Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

=== void reorder(assoc(modelAnswerId => orderNumber))===

Changes the order of the given model answers to the given order numbers. O6rders must be unique. When there are clashes, an exception will be thrown (defined later).

=== ModelAnswer getModelAnswer(modelAnswerID)===

Returns the model answer belonging to the given model answer ID.

=== void removeModelAnswer(modelAnswerID)===

Removes the model answer with the given model answer ID.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId, places)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId, places)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID, places)===

Moves the question one place to the front of the section.

=== void moveDown(questionID, places)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:55:47Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId, places)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId, places)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID, places)===

Moves the question one place to the front of the section.

=== void moveDown(questionID, places)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:55:38Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId, places)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId, places)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID, places)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:55:17Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId, places)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId, places)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:55:06Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId, places)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:54:49Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID, places)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:54:37Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID, places)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:33:07Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(surveyID)===

Constructs a new controller for the given survey.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:32:39Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(sectionID)===

Constructs a new controller for the given section.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== mixed exportResponses()===

Returns a double array containing all response information from the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:27:25Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(sectionID)===

Constructs a new controller for the given section.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== boolean hasFinished(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M2 API

2010-07-02T17:24:52Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes building the API for the [[Database Storage Engine Project|database system]].

We will release a preview of the API before the 1st of June in order to have plenty of time for the community to comment.

= Todo=
*Develop basic API and post it on the forums
*Explore comments on the basic API
*Complete the API
*Make sure it is possible to add/have support for current en future metadata related to single questions & whole surveys.
*Add methods to add and remove observers

= Basic API version (06-25)=

Below you find the first draft of the API.

== Survey==

A survey is a collection of sections. Surveys can have various metadata like a respondent e-mail adres, a name, ...

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the survey.

=== void addMetaData(key, value)===

Adds the given metadata to the survey.

=== void updateMetaData(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the survey.

== Section==

A section is a part of a survey, grouping questions together. Using conditions it is possible to loop or branch over sections.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the section.

=== void addMetaData(key, value)===

Adds the given metadata to the section.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the section.

== QuestionType==

A survey can have various types of questions, ranging from string & integers up to fileinput and matrix types. QuestionType will have subclasses: basic question types like IntegerQuestionType, StringQuestionType, DateQuestionType ... and structures like MatrixQuestionType, ArrayQuestionType, ...

=== abstract string render()===

Returns a template for this questiontype.

=== abstract mixed getFields()===

Returns a list of all fields required by this questiontype and their types.

=== abstract bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== Question==

A question is a combination of a string (the question) a QuestionType and possible various options - depending on the type.

=== mixed get()===

Getter method for all properties.

=== void set()===

Setter method for the properties.

=== assoc(key => value) listMetaData()===

Lists all metadata belonging to the question.

=== void addMetaData(key, value)===

Adds the given metadata to the question.

=== void updateMetaDate(key, newValue)===

Updates the given metadata with the new value.

=== void removeMetaData(key)===

Removes the given metadata from the question.

=== bool checkResponse(value)===

Returns true if the given value is a valid response to the question.

== ModelAnswer==

A model answer for a closed question.

=== mixed getValue()===

Returns the value of this model answer.

== Response==

A response is a combination of a token, questionID, answervalue and metadata.

=== mixed get()===

Getter method for all properties.

=== date getStartTime()===

Returns the time this response was started. This means when the question was displayed.

=== date getEndTime()===

Returns the time this response was ended. This means when the question was filled in.

=== int getIteration()===

Returns the iteration of this response (used for loops).

== ModelAnswerManagementController==

This controller will handle the management of model answers.

=== void storeModelAnswer(questionID, ModelAnswer)===

Stores the given model answer to the database. If the model answer has no ID, it will be considered a new model answer. In this case ModelAnswer->id will be set to the ID appointed to this model answer. The model answer must have a valid question id.

=== ModelAnswer[] listModelAnswers(questionID)===

Returns all model answers of the given question.

=== void moveUp(modelAnswerID)===

Moves the model answer one place to the front of the question.

=== void moveDown(modelAnswerID)===

Moves the model answer one place to the end of the question.

== SurveyManagementController==

This controller will handle the management of surveys.

=== Survey[] listSurveys()===

Lists all surveys.

=== void storeSurvey(Survey)===

Stores the given survey to the database. If the survey has no ID, it will be considered a new survey. In this case Survey->id will be set to the ID appointed to this survey.

=== Survey getSurvey(surveyID)===

Returns the wanted survey.

=== void removeSurvey(surveyID)===

Removes survey data and all answers.

=== void openSurvey(surveyID)===

Changes the state of the survey to open.

=== void closeSurvey(surveyID)===

Changes the state of the survey to closed.

=== void setDatabaseEngine(surveyID, engineID)===

Enables the chosen database engine for the given survey. Can only be called the first time before the survey is opened.

=== string[] getPossibleDatabaseEngines(surveyID)===

Returns the possible engineID's of the database engines which are possible for this survey.

== SectionManagementController==

This controller will handle the management of sections.

=== Section[] listSections(surveyID)===

Lists all sections in the given survey.

=== void storeSection(Section)===

Stores the given section to the database. If the section has no ID, it will be considered a new section. In this case Section->id will be set to the ID appointed to this section. The section must have a valid survey id.

=== Section getSection(sectionID)===

Returns the wanted section.

=== void removeSection(sectionID)===

Removes section data and all answers.

=== void moveUp(sectionId)===

Moves the section one place to the front of the survey.

=== void moveDown(sectionId)===

Moves the section one place to the end of the survey.

=== void <nowiki>reorder(assoc(sectionId => orderNumber))</nowiki>===

Changes the order of the given sections to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== interface DBSEObserver==

=== void notifySurveyCreated(Survey survey)===

Called on creation of survey.

=== void notifySurveyRemoved(int id)===

Called on removal of survey.

=== void notifySurveyChanged(Survey survey)===

Called on update of survey.

=== void notifySectionCreated(Section section)===

Called on creation of section.

=== void notifySectionRemoved(int id)===

Called on removal of section.

=== void notifySectionChanged(Section section)===

Called on update of section.

=== void notifyQuestionCreated(Question question)===

Called on creation of question.

=== void notifyQuestionRemoved(int id)===

Called on removal of question.

=== void notifyQuestionChanged(Question question)===

Called on update of question.

=== void notifyResponse(Response response)===

Called on submission of a response.

== QuestionManagementController==

This controller will handle the management of questions.

=== Question[] listQuestions(sectionID)===

Lists all questions in the given section.

=== void storeQuestion(Question)===

Stores the given question to the database. If the question has no ID, it will be considered a new question. In this case Question->id will be set to the ID appointed to this question. The question must have a valid section id.

=== Question getQuestion(questionID)===

Returns the wanted question.

=== void removeQuestion(questionID)===

Removes question data and all answers.

=== void moveUp(questionID)===

Moves the question one place to the front of the section.

=== void moveDown(questionID)===

Moves the question one place to the end of the section.

=== void reorder(assoc(questionID => orderNumber))===

Changes the order of the given questions to the given order numbers. Orders must be unique. When there are clashes, an exception will be thrown (defined later).

== AnswerAccessController==

This controller provides methodes to store and retrieve survey answers.

=== '''construct(sectionID)===

Constructs a new controller for the given section.

=== void addResponse(participantID, questionID, value, starttime, endtime, iteration=0)===

Adds the given answer and metadata for the given question to the answers of the given participant. If there already was an answer to the given question for the given participant, the answer will be overridden. The iteration parameter is used to express this is the answer for the i'th loop. If the given answer value is invalid for the given question, an exception will be thrown.

=== Response getResponse(participantID, questionID)===

Returns the response of the given participant to the given question and its metadata.

=== Response[] getResponsesToQuestion(questionID)===

Returns all responses to the given question and their metadata.

=== Response[] getResponses()===

Returns all responses to the survey.

=== boolean participated(participantID)===

Returns true if the given participant already finished the survey. Returns false if the participant did not complete the survey.

=== date getSurveyStart(participantID)===

Returns the start time of this participant.

=== date getSurveyEnd(participantID)===

Returns the end time of this participant.

=== assoc(section_id => date) getSectionStart(participantID)===

Returns the start times of this participant for each section.

=== assoc(section_id => date) getSectionEnd(participantID)===

Returns the end times of this participant for each section.

== ObserverController==

=== static ObserverController getInstance()===

Returns a statical instance to the ObserverController.

=== void addObserver(DBSEObserver observer)===

Adds an observer to the ObserverController.

=== void removeObserver(DBSEObserver observer)===

Removes an observer from the ObserverController.

=== void notifyObservers(callback $function ~091~, mixed $parameter ~091~, mixed $... ~093<span style="color:093~)===

Notifies all registered observers with the specific function and the given parameters.

==Global notes==
*Metadata keys can be chained in dot-notation. 'color.red' means the key 'color' with subkey 'red'.
*The returning of subkeys in metadata will result in assocs in the array. The 'color.red' example will give"> array(color => array(red => ...)). When you use a subkey, you cannot use the key itself anymore.
*Exceptions will be used for reporting errors. The exceptions thrown by each method will be added later in the development process.

= Discussions=

Comments and ideas here please:

== Comments from Machaven:==

1. All the functions that do not return anything (void)
*Should functions not return true/false (bool) depending on success or failure?

2. void updateMetaDate(key, value, newValue)
*Should this be spelled: updateMetaData?
*Why is the original value required to change the metadata? Are the keys not unique?

3. How are errors handled?
* Can we trigger some action on error, set logging or retrieve error information?

== Comments from Jason:==

'''From May'''

1. There has been some discussion about the use of the word token to represent each unique participant
*this may be better expressed using a different word internally. Since survey participants/token recipients will be represented as "users" maybe "userID" would be a better label than tokens - ie instead of "Answer getAnswer(token, questionID)", "Answer getAnswer(userID, questionID)"

2. The AnswerAccess controller, should it also be storing responses?
* So, there should be an equivalent of "getAnswer", being "putAnswer" (or "saveAnswer")

3. Once answers are being stored, either in a flatfile table, or a normalised one, there will be some kind of unique id for the "collection" of answers, so they can be grouped together.
* A collection of survey responses, with their unique identifier, become the "sheet of answers" to a particular survey. In the case of a controlled survey - where the user has been specifically invited, so we know who they are, they'll have a unique userID from the users table. In the case of open/anonymous or general public surveys, this unique identifier will have to be something else - where is that reflected in the getAnswers, and where will it be reflected in the putAnswer(s) call?

'''New June Comments'''

I've had a thought that the moveUp and moveDown methods should take an option of how many positions to move them. When you have 20 questions in a section, and you want to move your question to the top, moving it up one at a time can be really annoying. Can we have void moveUp(sectionId,positions) so if we want to move something 5 places up in the order, it could have a 5 for the positions? Default, of course, would be 1.

== Comments from Hai:==
* Add functions for reordering questions (something that would take an array and/or an assoc. map)
* Make sure you handle scalability for conditions well. This includes:
** ability to link survey elements to multiple conditions, each condition linkable to multiple actions.
** providing functions for various condition actions, such as question hiding, branching etc. (sorry, I know this is extremely vague, I'll try to specify later on)

Database Storage Engine Project M1 Database Design

2010-06-24T17:48:58Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes creating documentation and descriptions of the database schemes explained at [[Database Storage Engine Project]].

=Questions : Database Layout=

This is the design to store survey, section and question information and their related metadata.

[[File:survey_section_question_diagram.png]]

=Responses : Flat Database Layout=

This is the layout we propose for storing survey responses in a single database table.

[[File:Flat.png]]

=Responses : Multitable Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each question get stored in a seperate table.

[[File:Multitable2.png]]

=Responses : Sectionflat Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each section get stored in a seperate table.

[[File:SectionFlat2.png]]

=Question Type mockups=

These are database mockups of the question types presented [[Question types in version 1.90|here]]. Since the question types are presented as single questions, there is no difference between the 3 proposed database layouts.

==Array==

Choice matrix questions | ChoiceMatrixQuestionType with NumberOfRows child questions of type ChoiceQuestion

= Todo=
*Design flat DB layout (Awaiting comments)
*Design normalized DB layout (Awaiting comments)
*Design section-flat DB layout (Awaiting comments)
*Keep in mind all the Question types supported by Limesurvey1 : [[Question types]]
*Problem with loops with current response layouts (sectionflat and multitable), flat has no support for loops. (Done)

= Discussions=

Comments and ideas here please:

== Metadata requirements for databases==

- time question displayed/made available to participant (added by Jason)

this may be an indication of when the page was served to the participants browser (time can be generated by web server/php) or in the case of conditional questions, it may need to indicate the time that the question became visible on the page (in which case it may need to be generated by javascript, with all those inherent problems.. maybe it should indicate how many seconds since the page was loaded, and that can be added to the page-load time?)

- time question answered by participant (added by Jason)

this may be a recording of the time that the data in the question was posted (time could be generated by web serer/php) or the time that the question lost focus (after having gained it) - which would be a javascript issue

Any other metadata requirements?

Database Storage Engine Project M1 Database Design

2010-06-24T17:28:58Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes creating documentation and descriptions of the database schemes explained at [[Database Storage Engine Project]].

=Questions : Database Layout=

This is the design to store survey, section and question information and their related metadata.

[[File:survey_section_question_diagram.png]]

=Responses : Flat Database Layout=

This is the layout we propose for storing survey responses in a single database table.

[[File:Flat.png]]

=Responses : Multitable Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each question get stored in a seperate table.

[[File:Multitable2.png]]

=Responses : Sectionflat Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each section get stored in a seperate table.

[[File:SectionFlat2.png]]

=Question Type mockups=

These are database mockups of the question types presented [[Question types in version 1.90|here]]. Since the question types are presented as single questions, there is no difference between the 3 proposed database layouts.

==Array==

Stuff goes here

= Todo=
*Design flat DB layout (Awaiting comments)
*Design normalized DB layout (Awaiting comments)
*Design section-flat DB layout (Awaiting comments)
*Keep in mind all the Question types supported by Limesurvey1 : [[Question types]]
*Problem with loops with current response layouts (sectionflat and multitable), flat has no support for loops. (Done)

= Discussions=

Comments and ideas here please:

== Metadata requirements for databases==

- time question displayed/made available to participant (added by Jason)

this may be an indication of when the page was served to the participants browser (time can be generated by web server/php) or in the case of conditional questions, it may need to indicate the time that the question became visible on the page (in which case it may need to be generated by javascript, with all those inherent problems.. maybe it should indicate how many seconds since the page was loaded, and that can be added to the page-load time?)

- time question answered by participant (added by Jason)

this may be a recording of the time that the data in the question was posted (time could be generated by web serer/php) or the time that the question lost focus (after having gained it) - which would be a javascript issue

Any other metadata requirements?

Database Storage Engine Project M1 Database Design

2010-06-24T17:21:31Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes creating documentation and descriptions of the database schemes explained at [[Database Storage Engine Project]].

=Questions : Database Layout=

This is the design to store survey, section and question information and their related metadata.

[[File:survey_section_question_diagram.png]]

=Responses : Flat Database Layout=

This is the layout we propose for storing survey responses in a single database table.

[[File:Flat.png]]

=Responses : Multitable Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each question get stored in a seperate table.

[[File:Multitable2.png]]

=Responses : Sectionflat Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each section get stored in a seperate table.

[[File:SectionFlat2.png]]

=Question Type mockups=

These are mockups of the question types presented [[Question types in version 1.90|here]].

==Array==

Bla

= Todo=
*Design flat DB layout (Awaiting comments)
*Design normalized DB layout (Awaiting comments)
*Design section-flat DB layout (Awaiting comments)
*Keep in mind all the Question types supported by Limesurvey1 : [[Question types]]
*Problem with loops with current response layouts (sectionflat and multitable), flat has no support for loops. (Done)

= Discussions=

Comments and ideas here please:

== Metadata requirements for databases==

- time question displayed/made available to participant (added by Jason)

this may be an indication of when the page was served to the participants browser (time can be generated by web server/php) or in the case of conditional questions, it may need to indicate the time that the question became visible on the page (in which case it may need to be generated by javascript, with all those inherent problems.. maybe it should indicate how many seconds since the page was loaded, and that can be added to the page-load time?)

- time question answered by participant (added by Jason)

this may be a recording of the time that the data in the question was posted (time could be generated by web serer/php) or the time that the question lost focus (after having gained it) - which would be a javascript issue

Any other metadata requirements?

Database Storage Engine Project M1 Database Design

2010-06-20T13:05:58Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes creating documentation and descriptions of the database schemes explained at [[Database Storage Engine Project]].

=Questions : Database Layout=

This is the design to store survey, section and question information and their related metadata.

[[File:survey_section_question_diagram.png]]

=Responses : Flat Database Layout=

This is the layout we propose for storing survey responses in a single database table.

[[File:Flat.png]]

=Responses : Multitable Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each question get stored in a seperate table.

[[File:Multitable.png]]

=Responses : Sectionflat Database Layout=

This is the layout we propose for storing survey responses in multiple tables. Responses for each section get stored in a seperate table.

[[File:SectionFlat.png]]

= Todo=
*Design flat DB layout
*Design normalized DB layout
*Design section-flat DB layout
*Keep in mind all the Question types supported by Limesurvey1 : [[Question types]]
*Problem with loops with current response layouts (sectionflat and multitable), flat has no support for loops.

= Discussions=

Comments and ideas here please:

== Metadata requirements for databases==

- time question displayed/made available to participant (added by Jason)

this may be an indication of when the page was served to the participants browser (time can be generated by web server/php) or in the case of conditional questions, it may need to indicate the time that the question became visible on the page (in which case it may need to be generated by javascript, with all those inherent problems.. maybe it should indicate how many seconds since the page was loaded, and that can be added to the page-load time?)

- time question answered by participant (added by Jason)

this may be a recording of the time that the data in the question was posted (time could be generated by web serer/php) or the time that the question lost focus (after having gained it) - which would be a javascript issue

Any other metadata requirements?

Database Storage Engine Project M1 Database Design

2010-05-21T13:20:00Z

Ttielu:

__TOC__

= About the milestone=

This milestone includes creating documentation and descriptions of the database schemes explained at [[Database Storage Engine Project]].

= Todo=
*Design flat DB layout
*Design normalized DB layout
*Design section-flat DB layout
*Keep in mind all the Question types supported by Limesurvey1 : http://docs.limesurvey.org/tiki-index.php?page=Question+types&structure;=English+Instructions+for+LimeSurvey

= Discussions=

Comments and ideas here please:

== Metadata requirements for databases==

- time question displayed/made available to participant (added by Jason)

this may be an indication of when the page was served to the participants browser (time can be generated by web server/php) or in the case of conditional questions, it may need to indicate the time that the question became visible on the page (in which case it may need to be generated by javascript, with all those inherent problems.. maybe it should indicate how many seconds since the page was loaded, and that can be added to the page-load time?)

- time question answered by participant (added by Jason)

this may be a recording of the time that the data in the question was posted (time could be generated by web serer/php) or the time that the question lost focus (after having gained it) - which would be a javascript issue

Any other metadata requirements?

Database Storage Engine Project

2010-05-14T18:42:00Z

Ttielu:

__TOC__

= Outline=

The project is focused around the Google Summer Of Code of 2010. Maarten [[(UserPage ttielu|ttielu]]) and Pieter-Jan [[(UserPage MrP|MrP]]) are the students assigned to the project.

The project is based on the DB Storage Engine proposal found at [[LimeSurvey 2 Project Ideas for GSOC 2010]].

= Design and implementation=

A basic domain model of the problem can be found in [http://www.mediafire.com/?mytzjeggien this] pdf file.

This domain model can be used to build multiple databases. One would be to see the objects as tables. For the inheritance there would have to be some analysis to see how they should be mapped to the database. Here it would be important to use a low amount of joins. This structure has the disadvantage that when querying all information of a certain user, loads of joins might be required (depending on the complexity of the survey). On the other hand, queries about all answers on a single question can be very efficient. On top of that, tables are small.

Another example could be to remove the QuestionDependency and make one table per section. This would allow a more flat database structure, which reduces the number of joins necessary to retrieve all data from a single user. This could however create large tables and removes the possibility to loop over one question. This question will have to be placed into a new section and the loop will have to go over that section.

To allow these multiple database formats, we plan on using a [http://en.wikipedia.org/wiki/Factory_pattern factory pattern]. A DatabaseLayoutFactory can be used to choose the layout for a survey and in this way make it possible to add new database layouts for future use (for example a database which duplicates the data in both structures to get fast retrieval of both types of query).

Our plan would be to model the presented database models in detail and then implement at least one of them. Also we would want to model an API for the database (and of course implement that).

After creation of the survey, questions will be more or less static. To build upon this, it would be a good idea to store/cache the questions in a more static form, like a generated html-form, after creation of the survey.

== Database layouts==

=== Flat database===

A flat database would exist of a single table containing all answers to all questions.

Properties of this layout are:
* easy to export
* fast database operations
* hard to implement loops, branching & conditioning (introduce maximums on looping and have loads of NULL values OR use TEXT/BLOB fields containing sub structures => slow and unsearchable with quick operations)
* not suited for exotic question types (upload picture, matrix questions, multiple answer, multiple type questions, ...)
* database column limits might be hit
* best for simple surveys with huge amounts of answer data

=== Multitable database===

A multitable database would exist of multiple tables each containing the answers of a single question or questiontype.

Properties of this layout are:
* more difficult to export
* slower database operations (joins)
* supports all sorts of branching, conditioning, loops, ... including future features
* can support pictures, matrix questions, ... easily
* no problems with database column limits
* better for complex surveys with smaller amounts of replies

=== Hybrid database (section flat)===

The section flat model is a mix of the previous two models. In stead of mapping all answers in one table, we would map all answers to one section in one table. This allows the more advanced features (like looping, ...) to be handled between sections while still having a fast export of the different sections.

Properties of this layout are:
* easy to export
* fast database operations for simple surveys, operations for surveys with loads of loops, branching, ... will need joins (to handle the dependencies)
* database column limit only for really long sections (but they could be split in multiple sections, solving the problem)
* can support multiple question types (might result in using more columns, like in case of matrix questions)
* results in looping over sections instead of looping over questions in sections (hence if there is a loop over one question, there will be a section containing only this question; multiple questions in the same loop can be grouped in one section)

=== Layout mock-ups===

Mock-ups for the database layouts can be found in [http://www.mediafire.com/?nwjwy2c34mw this] pdf file.

The survey used is:

1) how many children do you have? '''int'''

loop: amount of children {

2.1) give the name of you i'th child '''string'''

2.2) what is the age of your i'th child '''int'''

}

3) what kind of ice cream do you like? (multiple choise)

3.1) i don't like ice cream

3.2) vanilla

3.3) strawberry

3.4) chocolate

3.5) other: 3e) '''string'''

4) what do you eat? (multiple answer: checkboxes)

4.1) dogs

4.2) pussy

4.3) birds

= Action Plan=

(To be specified more in detail later)

== Outline==

Main deliverables:
*Database design for flat database
*Database design for multitable database
*Database design for section-flat database
*Class diagram for the database system
*API and documentation with the database system - keep support for metadata in mind.
*Implementation of the database system with at least one database layout (more if spare time is found)

== Milestones==

The first series of milestones is slightly smaller since both Maarten and Pieter-Jan have exams in the month of June.

{|
|Milestone||Deadline
|-
|[[Database Storage Engine Project M1 Database Design||Database designs]]||26th of June
|-
|[[Database Storage Engine Project M2 API||API]]||30th of June
|-
|[[Database Storage Engine Project M3 Class diagram||Class diagram]]||7th of July
|-
|[[Database Storage Engine Project M4 Basic implementation||Implement basic classes]]||14th of July
|}

The second series of milestones will contain the biggest part of the implementation work and will be more specified once the class diagram has been fully worked out.
*Finish implementing basic classes
*Implement database layout engine
*Implement specific database layout
*Test and debug

Database Storage Engine Project

2010-04-28T10:24:18Z

Ttielu:

__TOC__

= Outline=

The project is focused around the Google Summer Of Code of 2010. Maarten [[(UserPage ttielu|ttielu]]) and Pieter-Jan [[(UserPage MrP|MrP]]) are the students assigned to the project.

The project is based on the DB Storage Engine proposal found at [[LimeSurvey 2 Project Ideas for GSOC 2010]].

= Design and implementation=

A basic domain model of the problem can be found in [http://www.mediafire.com/?mytzjeggien this] pdf file.

This domain model can be used to build multiple databases. One would be to see the objects as tables. For the inheritance there would have to be some analysis to see how they should be mapped to the database. Here it would be important to use a low amount of joins. This structure has the disadvantage that when querying all information of a certain user, loads of joins might be required (depending on the complexity of the survey). On the other hand, queries about all answers on a single question can be very efficient. On top of that, tables are small.

Another example could be to remove the QuestionDependency and make one table per section. This would allow a more flat database structure, which reduces the number of joins necessary to retrieve all data from a single user. This could however create large tables and removes the possibility to loop over one question. This question will have to be placed into a new section and the loop will have to go over that section.

To allow these multiple database formats, we plan on using a [http://en.wikipedia.org/wiki/Factory_pattern factory pattern]. A DatabaseLayoutFactory can be used to choose the layout for a survey and in this way make it possible to add new database layouts for future use (for example a database which duplicates the data in both structures to get fast retrieval of both types of query).

Our plan would be to model the presented database models in detail and then implement at least one of them. Also we would want to model an API for the database (and of course implement that).

After creation of the survey, questions will be more or less static. To build upon this, it would be a good idea to store/cache the questions in a more static form, like a generated html-form, after creation of the survey.

== Database layouts==

=== Flat database===

A flat database would exist of a single table containing all answers to all questions.

Properties of this layout are:
* easy to export
* fast database operations
* hard to implement loops, branching & conditioning (introduce maximums on looping and have loads of NULL values OR use TEXT/BLOB fields containing sub structures => slow and unsearchable with quick operations)
* not suited for exotic question types (upload picture, matrix questions, multiple answer, multiple type questions, ...)
* database column limits might be hit
* best for simple surveys with huge amounts of answer data

=== Multitable database===

A multitable database would exist of multiple tables each containing the answers of a single question or questiontype.

Properties of this layout are:
* more difficult to export
* slower database operations (joins)
* supports all sorts of branching, conditioning, loops, ... including future features
* can support pictures, matrix questions, ... easily
* no problems with database column limits
* better for complex surveys with smaller amounts of replies

=== Hybrid database (section flat)===

The section flat model is a mix of the previous two models. In stead of mapping all answers in one table, we would map all answers to one section in one table. This allows the more advanced features (like looping, ...) to be handled between sections while still having a fast export of the different sections.

Properties of this layout are:
* easy to export
* fast database operations for simple surveys, operations for surveys with loads of loops, branching, ... will need joins (to handle the dependencies)
* database column limit only for really long sections (but they could be split in multiple sections, solving the problem)
* can support multiple question types (might result in using more columns, like in case of matrix questions)
* results in looping over sections instead of looping over questions in sections (hence if there is a loop over one question, there will be a section containing only this question; multiple questions in the same loop can be grouped in one section)

=== Layout mock-ups===

Mock-ups for the database layouts can be found in [http://www.mediafire.com/?nwjwy2c34mw this] pdf file.

The survey used is:

1) how many children do you have? '''int'''

loop: amount of children {

2.1) give the name of you i'th child '''string'''

2.2) what is the age of your i'th child '''int'''

}

3) what kind of ice cream do you like? (multiple choise)

3.1) i don't like ice cream

3.2) vanilla

3.3) strawberry

3.4) chocolate

3.5) other: 3e) '''string'''

4) what do you eat? (multiple answer: checkboxes)

4.1) dogs

4.2) pussy

4.3) birds

= Action Plan=

(To be specified more in detail later)

== Outline==

Main deliverables:
*Database design for flat database
*Database design for multitable database
*Database design for section-flat database
*Class diagram for the database system
*API and documentation with the database system
*Implementation of the database system with at least one database layout (more if spare time is found)

== Milestones==

The first series of milestones is slightly smaller since both Maarten and Pieter-Jan have exams in the month of June.
*Database designs

+ # Flat layout

+ # multitable layout

+ # section-flat layout
*Class diagram
*API
*Implement basic classes

The second series of milestones will contain the biggest part of the implementation work and will be more specified once the class diagram has been fully worked out.
*Finish implementing basic classes
*Implement database layout engine
*Implement specific database layout

Database Storage Engine Project

2010-04-28T10:23:54Z

Ttielu:

__TOC__

= Outline=

The project is focused around the Google Summer Of Code of 2010. Maarten [[UserPage ttielu|ttielu]] and Pieter-Jan [[(UserPage MrP|MrP]]) are the students assigned to the project.

The project is based on the DB Storage Engine proposal found at [[LimeSurvey 2 Project Ideas for GSOC 2010]].

= Design and implementation=

A basic domain model of the problem can be found in [http://www.mediafire.com/?mytzjeggien this] pdf file.

This domain model can be used to build multiple databases. One would be to see the objects as tables. For the inheritance there would have to be some analysis to see how they should be mapped to the database. Here it would be important to use a low amount of joins. This structure has the disadvantage that when querying all information of a certain user, loads of joins might be required (depending on the complexity of the survey). On the other hand, queries about all answers on a single question can be very efficient. On top of that, tables are small.

Another example could be to remove the QuestionDependency and make one table per section. This would allow a more flat database structure, which reduces the number of joins necessary to retrieve all data from a single user. This could however create large tables and removes the possibility to loop over one question. This question will have to be placed into a new section and the loop will have to go over that section.

To allow these multiple database formats, we plan on using a [http://en.wikipedia.org/wiki/Factory_pattern factory pattern]. A DatabaseLayoutFactory can be used to choose the layout for a survey and in this way make it possible to add new database layouts for future use (for example a database which duplicates the data in both structures to get fast retrieval of both types of query).

Our plan would be to model the presented database models in detail and then implement at least one of them. Also we would want to model an API for the database (and of course implement that).

After creation of the survey, questions will be more or less static. To build upon this, it would be a good idea to store/cache the questions in a more static form, like a generated html-form, after creation of the survey.

== Database layouts==

=== Flat database===

A flat database would exist of a single table containing all answers to all questions.

Properties of this layout are:
* easy to export
* fast database operations
* hard to implement loops, branching & conditioning (introduce maximums on looping and have loads of NULL values OR use TEXT/BLOB fields containing sub structures => slow and unsearchable with quick operations)
* not suited for exotic question types (upload picture, matrix questions, multiple answer, multiple type questions, ...)
* database column limits might be hit
* best for simple surveys with huge amounts of answer data

=== Multitable database===

A multitable database would exist of multiple tables each containing the answers of a single question or questiontype.

Properties of this layout are:
* more difficult to export
* slower database operations (joins)
* supports all sorts of branching, conditioning, loops, ... including future features
* can support pictures, matrix questions, ... easily
* no problems with database column limits
* better for complex surveys with smaller amounts of replies

=== Hybrid database (section flat)===

The section flat model is a mix of the previous two models. In stead of mapping all answers in one table, we would map all answers to one section in one table. This allows the more advanced features (like looping, ...) to be handled between sections while still having a fast export of the different sections.

Properties of this layout are:
* easy to export
* fast database operations for simple surveys, operations for surveys with loads of loops, branching, ... will need joins (to handle the dependencies)
* database column limit only for really long sections (but they could be split in multiple sections, solving the problem)
* can support multiple question types (might result in using more columns, like in case of matrix questions)
* results in looping over sections instead of looping over questions in sections (hence if there is a loop over one question, there will be a section containing only this question; multiple questions in the same loop can be grouped in one section)

=== Layout mock-ups===

Mock-ups for the database layouts can be found in [http://www.mediafire.com/?nwjwy2c34mw this] pdf file.

The survey used is:

1) how many children do you have? '''int'''

loop: amount of children {

2.1) give the name of you i'th child '''string'''

2.2) what is the age of your i'th child '''int'''

}

3) what kind of ice cream do you like? (multiple choise)

3.1) i don't like ice cream

3.2) vanilla

3.3) strawberry

3.4) chocolate

3.5) other: 3e) '''string'''

4) what do you eat? (multiple answer: checkboxes)

4.1) dogs

4.2) pussy

4.3) birds

= Action Plan=

(To be specified more in detail later)

== Outline==

Main deliverables:
*Database design for flat database
*Database design for multitable database
*Database design for section-flat database
*Class diagram for the database system
*API and documentation with the database system
*Implementation of the database system with at least one database layout (more if spare time is found)

== Milestones==

The first series of milestones is slightly smaller since both Maarten and Pieter-Jan have exams in the month of June.
*Database designs

+ # Flat layout

+ # multitable layout

+ # section-flat layout
*Class diagram
*API
*Implement basic classes

The second series of milestones will contain the biggest part of the implementation work and will be more specified once the class diagram has been fully worked out.
*Finish implementing basic classes
*Implement database layout engine
*Implement specific database layout