About:Pharmacopedia.ext: Difference between revisions

= Pharmacopedia extension specification =

'''Author:''' MDElliottMD · '''License:''' GPL-2.0-or-later

'''Source:''' <code>/var/www/mediawiki/extensions/Pharmacopedia/</code>

* Structured medicine pages via the <code><nowiki>{{MedTemplate}}</nowiki></code> template

* Two-perspective data capture (personal vs. provider) wherever clinically meaningful

* User profile with dimensional personality / autism assessments (CATI, CAT-Q, MBTI, Enneagram, PID-5-BF, OCEAN/BFI-10) and rich auto-generated reports

* ADHD screening (ASRS and AMAAS-SR) plus a Formal testing log of standardized-test scores, every score field carrying its own visibility

* Diagnosis autocomplete backed by ~41,500 ICD-10-CM, ICD-11, and DSM-5 codes

* '''Life-story timeline''': visual swimlanes (vis-timeline 7.7.3, vendored Apache-2.0) plus a synchronized trait-trajectory overlay (vis.Graph2d); card-list view alongside; quick-add free-text observation parser; range-date episode form with severity slider

* '''Per-record sharing subsystem''': rule types include public, private, users, cohort, link_token, reciprocal; time-bounded; audit log of who-viewed-what; bulk free-text → structured ref upgrader; privacy mode that disables legacy fallback

* Chip-picker / autosave / slider-precise-input UI framework shared across editor surfaces

* Date + time + range kit: PCPDatePicker (point/range/possibility), PCPTimePicker (fuzzy time-only: "4p", "noon", "quarter past 6")

* '''Backend (PHP):''' <code>includes/</code>, one class per parser tag, store, special page, or API module. Auto-loaded under <code>MediaWiki\Extension\Pharmacopedia\</code>. Assessment classes under <code>includes/Assessments/</code>. API modules under <code>includes/Api/</code>.

** <code>ext.pharmacopedia</code>: main IIFE (chip-picker, dx autocomplete, BFI-10 compute, vote logic for both binary and choice/multi)

** <code>ext.pharmacopedia.blocksave</code>: debounced autosave per block (race-safe)

** <code>ext.pharmacopedia.share</code>: per-record share dialog (People / Link / Cohorts tabs)

** <code>ext.pharmacopedia.observation</code>: quick-add observation textarea + live preview

** <code>ext.pharmacopedia.refupgrade</code>: bulk linker for free-text → structured refs

** <code>ext.pharmacopedia.lifegraph</code>: trait-trajectory overlay (vis.Graph2d) synced to timeline

** <code>ext.pharmacopedia.kitsync</code>: glue that propagates kit-widget changes into legacy hidden inputs + drives privacy-mode toggle

== Parser tags ==

| <code>&lt;anecdote&gt;</code> || Personal or provider story with up/down vote || <code>AnecdoteTag</code>

|-

|-

| <code>&lt;pharmaInteractions/&gt;</code> || Self-closing; renders the Interactions section for the current page || <code>InteractionTag</code>

|-

| <code>&lt;pharmaExperience/&gt;</code> || Self-closing; renders the Experience report form (efficacy, burden, dose, route, schedule, stop-reasons) || <code>ExperienceTag</code>

|}

=== Tag wikitext examples ===

* '''Enneagram''' (9 type sliders + 45-item screening test)

* '''MBTI''' (4 dichotomy sliders + 32-item OEJTS test)

* '''ADHD screening''' (ASRS adult-ADHD screener and AMAAS-SR attention self-report, each a collapsible inline test)

* '''Formal testing''' (a log of standardized-test scores; raw score, percentile and pass/fail each carry their own privacy setting)

Autocomplete via <code>action=pharmacopediadxsearch</code>, multi-token AND search (e.g. "ADHD inattentive" matches the F90.0 row that contains both substrings); ORDER BY <code>FIELD(da_system, 'ICD-10-CM', 'ICD-11', 'DSM-5', ...)</code> so ICD-10-CM leads, then ICD-11, then everything else.

{| class="wikitable"

|-

| '''OCEAN (Big Five)''' || 5 direct sliders + optional BFI-10 (10 items) || 0–100 per trait || none (personality, not pathology) || trait deep-dives (high / mid / low at your score), BFI-10 item table, cross-system mapping (MBTI ↔ Enneagram ↔ PID-5-BF) pulling live data from the profile

|}

All assessment items submit raw responses to <code>pcp_profile_fields</code> under namespace <code>{key}_raw</code> (e.g. <code>cati_raw</code>); the computed scores live under namespace <code>{key}</code> with keys like <code>subscale_SOC</code>, <code>total</code>, plus a <code>taken_at</code> timestamp. Re-scoring happens automatically on every save (autosave fires <code>scoreResponses()</code> on the full raw set, skipping "unsure" rows). Each completed assessment also auto-upserts a Life-story keyframe row (see [[#Life-story timeline|Life-story timeline]]) so trajectories plot over time.

=== ADHD screening ===

Every permitted view through a rule (not legacy) writes a row to <code>pcp_visibility_view_log</code>. <code>Special:MyShareLog</code> shows the last 200 views with timestamp, viewer (or anonymous IP masked to /24), namespace, key, rule id.

== Choice / multi voting ==

Slider numbers are also clickable: a single delegated handler on every <code>&lt;output&gt;</code> next to a range slider swaps it for a number input on click, accepts a precise typed value (clamps to the slider's <code>min</code>/<code>max</code>), commits with Enter, cancels with Escape.

== Special pages ==

|-

| <code>Special:MyAssessment/cati</code>, <code>/catq</code>, <code>/pid5bf</code>, <code>/mbti</code>, <code>/enneagram</code>, <code>/ocean</code> || Rich report per assessment; 🔗 Share chip in subtitle for owner

|-

| <code>Special:MyLifeStory</code> || Owner editor + visual timeline + card list. Quick-add observation textarea + Event/Episode buttons. 🔗 Share chip in subtitle. Privacy-mode + free-text-refs banners.

|-

| <code>Special:LifeStory/&lt;name&gt;</code> || Public life-story view (read-only, visibility-filtered)

|-

| <code>Special:MyCohorts</code> || Owner-managed groups for share-with-cohort flows; create / rename / delete / add+remove members

|-

| <code>Special:MyRefLinks</code> || Bulk linker: find free-text refs in observations that now match a structured entity; one-click upgrade or dismiss

|-

| <code>Special:SaveProfileBlock</code> || AJAX endpoint for autosave (POST-only, JSON response)

| <code>Special:Problem/&lt;slug&gt;</code> || Individual problem page

|-

|-

| <code>Special:ManageProblems</code> || Sysop tool for problem-repository moderation

|-

|-

| <code>Special:ManageInteractions</code> || Sysop bulk-edit interaction reports

|-

| <code>Special:DeletePharmaElement</code> || Sysop delete tool for any votable element

|-

|}

! Table !! Purpose

|-

|-

| <code>pcp_votes</code> || Binary +1/−1 votes (v_value) AND choice/multi votes (v_choices CSV + v_options_h drift hash)

| <code>pcp_interactions</code> || Interaction edges (canonical-ordered pair)

|-

|-

| <code>pcp_user_profiles</code> || Per-user profile meta (alias, attribution, voter hash, prof_research_id)

| <code>pcp_visibility_view_log</code> || Audit trail of rule-permitted views (Special:MyShareLog)

|-

|-

| <code>pcp_formal_tests</code> || Catalog of standardized tests (abbrev, full name, category, score format)

* '''Synthetic Event needs bubbles:true to trigger delegated listeners.''' <code>new Event('input')</code> defaults to <code>bubbles:false</code>, so listeners on parent wrappers never see programmatic dispatches. Native input/change events bubble by default; only JS-fired ones don't. Pass <code>{ bubbles: true }</code> explicitly. Bit DatePicker calendar-cell clicks 2026-05-18, typing in the text field autosaved fine, but picking a date from the calendar didn't, because blocksave's wrapper listener never received the event.

* '''MediaWiki form-field names collide with reserved URL params.''' A form <code>&lt;input name="title"&gt;</code> or <code>name="action"&gt;</code> with user-controlled value silently HIJACKS MW's dispatch when POSTed (body param overrides URL param). Symptom: form submits but lands on a wiki article named whatever the user typed, with URL bar still showing the special page. Bit the episode form 2026-05-18 (user typed 'Fake one' as title → got a 404 'create article: Fake one' page). Fix: prefix ALL custom form inputs with <code>pcp_</code> (both the input <code>name="..."</code> AND the matching <code>$request->getVal('...', ...)</code> read). Self-referential hidden inputs (<code>name="title" value="&lt;getPageTitle()&gt;"</code>) are safe.

* '''Cargo string fields cap at ~300 chars.''' <code>structure</code> and <code>mechanism</code> on MedTemplate are short VARCHARs; long prose goes in MEDIUMBLOB sections. Overruns silently lose Cargo data (MySQL Error 1406).

* '''VARBINARY + LOWER() is a no-op.''' MariaDB's LOWER() returns binary types unchanged. <code>pcp_diagnosis_abbreviations</code> was migrated VARBINARY → VARCHAR/utf8mb4 so case-insensitive LIKE works natively without CONVERT() wrappers.

* '''<code>&lt;span&gt;</code> can't contain <code>&lt;p&gt;</code>.''' MediaWiki auto-wraps tag content in <code>&lt;p&gt;</code> when there are newlines; browsers auto-close any <code>&lt;span&gt;</code> before the <code>&lt;p&gt;</code>, scattering child elements into wrong DOM positions. Use <code>&lt;div&gt;</code> for parser-tag wrappers whose content can span paragraphs (choice votes, life-story cards).

* '''vis.Graph2d group <code>style</code> belongs at TOP LEVEL''' not nested in <code>options</code>. Nesting silently fails (no error, just invisible lines). Bit the trait-trajectory graph on first build.

== Hooks ==

* <code>ParserFirstCallInit</code>: register all parser tags

* <code>LoadExtensionSchemaUpdates</code>: install / migrate schema (the sql/ directory + patches)

* <code>UserGetRights</code> + <code>UserEffectiveGroups</code>: verified-provider role wiring

* Various special-page registrations via <code>SpecialPage_initList</code>

* <code>$wgPharmacopediaInteractionCategoryMarker</code> (default <code>Category:MedCategory</code>): only categories tagged with this marker appear in the add-interaction modal

* <code>$wgPharmacopediaVoteHashSecret</code> (required): HMAC secret for <code>v_voter_hash</code> so vote rows can't be mapped back to user accounts by anyone reading the DB without the secret

* (Various permission-grant arrays via standard MW <code>$wgGroupPermissions</code>)

   |-- includes/

   |  |-- Hooks.php

   |  |-- *Store.php                (data access: EffectStore, ProblemStore, ElementStore, LifeStoryStore, ...)

   |  |-- UserProfileStore.php      (the big one; profile / dx / meds / abbreviations)

   |  |-- ObservationParser.php    (plain-text -> structured observation)

   |  |-- SpecialMyProfile.php      (the user profile editor; large)

   |  |-- SpecialMyLifeStory.php    (life-story editor + visual timeline; large)

   |  |-- Special*.php              (other special pages)

   |  |-- ProfileDatasets.php      (countries, languages, genders, religions, etc.)

   |  |-- DatePicker.php            (range / possibility-mix date widget backend + injectBirthdayContextOnce)

   |  |-- Assessments/

   |  |  |-- Cati.php, CatiNorms.php

   |  |  |-- Mbti.php

   |  |  |-- Enneagram.php

   |  |  `-- Raadsr.php            (deprecated 2026-05-17 in favor of CATI, kept for archival reads)

   |  `-- Api/

   |-- resources/

   |  |-- ext.pharmacopedia.js              (single IIFE: chip-picker, dx autocomplete, vote logic, ...)

   |  |-- ext.pharmacopedia.blocksave.js    (debounced autosave per block)

   |  |-- ext.pharmacopedia.share.js + .css

   |  |-- ext.pharmacopedia.observation.js + .css

   |  |-- ext.pharmacopedia.refupgrade.js + .css

   |  |-- ext.pharmacopedia.lifegraph.js + .css

   |  |-- ext.pharmacopedia.kitsync.js

   |  `-- vendor/vis-timeline/              (vis-timeline 7.7.3, Apache-2.0 + MIT)

   |      |-- vis-timeline-graph2d.min.js