=== 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.0.2
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 2.9.0) is in changelog.txt.

= 3.0.2 =
* Fixed: "Fatal error: Call to a member function add_rewrite_tag() on null" on the first page load after updating the plugin (a refresh made it go away). The upgrade routine registered the custom post type on plugins_loaded, before WordPress has created its rewrite rules object. It now runs on init, and if it is ever reached earlier it schedules the work in the background instead of failing
* New: report log. One small table (ravanix_report_instances, created automatically on the first page load after updating) records each time Ravanix Pro opens a formal report for a result: report type, built-in layout or custom template and its version, the test version the result was scored with, plugin version, who opened it and when. It holds no report content. Rows are deleted with their result or test, included in WordPress's Export Personal Data, detached from a user by Erase Personal Data, and dropped on uninstall when you chose to delete all data
* Requires Ravanix Pro 3.0.2 if you use Pro

= 3.0.1 =
* Fixed: Audit Trail. If the chain lock cannot be obtained within 5 seconds the entry is still written (an audit record is never lost and a stuck lock never blocks an administrator), the entry is remembered, and "Verify integrity" accepts exactly that known concurrent write with a note instead of reporting a false break. Any other mismatch is still reported as a break. The audit CSV download now also clears the output buffer first
* Fixed: WordPress's Export Personal Data now includes a result's stored composite scores when Ravanix Pro is not active (with Pro, its own export of composites is used)
* Requires Ravanix Pro 3.0.1 if you use Pro

= 3.0.0 =
* New: the sample questionnaire is rewritten in Persian (right-to-left) and English; the one matching the site language is created on first activation (25 items on 4 pages, composites, skip logic with AND and OR). Sites that already have the earlier sample keep it. Filter `ravanix_demo_language` overrides the choice
* New: long admin help texts collapse behind an info button (optional "Show all help text"); works in RTL and LTR, on phones and with the keyboard
* Fixed: the roles and permissions table on phones; CSV downloads now start with the UTF-8 byte-order mark (Persian and Arabic text in Excel)
* Improved: help assets are versioned by file time; tools/i18n.py keeps the language files in sync

= 2.9.0 =
* New: Audit Trail (Ravanix > Audit Trail, for administrators; Settings > Privacy and data retention to switch it off or set how long entries are kept). It records who changed what and when: every change to a test -- its settings, consent text, access code (recorded as "set / changed", never the value), execution limits, dimensions, questions, interpretations, norms, composite factors, validity rules -- with the values before and after; created and deleted tests; deleted results; exports and imports; Ravanix settings and the roles and permissions table; and, with Ravanix Pro, report templates and AI actions. It never stores participants' answers, names, e-mail addresses or IP addresses, or any secret
* Each entry is chained to the previous one with a hash, and "Verify integrity" detects entries that were edited or removed in the database. No screen edits or deletes entries; filters, a before/after view and a CSV download are available. The entries of a staff member can be exported through the WordPress privacy tool; they are kept (not erased) because they are a security record
* New capability "View the audit trail" (administrators by default; assignable in the permissions table). Tests now also record who last updated them (updated_by)
* Accessibility (WCAG 2.2 AA review of the participant form and result): answer options are announced with their question (radio groups), participant fields have real labels and required state, validation errors are announced and keyboard focus moves to the first unanswered question, focus moves to the new page and to the result, the progress bar exposes its value, charts have a text alternative, level badges choose black or white text for sufficient contrast, errors use a darker colour, tap targets are at least 44px, and animations respect the "reduce motion" setting
* Improved: the CSV export reads results in batches

== Upgrade Notice ==

= 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.
