* Resources for writing plugins/DEAs

[sbell95]

I would like to try my hand at writing some plugins/DEAs to support specific workflows I have for entering sources and facts from census, etc. I’ve tried a few of the various plugins and find them close but not exactly what I need, so I’d like to try writing my own. I have a little programming knowledge from uni study but no experience with Lua. I’ve read the program help files and some KB articles, but can anyone recommend any other resources/readings/examples/videos for me to learn more about this? Thanks!

[ColeValleyGirl]

The KB article Lua References and Library Modules points to some resources (free and otherwise).

It's also worth reviewing the existing DEAS to understand their structure and some of the library functions available.

[tatewise]

Sarah, I don't want to put you off writing plugins, but have you investigated Ancestral Sources for capturing facts & sources associated with Census returns, and many other popular BMD source documents?

[sbell95]

The KB article Lua References and Library Modules points to some resources (free and otherwise).

It's also worth reviewing the existing DEAS to understand their structure and some of the library functions available.

Thanks for these suggestions -- I'll do some more reading and reviewing!

Sarah, I don't want to put you off writing plugins, but have you investigated Ancestral Sources for capturing facts & sources associated with Census returns, and many other popular BMD source documents?

Thanks -- I've tried Ancestral Sources and used it extensively in my previous project version, but it had some peculiar behaviour in regards to updating the file that I wasn't a fan of... I also prefer to keep everything in Family Historian itself, and DEAs in v7 seem to be aimed at doing just that. The census DEA I have been using so far fits my purposes quite well, except that I would like it to do a few more things and modify existing facts in a different way.

I'm sure there are other people wondering the same as me, so I would love to keep this thread focused on good resources for Lua and general plugin writing tips and tricks!

[ColeValleyGirl]

A good first step might be to customise the census dea. Do you have a list of what you want to change and I can point you to where you should look.

[tatewise]

I've tried Ancestral Sources and used it extensively in my previous project version, but it had some peculiar behaviour in regards to updating the file that I wasn't a fan of... I also prefer to keep everything in Family Historian itself.

What was the 'peculiar behaviour'? Have you reported that in the Ancestral Sources forum? I'm sure the author would appreciate your feedback.

Maybe you misunderstand how Ancestral Sources operates, or I have misunderstood your point, but everything entered via Ancestral Sources is saved in FH. Ancestral Sources keeps none of the data itself. All it keeps are formatting templates for titles, transcripts, etc, but even that is reduced if using Templated Sources.

[ColeValleyGirl]

Mike, a simple example of what Sarah might not like: the fact the FH and AS need to keep reloading the Gedcom file every time the other program changes it. It drives me mad, and isn't anything Nick Walker can fix; it's a natural consequence of AS running alongside FH -- whereas (as already pointed out), DEAs keep all activity in FH itself and you can't get potentially conflicting edits.

I know you're a great fan of AS, and when it was the only alternative, I used it too, even though the setup was so complex because of all the options/flexibility introduced over time but (as you would expect) I much prefer the DEA approach.

Another advantage of the DEA approach is that they're open source, so Sarah can amend my Census DEA as much as she pleases to get the behaviour she wants -- AS is proprietary, and only Nick can make changes.

[sbell95]

A good first step might be to customise the census dea. Do you have a list of what you want to change and I can point you to where you should look.

That is very generous, Helen, thank you! Your census DEA has been very helpful for me so far. Something I'd like to change is the ability to simply add the census as a source for an existing birth fact as opposed to having to choose between updating the existing fact or adding a new one -- this is because often I prefer to keep something like the quarter and year as the birth date as opposed to a calculated or about date.

Screenshot 2021-10-06 200359.jpg (42.55 KiB) Viewed 2614 times

This is minor, but I've also noticed that the autotext produced has a few broken carriage lines... I tried editing the DEA myself, but I think I needed to make a copy of it first as my changes didn't seem to have any effect.

Screenshot 2021-10-06 200212.jpg (14.19 KiB) Viewed 2614 times

Those are probably the main changes I would want to make -- but the whole point is to learn the skills to write my own plugins and DEAs in the future! Since they are open source, as you say, and Calico Pie thought to include the ability for users to write their own plugins, I'd like to try it out and experiment.

I've tried Ancestral Sources and used it extensively in my previous project version, but it had some peculiar behaviour in regards to updating the file that I wasn't a fan of... I also prefer to keep everything in Family Historian itself.

What was the 'peculiar behaviour'? Have you reported that in the Ancestral Sources forum? I'm sure the author would appreciate your feedback.

Mike, a simple example of what Sarah might not like: the fact the FH and AS need to keep reloading the Gedcom file every time the other program changes it. It drives me mad, and isn't anything Nick Walker can fix; it's a natural consequence of AS running alongside FH -- whereas (as already pointed out), DEAs keep all activity in FH itself and you can't get potentially conflicting edits.

I know you're a great fan of AS, and when it was the only alternative, I used it too, even though the setup was so complex because of all the options/flexibility introduced over time but (as you would expect) I much prefer the DEA approach.

Another advantage of the DEA approach is that they're open source, so Sarah can amend my Census DEA as much as she pleases to get the behaviour she wants -- AS is proprietary, and only Nick can make changes.

Helen has wonderfully articulated the issues I experienced with Ancestral Sources. I understand that the reloading is inherent in the fact that the two programs run in parallel, but I noticed it sometimes caused some data losses/conflicts when changes were saved across. I think the utility is wonderful, and Nick clearly has a large following of users of his program, but at this stage I'm more interested in pursuing DEAs.

[ColeValleyGirl]

The easy fix first (for autotext):

Tools > Manage Autotext > Autotext for plugins

Either:

1. Delete the errant autotext entries under Record Census Data (UK) -- it will be recreated the next time you use that autotext with your changes included (if it already exists, the plugin won't update it).

Or:

2. Edit the autotext directly. (It is because you can do this that the plugin won't overwrite existing autotext).

Give me a while to refresh my memory about the other point.

However, as you say, the whole idea is to learn the skills, so I'll just give you a few signposts on that one if that's OK?

[sbell95]

The easy fix first (for autotext):

Tools > Manage Autotext > Autotext for plugins

Either:

1. Delete the errant autotext entries under Record Census Data (UK) -- it will be recreated the next time you use that autotext with your changes included (if it already exists, the plugin won't update it).

Or:

2. Edit the autotext directly. (It is because you can do this that the plugin won't overwrite existing autotext).

That was an easy enough fix, thanks!

Give me a while to refresh my memory about the other point.

However, as you say, the whole idea is to learn the skills, so I'll just give you a few signposts on that one if that's OK?

I think I may have discovered a workaround -- simply to add the pre-existing date in the birth fact into the 'New Birth Date' field (so that it matches 'Current Birth Date'), then the 'Update existing fact with new values' action simply adds the source citation to that birth fact! I'm not sure if adding a new action is required, but to me it makes sense to have an option to simply add the source to the birth fact without otherwise changing it.

In the same vein, something else I thought I might like the DEA to do is to add the census as a source to the '<whole record>' and 'Name' fields.

[ColeValleyGirl]

Yes, that's the workaround.

The code that determines what options you get offered when adding/updating a fact is actually in a library supplied by Calico Pie (fhUtils) but it makes sense to me to have the option just to cite -- let me think about how we could do it.

If an individual is created by the DEA the 'whole record' and the name both get a citation. That happens in the createIndi function at line 572. You could steal the relevant lines from there and put them in after line 363 to always have the census cited for an individuals whole record and name... let me know of you need further hints.