1# THIRD-PARTY MODULES 2 3Many webtrees functions are provided by “modules”. 4Modules allows you to add additional features to webtrees. 5 6## Installing and uninstalling modules 7 8A module is a folder containing a file called `module.php`. 9There may be other files in the folder. 10 11To install a module, copy its folder to here. 12 13To uninstall it, delete its folder from here. 14 15Note that module names (i.e. their folder names) must not contain 16spaces or the characters `.`, `[` and `]`. 17 18TIP: renaming a module from `<module>` to `<module.disable>` 19is a quick way to hide it from webtrees. This works because 20modules containing `.` are ignored. 21 22## Writing modules 23 24To write a module, you need to understand the PHP programming langauge. 25 26The rest of this document is aimed at PHP developers. 27 28TIP: The built-in modules can be found in `app/Module/*.php`. 29These contain lots of useful examples that you can copy/paste. 30 31## Creating a custom module. 32 33This is the minimum code needed to create a custom module. 34 35```php 36<?php 37 38use Fisharebest\Webtrees\Module\AbstractModule; 39use Fisharebest\Webtrees\Module\ModuleCustomInterface; 40use Fisharebest\Webtrees\Module\ModuleCustomTrait; 41 42return new class extends AbstractModule implements ModuleCustomInterface { 43 use ModuleCustomTrait; 44 45 /** 46 * How should this module be labelled on tabs, menus, etc.? 47 * 48 * @return string 49 */ 50 public function title(): string 51 { 52 return 'My Custom module'; 53 } 54 55 /** 56 * A sentence describing what this module does. 57 * 58 * @return string 59 */ 60 public function description(): string 61 { 62 return 'This module doesn‘t do anything'; 63 } 64}; 65``` 66 67If you plan to share your modules with other webtrees users, you should 68provide them with support/contact/version information. This way they will 69know where to go for updates, support, etc. 70Look at the functions and comments in `app/ModuleCustomTrait.php`. 71 72## Available interfaces 73 74Custom modules *must* implement `ModuleCustomInterface` interface. 75They *may* implement one or more of the following 76 77* `ModuleAnalyticsInterface` - adds a tracking/analytics provider. 78* `ModuleBlockInterface` - adds a block to the home pages. 79* `ModuleChartInterface` - adds a chart to the chart menu. 80* `ModuleListInterface` - adds a list to the list menu. 81* `ModuleConfigInterface` - adds a configuration page to the control panel. 82* `ModuleMenuInterface` - adds an entry to the main menu. 83* `ModuleReportInterface` - adds a report to the report menu. 84* `ModuleSidebarInterface` - adds a sidebar to the individual pages. 85* `ModuleTabInterface` - adds a tab to the individual pages. 86* `ModuleThemeInterface` - adds a theme (this interface is still being developed). 87 88For each interface that you implement, you must also use the corresponding trait. 89If you don't do this, your module may break whenever the interface is updated. 90 91Where possible, the interfaces won't change - however new methods may be added 92and existing methods may be deprecated. 93 94## How to extend/modify an existing modules 95 96To create a module that is just a modified version of an existing module, 97you can extend the existing module (instead of extending `AbstractModule`). 98 99```php 100<?php 101use Fisharebest\Webtrees\Module\ModuleCustomInterface; 102use Fisharebest\Webtrees\Module\ModuleCustomTrait; 103use Fisharebest\Webtrees\Module\PedigreeChartModule; 104 105return new class extends PedigreeChartModule implements ModuleCustomInterface { 106 use ModuleCustomTrait; 107 108 /** 109 * @return string 110 */ 111 public function description(): string 112 { 113 return 'A modified version of the pedigree chart'; 114 } 115 116 // Change the default layout... 117 public const DEFAULT_ORIENTATION = self::OLDEST_AT_TOP; 118}; 119``` 120