=== AP One-Name Studies ===
Contributors: ancestorpress
Tags: one-name study, surname, genealogy, family history, surname distribution
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Publish your one-name study on WordPress: surname variants, a searchable occurrence index, distribution maps and full CSV export.

== Description ==

**Keep your one-name study on your own WordPress site - self-hosted, with your data in your own database rather than locked inside a third-party genealogy platform.** AP One-Name Studies is built for registered one-name studies: manage surname variants and deviants to Guild of One-Name Studies definitions, index every occurrence of the name wherever it is found, map its distribution across the historic counties of Britain and Ireland, and publish it all as searchable pages on your own site - without needing TNG or any external service.

Your data lives in your own WordPress database and can always be exported in full as CSV. No lock-in, ever - a study should outlive its author, and it only can if the data is truly yours.

Built by [AncestorPress](https://ancestorpress.com) - tools for family history, built to last.

---

### What You Can Do With the Free Version

- **A dedicated home for your study** - one registered surname per site, with its spellings, occurrence index, maps and public pages all in one place
- **Variants and deviants to Guild definitions** - variants are registered and grouped under the study surname; deviants (one-off clerical errors) are held on file without polluting the canonical spelling family
- **Occurrence entry built for record-taking** - context fields stick between entries, the cursor returns to the name field, Enter saves; dates like "Q3 1861", "abt 1790" and "1751/52" are understood, and anything unreadable is stored exactly as written
- **CSV import with column matching** - upload your spreadsheet and point each column at a study field; FreeBMD and census layouts are recognised automatically; census facts (age, occupation, relation, condition, birthplace) land in their own fields; values are stored verbatim and nothing is ever merged or overwritten
- **Save your own import templates** - your workbook's column matching remembered by heading, so next quarter's import is a single click
- **Every import is undoable** - each import is kept as a record set, so a wrong file or wrong matching can be removed as a whole without touching anything else
- **Public study pages in one click** - homepage, registered spellings, a searchable paginated occurrence index and a contact form, created as draft pages ready for you to review and publish
- **Distribution analysis** - occurrences by place and period, plus a choropleth map of the historic counties of the UK and Ireland (the boundaries GRO-era records were kept in, keyed by Chapman code)
- **Privacy that fails closed** - nothing shows until you switch the study public; private entries and anything linked to a living person are never displayed
- **Complete CSV export** - every field of every occurrence, including your as-recorded originals, plus the spelling register
- **Archive export for preservation and handover** - one ZIP holding the whole study as documented JSON plus flat CSVs and a plain-English README, built so your study outlives you and your platform
- **GEDCOM export** of the study's reconstructed people - a standard GEDCOM file, at full fidelity, that opens in Family Historian, Legacy, RootsMagic, TNG and any genealogy application. Your data is never locked in
- **Three display styles** - Heritage (matches AP Family Trees), Modern, or hand the styling entirely to your own theme

---

### Pro

Add the worldwide picture:

- **The worldwide distribution map** - the name's emigration story by country, with your UK and Ireland county work rolled up automatically
- Coming to Pro: distribution over time (census and GRO period presets), Guild register-ready study reports, the reconstitution workbench, and record-collection backing

---

> This free plugin is the complete home of a one-name study: a single registered surname with its spellings, occurrence index, maps and public pages. All current editions manage one surname study per WordPress site. The Pro version (the worldwide distribution map) is obtained from ancestorpress.com and installed as the paid build of the plugin - its code is not part of this free package.

---

### Who It Is For

AP One-Name Studies is designed for:

- **Registered one-namers** who want their study published on their own site, in their own hands, rather than on a shared platform
- **Guild of One-Name Studies members** who follow the variant and deviant conventions and need them respected exactly
- **Family history societies** presenting a surname study in a structured, public, professional format
- **Anyone tracking a surname across records** who has outgrown a spreadsheet and wants a proper occurrence index, distribution maps and public pages

### What Makes It Different

Most genealogy plugins publish a family tree. A one-name study is a different shape of work: it collects every occurrence of a surname wherever it appears - not one lineage but the whole spread of a name - and asks where and when it occurs. AP One-Name Studies is built for that shape. It keeps your spellings to Guild definitions, indexes occurrences without ever rewriting your originals, and maps distribution by the historic counties records were actually kept in.

Your data stays on your server, stored in your own WordPress database - not uploaded to an external genealogy platform or locked behind someone else's service. And because it shares a data core with AP Family Trees, the families you reconstitute from a study can be published through the tree plugin too.

---

= Works with AP Family Trees =

AP One-Name Studies is part of the AncestorPress suite and shares its data core with **[AP Family Trees](https://wordpress.org/plugins/ap-family-trees/)** - our free plugin for publishing beautiful, interactive family trees on WordPress. Reconstitute families from your one-name study and publish them as charts and profile pages through AP Family Trees, from the very same data, with no re-entry and no export/import round-trip. If you publish family history on WordPress, the two are built to work side by side.

Get AP Family Trees free from the WordPress.org plugin directory: [https://wordpress.org/plugins/ap-family-trees/](https://wordpress.org/plugins/ap-family-trees/)

---

= Help us get it right - one-namers, we are listening =

AP One-Name Studies is brand new. We have built it with care and with respect for the discipline, but we are software makers first, not career one-namers - and one-name study is a deep field with conventions and niches we may not have caught. If we have missed something that matters to your study, we would genuinely rather hear it than not.

Tell us what a one-name study needs, flag anything that works against Guild practice, and suggest features on our Future Direction page: [https://www.ancestorpress.com/ap-one-name-studies-wordpress-plugin/future-direction/](https://www.ancestorpress.com/ap-one-name-studies-wordpress-plugin/future-direction/) - it has a short, open suggestions form and shows where we are looking next. Every idea from a working one-namer is read and weighed. (For troubleshooting, please use the [WordPress.org support forum](https://wordpress.org/support/plugin/ap-one-name-studies/).)

---

= Maps and data =

The county and country maps use openly licensed boundary data. UK county boundaries come from the [Historic County Borders Project](https://county-borders.co.uk/); Irish county and world country boundaries are derived from [Natural Earth](https://www.naturalearthdata.com/) (public domain). These are the historic geographies GRO-era records were kept in, keyed by Chapman code - not modern administrative boundaries.

= Third-party libraries =

This plugin bundles the following open-source libraries. All are GPL-compatible.

* [php-gedcom](https://github.com/mrkrstphr/php-gedcom) by Kristopher Wilson - MIT licence. A namespaced GEDCOM library bundled with the shared AncestorPress Core, used by the suite's GEDCOM import/export services.
* [Freemius WordPress SDK](https://github.com/Freemius/wordpress-sdk) by Freemius - MIT licence. Used for licence management on the Pro plan.

= Privacy and data =

This plugin does not collect or transmit any personal data from your site or your visitors to us. All study data is stored exclusively in your own WordPress database. The optional public contact form emails enquiries to the study contact address you set, and nowhere else.

This plugin bundles the Freemius SDK for licensing and update management. What it does, and when:

* **On activation** Freemius may show a one-time opt-in screen. Opting in sends basic environment and account information - your site URL, WordPress and PHP versions, and the email address you enter - to Freemius so it can provide update notices and support. This opt-in is **optional**: click **Skip** and the plugin stays fully functional; nothing is transmitted, and no licence activation is required to use the free plugin.
* **If you buy and activate a Pro licence** the SDK contacts Freemius to validate the licence and deliver Pro updates.
* Your study data and your visitors' data are **never** sent to Freemius.

Freemius's terms and privacy policy: [Terms of Use](https://freemius.com/terms/) and [Privacy Policy](https://freemius.com/privacy/).

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/ap-one-name-studies`, or install the plugin directly from the WordPress plugin repository under **Plugins > Add New**.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Go to **One-Name Studies** in the admin menu and add your study, then work through the tabs: Spellings, Import (or enter records directly), Distribution and Settings.
4. On the Settings tab, click **"Make the pages for me"** to generate the public pages as drafts, review and publish them, and tick **Public pages** when you are ready to go live.

For full documentation, visit [ancestorpress.com](https://ancestorpress.com).

== Frequently Asked Questions ==

= What is the difference between a variant and a deviant? =

The plugin follows the Guild of One-Name Studies definitions exactly. A variant is a spelling actually used - by the person, or consistently in official documents - and is grouped under the study surname. A deviant is a one-off error (a typo, misreading or mishearing); it is kept on record so its entries stay findable, without joining the surname's spelling family.

= Can I run more than one study on a site? =

AP One-Name Studies is designed to manage one surname study per WordPress site, in every edition. Each site is the home of a single registered surname, with its own spellings, occurrence index, maps and public pages. A separate WordPress installation or multisite subsite should be used for each additional study.

= Will it change or "clean up" my data? =

Never. Names, dates and places are stored exactly as recorded; standardised values used for sorting and mapping are stored separately and stay correctable. Importing never merges or overwrites existing entries.

= Can I get my data back out? =

Always, and completely - the full occurrence CSV (every field, including your as-recorded originals) and GEDCOM export of the reconstructed people are both free features and always will be.

= Which counties does the map use? =

The historic counties of the United Kingdom and Ireland - the geography GRO-era records were kept in, keyed by Chapman code - not modern administrative boundaries. UK boundaries come from the Historic County Borders Project; Irish counties from Natural Earth.

= Does it work with my family tree plugin? =

It shares a data core with [AP Family Trees](https://wordpress.org/plugins/ap-family-trees/) - our free tree-publishing plugin, also on WordPress.org - so occurrences you link to people appear in both. GEDCOM export (free) opens in any standard genealogy program.

= How do I upgrade to Pro? =

AP One-Name Studies Pro is supplied separately from WordPress.org. After purchasing a licence from the Upgrade tab in the plugin sidebar, download and install the Pro package using the instructions supplied with your purchase (it replaces this free build). The Pro package adds the worldwide distribution map and retains the same one-study-per-site design as this free edition; its code is not part of this free package.

= Does it work with my theme? =

AP One-Name Studies outputs standard WordPress HTML and loads its own styles only for its public components. Choose the Modern or Heritage display style, or hand styling entirely to your theme. It is designed to sit cleanly within any well-coded theme.

= Is this for one-place studies too? =

One-place studies deserve their own tool, built place-first - it is on the AncestorPress roadmap as a separate plugin.

== Screenshots ==

1. The occurrence index for a study - every recorded occurrence of the name, searchable and paginated.
2. Keyboard-first occurrence entry - context fields stay put between records, so you can key an entire register without touching the mouse.
3. CSV import with column matching - point each spreadsheet column at a study field; FreeBMD and census layouts are recognised automatically.
4. Distribution analysis - occurrences by place and period, from the study's own data.
5. The historic-county choropleth of the UK and Ireland, keyed by Chapman code - the default map, available free.
6. The worldwide distribution map (Pro) - the name's emigration story by country.
7. A public study page - registered spellings and the searchable occurrence index, in the Heritage display style.

== Changelog ==

= 1.1.0 =
* Saveable import templates are now FREE. Your workbook's column matching is remembered by heading and re-applied in one click; templates already saved under Pro are carried over automatically.
* Census facts get their own fields: age, occupation, relation to head, condition and birthplace are stored as recorded in dedicated columns (entry form and CSV import alike) instead of being folded into the note, so they stay searchable and analysable. FreeBMD mother's maiden name and spouse surname are captured structurally too.
* Every import is now a record set: the Import tab lists each import with its row count, and a wrong import can be undone as a whole without touching anything else. Existing and hand-entered occurrences are filed under a "Manual entries" set automatically.
* Dates now carry their precision: "Q3 1861" is stored as a quarter, "abt 1790" as an approximate year - the sortable date states what it actually asserts instead of implying a false exact day. Census households can be grouped with a household reference.
* New archive/handover export (free): one ZIP holding the whole study as documented, schema-stamped JSON plus flat CSVs, a media manifest and a plain-English README - built for preservation, deposit and handover.
* The shared AncestorPress core gains the record-set, saved-template, candidate, judgement and standing-interest foundations that later research features build on, with no future migration needed.
* Housekeeping for WordPress.org standards: the free package now contains no implementation, storage helpers, controls or assets belonging to the separately sold worldwide map (paid functionality attaches through neutral extension hooks instead), the shared core's one remaining global helper became a class method, the shared library's classes now carry fully descriptive namespaced names, and database queries bind table names through WordPress identifier placeholders. Now requires WordPress 6.2 or newer.
* The plugin is now structurally a single-study tool in every edition: creating your study is the first-run setup, and no limit code of any kind exists. All current editions manage one surname study per WordPress site.
* Admin screens no longer load fonts from an external CDN - typography now uses fonts available on your system, so admin pages make no third-party requests.
* The [aponst_distribution] shortcode now shows the standard distribution table when a requested map style is not available, instead of showing nothing.

= 1.0.5 =
* Prefix rename completed and made upgrade-safe: the plugin's internal code prefix is now the distinctive `aponst`, reaching the map SVG group class as well as all code. Existing study pages that embed the plugin's shortcodes are rewritten to the new `[aponst_*]` tags automatically on update, alongside the table, option and meta-key migration, so nothing stops rendering. (Shortcodes hand-placed in a widget should be updated by hand - see the upgrade notice.)
* GEDCOM export of your study's reconstructed people is a free feature (via the shared AncestorPress core), at full fidelity. The worldwide distribution map and saveable import templates remain Pro, supplied as a separate Pro package.
* Fixed the county map's base fill and stroke not applying (the map group class now matches the renderer).
* Security and code-quality hardening: a nonce on the public contact form, tighter place-assignment ownership checks, a hardened data-migration routine, and clearer documentation of how the Pro package is obtained.

= 1.0.3 =
* GEDCOM export of your study's reconstructed people is now a free feature (via the shared AncestorPress core), at full fidelity. The worldwide distribution map and saveable import templates remain Pro.
* Security and code-quality hardening: a nonce on the public contact form, tighter place-assignment ownership checks, and a more distinctive internal code prefix (existing data is migrated automatically on update).

= 1.0.2 =
* The plugin is now shaped around a single study - a dedicated home for one registered surname.

= 1.0.1 =
* Housekeeping: the Pro features (worldwide distribution map, saveable import templates) are cleanly separated from the free plugin, and map styling and shortcode output escaping were tidied.

= 1.0 =
* Initial public release: one-name study management with Guild-exact variant and deviant handling, keyboard-first occurrence entry, CSV importer with prebuilt FreeBMD and census matching, one-click public study pages, distribution table and UK & Ireland historic-county map, three display styles, and complete CSV plus GEDCOM export. Pro: worldwide distribution map and saveable import templates.

== Upgrade Notice ==

= 1.0.5 =
Internal code prefix finalised; existing study pages are migrated automatically. If you placed a study shortcode in a widget by hand, change its `[apon_...]` tag to `[aponst_...]`.

= 1.0.2 =
AP One-Name Studies is now shaped around a single study. Recommended for all users.

= 1.0.1 =
Housekeeping and hardening. Recommended for all users.

= 1.0 =
Initial public release.
