Proof of concept for plugins (still WIP)

[sgirard84]

I'd like to share some minor modifications I made to introduce the notion of plugins.

Notes:

• I wanted to make minimal changes to formwork core for this concept
• I still have a lot of things to learn from Formwork
• I'm not php expert (my daily job is about database servers, ETLs, BI)
• My plugin is still WIP, but enough done to share the idea

Context:
I'm trying to convert my friend's website I made with Flextype. His company is about guided kayaking tours. His website is basic, but it has the "complexity" of letting visitors to book and pay online for a tour. So I orignally made a small booking Flextype plugin that enable online booking, validation, online payment with Square and email confirmations.

My idea is to migrate his website to Formwork

Page structure in Formwork:

• I made a 'guided tour' scheme with all tours available for booking. Tours are also displayed on website with all info (desc, images, price, schedule, etc).

• I made a 'reservation-data' scheme to store all reservations. Info such as : first/last name, selected tour, date, info on group size, status, info about square payment (transaction id, status, payment receipt id, etc).

Note: As I mention in another post, I use the concept of 'pages' to store all content from website.. not only front end pages. I might rename 'pages' label to 'content' in the final published site and remove badge for page count as it make no sense for this website.

Sorry for French screenshot ;) First after home page is the list of available guided tours and second is list of reservations (not routable, not visible, not listed, etc, to avoid any personal information leak on webiste or via URL)

Plugin I made

• provide a calendar view in the admin panel to consult reservations more easily

• all functions to handle and validate online reservation, and store the online form POST into Formwork data
• manage payment

Plugin structure (into site folder)

Definitions of each file

Plugins.php

This class initialize the loading of plugins. It would make sense to have this object part of Formwork folder but again, goal here is to minimize the modifcations to make updates easier (by re-applying the core modificaiton after an update).

I modified formwork\src\cms\App.php to use this class, call init function, add also register a function plugins() that return the class

calendar/autoload.php

self explanatory.. load all php files

calendar/routes.php

contains panel routes

calendar/app/Controller.php

panel controller that extends Formwork\Panel\Controllers\AbstractController
used to process panel routes

calendar/app/Model.php

Store all logics. WIP. Will handle front-end reservation, payment, email, etc
example:

calendar/assets folder

any asset needed for the panel UI

The controller, when rendering the view, registers new variable "assets". Then I modified the panel layout.php to include assets in header (css) and at the end of body for js. Example for css

calendar/config/calendar.yaml

Config file of the plugin.

I also modified formwork\src\Panel\Controllers\AbstractController.php and its function loadDefaults() that build the panel nav, to include any plugin menu items. I merge this nav with built-in nav array later.

edit: the part that builds the additional nav items from plugins for the panel, will move to Plugins class, which make more sense. And the only small modification to this core function loadDefaults() will be the merge of built-in nav + plugin nav items.

Result:

calendar/translations folder

self explanatory, but here is example

calendar/views folder

IMPORTANT
This folder would contain the panel views. But right now in Formwork, views for panel are all defined into panel/views. I would require a lot more changes to the core to allow different paths for the views. So I created a 'calendar' folder here and copied all views

How to use plugin functions in the front end:

Example: in the front end controller, I can get the model and use any logic.

This is where I'll call the model to handle form-submission and store reservation, redirect to payment etc.

In summary, here are all the core files I needed to modify. Most of the changes are really small, and only add a reference to Plugins class and functions

• index.php (require Plugins class)
• panel\views (add subfolder of each plugin and their views)
• formwork\src\cms\App.php (reference Plugins, add function plugins() that return the class, and also call the plugins->init() function
• formwork\src\Panel\Controllers\AbstractController.php (alter loadDefaults to add panel sidebar items)
• panel\views\layouts\panel.php (dynamically add css/js files registered by the plugins)

Feel free to comment and add suggestions! Obviously, it's still WIP and some code has hardcoded stuff that will be replaced. Things like paths for '/panel/' or '/site', etc

Hopefully the concept of plugins can be implemented officially soon!

---

Side note, I also want to migrate my personal website which is a photography portfolio. In the same idea, I'll make a small plugin that adds panel menu item "Gallery" that will simply displays a gallery of thumbnails. Again, justs a view over Formwork pages that I'll use to store each photography information (image, title, desc, tags, purchase option links, etc). Managing pictures is easier with actual images than just a list of image titles (unlike a blog)

[giuscris]

Hi Sebastien, thank you for sharing the proof of concept.
You did an amazing job! It's inspirational for next development. ✨

I think we could have plugins with Formwork 2.1, since we're in a late development stage for the 2.0 release.
I would do some work just to prepare the arrival of plugins.

I like your implementation, I'd do just some little changes to fit more into the existing structure, naming and internal conventions.
But it's already a good concept.

Of course Plugins will be a class under src/Formwork, and from the panel there will be access for plugin views and assets too.

What we could do for now, in preparation, is to use a content folder with a structure like site/content/{type}/...
We'd have only "pages" for now.
Now it makes sense to me why it would be a good idea to avoid limiting content to pages, we could have a notion of "content" and pages would be just only one type of content.
I'm just not convinced by mixing in a single view pages and other content types.
If we overcome the limitation of only having pages, could make sense to have a different page for reservations in the panel in your example? I think it would be less misleading. And also from an user perspective, I'm talking about your friend and his company workers, when they have to consult reservation.

Another change to do now would be to make a better use of the Assets class, now it's just a convenience wrapper to version assets, etc. But it has no knowledge of which assets are really there.

Thank you, and please let me know of future developments of your implementation!

[sgirard84]

Thanks for your comment!

I also agree and wish for a distinction of page vs other content. Pages are really unique since they are closely tied to front-end navigation system and pages. This would also 'protect' other content from direct and easy access by the public website. There is no need for all basic fields like listed, routable, etc. for other content type I think.

I often mention Flextype and its term 'entries' but it has the same confusion.. you end up by having any kind of content mixed with pages. You need to be careful about how you setup and flag content type.

But I'm also not sure how to present content on the admin panel.. Maybe add a sidebar item 'content', which open a page that shows a list of content type. Then you click on a content type to finally display a similar page to "Pages" where you can see all items of the current content type (with search bar, etc). And on this page, the grid could be dynamic in terms of columns...

In the content scheme yaml file, there could be a parameter to define which field to display on the grid (because, unlike Pages that always have a field 'title', it's not something mandatory for content. In my concept for a reservation, the 'title' will be system generated by concatenating first name, last name and date, probably.. or I'll just generate a UUID (would be also the slug) as I do with Flextype. This field doesn't matter for reservations.

Or even more flexible, ability to add more fields to the grid that displays the list of entries for the current content type. Either having a flag 'grid:true|false' on each field definition. Or having an option 'grid:[field1, field2, field3]'

---

To go back to my plugin concept. By implementing plugins officially, a plugin could have a folder 'schemes/config' with the form definition. Then the panel would have the ability to edit plugin config just like regular config. In my concept, the yaml config is alone and 'static. But in reality, this yaml file would contains default config values. Then, once we start editing some values, a final plugin yaml file could be created under "/site/config/plugins/calendar.yaml" or "site/config/plugins/calendar/config.yaml".. someting like that. Again, just like regular config.

[giuscris]

I agree pages should not be used, because they are "special", and have stuff we don't need in other content types.
Another option that could make sense is to leave pages like they're now, but when adding plugins we could make it easier to define new content types and access them with the api. Like you added a calendar view, with its own view, you could also add, with the same plugin a "Reservations" view with its own menu item, and then display the content.
This to leave more flexibility, without complicating the code and making "default" decision on how to display it.
I'm not sure how to abstract a generic content type by now. I think it'd be a more viable option to leave it to the plugin side.
The reservations could be yaml or json files or whatever it makes sense for the plugin.
The only change I'd make is to move "site/pages" to "site/content/pages" and of course make some changes to the Site object to anticipate the possibility to have more content types.

---

As for the folder structure, I think it would make more sense having a "site/plugins/{pluginName}/" folder and then have all the related stuff under this folder. So it would be easy to install/remove them, having only a single folder.
Of course inside the folder, using the naming we already use, we would have "config", "routes.php", "assets", etc.
The only exception I'd make is the content. It should be decoupled from the plugin, so if your plugin handles reservation, they would be stored not under "site/plugins/{name}/content/reservations" but under "site/content/reservations".
The same with the config, if I understand what you're suggesting, so "/site/config/plugins/{name}.yaml" would have the actual config while leaving the defaults under "/site/plugins/{name}/config/plugin.yaml".

Some work has be done to have a more generic Config object. Actually I changed my mind and I want to decouple it from defaults like I've done recently. When we need to handle defaults we should have another config object with the defaults, and compare it with the actual config. The Config object itself should have no knowledge of defaults.

[sgirard84]

Happy to hear that aboug config.. I also think the current way to handle default / final config is a bit complicated and make the config controller more complex that it should.

The concept defaults is fine, but should be only used when a fresh install is done, of after a version update that's shipped with a new config item. The actual site config should contains all config items, not only what's different from the default.

Same for plugins, when someone install a plugin, the sytem will take a physical copy of the /site/plugins/pluginName/config/xxx.yaml file into site configuration folder.

---

The big strength about a CMS like Formwork, Flextype, Grav, etc is the ability to define a content field set (scheme) and let the system manage all CRUD actions.

If you are about to decouple content from pages, which make sense, I just hope that this big functionnality remains. Not convinced about having content into plugin folder.. unless the panel can read his content and also support CRUD actions.

For instance, in my current plugin, when I click on an item from the calendar, I simply redirect to:
"/panel/ pages/ [parent page slug for reservation container]/ [reservation page slug]/ edit/ " and let Formwork do the rest

Now, with concept of content type, I guess I'd redirect to:
"/panel /content /[reservation content type] /[content slug] /edit" and let Formwork do its magic for form rendering, basic validation, save, etc.

Also, if you look at my calendar UI screenshot, you'll see a 'create reservation' on top right corner. What I do with Flextype (and I'd lke to do the same with Formwork is:
redirect to MY plugin view (ie: /panel/calendar/create-reservation), but use core functions to render the form and save. I'd do the same with the notion of content type. Even if 95% of reservations come from the 100% custom front end form, my friend can always create a reservation manually without having to deal with "CMS knowledge".. but from my developer's perspective, I'm using CMS core functions as much as I can. I would not like to have my plugin to handle all the content management.

Obviously, I'm giving ideas and opinions, not want to break your vision 😀

[giuscris]

I think indeed we have similar visions 😁

Just I'm not sure to remove defaults, I just want to decouple them from the Config class and change the logic to the OptionsController.

---

For plugins and content, I didn't mean to have content inside plugins, but instead into "site/content", so it remains if you delete the plugin since they will be decoupled.

We can definitely standardize the "/edit", "/delete", "/create" actions and have them on the panel, thank you for sharing the abstraction.

We could do fields rendering and form handling, I'd only leave the save/create/remove logic to the controller, so you can customize the plugin based on your needs, i.e. decide to save content as json, or other formats.

[sgirard84]

Continuation of ideas 😊 Ok same idea I said before lol.. but maybe with more visual stuff

Maybe a new panel section like this (Content) (don't bother with 'Pages' missing from the nav.. I was just using Chrome dev options to play with pages 🤣)

Then

What I like on this idea.. is, if for some reason, I'd like to manage or store other content than pages, but noting special about it to make a plugin... just manage various content (ie: simply process front-end contact forms and create new content here... no plugin needed).

Also, on a specific page scheme, having the ability to refer to a content, using a new 'content field'. And vice-versa.. in my example, content 'reservations' will refer to page 'guided tours' because tour is also a page.

Also, by having this UI.. I would remove 'create new reservation' on my plugin calendar view.. because from a user's perspective, it's super clear to go under content type reservations, and click on Create new... user don't have to bother with options like template, page type, parent, etc. as the system already know the context.

---

Or as you said before.. simply create a new nav item for each content type.

If so... the content type schema would have an option like 'includeToPanelMenu: true|false'

[giuscris]

Wow, I like the idea ✨
Thank you for the detailed explanation.

Just I'm a little confused by the first screenshot. Why content types should have a duplicate and rename actions?
Unless you put the note there because you didn't have any room in the second screen.
To me it makes sense for the content entries, and pages of course, to have these actions.

Would you like to contribute with a PR? I think you have the ideas clear enough.
I could review your changes to fit more into the codebase.

I think it's a good candidate to be merged into Formwork 2.1 (won't take years as for 2.0 😅).

Now personally I'm focusing on refinements to finally release Formwork 2.0.

[sgirard84]

Sorry what means PR ? pull request ?

These screenshots are just mock up right now unfortunately 😎 But I can dig more into Formwork architecture to see if I could start working on it.

You can ignore actions for duplicating or renaming content type. Actually, thinking even more long term, it would make more sense to have either a dedicated module or plugin to edit schemes (I was already thinking about it as a plugin!) Of course.. only available for admin user.

I'm really happing you are working to improve your CMS, and open to changes like this. For me, this would become the ideal CMS I always wished ! 😃

[giuscris]

Yes, I mean Pull request.
I will help of course.

I think changes to the core should be kept to a minimum, since then with plugins you can extend functionality.
Not limiting content to pages is groundwork to leave flexibility.