webtrees module LinkEnhancer

TL;DR

Cross-references to Gedcom datasets, Markdown editor, context-sensitive link to the GenWiki Webtrees manual

What you can expect from the module, illustrated with screenshots:

Screenshots	Screenshots

note with enhanced links and image from media record	site title as home link small menu with help link

markdown editor	markdown help

Here are the available options that can be set on the admin page of this module:

Description

This module wraps up some examples mentioned in the German Webtrees Manual and improves the application of these features - each component can be activated individually.

The main purpose of this module is to make links to data records stored in family trees more convenient. This avoids having to store fully qualified links, which impairs the portability of Gedcom data. By linking the notes to the GEDCOM data records (persons, families, sources, etc.) from the text makes story telling much easier and thus also save this information in the GEDCOM file (maybe this is an alternative for the stories module). The option of embedding the images already inserted in the family tree in the notes rounds off this approach. The link function is controlled via the anchor part of the URI, so it's no problem, if this module is not active - the url just points to the current webtrees page.

Additionally there are some goodies more or less related with links:

The note textarea can be a visual markdown editor with markdown help.
Enabling further markdown extensions.
Context sensitive help links to the german webtrees manual can be activated in the small menu at the top of the page and for subcontext topics on the page. Furthermore, full-text search is supported and it is possible to browse the table of contents.
The site title can be a link to the tree homepage or the user my page.
A few minor patches, that can applied by bash script (not necessary for this module).

Enhanced links

Although webtrees replaces XREFs such as @I2@ in notes with a cross-reference and it's appropriate display name, this is not so flexible. You can't determine the display name. Unfortunately, this does not work in the HTML block on the start page if you want to refer to a data record in the continuous text without inserting absolute references (such absolute references could be entered in the source code of the HTML block as follows, for example: <a href="https://mytree.somewhere/tree/mytree/individual/I2">Jon Doe</a>).

Hint: The custom module webtrees-mitalteli-show-xref can help you find the XREF reference of personal data records.

The enhanced links function is implemented via Javascript and searches in the rendered output of webtrees for <a> tags whose href attribute values begin with #@. This way it is possible to handle links in markdown and html markup. Because it is processed in the browser on client side, the existence of the cross-referenced data records in webtrees is not checked in advance. Errors only occur when the link is clicked (e. g. if the access to the ressource is restricted).

As a bonus different destinations can be addressed with one link definition, whereby the cross-reference is always the first link (if set) and the others are represented by attached clickable icons only. Included are the following predefined external targets (the parameter keys are listed in parentheses):

Wikipedia (wp)
Family Search Family Tree (fsft)
Residents database - Family research in West Prussia (ewp)
OpenStreetMap (osm)
Wer-wir-waren.at (www) - a service of the Vorarlberger Landesmuseumsverein
CompGen services:
- GenWiki (gw)
- Online Local heritage books (ofb)
- The Historic Geo Information System (gov)
- GEDBAS - Genealogical Database - collected personal data (gedbas)

Syntax:

Markdown: In general, an enhanced link looks like this [Link display title](#@param1&paramN) so that one or more targets can be addressed at once. For cross-references in webtrees a record type and the XREF is expected, the parameter looks as follows
- wt=n@XREF@ - standard link to note with XREF in the current tree
  available record types:
  - i=individual
  - f=family
  - s=source
  - r=repository
  - n=note
  - l=sharedPlace
- wt=i@XREF@othertree+dia - link to record type individual with XREF from tree "othertree" and also link to Interactive tree of this person
HTML: The same applies to html links: <a href="#@wt=i@I1@">Link display title</a> So this is also useable in cooperation with the name badge function of the “⚶ Vesta Classic Look & Feel” module in the HTML snippet field: <a href="#@fsft=<ref/>"></a> for linking to a record in the Family Search Family Tree.

The syntax of the external targets is listed by the markdown help function of this module. In most cases, only one key-value parameter pair needs to be specified, consisting of the short name of the desired target and the ID of the data record located there.

After a lot of theory: How does it looks like in webtrees?! In the upper part of the image we can see the edit mode of a note record, below how it ist rendered in view mode:

Additional external targets can be configured by providing a custom JavaScript object on the admin page of this module. Here two example entries from predefined targets to illustrate the principle:

{
  "fsft": {
      name: 'Family Search Tree - $ID',
      url: 'https://www.familysearch.org/tree/person/details/',
      cname: 'icon-fsft'
  },
  "osm": {
      name: 'OpenStreetMap',
      url: (id, title) => { 
          let parts = id.split('/');
          if (parts.length < 3) {
              title = title + ' - ' + I18N['syntax error'] + "!";
              return { url: '', title };
          }
          let map = parts.slice(0, 3).join('/');
          let urlsearch = '';
          if (parts.length > 3 && parts[3].trim()) {
              if (parts[3].trim() === '!') {
                  urlsearch = `?mlat=${parts[1]}&mlon=${parts[2]}`;
              } else {
                  urlsearch = parts.slice(3).join('/');
              }
          }
          return {url:`https://www.openstreetmap.org/${urlsearch}#map=${map}`, title};
      },
      cname: 'icon-osm',
      help: [
          { n: I18N['osm-help1'], e: '17/53.619095/10.037395' },
      ]
  }
}

Now some explanation for the used properties in the code snippet above (as a reminder, how the syntax of a base enhanced link looks like: #@param-key=param-value):

key = is the above mentioned short name or query parameter key (param-key)
name = title or label to be displayed as link title;
standard: the placeholder $ID will be replaced by the given id (param-value)
url = service url to be called
standard: the parameter value / given record id (param-value) will be appended to the end of the url It can also be a function provided, that accepts as parameter (id, title) and returns an object { url, title }. This returned title will be set instead of the name-property.
cname = CSS class name(s) whitespace separated
help = optional array of objects [{n:'', e:''},..] to illustrate the use of a non standard target (where the url-property is a function) by examples (in e), provided with explanatory text (in n). This information is listed in the markdown help.

I18N is an JavaScript object passed through from this module.

Any CSS rules required are best added via the “CSS and JS” module. Only the definition of the icon (size 30 x 30 pixels is sufficient) as a background image is actually needed - referencing as data: URL (see also: mdn web docs - data: URLs).
For example: .icon-whatever { background-image: url(...) }

Note: When Webtrees provides better support for UID, referencing via UID will probably also be implemented in this module, as this will make links more fail-safe. See also:

Forum post Feature Request: Improved support for UID / _UID
PR UID References in notes and text #5145

Markdown

Markdown is a simple system of formatting, used on websites such as Wikipedia or Github. It uses unobtrusive punctuation characters to create headings and sub-headings, bold and italic text, lists, tables, etc.

Webtrees uses a CommonMark implementation and supports a subset of the markup. It is optionally supported in note records on a per tree basis.

On the subject of markdown see also:

https://commonmark.thephpleague.com/
Github webtrees Issues
GEDCOM-Standard: NOTE.MIME and markdown #222 - support in GEDCOM 7.1

Markdown Image Support

This feature allows you to easily embed images from GEDCOM media records (first image) or from the public directory into notes. If restriction rules apply to the record, instead of the image, a message is displayed.

Syntax:

![alternate text for gedcom object](#@id=@M1@)
![alternate text for picture in public folder](#@public=webtrees.png "title")
![picture with defined height, width and additional css class](#@id=@M1@&h=200&w=200&cname=float-right)

Technically the images are packed into a div container together with an image subtitle - which is also a link to the media data set for GEDCOM objects. The display can be customized as required using the standard CSS classes or per image additional CSS classes (e.g. float-start or float-end from webtrees vendor.css).

Images of gedcom media records reside behind the media firewall. Therefore, this function cannot be provided with JavaScript, but by extending the MarkDownFactory class.

Markdown editor

You can also enable a visual markdown editor for note textareas. Under the hood the project “TinyMDE - A tiny, dependency-free embeddable HTML/JavaScript Markdown editor” is used - see also: https://github.com/jefago/tiny-markdown-editor

Besides syntax highlighting it ships with an icon bar for common format commands, a help popup and line numbering.

Note: Unfortunately, the on-screen keyboard does NOT work as before with the previous text input field. The selected characters end up as an intermediate step in the small text field below the Markdown editor and then must be copied manually to the desired position.

Markdown Extensions

The package League\CommonMarkdown used for processing Markdown texts offers several useful extensions that can be activated optionally:

Strikethrough - see also fisharebest/webtrees#5113
Description Lists
Footnotes

German webtrees manual

A context sensitive help link to the german webtrees manual can be added to the small navigation menu. Context links are also available for components on pages provided by custom extensions (e.g. on the individuals page, the start page or items in the main menu) – these can be identified by the i symbols in a circle.

If this feature is also required in the admin backend, patch P002 must be applied or at least the custom module vesta_common must be installed

If the webtrees page is displayed in a language other than german, it is possible to open the webtrees manual URL via a translation service (Google Translate). This can be enabled or disabled as a site setting or delegated to the visitor to decide. The settings dialogue can be accessed via the popover of the help link in the top menu. When this option is enabled, you will also find a link to a dialogue box that displays a full-text search in the german webtrees manual (using various search engines) and the table of contents.

The mapping of routes to help articles in the manual is stored in the database table route_help_map. This module comes with predefined mapping rules. If there is something missing or you find an issue, don't hesitate to share it. I'll include it in the next release.

Technical background information follows now.
The table has the following headers (the headers required in a CSV file for import are marked with !!):

id: automatic key - not relevant, the data field is only used to make it easier to identify the data record during editing.
path !!: route path - corresponds to the path of webtres pretty urls
handler !!: usually corresponds to the php class name of the code that handles the request
method !!: web request method (GET, POST, HEAD)
Only GET routes are generally relevant for assignment to manual sections.
extras !!: php class name of access level (Fisharebest\Webtrees\Http\Middleware\Auth*)
subcontext !!: CSS selector string or JSON object string to address a component/subcontext topic on the given page
category: string value for better grouping data rows; only value 'generic' has a special meaning
order !!: arbitrary numerical sort key, matching data rows are sorted in ascending order standard value is 10
url !!: path of the url to the webtrees manual (then it's concated with the given GenWiki base/domain url) also fully qualified url to other web ressources are possible and supported (for example to Github repo readmes or wikis of custom modules, that aren't documented in the manual yet)
updated_at: timestamp of last update this helps to identify possibly outdated data rows

As we can see in app/Http/Routes/WebRoutes.php, where standard webtrees routes are defined, for a route the following information is mandatory:

path
handler
method

Optionally extras can be provided. If none of those four mentioned fields is set, the data row ist filtered by the seeder. On import category and order are set automatically if not set.

In order to get a first class match with the current route those four fields have to match.

Normally, it is only necessary to assign GET routes to an article. We also have a few redirect routes and ajax helper routes (which provide data for form controls) that can be ignored.

A special case is the path which starts with /module/{module}/{action}. It is handled by the ModuleAction class, that has a proxy function for custom module admin pages. For mapping such a route to a specific custom module help article the handler is set to the routes attribut value for module (e.g. _vesta_classic_look_and_feel_). For a more generic rule, path can also be empty.

Fallback rules for access levels are matched by category='generic' and the specific Auth classname in extras.

In ascending order the first rule where subcontext = '' is selected for the top menu link. If nothing else applies, the link points to the startpage of the manual.

If activated, subcontext topics on a page can be provided with an additional help link. You can set a CSS selector string or a JSON object string with the following properties:

p: position of popover, optional (default is top, other possible values: left, right, bottom)
f: css selector/filter string (only necessary if you want the popover to be positioned differently) OR
e: javascript expression string

This is useful, if there are components on the page that require more detailed information than offered by the help link in the top menu (e.g. for custom module functions on the individuals page). This help link is displayed in a popover (because an additional link does not always work in bootstrap tabs, accordeon headers or menu titles). Set category='generic' for rules that should apply to more than one page.

On the admin page of this module it is possible to import routes registered in webtrees on demand. This make it easier to cover individual custom module configurations. Further more you can import and export data in csv format in order to make changes more convenient. You can define the separator and for import the character encoding (on export it is always utf-8). You can see at a glance how many data rows are stored in the table and how many of them have an url assigned.

In case of discrepancies the context help can be more easily adjusted by activating the option "Output of debug information on the JS console". This provides you with information on the active route and, if applicable, data table entries found for matching routing to help topics.

This module comes with a local copy of the german webtrees manual table of contents. An automatic update is not implemented so far. If you wish to update it without updating this module, you can use the utility script update-wthb-toc.sh.

Home link

The site title can be a link to the tree homepage or the user my page.

Dynamic CSS styles can be applied to match the current theme, ensuring that the display contrasts well. Of course it is not limited to the home link use case.

On the admin page of this module you can configure a JSON object to achieve this:

{ 
  "*": ".homelink { color: #039; }",
  "colors_nocturnal": ".homelink { color: antiquewhite; }"
}

Explanation: The object key name is set to the theme name to be matched, and the string value contains one or more css style rules. In this example we have a fallback rule with key * that matches all themes unless there is a specific key. Theme colors is a special case, where we also have palettes. In order to address this combination the key is set to theme name_palette name. The Key colors matches to all subthemes.

Just activate the option "Output of debug information on the JS console" in order to figure out the correct values.

Patches

The patches can be applied additionally — the module also works without them!

The util subfolder contains minor patches for the webtrees core. These are diff-files that can be easily applied or removed using shell from within the installed module folder (necessary for auto detecting webtrees sources):

Usage: util/wt-patch.sh [-R] [FILTER]
  -R                  undo Patch (patch -R)
  FILTER              '*' for all or specific (e.g. '01')

Don't forget to reapply the patches after updating webtrees.

These are minor bug fixes or functional enhancements — usually in a single file — that are intended to bridge the gap until they are officially fixed/implemented in the webtrees core.

#	Description	applies to version
P001	Backlink for level 1 shared notes #5181 /app/Fact.php	2.2.1 -
P002	Enable headContent/bodyContent for this module on admin backend in order to show the context help link #5214 resources/views/layouts/administration.phtml	2.2.1 -
~~P003~~	Record has multiple uid fields #4828 app/Services/GedcomEditService.php	2.2.1

webtrees

webtrees is an online collaborative genealogy application. This can be hosted on your own server by following the Install instructions.

Requirements

This module requires webtrees version 2.2. This module has the same requirements as webtrees#system-requirements.

This module was tested with webtrees version 2.2.4 and build-in themes and some other custom modules.

Installation

Install and use Custom Module Manager for an easy and convenient installation of webtrees custom modules.
Open the Custom Module Manager view in webtrees, select "linkenhancer", and click on the "Install Module" button.

Manual installation:

Download the latest release of the module.
Upload the downloaded file to your web server.
Unzip the package into your modules_v4 directory.
Rename the folder to linkenhancer

If everything was successful, you should see a subdirectory linkenhancer with the unpacked content in the modules_v4 directory.

During the initial installation, the following problem may occur: "PDO error - There is no active transaction" - for more details see known issues.

Contributing

If you'd like to contribute to this module, great! You can contribute by

Contributing code - check out the issues for things that need attention. If you have changes you want to make not listed in an issue, please create one, then you can link your pull request.
Testing - it's all manual currently, please create an issue for any bugs you find.

Translation

You can use a local editor, like Poedit or Notepad++ to make the translations and send them back to me. You can do this via a pull request (if you know how) or by e-mail.

Discussion on translating can be done by creating an issue.

Updated translations will be included in the next release of this module.

Beside English the following languages are available:

Catalan (by Bernat Josep Banyuls i Sala)
Dutch (by TheDutchJewel)
Español (by Bernat Josep Banyuls i Sala)
German

Support

Issues: for any ideas you have, or when finding a bug you can raise an issue.
Forum: general webtrees support can be found at the webtrees forum.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Name		Name	Last commit message	Last commit date
Latest commit History 252 Commits
.vscode		.vscode
CommonMark		CommonMark
Factories		Factories
Schema		Schema
Services		Services
resources		resources
util		util
.gitignore		.gitignore
LICENSE.md		LICENSE.md
LinkEnhancerModule.php		LinkEnhancerModule.php
LinkEnhancerModuleExt.php		LinkEnhancerModuleExt.php
LinkEnhancerUtils.php		LinkEnhancerUtils.php
MDTEST.md		MDTEST.md
README.md		README.md
autoload.php		autoload.php
gulpfile.mjs		gulpfile.mjs
latest-version.txt		latest-version.txt
module.php		module.php
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

webtrees module LinkEnhancer

TL;DR

Description

Enhanced links

Markdown

Markdown Image Support

Markdown editor

Markdown Extensions

German webtrees manual

Home link

Patches

webtrees

Requirements

Installation

Contributing

Translation

Support

License

About

Uh oh!

Releases 9

Packages

Contributors 2

Languages

License

bschwede/linkenhancer

Folders and files

Latest commit

History

Repository files navigation

webtrees module LinkEnhancer

TL;DR

Description

Enhanced links

Markdown

Markdown Image Support

Markdown editor

Markdown Extensions

German webtrees manual

Home link

Patches

webtrees

Requirements

Installation

Contributing

Translation

Support

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Contributors 2

Languages

Packages