README

Exponential Survey lets editors build questionnaires inside ordinary content objects, publish them on the site, collect the answers, and then read, edit, remove and export the results in the administration interface.

It is for site builders and editors who need customer feedback forms, member questionnaires, registrations, quizzes or simple polls without writing code. Every survey is an attribute of a content object (by default of the Survey class), so it has a URL, a section, translations, permissions and versions like any other content.

Features

An ezsurvey datatype: add a Survey attribute to any content class.
Question types: section header, paragraph, single/multiple choice (radio buttons or check boxes in a row or a column, or a selector), text entry, number entry, email entry, related object (a "Survey attribute" object with formatted text shown between questions), form receiver (send the answers by mail to an address the user picks, one per survey), and feedback field (send the user a copy of the answers).
Per survey: title, enabled, valid from / valid to dates, a URL to redirect to after Cancel and after Submit, "only one answer allowed" (per logged-in user) and "persistent user input" (users can come back and change their answers).
A Survey tab in the administration interface (admin4 draws the ui-radios icon before its name) with the list of surveys, their results, an overview per question, each single answer, editing and removing of answers, and CSV export.
A setup wizard that creates the database tables, installs the two content classes from the bundled package and configures the "related object" question.
Fetch functions and template functions to show surveys and results in your own templates.
A survey custom tag for XML text and a full view override for objects of the survey class.
Custom question types in your own extension (see Configuration).
Translations: Catalan, Croatian, English, Finnish, French, German, Japanese, Norwegian, Brazilian Portuguese, Spanish and Swedish.

Requirements

Exponential 6.x (the legacy kernel)
PHP 8.0 or later
MySQL/MariaDB, PostgreSQL or Oracle (SQL files for each are in sql/)
Working mail settings (site.ini [MailSettings]) if you use the receiver or feedback field questions.

Installation

With Composer

composer config repositories.ezsurvey vcs https://github.com/se7enxweb/ezsurvey
composer require se7enxweb/ezsurvey:^5.3.4

The se7enxweb/ezpublish-legacy-installer plugin puts it into extension/ezsurvey.

By hand

Download the release archive from https://github.com/se7enxweb/ezsurvey/releases and unpack it, or clone the repository, so that the files end up in extension/ezsurvey:

cd /path/to/exponential
git clone https://github.com/se7enxweb/ezsurvey.git extension/ezsurvey

Activate it

In settings/override/site.ini.append.php:

[ExtensionSettings]
ActiveExtensions[]=ezsurvey

To use it on some siteaccesses only, put ActiveAccessExtensions[]=ezsurvey into those siteaccesses' site.ini.append.php instead, and keep it active in the admin siteaccess.

Then regenerate the autoloads and clear the caches, from the installation's root directory:

php bin/php/ezpgenerateautoloads.php -e
php bin/php/ezcache.php --clear-all

Run the setup wizard

Open the administration interface and click the Survey tab. As long as the setup is not complete, the tab opens the wizard (survey/wizard), which takes you through:

Database: creates the tables ezsurvey, ezsurveyquestion, ezsurveyresult, ezsurveyquestionresult, ezsurveymetadata, ezsurveyrelatedconfig and ezsurveyquestionmetadata.
Survey classes: installs the package packages/ezsurvey_2.0-1.0-1.ezpkg with two content classes, Survey (survey) and Survey attribute (survey_attribute, used by the "formatted paragraph" question).
Related object configuration: choose the class used for those related objects and the folder where they are stored (for example a folder under Media). Make sure anonymous users can read that folder's section.

After that the tab shows the list of surveys.

To create the tables by hand instead, for MySQL/MariaDB:

mysql -u <user> -p <database> < extension/ezsurvey/sql/mysql/schema.sql

(sql/postgresql/schema.sql plus indices.sql, and sql/oracle/schema.sql, for the other databases.) The classes can also be imported in Setup > Packages > Import new package from extension/ezsurvey/packages/.

Configuration

The extension reads ezsurvey.ini. Override it in settings/override/ezsurvey.ini.append.php, never inside the extension.

<?php /*

[QuestionTypeSettings]
# Extensions that provide question types
ExtensionDirectories[]
ExtensionDirectories[]=ezsurvey
ExtensionDirectories[]=mysurveytypes

# Question types of an extension: each <name> is loaded from
# extension/<extension>/modules/survey/classes/ezsurvey<name>.php
[QuestionTypeSettings_mysurveytypes]
QuestionTypeList[]
QuestionTypeList[]=rating

[CSVExportSettings]
# true: the CSV export has a column with the user who answered
ShowUserName=true
# heading of that column
HeadlineUserName=Answer from

[PackageSettings]
# the package the wizard installs the classes from
PackageName=ezsurvey_2.0
PackagePath=ezsurvey/packages
PackageFileName=ezsurvey_2.0-1.0-1.ezpkg

*/ ?>

[RelatedObjectSettings] ContentObjectClasses[] is present in the file but not read by the code; the related object class is chosen in the wizard or in Survey > Related object configuration and stored in the database.

The extension also sets these in other INI files:

File	Setting	Purpose
`content.ini`	`AvailableDataTypes[]=ezsurvey`	registers the datatype
`content.ini`	`AvailableCustomTags[]=survey`	the `survey` custom tag
`content.ini`	`[VersionManagement] VersionHistoryClass[survey]=1000`	keeps 1000 versions of survey objects (see below)
`menu.ini`	`[Topmenu_survey]`	the admin tab, its icon (`Icon=ui-radios`) and URL `survey/list`
`module.ini`	`ModuleList[]=survey`	the `survey` module
`override.ini`	`[full_survey]`	full view template for objects of class `survey`
`browse.ini`	`[AddRelatedSurveyNode]`, `[AddRelatedSurveyObject]`	browse settings used by the wizard and the related object question
`design.ini`	`CSSFileList[]=survey.css`	the front-end stylesheet
`site.ini`	`ExtensionAutoloadPath[]`, `TranslationExtensions[]`	template operators and translations

Important: results belong to object versions. When a survey object reaches its version limit, the oldest versions are removed together with the results stored for them. Keep the limit high for every class that has a survey attribute:

# settings/override/content.ini.append.php
[VersionManagement]
VersionHistoryClass[survey]=1000
VersionHistoryClass[my_feedback_form]=1000

Usage

Create a survey

In Content structure, create an object of class Survey (or of any class with a Survey attribute).
In the Survey attribute, set the title and options, then choose a question type and add it with New attribute. Each question has its text, an order number, a visible flag and, where it makes sense, a Mandatory answer box and a default answer.
Publish the object. Visitors answer the survey on the object's page.

Read the results

Click the Survey tab. For each survey:

Results (survey/result/<object id>/<class attribute id>/<language>): an overview per question.
All evaluations (survey/result_list/...): each submitted answer, with links to view (survey/rview/...), edit (survey/result_edit/<result id>) and remove (survey/rremove/<result id>) it.
Export CSV (survey/export/<object id>/<class attribute id>/<language>): the answers as export.csv.

Templates

Show a survey attribute with the normal attribute view:

{attribute_view_gui attribute=$node.data_map.survey}

Embed a survey in XML text with the survey custom tag; its template fetches the survey by its id:

{fetch( 'survey', 'survey', hash( 'id', $id ) )}

Fetch functions of the survey module:

{* a survey by id *}
{def $survey = fetch( 'survey', 'survey', hash( 'id', 12 ) )}

{* number of answers to a survey attribute *}
{def $count = fetch( 'survey', 'result_count', hash( 'contentobject_id', $node.contentobject_id,
                                                     'contentclassattribute_id', $attribute.contentclassattribute_id,
                                                     'language_code', $attribute.language_code ) )}

{* has the current user answered this survey already? *}
{if fetch( 'survey', 'already_posted', hash( 'survey_id', $survey.id ) )}
    <p>Thank you, you have answered this survey.</p>
{/if}

{* one stored result *}
{def $result = fetch( 'survey', 'survey_result', hash( 'result_id', $result_id ) )}

multiple_choice_result, text_entry_result, multiple_choice_result_item and text_entry_result_item return the answers of one question; see design/standard/templates/survey/result/ for how the bundled templates use them.

Template functions draw one question with the template of its type: survey_question_edit_gui, survey_question_view_gui and survey_question_result_gui (templates under survey/edit/, survey/view/ and survey/result/). The number operator is also available.

Permissions

The survey module has two functions:

Function	Views	Give it to
`survey/administration`	`wizard`, `list`, `relatedobjectconfig`, `edit`, `copy`, `preview`, `result`, `rview`, `result_list`, `result_edit`, `rremove`, `remove`, `export`	editors who manage surveys and results
`survey/filling`	`view`, `action`	everyone who answers surveys, including the Anonymous role

Add them in Users > Roles (module survey). Answering a survey shown as a content attribute also needs the usual content/read on the object.

Cron jobs and scripts

No cron job is needed. bin/php/ezsqldumpsurveydata.php is an old development helper; it is not needed to install or run the extension.

Upgrading

From 5.3.x: replace the extension's directory, regenerate the autoloads and clear the caches. No database change.
From 1.x on MySQL/MariaDB: run update/database/mysql/2.1/dbupdate-1.0.0-to-2.1.0.sql, then continue as above. On Oracle, from 2.2: run update/database/oracle/2.3/dbupdate-2.2.0-to-2.3.0.sql.

Known limits

Results are stored per object version; see the version limit note under Configuration.
"Only one answer allowed" can only be enforced for logged-in users; anonymous visitors are asked to log in.
The admin templates use the classic admin markup; they render in every admin design but do not use admin4's own components.

Troubleshooting

The Survey tab always opens the wizard: a setup step is missing; the wizard shows which one (tables, classes, related object class or its folder).
Results disappeared after editing the survey: the version limit removed old versions; raise VersionHistoryClass[<class>].
"File does not exist: .../ezsurvey.php" in the debug output: a QuestionTypeList[] entry has no class file in that extension.
Mails of receiver or feedback questions are not sent: check [MailSettings] in site.ini (EmailSender or AdminEmail is used as sender).
See also doc/FAQ.

Contributing

Issues and pull requests are welcome at https://github.com/se7enxweb/ezsurvey. The original installation notes are in INSTALL and doc/.

License

GNU General Public License v2.0, see the LICENSE file.

Credits and history

eZ Systems developed eZ Survey for eZ Publish, the content management system that Exponential continues, and maintained it with the community until release 5.3.3 (2014). 7x maintains it for Exponential since 2026: release 5.3.4 added the admin tab's icon and modernized the package files and this guide.

se7enxweb / ezsurvey

Package info

Security

Fund package maintenance!

Statistics