|
| 1 | + |
| 2 | +# Leantime Plugin Development Guide |
| 3 | + |
| 4 | +## Introduction to the Hello World Plugin |
| 5 | + |
| 6 | +Leantime plugins provide a way to extend the core functionality of Leantime without modifying the core codebase. Plugins can add new features, modify existing functionality, and integrate with external services. This guide will walk you through creating your first plugin using a Hello World example. |
| 7 | +This guide demonstrates plugin development in Leantime using our Hello World plugin as a practical example. The Hello World plugin shows the basic concepts of: |
| 8 | +- Plugin structure and organization |
| 9 | +- Menu integration |
| 10 | +- Language/translation support |
| 11 | +- MVC pattern implementation |
| 12 | +- Event handling |
| 13 | + |
| 14 | +## Plugin Structure |
| 15 | + |
| 16 | +The Hello World plugin uses this directory structure: |
| 17 | +``` |
| 18 | +/app/Plugins/HelloWorld/ |
| 19 | +├── bootstrap.php # Plugin initialization |
| 20 | +├── composer.json # Plugin metadata |
| 21 | +├── register.php # Event/feature registration |
| 22 | +├── Controllers/ # Plugin controllers |
| 23 | +│ └── HelloWorld.php # Main controller |
| 24 | +├── Views/ # Blade templates |
| 25 | +│ └── show.blade.php # Main view |
| 26 | +├── Language/ # Translation files |
| 27 | +│ └── en-US.ini # English translations |
| 28 | +└── Docs/ # Documentation |
| 29 | + └── plugin-development.md |
| 30 | +``` |
| 31 | + |
| 32 | +## Key Components |
| 33 | + |
| 34 | +### 1. composer.json |
| 35 | +The composer file is a key component for plugin management. The core plugin manager will use this file to determine namespace and description. |
| 36 | +```json |
| 37 | +{ |
| 38 | + "name": "leantime/helloworld", |
| 39 | + "description": "A simple Hello World plugin for Leantime", |
| 40 | + "version": "1.0.0", |
| 41 | + "type": "leantime-plugin", |
| 42 | + "license": "MIT", |
| 43 | + "autoload": { |
| 44 | + "psr-4": { |
| 45 | + "Leantime\\Plugins\\HelloWorld\\": "/" |
| 46 | + } |
| 47 | + } |
| 48 | + } |
| 49 | +``` |
| 50 | + |
| 51 | +### 2. register.php |
| 52 | +The register file allows you to hook into events. Register.php files are read and included early in the stack. |
| 53 | +Our Registration helper class comes with various methods to hoook into often used events such as middleware, language files and menus. |
| 54 | + |
| 55 | +```php |
| 56 | +$registration = app()->makeWith(Registration::class, ['pluginId' => 'HelloWorld']); |
| 57 | + |
| 58 | +// Register languages |
| 59 | +$registration->registerLanguageFiles(['en-US']); |
| 60 | + |
| 61 | +// Add menu item |
| 62 | +$registration->addMenuItem([ |
| 63 | + 'title' => 'helloworld.menu.title', |
| 64 | + 'icon' => 'fa fa-smile', |
| 65 | + 'tooltip' => 'helloworld.menu.tooltip', |
| 66 | + 'href' => '/hello-world/show', |
| 67 | + ], 'personal', [10]); |
| 68 | +``` |
| 69 | + |
| 70 | +### 3. Language File (en-US.ini) |
| 71 | +```ini |
| 72 | +helloworld.menu.title = "Hello World" |
| 73 | +helloworld.menu.tooltip = "A simple Hello World example" |
| 74 | +helloworld.headline = "Hello World Plugin" |
| 75 | +helloworld.text = "Hello from your first Leantime plugin!" |
| 76 | +``` |
| 77 | + |
| 78 | +### 4. Controller (HelloWorld.php) |
| 79 | +Leantimne uses frontcontroller pattern and directs routes automatically based on url structure. |
| 80 | +As such make sure to call your controllers and controller methods in the way you'd like them to be accessible via url. |
| 81 | +In the example below the controller will be available via `domain/helloworld/HelloWorldController/show` |
| 82 | +```php |
| 83 | +namespace Leantime\Plugins\HelloWorld\Controllers; |
| 84 | + |
| 85 | +class HelloWorldController extends Controller |
| 86 | +{ |
| 87 | + public function show() |
| 88 | + { |
| 89 | + return $this->tpl->display('plugins.helloworld.show'); |
| 90 | + } |
| 91 | + } |
| 92 | +``` |
| 93 | + |
| 94 | +### 5. View (show.blade.php) |
| 95 | +```php |
| 96 | +@extends($layout) |
| 97 | + |
| 98 | +@section('content') |
| 99 | + <div class="pageheader"> |
| 100 | + <div class="pageicon"><i class="fa fa-smile"></i></div> |
| 101 | + <div class="pagetitle"> |
| 102 | + <h1>{{ __('helloworld.headline') }}</h1> |
| 103 | + </div> |
| 104 | + </div> |
| 105 | + |
| 106 | + <div class="maincontent"> |
| 107 | + <div class="maincontentinner"> |
| 108 | + <h3>{{ __('helloworld.text') }}</h3> |
| 109 | + </div> |
| 110 | + </div> |
| 111 | +@endsection |
| 112 | +``` |
| 113 | + |
| 114 | +## Integration Points |
| 115 | + |
| 116 | +### Menu Integration |
| 117 | +The plugin adds a menu item using `addMenuItem()`: |
| 118 | +- Title and tooltip from language file |
| 119 | +- Font Awesome icon |
| 120 | +- Route to controller action |
| 121 | +- Position in personal menu section |
| 122 | + |
| 123 | +### Language Support |
| 124 | +- Uses INI format for translations |
| 125 | +- Registered in register.php |
| 126 | +- Accessed via `__()` helper |
| 127 | +- Supports multiple languages |
| 128 | + |
| 129 | +### Controller |
| 130 | +- Extends base Controller class |
| 131 | +- Simple show() action |
| 132 | +- Returns Blade template view |
| 133 | + |
| 134 | +### View |
| 135 | +- Uses Blade templating |
| 136 | +- Extends main layout |
| 137 | +- Translatable strings |
| 138 | +- Consistent styling |
| 139 | + |
| 140 | +## Best Practices |
| 141 | + |
| 142 | +1. **Structure** |
| 143 | + - Follow PSR-4 autoloading |
| 144 | + - Use namespaces properly |
| 145 | + - Organize files logically |
| 146 | + |
| 147 | +2. **Code Style** |
| 148 | + - Follow PSR-12 coding standards |
| 149 | + - Use meaningful names |
| 150 | + - Document your code |
| 151 | + |
| 152 | +3. **Integration** |
| 153 | + - Use event system |
| 154 | + - Follow MVC pattern |
| 155 | + - Leverage existing components |
| 156 | + |
| 157 | +4. **Translations** |
| 158 | + - All strings in language files |
| 159 | + - Use clear translation keys |
| 160 | + - Support multiple languages |
| 161 | + |
| 162 | +## Testing |
| 163 | + |
| 164 | +1. **Manual Testing** |
| 165 | + - Menu item appears |
| 166 | + - Page loads correctly |
| 167 | + - Translations work |
| 168 | + - Styling is consistent |
| 169 | + |
| 170 | +2. **Automated Testing** |
| 171 | + - Unit test controllers |
| 172 | + - Test translations |
| 173 | + - Verify routing |
| 174 | + |
| 175 | +## Common Issues |
| 176 | + |
| 177 | +1. **Menu Not Showing** |
| 178 | + - Check registration code |
| 179 | + - Verify menu section |
| 180 | + - Check permissions |
| 181 | + |
| 182 | +2. **Translations Missing** |
| 183 | + - Verify language file registered |
| 184 | + - Check INI file syntax |
| 185 | + - Confirm translation keys |
| 186 | + |
| 187 | +3. **View Not Loading** |
| 188 | + - Check view path |
| 189 | + - Verify template syntax |
| 190 | + - Confirm controller return |
| 191 | + |
| 192 | +## Next Steps |
| 193 | + |
| 194 | +After mastering the Hello World plugin: |
| 195 | + |
| 196 | +1. **Add Features** |
| 197 | + - Database integration |
| 198 | + - User interactions |
| 199 | + - API endpoints |
| 200 | + |
| 201 | +2. **Enhance UI** |
| 202 | + - Custom styling |
| 203 | + - JavaScript functionality |
| 204 | + - AJAX interactions |
| 205 | + |
| 206 | +3. **Extend Integration** |
| 207 | + - Hook into more events |
| 208 | + - Add middleware |
| 209 | + - Create services |
| 210 | + |
| 211 | +## Resources |
| 212 | + |
| 213 | +1. **Documentation** |
| 214 | + - Leantime API docs |
| 215 | + - Plugin development guide |
| 216 | + - Blade template docs |
| 217 | + |
| 218 | +2. **Community** |
| 219 | + - GitHub discussions |
| 220 | + - Discord channel |
| 221 | + - Stack Overflow |
| 222 | + |
| 223 | +## Conclusion |
| 224 | + |
| 225 | +The Hello World plugin demonstrates: |
| 226 | +- Basic plugin structure |
| 227 | +- Essential integration points |
| 228 | +- Best practices |
| 229 | +- Common patterns |
| 230 | + |
| 231 | +Use this example as a foundation for building more complex plugins. |
0 commit comments