=== Ravanix – Smart Psychological Assessment ===
Contributors: ravanix
Tags: psychological test, questionnaire, psychometrics, personality test,
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 3.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Psychological test and questionnaire builder: Likert scales, scoring, skip logic, composites, charted results, audit trail. Persian and RTL ready.

== Description ==

**Ravanix is a free psychological test and questionnaire builder for WordPress.** Design any questionnaire -- personality, wellbeing, screening, satisfaction, education or research surveys -- with dimensions (subscales), 5- and 7-point Likert, yes/no and custom multiple-choice items, reverse scoring, weights, skip logic and your own interpretation ranges. When a participant finishes, Ravanix scores the answers on the server, draws a profile chart and shows a plain-language interpretation for every dimension. You review every result in the admin panel.

Ravanix is built for psychologists, counselors, teachers, clinics and researchers who need results they can trust: scoring is deterministic and testable, every result stays tied to the exact version of the questionnaire that scored it (even after you edit the test), and to the exact consent wording the participant agreed to. It works the same in right-to-left (Persian, Arabic) and left-to-right languages, and every screen is translation-ready.

= Try it in one minute =

On activation Ravanix creates a ready-made sample questionnaire so you can see everything working. **The sample follows your site language:** a Persian (right-to-left) version on a Persian site, an English version otherwise. It has 25 items on 4 pages and uses nearly every free feature -- Likert 5 and 7, yes/no and multiple-choice items, reverse and weighted scoring, five scored dimensions, two composite scores, skip logic with AND/OR and all six operators, shuffling that respects dependencies, a consent notice, Save my progress and ranked results. Take it, then open it in the builder to see how each feature is set up.

= Key features (free, in this plugin) =

* A fully dynamic test builder: any number of tests, each with its own dimensions, questions and interpretation ranges
* Question types: 5- and 7-point Likert, yes/no, custom multiple-choice with any numeric value; reverse scoring and an importance weight per question
* Interpretation ranges per dimension, each with a label, colour and description
* **Composite factors:** combine several dimensions into a total or an average and interpret that on its raw score
* **Conditional logic (skip logic):** show a question only when earlier answers match, combined with AND or OR and six comparison operators; randomization of questions and answer options is dependency-aware, so it never moves a question before one it depends on
* **Test versioning:** an immutable snapshot of the scoring-relevant definition is kept whenever a test meaningfully changes, so a result always says which version scored it
* **Informed consent:** a site-wide or per-test notice the participant must agree to, recording exactly which wording was shown and when
* **Save and resume:** answers always autosave in the browser; an optional button lets a logged-in participant continue on another device
* **Audit Trail:** a tamper-evident, hash-chained log of who changed what and when, with before/after values, integrity verification and CSV download
* **My Results:** a shortcode that shows a logged-in participant their own past results; a Print this result button on every result screen
* **CSV export** of a test's results (spreadsheet formulas in participant text are neutralized; the file is UTF-8 with a byte-order mark, so Persian and Arabic text opens correctly in Excel)
* Display a test with a shortcode, a Gutenberg block, a widget, or as its own custom-post-type page with an SEO-friendly URL, tags and categories
* Bulk paste-import of questions and options; pagination with a progress bar for long questionnaires
* Configurable participant fields (name, education, mobile, email, age, gender)
* A clean Material Design 3-inspired front end with an adjustable brand colour and automatic light/dark appearance
* Result charts drawn with Chart.js (bundled locally, no external CDN)
* **Accessibility:** a WCAG 2.2 AA review of the participant form and result -- labelled fields, announced errors, keyboard focus management, chart text alternatives and contrast-safe level badges
* **A tidier admin:** long help texts collapse behind a small info button, with an optional "Show all help text" switch; the roles and permissions table scrolls cleanly on phones
* Anti-spam protection (honeypot, minimum completion time, rate limiting)
* Right-to-left and left-to-right layouts that follow the site language; fully translation-ready (a .pot file is included)
* WordPress Export and Erase Personal Data integration, plus an opt-in "delete all data on uninstall" setting

= Ravanix Pro =

A separate, paid companion plugin, **Ravanix Pro**, is available from [psykey.ir](https://psykey.ir). It adds norm-based Z and T scores and estimated percentiles with full norm provenance, weighted, standardized and formula composites, validity scales and advanced validity rules, response-quality analysis, forced-choice and overlapping scales, a Report Builder, research exports (wide CSV, codebook, SPSS and R), AI-assisted draft interpretations with human review, JSON import/export, access codes and execution limits, WooCommerce integration and repeated-attempt trend charts. It also installs a 40-item training test (Persian or English, to match your site) that shows all of it. Ravanix Pro requires this plugin and is not hosted on WordPress.org. See the "Upgrade to Pro" page in the plugin's menu for a full comparison.

= Important note about standardized instruments (NEO, Millon, Beck, MMPI, etc.) =

The items, official scoring keys and norms of standardized, copyrighted instruments (NEO-PI-R, MMPI, Millon CMI, the original Beck inventories, etc.) belong to their publishers and are not included in this plugin. With legitimate, licensed access to such an instrument you can enter its items, scoring and interpretive keys yourself; the plugin only provides the technical infrastructure. Questionnaire results are screening and descriptive information, not a diagnosis.

== Installation ==

1. Upload the plugin folder to wp-content/plugins, or go to Plugins > Add New > Upload Plugin and upload the zip file.
2. Activate the plugin.
3. A sample questionnaire (Persian on a Persian site, English otherwise) is created automatically so you can see how it works; create your own test from the "Ravanix" menu.

== Frequently Asked Questions ==

= Which sample questionnaire is installed, and can I choose? =

The language of your site decides: Persian (right-to-left) when the site language is Persian, English (left-to-right, or right-to-left on an RTL site) otherwise. The sample is created once, the first time Ravanix is activated. Developers can change the choice with the `ravanix_demo_language` filter. You can edit or delete the sample like any other test.

= Does the plugin include items from standardized tests like the NEO or the Beck inventory? =

No. These instruments are copyrighted. The plugin only provides the technical infrastructure (scoring engine, display and interpretation); you enter the items yourself from your own official, licensed source.

= Can a test be displayed on its own dedicated page with its own URL? =

Yes. In the plugin settings you can enable "Display as a custom post type" so that, in addition to the shortcode, each test also gets its own URL.

= Can I build a right-to-left (Persian or Arabic) questionnaire? =

Yes. A test's display direction (RTL or LTR) follows the site's active language -- a test displays right-to-left on a site running in Persian or Arabic, and left-to-right on a site running in English. The plugin's own screens are in English and translation-ready (a .pot file is included; use Poedit or Loco Translate to build your language file).

= Can I require participants to agree to a consent notice before starting? =

Yes. Set a default notice in Ravanix Settings, or a custom one per test (or turn it off) in that test's settings. It is shown collapsed with an "I agree" checkbox required before "Start Test", verified on the server too.

= Can a long questionnaire be saved and finished later? =

Yes. Answers always autosave in the browser. For long tests you can also turn on a visible "Save my progress" button per test, letting a logged-in participant resume on a different device.

= Can a question be shown only if an earlier question was answered a certain way? =

Yes, via each question's Conditional Logic setting: add one or more conditions ("this earlier question" / "equals, is not, greater than, less than, greater-or-equal, less-or-equal" / "this value") and choose whether all of them must be true (AND) or any one of them (OR). A hidden question is not required and is excluded from its dimension's score, like any unanswered one. If question randomization is on, a question is still never placed before another one its conditions depend on.

= If I edit a published questionnaire, do old results change meaning? =

No. Ravanix keeps an immutable snapshot of a test's scoring-relevant definition (questions, options, weights, reverse keys, interpretations and, with Ravanix Pro, norms, composites and branching) whenever it meaningfully changes, and stamps each result with the version that scored it. The result page says so explicitly if the questionnaire has since been edited.

= Can I combine several dimensions into one score? =

Yes. Open a test's Composite Factors tab, create a composite, choose "sum" or "average" and attach the dimensions that belong to it; interpretation ranges are set on the composite's raw score. With Ravanix Pro, composites can also be weighted, standardized or formula-based, with norms.

= Can I export results to Excel? =

Yes. The results list has a CSV export for one test (participant, date, raw score and percentage of every dimension and composite). The file is UTF-8 with a byte-order mark so Persian and Arabic text displays correctly in Excel. Some phone spreadsheet apps ignore the byte-order mark; if text looks garbled there, open the file on a computer or import it choosing UTF-8.

= Is there a record of who changed a test? =

Yes. Ravanix > Audit Trail (for administrators) logs every change to a test, deleted results, exports, imports and settings changes with the values before and after. Entries are chained with a hash and "Verify integrity" detects entries edited or removed in the database. Note that a hash chain shows tampering; it does not make the database itself immutable.

= What happens to my data if I delete the plugin? =

By default nothing is deleted; your questionnaires, results and settings stay in the database and come back if you reinstall Ravanix. To permanently delete everything, enable "Delete data on uninstall" in the Danger zone section of Ravanix Settings before removing the plugin -- this cannot be undone and never deletes Media Library images.

= Can a logged-in participant ask for their data to be removed or get a copy? =

Yes, through WordPress's own Tools > Erase Personal Data and Export Personal Data for a request tied to a registered user's email. Ravanix removes that user's identifying details (name, contact info, individual answers) while keeping the resulting dimension scores as anonymous data points, so site-wide statistics are not affected. The export includes the test, date, per-item answers (with the exact wording shown), dimension scores, consent record, completion time and any validity or response-quality flag. Both tools only cover logged-in users, since a guest submission has no account or email for WordPress to look up.

= What's the difference between Ravanix and Ravanix Pro? =

Ravanix (this plugin) is fully functional on its own. Ravanix Pro is a separate, paid add-on for professional and research use: norm-based scoring with provenance, advanced composites, validity scales, a Report Builder, research exports, AI-assisted draft interpretations with human review, data portability, access control and selling access to tests. See "Upgrade to Pro" in the plugin's menu for a full comparison.

== Screenshots ==

1. Test builder panel and dimension setup
2. Test form on the front end
3. Psychological profile display with a bar chart

== Privacy ==

For a guest participant: a `ravanix_guest_token` cookie (random ID, 3-year lifetime) and the submitting IP are stored with each result, solely for anti-spam rate-limiting and letting that guest resume an in-progress test. Nothing is sent to any external server. A logged-in participant using "Save my progress" (if enabled for that test) also has in-progress answers stored server-side until the test is completed or restarted.

Each completed result also stores: total completion time; if a consent notice was required, a short content hash of the exact wording shown and when it was agreed to (not the full consent text itself); and, if Ravanix Pro's response-quality analysis is active, a plain-language note rather than raw signal data. Questionnaire answers and scores can be sensitive personal data even without a name, so limit who gets the "view results" permission.

Participant info fields (name, email, etc.) are only collected if the admin turns them on. The Audit Trail stores the administrator's user id and the changed values (never access codes or passwords); its retention can be set or switched off in Settings. See the FAQ above for uninstall data deletion and WordPress's Erase/Export Personal Data tools.

== Changelog ==

Full history of earlier releases (before 3.0.3) is in changelog.txt.

= 3.1.0 =
* New: per-test setting "Who sees the scores": hide results from the participant, or mark a test "clinical results only" (needs the new capability "View scores of tests marked clinical results only")
* New: scores withheld by a Pro validity rule are left out of the participant response, My Results, print, exports and emails (never shown as zero)
* New: per-dimension missing-data policy, converted values as the basis of interpretation ranges, "Install the sample questionnaire" button
* Changed: deleting a test, dimension or question now needs a POST request; access codes are stored as a salted hash (existing codes are hashed on update and cannot be read back)
* Added: participant information fields can be chosen per test (a collapsible box on the test's general tab); by default a test follows the site-wide settings, so nothing changes for existing tests. A warning appears when norm groups or score tables depend on age or gender and those fields are not required
* Added: database update (schema revision 2 and 3) for Ravanix Pro's item-pair index; applied automatically, nothing changes for Lite-only sites
* Changed: result emails are sent once per result; a send that fails is retried up to two more times (about 10 minutes apart) and the state is kept per result, so a failure no longer blocks a retry for 24 hours
* Fixed: a score withheld by a Pro validity rule stays withheld if Ravanix Pro is later deactivated (Lite reads the stored decision itself; unreadable stored data withholds the scores)
* Changed: deleting a result, an interpretation range or a composite factor now needs a POST request
* Requires Ravanix Pro 3.1.0 if you use Pro

= 3.0.5 =
* New: score tables can belong to a composite as well as to a dimension (new column on ravanix_score_tables and on stored composite scores, created automatically on the first page load after updating). Deleting a composite or a test deletes its score tables. The result screen lists converted values of composites too
* Requires Ravanix Pro 3.0.5 if you use Pro

= 3.0.4 =
* New: the result screen shows converted scores from score tables (output, value, and the table used with its source and rights holder). A value that could not be converted says why (outside the table, no table for this participant, scale only partly answered); it is never shown as zero
* Requires Ravanix Pro 3.0.4 if you use Pro

= 3.0.3 =
* New (groundwork): score tables. Two new tables (ravanix_score_tables and ravanix_score_table_rows, created automatically on the first page load after updating) and one new column on stored scores hold explicit raw-score conversion tables, such as a published raw-to-base-rate table, with provenance (source, version, rights holder, licence). Nothing changes for existing tests: a test without score tables is scored and versioned exactly as before. The screens to manage score tables come with Ravanix Pro.
* Deleting a dimension or a test now also deletes its score tables
* Requires Ravanix Pro 3.0.3 if you use Pro

== Upgrade Notice ==

= 3.1.0 =
New columns are added automatically. Access codes already saved are hashed once on update: you cannot read them back afterwards, so set a code again if you need to share it. No change for tests that do not use the new settings.

= 3.0.5 =
Adds score tables for composites (one new column on two tables, created automatically). No change for tests that do not use them. Update Ravanix Pro to 3.0.5 as well.

= 3.0.4 =
Adds the converted-scores table to the result screen. Update Ravanix Pro to 3.0.4 as well.

= 3.0.3 =
Adds the database groundwork for score tables (two small tables, created automatically). No visible change for existing tests. Update Ravanix Pro to 3.0.3 as well.

= 3.0.2 =
Fixes a one-time fatal error right after updating the plugin and adds a small report-log table (created automatically). Update Ravanix Pro to 3.0.2 as well.

= 3.0.1 =
More reliable Audit Trail verification under heavy simultaneous activity and a more complete personal-data export. No database changes. Update Ravanix Pro to 3.0.1 as well.

= 3.0.0 =
New sample questionnaire in Persian or English (by site language, only on first activation), an info-button help text in the admin and a phone-friendly permissions table. No database changes. Update Ravanix Pro to 3.0.0 as well.

= 2.9.0 =
Adds the Audit Trail (two tables, created automatically; on by default) and accessibility improvements. Update Ravanix Pro to 2.8.0 as well.

= 2.8.0 =
Adds composite factors, a CSV export and the My Results page to the free version. No database changes. Update Ravanix Pro to 2.7.2 as well.

= 2.7.0 =
Adds two tables for Ravanix Pro 2.7.0 (created automatically). Update Ravanix Pro at the same time.

= 2.6.2 =
Fixes a bug in 2.4.0-2.6.1 that stored a wrong submission date (and lost per-question timing and the consent time) for new results. Update immediately; results saved by the affected versions keep their scores but show an unknown date.

= 2.6.1 =
Code-quality release; no database or behaviour changes.

= 2.6.0 =
Adds columns and a table for Ravanix Pro 2.6.0 (advanced composites, advanced validity, research export). Created automatically; back up first and update Ravanix Pro at the same time.

= 2.5.0 =
Adds two tables for Ravanix Pro's Report Builder (created automatically). Update Ravanix Pro to 2.5.0 at the same time.

= 2.4.0 =
Adds columns for response-quality data and widens the guest-token column (done automatically). Unsubmitted Save & Resume drafts are now deleted after 90 days by default (Settings > Privacy and data retention). Back up first; update Ravanix Pro to 2.4.0 at the same time.

= 2.2.0 =
Adds a table for stored composite scores and a richer version snapshot (one new test version appears after the first result saved following the update). Includes security and data-integrity fixes from 2.1.1 -- back up first. If you use Ravanix Pro, update it to 2.2.0 at the same time.

= 2.1.0 =
Adds a new database table (validity rules) automatically on activation. Existing single-threshold validity scales keep working unchanged. If you use Ravanix Pro, update it to 2.1.0+ at the same time.

= 2.0.1 =
Recommended: adds the Personal Data Exporter (Tools -> Export Personal Data). No database changes since 2.0.0.

= 2.0.0 =
Major update: Test Versioning, richer AND/OR Conditional Logic, consent provenance, two mobile-display fixes. Adds new DB tables/columns on activation -- back up first. If you use Ravanix Pro, update it to 2.0.0+ at the same time.

= 1.3.2 =
Recommended: faster loading for large questionnaires, safer background site updates, and several accessibility/security fixes. No database changes.

= 1.3.1 =
Recommended: fixes horizontal-scroll layout issues on several admin tabs.

= 1.3.0 =
Recommended: fixes dark-mode readability that 1.2.3 missed on three pages, plus a horizontal-overflow bug on the Dimensions admin tab.

== Technical Note ==

Chart.js is bundled locally (no external CDN). The source translation
file is at languages/ravanix.pot; use Poedit or Loco Translate to build
.po/.mo files for your language from it.
