PHPackages numencode/wn-fundamentals-plugin - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. numencode/wn-fundamentals-plugin ActiveWinter-plugin[Utility & Helpers](/categories/utility) numencode/wn-fundamentals-plugin ================================ NumenCode Fundamentals plugin for Winter CMS v1.1.0(1y ago)42512MITPHPPHP ^8.0.2CI passing Since Jan 13Pushed 1y ago1 watchersCompare [ Source](https://github.com/numencode/wn-fundamentals-plugin)[ Packagist](https://packagist.org/packages/numencode/wn-fundamentals-plugin)[ Docs](https://www.numencode.com)[ RSS](/packages/numencode-wn-fundamentals-plugin/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (2)Versions (4)Used By (2) Fundamentals Plugin =================== [](#fundamentals-plugin) The **Fundamentals Plugin** provides essential functionalities to streamline application development within the Winter CMS ecosystem. It includes backend overrides, helper functions, Twig extensions, and more, allowing developers to build robust applications efficiently. [![Version](https://camo.githubusercontent.com/31912b41bfc0148114a733bac624091ff827125c29862b47a950e248292b1fe6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6e756d656e636f64652f776e2d66756e64616d656e74616c732d706c7567696e3f7374796c653d666c61742d73717561726526636f6c6f723d303039394646)](https://github.com/numencode/wn-fundamentals-plugin/releases)[![Packagist PHP Version Support](https://camo.githubusercontent.com/7207afd4867842647efaec2b0209ae3ff74d6c4026344d0acd80c45d4b6f4bd4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e756d656e636f64652f776e2d66756e64616d656e74616c732d706c7567696e3f7374796c653d666c61742d73717561726526636f6c6f723d303039394646)](https://packagist.org/packages/numencode/wn-fundamentals-plugin)[![Checks](https://camo.githubusercontent.com/6faea4e9cd73961c32210c851cad59e6f453107a043fddcf870ee8fdd8457c7f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636865636b2d72756e732f6e756d656e636f64652f776e2d66756e64616d656e74616c732d706c7567696e2f6d61696e3f7374796c653d666c61742d737175617265)](https://github.com/numencode/wn-fundamentals-plugin/actions)[![Tests](https://camo.githubusercontent.com/a867d928cabbf92bd6d422c430ea8ddc34b7cf08358ab175bc87d06d372cde93/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6e756d656e636f64652f776e2d66756e64616d656e74616c732d706c7567696e2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/numencode/wn-fundamentals-plugin/actions)[![License](https://camo.githubusercontent.com/a0e57b0964bb70fccde34ebb4e481a082cb0b8133cac7123933a45638da6b0b1/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6e756d656e636f64652f776e2d66756e64616d656e74616c732d706c7567696e3f6c6162656c3d6f70656e253230736f75726365267374796c653d666c61742d73717561726526636f6c6f723d303039394646)](https://github.com/numencode/wn-fundamentals-plugin/blob/main/LICENSE.md) --- Target Audience --------------- [](#target-audience) This plugin is designed for developers working with Winter CMS who seek to accelerate development processes and enhance code maintainability by leveraging reusable components and utilities. Dependencies ------------ [](#dependencies) This plugin is a prerequisite for other `NumenCode` Winter CMS plugins. To use those plugins, this one must be installed first as it provides essential components and utilities required for their functionality. Installation ------------ [](#installation) This plugin is available for installation via [Composer](http://getcomposer.org/). ``` composer require numencode/wn-fundamentals-plugin ``` After installing the plugin you will need to run the migrations. ``` php artisan winter:up ``` Requirements ------------ [](#requirements) - [Winter CMS](https://wintercms.com/) 1.2.7 or higher. - PHP version 8.0 or higher. --- Features Overview ----------------- [](#features-overview) Common Translations ------------------- [](#common-translations) The Fundamentals plugin provides a comprehensive set of common language translations designed for reuse across applications. These translations promote consistency, streamline development, and eliminate the need for repetitive localization efforts. Additionally, the common translations are fully compatible with and intended for use alongside other NumenCode plugins. Since the Fundamentals plugin is a prerequisite for all NumenCode plugins, these translations serve as a standardized foundation, ensuring seamless integration and uniformity across projects utilizing the NumenCode ecosystem. --- Backend Overrides ----------------- [](#backend-overrides) The `BackendOverride` class customizes and extends the behavior of the Winter CMS backend panel. It provides a centralized way to enhance the backend's functionality, styling, and user experience. This class is useful for injecting custom styles, scripts, or modifying the backend behavior without altering the core framework. ### Key Features [](#key-features) - **Custom Styles and Scripts:** - Automatically adds custom SCSS and JavaScript files to backend pages. - Combines and serves these assets for improved performance. - **Enhanced Settings Page:** - Modifies the behavior of the Settings page (System\\Controllers\\Settings) and displays a customized layout. - **Custom List Column Rendering:** - Overrides the value rendering for list columns of type switch to provide a visually enhanced representation (icons and colors). --- Config Overrides ---------------- [](#config-overrides) The `ConfigOverride` class enables developers to customize and extend configuration files dynamically across a Winter CMS application. Its primary purpose is to facilitate granular or global overrides of configuration files, reducing duplication and enhancing flexibility. ### Key Features [](#key-features-1) - **Field Customization**: Modify or extend `fields.yaml` files for any class using the `extendFields()` method. - **Column Customization**: Adjust or add columns to `columns.yaml`, `columns_import.yaml`, or `columns_export.yaml` via dedicated methods like `extendColumns()`, `extendImportColumns()`, and `extendExportColumns()`. - **Import/Export Enhancements**: Extend configurations for `config_import_export.yaml` using `extendImportExport()`. - **Global Overrides**: Apply global overrides to all configuration files using the `extendAll()` method, ensuring system-wide customizations. - **Scoped Overrides**: Limit overrides to specific classes and configuration files using methods like `extend()` for precise control. - **Pages Plugin Integration**: Automatically aligns form tabs and secondary tabs for the Winter Pages plugin to improve backend usability. ### Usage Example [](#usage-example) ``` use NumenCode\Fundamentals\Bootstrap\ConfigOverride; // Extend fields.yaml for a specific model ConfigOverride::extendFields(ExampleModel::class, function ($fields) { $fields['new_field'] = [ 'label' => 'New Field', 'type' => 'text', 'default' => 'Default Value', ]; return $fields; }); // Extend columns.yaml for a list view ConfigOverride::extendColumns(ExampleModel::class, function ($columns) { $columns['new_column'] = [ 'label' => 'New Column', 'type' => 'text', ]; return $columns; }); // Global Overrides: Apply global configuration changes across the system. ConfigOverride::extendAll(function ($filePath, $config) { if ($filePath === 'backend/models/user/fields.yaml') { $config['tabs']['fields']['new_field'] = [ 'label' => 'Global New Field', 'type' => 'text', ]; } return $config; }); // Integration with Winter Pages Plugin: Automatically align form tabs for Pages Event::listen('backend.form.extendFieldsBefore', function ($form) { if (get_class($form->model) === Winter\Pages\Classes\Page::class) { // Adjust fields in the secondary tab foreach ((array) $form->secondaryTabs['fields'] as $key => $value) { $value['cssClass'] = trim(str_replace('secondary-tab', '', $value['cssClass'])); unset($form->secondaryTabs['fields'][$key]); $form->tabs['fields'][$key] = $value; } } }, 1000); ``` --- Form Widgets Overrides ---------------------- [](#form-widgets-overrides) ### Repeater Field Type [](#repeater-field-type) The `Repeater` field type allows you to display and manage a form with multiple collapsible sections, each representing an individual record. This is useful for managing lists of related data, where each item can be edited using the same form structure. #### Usage Example [](#usage-example-1) Define a `Repeater` field in your form configuration YAML: ``` fields: posts: label: Posts type: repeater span: auto form: fields: id: label: ID type: number cssClass: hidden title: label: Title type: text span: full content: label: Content type: textarea span: full ``` #### Example [](#example) - In the form, each item appears as a collapsible section. - Clicking "Add new item" adds a new collapsible section with an empty form. - Saving the form saves each item in the repeater as a separate record in the database table. This setup provides a flexible and user-friendly interface for managing lists of related data. --- Behaviors --------- [](#behaviors) ### RelationableModel Behavior [](#relationablemodel-behavior) The `RelationableModel` behavior allows a `Repeater` to be used as a relations editor via relation behavior. #### Example [](#example-1) For a `Category` model with multiple `Item` relations: ``` class Category extends Model { public $implement = [ '@NumenCode.Fundamentals.Behaviors.RelationableModel', ]; public $hasMany = [ 'items' => [Item::class, 'key' => 'category_id'], ]; public $relationable = [ 'items_list' => 'items', ]; } ``` In `\models\category\fields.yaml`: ``` fields: items_list: prompt: Add new item span: full type: repeater cssClass: 'repeater-collapsible repeater-open' form: $/models/item/fields.yaml ``` --- Helper Functions ---------------- [](#helper-functions) The plugin provides a collection of helper functions to simplify complex operations. These can be used across the application to improve code readability and functionality. **Function****Description**`numencode_partial`Returns the path to the NumenCode partial file.`validate_request`Validates the current request and flashes errors to the session. Returns `true` if the request is valid, `false` otherwise.`select_options`Creates options for the `` element.`array_insert`Inserts a new element into a specific position within an array.`array_before`Moves a specific array element before another array element.`array_merge_reference`Merges elements from passed arrays into one array, retaining references to the original arrays.`array_search_recursive`Recursively searches an array for a value and returns the corresponding keys if successful.`round_global`Rounds a number to a predefined number of decimals set in a global configuration.`plugin_exists`Checks if a plugin exists and is enabled.`extend_class`Extends a class with a behavior.`dumpbug`Dumps a simple debug backtrace.`diebug`Dumps a simple debug backtrace and terminates the script.`dd_query`Dumps the next database query.`d`Dumps the passed variables without terminating the script.`ddd`Resolves rendering issues with `dd()` in the browser's network tab.`ddt`Dumps a debug backtrace and terminates the script, useful for console debugging.--- CMS Permissions --------------- [](#cms-permissions) The `CmsPermissions` class enables fine-grained control over user group actions, such as creating, updating, and deleting data. ### Configuration Example [](#configuration-example) **Step 1**: Configure permissions in the plugin's `boot()` method: ``` use NumenCode\Fundamentals\Classes\CmsPermissions; class Plugin extends PluginBase { public function boot() { CmsPermissions::revokeDelete('owners', AcmeController::class); CmsPermissions::revokeUpdate(['owners', 'publishers'], CustomController::class); } } ``` **Step 2**: Apply permission logic in templates: ```