Search by 
mvqn / ucrm-plugin-template
A project template for developing UCRM Plugins.
1.1.1
2019-12-05 03:11 UTC
Requires
- php: ~7.3
- ext-json: *
- ext-pdo: *
- ext-ssh2: *
- ext-zip: *
- monolog/monolog: ^1.24
- mvqn/http: ^1.0
- mvqn/localization: 1.*
- mvqn/twig: 1.*
- slim/slim: ^3.1
- slim/twig-view: ^2.0
- ucrm-plugin-sdk/common: ~1
- ucrm-plugin-sdk/data: ~1
- ucrm-plugin-sdk/http: ~1
- ucrm-plugin-sdk/logging: ~1
- ucrm-plugin-sdk/rest: ~1
- vlucas/phpdotenv: 2.5.*
Requires (Dev)
- composer/composer: ^1.9
- consolidation/robo: ^1.4
- mvqn/robo-tasks: ^1.0
- phpunit/phpunit: ~8
This package is auto-updated.
Last update: 2024-04-19 09:40:23 UTC
README
A template to use for development of UCRM Plugins.
Installation
IMPORTANT: The recommended way to use the template is to fork the repo, so that you can later merge any upstream changes to the template.
If this method is chosen, then you will obviously need to clone your forked repo to your development machine and then run:
composer update
OR
If you simply want a one-off project ready for development and are not concerned with upstream changes, then run the following:
composer create-project ucrm-plugins/plugin-template-vue <project_name>
NOTES:
- Either of the above two methods will provide a fully functional plugin template, ready for immediate use.
- Included in the template is a pre-bundled example
`plugin-template-vue.zip`of what you get out-of-the-box.
Folder Structure
The template folder structure is as follows:
project # Project Root
├── src # Plugin Root
│ ├── .cache * # Plugin Cache
│ ├── client * # Client Application
│ │ ├── node_modules # Client Libraries
│ │ │ └── ... #
│ │ ├── public # Client Static Assets
│ │ │ ├── css # - All files and folders in this public/ folder are copied without modification
│ │ │ │ └── ... # by Webpack everytime the Client application is built.
│ │ │ ├── js # - These files are output to the Plugin's public/ folder and will be served
│ │ │ │ └── ... # without authentication of any kind.
│ │ │ └── favicon.ico #
│ │ ├── src # Client Source (bundled by Webpack)
│ │ │ ├── assets # Client Assets
│ │ │ │ └── ... # - Any assets used by components and views that should be bundled.
│ │ │ ├── components # Client Components
│ │ │ │ └── ... # - This is a mix of the built-in components and your own.
│ │ │ ├── plugins # Client Plugins
│ │ │ │ └── ... # - Include any plugins here.
│ │ │ ├── router # Client Routes
│ │ │ │ └── ... # - Include your own routes here, as they will be included by "../router.js".
│ │ │ ├── services # Client Services
│ │ │ │ └── ... # - Include common services here.
│ │ │ ├── store # Client Vuex Store
│ │ │ │ └── ... # - Include any Vuex stores here.
│ │ │ ├── views # Client Views
│ │ │ │ └── ... # - This is a mix of the built-in views and your own.
│ │ │ ├── App.vue # Client Root Vue Component
│ │ │ ├── main.js # Client Entrypoint
│ │ │ └── router.js # Client Routes
│ │ ├── index.html # Client "index.html" Template (auto-injected by Webpack on build)
│ │ └── ... # Client Config Files (i.e. package.json, babel.config.js, etc.)
│ ├── data # Plugin Data (include any default data files here)
│ │ ├── config.json *** # Plugin Configuration
│ │ ├── permissions.json # Plugin Permissions
│ │ └── ... # - This is likely to move into the database shortly.
│ ├── public ** # Client Application
│ │ └── ... # NOTES:
│ │ # - This is the plugin's bundled client-side application.
│ │ # - The permission system is used here.
│ │ # - No files should be manually placed here, as this entire folder is deleted
│ │ # and then re-generated by Webpack on every build.
│ │ #
│ ├── server # Server Root
│ │ ├── App # Server Source (powered by the Slim Framework & Twig Template Engine)
│ │ │ ├── Controllers # Server Controllers
│ │ │ │ └── ... # NOTES:
│ │ │ │ # - This folder contains some of the base API Controllers, which should not be
│ │ │ │ # altered.
│ │ │ │ # - Your own Controllers should be added here, as well.
│ │ │ │ # - An ExampleController has been included for reference.
│ │ │ │ #
│ │ │ ├── Handlers # Server Handlers
│ │ │ │ └── ... # NOTES:
│ │ │ │ # - This folder contains the Webhook Event Handlers and while it does contain
│ │ │ │ # the Webhooks/WebhookHandler as an example and also to respond to any UCRM
│ │ │ │ # Webhook tests, you can include or remove any combination of Handlers you
│ │ │ │ # like, even none!
│ │ │ │ # - If a Handler does not exists when a Webhook event is captured by public.php,
│ │ │ │ # it repsonds as unsupported and shoudl cause no issues.
│ │ │ │ # - Any Handler's file and class name needs to match the UCRM Webhook entity of
│ │ │ │ # which it is handling, with the first letter capitalized and suffixed with
│ │ │ │ # Handler (i.e. ClientHandler, ServiceHandler, etc...).
│ │ │ │ # - The class then also needs to have a method named exactly as the UCRM Webhook
│ │ │ │ # eventName (i.e. add(), edit(), delete(), test(), etc...).
│ │ │ │ # - The method will be passed standard Slim Framework route arguments.
│ │ │ │ # - See Webhooks/WebHookHandler for an example.
│ │ │ │ #
│ │ │ ├── Middleware # Server Middleware
│ │ │ │ └── ... # NOTES:
│ │ │ │ # - This folder contains any Middleware the Server might want to use.
│ │ │ │ # - By default, it only contains the WebhookMiddleware that specifically handles
│ │ │ │ # any requests to public.php that might be a Webhook.
│ │ │ │ # - Feel free to add your own and them include them in any of your bootstrap
│ │ │ │ # files, as per the Slim Framework middleware practices.
│ │ │ │ #
│ │ │ ├── Models # Server Models
│ │ │ │ └── ... # - No Models are included by default.
│ │ │ │ # - Feel free to add your own and use them as necessary in your application.
│ │ │ │ #
│ │ │ ├── Views # Server Views
│ │ │ │ └── ... # NOTES:
│ │ │ │ # - By default, the only view I include is the 404 Page Handler.
│ │ │ │ # - Feel free to add your own and use them as necessary in your application,
│ │ │ │ # keeping in mind that permissions do apply here.
│ │ │ │ #
│ │ │ ├── ... # Server Miscellaneous
│ │ │ │ # NOTES:
│ │ │ │ # - You can include any other files/folders here that you need...
│ │ │ │ #
│ │ │ └── Settings.php * # Plugin Settings
│ │ │ # NOTES:
│ │ │ # - This Settings file is auto-generated as needed to group all common Plugin
│ │ │ # settings in one place.
│ │ │ # - It gathers its data from numerous places, including:
│ │ │ # 1. ucrm.json
│ │ │ # 2. manifest.json
│ │ │ # 3. data/config.json
│ │ │ # 4. UCRM Database
│ │ │ #
│ │ ├── bootstrap # Server Version-Specific Bootstrappers
│ │ │ ├── <VERSION>[.inc].php # NOTES:
│ │ │ └── ... # - Any existing <VERSION>.php files should remain untouched, if you are
│ │ │ # planning on merging any upstream changes in the future.
│ │ │ # - Individual <VERSION>.inc.php files would be the place to include any of your
│ │ │ # own version-specific bootstrap code. See below for order of inclusion.
│ │ │ # - The file naming format should follow the same UBNT versioning, like:
│ │ │ # * 3.0.0-beta.10.inc.php (for UCRM version 3.0.0-beta.10)
│ │ │ # * 2.16.5.inc.php (for UCRM version 2.16.5)
│ │ │ #
│ │ ├── translations # Server Translations
│ │ │ └── ... # NOTES:
│ │ │ # - This will be used by the upcoming Translations API
│ │ │ #
│ │ ├── vendor # Server Vendor Libraries
│ │ │ └── ... # NOTES:
│ │ │ # - This folder is handled entirely by Composer.
│ │ │ #
│ │ └── bootstrap[.inc].php # Server Common Bootstrappers
│ │ # NOTES:
│ │ # - bootstrap.php should remain untouched, if you are planning on merging any
│ │ # upstream changes in the future.
│ │ # - bootstrap.inc.php would be the place to include any of your own common
│ │ # bootstrap code.
│ │ # - Bootstrap files will be included in the following order, if they exist:
│ │ # 1. boostrap.php
│ │ # 2. bootstrap.inc.php
│ │ # 3. bootstrap/<VERSION>.php
│ │ # 4. bootstrap/<VERSION>.inc.php
│ │ #
│ ├── .env * # An optional development-only set of environment variables.
│ ├── .zipignore * # An ignore list to be used when bundling.
│ ├── index.html ** # Client bundled entrypoint (regenerated by Webpack on build)
│ ├── main.php # Required Plugin file.
│ ├── mainfest.json # Required Plugin file.
│ ├── public.php # The Front-Controller that handles almost EVERYTHING!
│ ├── router.php * # A development-only router, used by the PHP Web Server.
│ └── ucrm.json *** # The UCRM Plugin Information
├── .editorconfig #
├── .gitignore #
├── composer.json #
├── composer.lock #
├── <PLUGIN>.zip #
└── README.md #