Jump to content
dadish

GraphQL for ProcessWire

Recommended Posts

NOTE: This thread originally started in the Pub section of the forum. Since we moved it into the Plugin/Modules section I edited this post to meet the guidelines but also left the original content so that the replies can make sense.  

ProcessGraphQL

ProcessGraphQL seamlessly integrates to your ProcessWire web app and allows you to serve the GraphQL api of your existing content. You don't need to apply changes to your content or it's structure. Just choose what you want to serve via GraphQL and your API is ready.

Warning: The module supports PHP version >= 5.5 and ProcessWire version >= 3.

Links:

Please refer to the Readme to learn more about how to use the module.

 

Original post starts here...

Hi Everyone! I became very interested in this GraphQL thing lately and decided to learn a bit about it. And what is the better way of learning a new thing than making a ProcessWire module out of it! :)

For those who are wondering what GraphQL is, in short, it is an alternative to REST. I couldn't find the thread but I remember that Ryan was not very happy with the REST and did not see much value in it. He offered his own AJAX API instead, but it doesn't seem to be supported much by him, and was never published to official modules directory. While ProcessWire's API is already amazing and allows you to quickly serve your content in any format with less than ten lines of code, I think it might be convenient to install a module and have JSON access to all of your content instantly. Especially this could be useful for developers that use ProcessWire as a framework instead of CMS.

GraphQL is much more flexible than REST. In fact you can build queries in GraphQL with the same patterns you do with ProcessWire API.

Ok, Ok. Enough talk. Here is what the module does after just installing it into skyscrapers profile.

ProcessGraphQL-Query.gif

It supports filtering via ProcessWire selectors and complex fields like FieldtypeImage or FieldtypePage. See more demo here

The module is ready to be used, but there are lots of things could be added to it. Like supporting any type of fields via third party modules, authentication, permissions on field level, optimization and so on. I would love to continue to develop it further if I would only know that there is an interest in it. It would be great to hear some feedback from you. I did not open a thread in modules section of the forum because I wanted to be sure there is interest  in it first.

You can install and learn about it more from it's repository. It should work with PHP >=5.5 and ProcessWire 3.x.x. The support for 2.x.x version is not planned yet.

Please open an issue if you find bugs or you want some features added in issue tracker. Or you can share your experience with the module here in this thread.

  • Like 41
  • Thanks 3

Share this post


Link to post
Share on other sites
1 hour ago, Nurguly Ashyrov said:

I would love to continue to develop it further if I would only know that there is an interest in it.

I don't know much about GraphQL but I want to learn more, and your module looks like it will make it easy to get started with in PW. So definitely interested. :)

  • Like 4

Share this post


Link to post
Share on other sites

First of all, I think this looks great. I'm not entirely sure if I'll ever need something like this personally, but a module like this would no doubt be useful for some cases :)

To my best understanding the main point Ryan was making about REST was that since it's easy to add new views (or whatever you choose to call them) for a ProcessWire site, a separate module doesn't make as much sense as it does for a system that doesn't provide similar flexibility. I've got some, albeit very limited, experience with the REST API in WP, and in their case it definitely makes a lot of sense.

There's also the question of security: there may be cases where something is technically speaking public, but not accessible via your existing web site, and a "generic" REST API could result in some surprises there.. and, of course, if it's not read-only, that's a whole another thing to worry about.

All that being said, I'm looking forward to seeing where this module goes. An easy-to-use plug-n-play GraphQL API sounds like a great thing to have in one's toolbox :)

  • Like 4

Share this post


Link to post
Share on other sites
On 1/28/2017 at 6:10 PM, teppo said:

There's also the question of security: there may be cases where something is technically speaking public, but not accessible via your existing web site, and a "generic" REST API could result in some surprises there.. and, of course, if it's not read-only, that's a whole another thing to worry about.

By the way, in terms of security, this module follows the permission settings in ProcessWire. All it does is collects the templates that are viewable by the client via

$user->hasPermission('page-view', $template);

and for every request it makes sure to returns only those pages that have one of those templates. So, as long as user does not have permission to view the page, she won't be able to fetch it. I tried to make module reflect your existing settings as much as possible. It basically delegates everything possible to ProcessWire itself. 

 

On 1/28/2017 at 6:54 PM, LostKobrakai said:

I always though graphql would only be for qraph databases, but really this looks damn rad.

That is so true. I personally thought GraphQL was new SQL.

  • Like 5

Share this post


Link to post
Share on other sites
1 hour ago, Nurguly Ashyrov said:

All it does is collects the templates that are viewable by the client

There are also field access settings, just to be sure you're aware of them.

  • Like 1

Share this post


Link to post
Share on other sites
36 minutes ago, LostKobrakai said:

There are also field access settings, just to be sure you're aware of them.

Yes, I am aware of field permissions, thank you for reminding. I have not added support for them yet. Though it is definitely in my todo list for this module.

  • Like 3

Share this post


Link to post
Share on other sites

Looks super cool!

Does it add some public endpoint to fetch data or how does it work outside the "console" example shown on the videos?

  • Like 1

Share this post


Link to post
Share on other sites
1 hour ago, apeisa said:

Looks super cool!

Does it add some public endpoint to fetch data or how does it work outside the "console" example shown on the videos?

Of course. In one of your templates (edit: In one of your template files) you simply do

<?php
echo $modules->get('ProcessGraphQL')->executeGraphQL();

and that's it. It will handle all GraphQL requests. There is more info in the repository.

  • Like 2

Share this post


Link to post
Share on other sites

Thank you very much for this module, @Nurguly Ashyrov!

I missed this graphql thing completely, though was messing around json api a bit. Had some great time reading about it. Seems like ProcessWire fits graphql like a glove. Your module should answer a lot of recent questions about integrating PW with vue.js and alike.

Dries Buytaert, the Drupal "godfather", has a nice article in his blog about the necessity for a contemporary CMS to have support for web-services built in. And his choice seems to be graphql and json api. I am sure that improving and promoting PW as a "headless CMS" kind of thing is something that could bring a lot of frontend developers to use PW. This module is the perfect start.

As I understand, mutations are a way to not only read, but write data? If so, that is certainly worth implementing, so a complete SPA could be possible with this graphql module alone.

 

  • Like 8

Share this post


Link to post
Share on other sites
16 hours ago, Ivan Gretsky said:

Seems like ProcessWire fits graphql like a glove.

You couldn't be more precise! GraphQL and ProcessWire fit each other very well. All this module does is just maps the ProcessWire's fieldtypes with GraphQL type system. It literally tells GraphQL that FieldtypeText is a StringType, FieldtypeDate is DateType and so on. And for getting the data, on average, it is less than a single line of code :). Since you can access value of a page field like $pages->$fieldName all primitive fields inherit a method for accessing data from one place. I sure having lots of fun writing this module.

16 hours ago, Ivan Gretsky said:

Dries Buytaert, the Drupal "godfather", has a nice article in his blog about the necessity for a contemporary CMS to have support for web-services built in. And his choice seems to be graphql and json api. I am sure that improving and promoting PW as a "headless CMS" kind of thing is something that could bring a lot of frontend developers to use PW. This module is the perfect start.

I agree with Drupal "godfather" totally. The need for quick bootstrapping of an api service with flexible content structure is in very high demand. I had a hard time landing a job as a ProcessWire developer. So I target myself as a full-stack SPA developer in React.js/Node.js. I tried many of open source REST frameworks in Node.js that would help me get started with a project quickly. But non of them offered enough flexibility for my style of programming (I guess ProcessWire spoiled me :)). At the time I figured out the best way to build REST api in Node.js I found out that REST is not flexible either. When an app starts evolving REST gets very messy. The Github built three versions of their REST api and still are not happy with it and now decided to release a GraphQL api which probably will not introduce breaking changes in the future, because GraphQL is designed that way.

I think if made correctly, this module could bring a great value to many ProcessWire users.

16 hours ago, Ivan Gretsky said:

As I understand, mutations are a way to not only read, but write data? If so, that is certainly worth implementing, so a complete SPA could be possible with this graphql module alone.

 That's right. That is the main goal of this module. I will eventually implement all the features that needed to build a complete SPA with this module. I just try to move carefully and a usage feedback from community would help a lot. Just installing it and making couple queries to confirm that it works as expected would be great.

  • Like 9

Share this post


Link to post
Share on other sites
On 28/01/2017 at 4:11 PM, Nurguly Ashyrov said:

By the way, in terms of security, this module mimics the permission settings in ProcessWire. All it does is collects the templates that are viewable by the client via [...] and for every request it makes sure to returns only those pages that have one of those templates. So, as long as user does not have permission to view the page, she won't be able to fetch it. I tried to make module reflect your existing settings as much as possible. It basically delegates everything possible to ProcessWire itself.

This sounds good, and that's basically everything that a "generic", publicly accessible API can do. I've got no complaints here :)

What I've found out while playing with the WP REST API a while ago is that even though permissions are sensible, it may end up showing more than the public site. Part of it is about things like (not just page but) field level permissions, and part is about pages that exist and are publicly viewable for technical reason, but are not *intended* for public consumption, if you get what I mean.

Surely it would be best to always use native permission rules to limit the visibility, but sometimes a site may have content that is viewable only if you know the direct URL, and a public API like this may make it "more public" than the developer intended. Another thing is that there may be a code-level permission check in place, and a module like this would have hard time figuring that out.

That being said, have you already implemented or are you considering implementing custom selector support for such limits? I.e. allow the developer to manually define a selector that returned pages must match, or alternatively should never match? I think that could make a lot of sense from a security point of view, particularly for public API endpoints, where it might actually work best as a per-endpoint setting :)

  • Like 8

Share this post


Link to post
Share on other sites
41 minutes ago, teppo said:

...sometimes a site may have content that is viewable only if you know the direct URL, and a public API like this may make it "more public" than the developer intended.

Are you talking about pages with the status hidden? If thats the case, it should behave as expected. At this point this module accesses content only via $pages->find(). As long as $pages->find() does not return pages that are not intended for public this module should not make it accessible. I do not use $pages->get()as it bypasses some permission rules.

41 minutes ago, teppo said:

Another thing is that there may be a code-level permission check in place, and a module like this would have hard time figuring that out.

As a proper citizen of ProcessWire, one would implement code-level permission check by attaching a hook to User::hasPagePermission, User::hasTemplatePermission or any other equivalent, including field level permissions. For that cases this module wouldn't have to figure out anything, it will happen naturally. But for those cases where access to resources are checked outside of ProcessWire's permissions context, this module might not be a good fit for building service api.

Share this post


Link to post
Share on other sites
1 hour ago, teppo said:

That being said, have you already implemented or are you considering implementing custom selector support for such limits? I.e. allow the developer to manually define a selector that returned pages must match, or alternatively should never match? I think that could make a lot of sense from a security point of view, particularly for public API endpoints, where it might actually work best as a per-endpoint setting :)

I have not thought about this kind of security layer. Though it sounds reasonable. I will keep in mind this option. For now I plan to add an option to limit the templates that are meant to be accessible via public api by explicitly selecting them.

  • Like 1

Share this post


Link to post
Share on other sites
3 hours ago, Nurguly Ashyrov said:

Are you talking about pages with the status hidden? If thats the case, it should behave as expected. At this point this module accesses content only via $pages->find(). As long as $pages->find() does not return pages that are not intended for public this module should not make it accessible. I do not use $pages->get()as it bypasses some permission rules.

As a proper citizen of ProcessWire, one would implement code-level permission check by attaching a hook to User::hasPagePermission, User::hasTemplatePermission or any other equivalent, including field level permissions. For that cases this module wouldn't have to figure out anything, it will happen naturally. But for those cases where access to resources are checked outside of ProcessWire's permissions context, this module might not be a good fit for building service api.

Generally speaking you're, of course, right -- in most cases one should use built-in visibility settings and permission-related hooks, but it's not unheard of to check permissions in a template file either. Depends a bit on the use case. And yes, you're right that in such cases it may be preferable to avoid installing such a module at all.

Obviously this is mainly a problem with systems that include a enabled-by-default (or always enabled) built-in public API, and less so when enabling/installing the API itself is a conscious choice.

Either way, it's good to understand that exposing your content to the world via a publicly queryable API may uncover some surprises. This is one of the reasons why I find certain value in the idea of crafting the API per current needs and so that it only exposes the minimum viable amount of data :)

Note: don't get me wrong, I'm definitely not against this module. What I've said here is mostly theoretical. I also think that your idea of being able to manually define queryable templates makes a lot of sense. While I'd still suggest enabling a selector instead, you obviously know the use cases (and the implementation) better.

 

  • Like 5

Share this post


Link to post
Share on other sites

I hear what Teppo is saying, but choosing templates would pretty much nail that concern. Developer has chosen to show those templates through API, so leaves no place for confusion in my opinion. 

I will definitely give this one a good ride. 

  • Like 3

Share this post


Link to post
Share on other sites
On 1/30/2017 at 7:22 PM, teppo said:

Obviously this is mainly a problem with systems that include a enabled-by-default (or always enabled) built-in public API, and less so when enabling/installing the API itself is a conscious choice.

Either way, it's good to understand that exposing your content to the world via a publicly queryable API may uncover some surprises. This is one of the reasons why I find certain value in the idea of crafting the API per current needs and so that it only exposes the minimum viable amount of data :)

You are completely right. I can't argue that "enabled-by-default" approach can lead to lots of security issues. That's why I am limiting the exposable pages only to selected templates. While the selector option is quite simple to implement I don't want to enable this kind of option because I believe it should not be this module's concern.

The way I see it, if this module stays consistent and retrieves data only through $pages->find() api (or it's equivalent like $page->children(), $page->siblings() etc) that should give the user any type of control with the security. For example what you suggest could be achieved with a single hook. Say this is your template file where you expose your GraphQL api (something like /site/templates/graphql.php).

<?php

echo $modules->get('ProcessGraphQL')->executeGraphQL();

What you suggest could be achieved like this.

<?php

wire()->addHookAfter('Pages::find', function($event) {
  $event->return = $event->return->filter($mySecuritySelector);
});

echo $modules->get('ProcessGraphQL')->executeGraphQL();

I would prefer users to approach security this way. This strategy to security gives full control for the user while allowing me to stick to a single rule when concerned about security and makes the code of the module much easier to reason about. I do realize that I could just insert the above code in the module and that's basically an implementation of what you suggest. But I don't want to encourage the user to solve security problems via module settings because no matter how hard I try, I won't be able to make this module dummy proof without limiting it's capabilities.

Another thing I wanted to mention is that I see this module as a GraphQL representation of ProcessWire api. Like @Ivan Gretsky mentioned, if done right, this could allow us to build lot's of useful developer tools on top of this module. Even a mobile app that gives you limited site administration capabilities. But only if module is consistent with how ProcessWire behaves. And that includes the security of course.

On 1/30/2017 at 7:22 PM, teppo said:

Note: don't get me wrong, I'm definitely not against this module. What I've said here is mostly theoretical. I also think that your idea of being able to manually define queryable templates makes a lot of sense. While I'd still suggest enabling a selector instead, you obviously know the use cases (and the implementation) better.

Oh no sir, not at all. I value your opinion very much. That's exactly what I wanted to hear from the community, opinions. I am thankful to you for mentioning this aspect of the module in it's early stage, before I started to implement other features that depend on it, like authentication or others that I might not think of right now.

  • Like 9

Share this post


Link to post
Share on other sites

Just a thought, since this is what I try to do with my own modules: could you add hookable methods in ProcessGraphQL that allow implementing custom restrictions? These hookables could be no-ops if not hooked and receive all information about the query at the time of calling, enabling users to filter or reject queries before or after they've run.

It's an intriguing module in any case. Thanks for sharing it with us!

  • Like 5

Share this post


Link to post
Share on other sites
1 hour ago, BitPoet said:

Just a thought, since this is what I try to do with my own modules: could you add hookable methods in ProcessGraphQL that allow implementing custom restrictions? These hookables could be no-ops if not hooked and receive all information about the query at the time of calling, enabling users to filter or reject queries before or after they've run.

That's a very good idea! Will do that. Thank you for the tip.

  • Like 2

Share this post


Link to post
Share on other sites

Here is another idea. What about the ability to make a number of API endpoints with different allowed templates and restrictions based on single instance of a module. By passing an argument to executeGraphQL() or something like that. With the ability do distinguish them in hooks.

A way to have a public and less public API on the same site. I guess than some authentication questions could be solved on a template level.

Share this post


Link to post
Share on other sites
19 hours ago, Ivan Gretsky said:

Here is another idea. What about the ability to make a number of API endpoints with different allowed templates and restrictions based on single instance of a module. By passing an argument to executeGraphQL() or something like that. With the ability do distinguish them in hooks.

But all you said is already can be achieved. :) No need to do anything on my side. Maybe add documentation on module's properties though. You can modify the module settings via api by overwriting them. So here how you can set different templates for different endpoints.

// /site/templates/graphql-endpoint1.php
<?php
$ProcessGraphQL = $modules->get('ProcessGraphQL');
$ProcessGraphQL->legalTemplates = array('skyscraper', 'city');
echo $ProcessGraphQL->executeGraphQL();
?>

// /site/templates/graphql-endpoint2.php
<?php
$ProcessGraphQL = $modules->get('ProcessGraphQL');
$ProcessGraphQL->legalTemplates = array('architect', 'basic-page');
echo $ProcessGraphQL->executeGraphQL();

// /site/templates/graphql-endpoint3.php
$ProcessGraphQL = $modules->get('ProcessGraphQL');
echo $ProcessGraphQL->executeGraphQL(); // here it will use default settings that you set via admin interface

 

For the ability to distinguish the versions of your GraphQL endpoints. That's also doable without much effort. We are talking about ProcessWire after all. Here how it might look like.

$config->GraphqlEndpointID = 123;
echo $modules->get('ProcessGraphQL')->executeGraphQL();
$config->GraphqlEndpointID = false;

And same thing in other template files with different endpoint id. Now anywhere you attach a hook, you can know which endpoint of your api is being executed, or if it is being executed at all. You just need to add a conditional block in your hook. Something like

if (wire('config')->GraphqlEndpointID === 123) {
  // some bussiness here
}

 

I am a bit confused though. One of selling points of GraphQL is that there is only one url that you need to deal with. It's just `example.com/graphql/` and nothing more. No more this

  GET example.com/graphql/skyscrapers/
  GET example.com/graphql/skyscrapers/{id}
 POST example.com/graphql/skyscrapers/
  PUT example.com/graphql/skyscrapers/{id}
PATCH example.com/graphql/skyscrapers/{id}
  GET example.com/graphql/architects/
 ...

It's only one endpoint for everything you need. That's actually is the way it is encouraged to build GraphQL api. Also it is only one HTTP verb you need to use, which is POST. You can stop thinking about dealing with PUT, PATCH, HEAD, OPTION and more. You only need this with GraphQL.

POST example.com/your-endpoint-url/

And that's it. One HTTP verb and one url to rule them all :)

  • Like 3

Share this post


Link to post
Share on other sites

I was thinking of a few endpoints to handle authentication with the template permissions. One for the public, another for the registered users with the ability to make changes via mutations when they'll be implemented. There are other ways to handle authentication of course. But then we will have to implement some restrictions via module itself. But maybe I am not seeing something obvious here.

Share this post


Link to post
Share on other sites
2 hours ago, Nurguly Ashyrov said:

I am a bit confused though. One of selling points of GraphQL is that there is only one url that you need to deal with. It's just `example.com/graphql/` and nothing more. No more this [...]

Thats true - yet, when I was reading this thread and thinking about that restriction and security stuff and about the differences of graphQL and REST - 
I thought that it might actually be handy to simply combine the two.
Using REST for simple API calls - simple forms, logins... and so on - and using graphQL for sophisticated stuff for your interactive JS app.

You might want to do this to differ between the general public and logged in users.

/graphQL/public/ and /graphQL/private/

Since by defining legal templates in one endpoint those will be legal for anyone. But you want to restrain the public data for the guest user as much as possible - but at the same time allow more available data for logged in users, even granularly define legal data for different user roles.

You could do it just like that I think?
/public/ will only allow very few legal things in general.
/private/ will handle anything else automatically via ProcessWires granular permission system for logged in users.

Or maybe there is a way to handle that all in one endpoint? Idk ...  ... oh. of of course you can ask in your single endpoint for the user role ...... .... ... :rolleyes: as simple as that.

 

Maybe it would also be handy to have an option to define "legalFields" in the same way as templates? So you can restrain the amount of data which is instantly public a bit more granularly. So you can just hide anything which doesn't need to be public at all.

 

And by the way - good work!
I will definitely learn a couple of things here again ... thanks!

Edited by blynx
having a fancy fancy

Share this post


Link to post
Share on other sites
3 hours ago, Ivan Gretsky said:

I was thinking of a few endpoints to handle authentication with the template permissions. One for the public, another for the registered users with the ability to make changes via mutations when they'll be implemented. There are other ways to handle authentication of course. But then we will have to implement some restrictions via module itself. But maybe I am not seeing something obvious here.

There is not need for different endpoint for users with different roles. The module does not have any authentication/authorization logic on it's own. The users that will be able to authenticate with this module are the same users in your ProcessWire installation. When I mentioned implementing authentication, I was talking about logging in via GraphQL api, like via AJAX. In reality it will be the same $session->login('username', 'password'), nothing more.

1 hour ago, blynx said:

Since by defining legal templates in one endpoint those will be legal for anyone.

No, no. Of course not. I am sorry for the confusion here. Legal templates mean legal for the api. It does not mean it will make it available to the public. Like I mentioned earlier the module checks if the requesting user has permissions to view, edit, create and etc. If say you select user template as legal. It does not mean it will be public. It means it is available via api to those who are authorized to view it, authorized via ProcessWire's access control system.

I personally don't think there is even a need for the legal templates option. But it is helpful if you have too many templates and selecting only few can reduce the schema size and make api faster.

I think there is a bit confusion about this. I want emphasize that this module does not make any data public, nor does it anything private. That is not the module's concern. The module's job is to make your data available in a JSON format, in addition providing the ability to consume that JSON data via GraphQL api. If the user does not have permissions to view a certain page according to ProcessWire's access control system then he won't be able to fetch it.

45 minutes ago, blynx said:

Maybe it would also be handy to have an option to define "legalFields" in the same way as templates? So you can restrain the amount of data which is instantly public a bit more granularly. So you can just hide anything which doesn't need to be public at all.

The same goes for fields. When implemented the user will be able to access only those fields that he is authorized via ProcessWire's access control. But I will add an option for legal fields also, because that also could help reduce the initial schema size.

  • Like 2

Share this post


Link to post
Share on other sites
50 minutes ago, Nurguly Ashyrov said:

I am sorry for the confusion here. Legal templates mean legal for the api. It does not mean it will make it available to the public. Like I mentioned earlier the module checks if the requesting user has permissions to view, edit, create and etc.

Ah sorry, I know - I expressed myself not accurately -

I also think legalTemplates and Fields are basically not necessary - but i think it is just a very convenient way to reduce the available data :)

 

50 minutes ago, Nurguly Ashyrov said:

I think there is a bit confusion about this. I want emphasize that this module does not make any data public, nor does it anything private. That is not the module's concern. The module's job is to make your data available in a JSON format, in addition providing the ability to consume that JSON data via GraphQL api. If the user does not have permissions to view a certain page according to ProcessWire's access control system then he won't be able to fetch it.

The confusion might be about this:

Normally in processwire templates you have to "make the fields public" by manually echoing data in a template (echo $page->title) - so actually for a guest user everything is hidden by default - though by permission actually authorized.

With this module - everything gets "unveiled" (to use another term here) automatically. This is what I meant by "public" and "private".

... am I right?

Edited by blynx
added second quote and blabla
  • Like 4

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.


  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By Robin S
      First a note about my other modules...
      I have three existing modules that are similar in that they allow restrictions to be placed on repeating inputfields: Limit Repeater, Limit PageTable, Limit Table
      Restrict Repeater Matrix takes a different approach to the module configuration from those other modules. The module settings for Restrict Repeater Matrix are applied in the field settings rather in a module config screen. I think this new approach is better, but it means that it isn't practical to create different settings for different roles via the admin interface. Instead the module has a hookable method, allowing roles to be targeted and other advanced usages to be achieved via a hook. The result is that the module is more flexible.
      I intend to transition my other modules to the same approach over the coming weeks, but because this will result in breaking changes I will be releasing the updated modules under new names ("Restrict Repeater", etc) to avoid users upgrading via the Upgrades module without full awareness of the changes. The old modules will be marked as deprecated.
      Restrict Repeater Matrix
      A module for ProcessWire CMS/CMF. Allows restrictions and limits to be placed on Repeater Matrix fields. Requires ProcessWire >= v3.0.0 and FieldtypeRepeaterMatrix >= v0.0.5.
      For any matrix type in a Repeater Matrix field you have the option to:
      Disable settings for items (cannot change matrix type) Prevent drag-sorting of items Prevent cloning of items Prevent toggling of the published state of items Prevent trashing of items Limit the number of items that may be added to the inputfield. When the limit is reached the "Add new" button for the matrix type will be removed and the matrix type will not be available for selection in the "Type" dropdown of other matrix items. Please note that restrictions and limits are applied with CSS/JS so should not be considered tamper-proof.
      Usage
      Install the Restrict Repeater Matrix module.
      For each matrix type created in the Repeater Matrix field settings, a "Restrictions" fieldset is added at the bottom of the matrix type settings:

      For newly added matrix types, the settings must be saved first in order for the Restrictions fieldset to appear. Set restrictions for each matrix type as needed. A limit of zero means that no items of that matrix type may be added to the inputfield.
      Setting restrictions via a hook
      Besides setting restrictions in the field settings, you can also apply or modify restrictions by hookingRestrictRepeaterMatrix::checkRestrictions. This allows for more focused restrictions, for example, applying restrictions depending on the template of the page being edited or depending on the role of the user.
      The checkRestrictions() method receives the following arguments:
      $field This Repeater Matrix field $inputfield This Repeater Matrix inputfield $matrix_types An array of matrix types for this field. Each key is the matrix type name and the value is the matrix type integer. $page The page that is open in ProcessPageEdit The method returns a multi-dimensional array of matrix types and restrictions for each of those types. An example of a returned array:

      Example hooks
      Prevent the matrix type "images_block" from being added to "my_matrix_field" in a page with the "basic-page" template:
      $wire->addHookAfter('RestrictRepeaterMatrix::checkRestrictions', function(HookEvent $event) { $field = $event->arguments('field'); $page = $event->arguments('page'); $type_restrictions = $event->return; if($field->name === 'my_matrix_field' && $page->template->name === 'basic-page') { $type_restrictions['images_block']['limit'] = 0; } $event->return = $type_restrictions; }); Prevent non-superusers from trashing any Repeater Matrix items in "my_matrix_field":
      $wire->addHookAfter('RestrictRepeaterMatrix::checkRestrictions', function(HookEvent $event) { $field = $event->arguments('field'); $type_restrictions = $event->return; if($field->name === 'my_matrix_field' && !$this->user->isSuperuser()) { foreach($type_restrictions as $key => $value) { $type_restrictions[$key]['notrash'] = true; } } $event->return = $type_restrictions; }); http://modules.processwire.com/modules/restrict-repeater-matrix/
      https://github.com/Toutouwai/RestrictRepeaterMatrix
    • By BitPoet
      Here's a little text formatter module that redirects all external links found in a textarea (e.g. for hit counting) to a given URL.
      TextformatterExternalRedirect
      GitHub repo
      As TextFormatters do, this module modifies the contents of the textarea (HTML) at rendering time. It prepends the given URL to the link address for external links (http and https), optionally makes sure that the link is opened in a new window and allows you to add css classes to such links.
      All options can be configured in the module's configuration settings.
      Usage:
      Download the zip archive and extract it to site/modules, the rename the top folder to TextformatterExternalRedirect Go to the backend and select "Modules" -> "Refresh", then click "Install" for "External Link Redirect" Click "Settings" and configure the module
      Go into the field configuration for the field(s) you want this formatter to apply to and add it from the dropdown
      Done, now any external links in the configured fields will have the configured settings applied Feel free to leave feedback and post and questions you have here.
       
    • By teppo
      Hey folks!
      Took a couple of late nights, but managed to turn this old gist of mine into a proper module. The name is SearchEngine, and currently it provides support for indexing page contents (into a hidden textarea field created automatically), and also includes a helper feature ("Finder") for querying said contents. No fancy features like stemming here yet, but something along those lines might be added later if it seems useful (and if I find a decent implementation to integrate).
      Though the API and selector engine make it really easy to create site search pages, I pretty much always end up duplicating the same features from site to site. Also – since it takes a bit of extra time – it's tempting to skip over some accessibility related things, and leave features like text highlighting out. Overall I think it makes sense to bundle all that into a module, which can then be reused over and over again 🙂
      Note: markup generation is not yet built into the module, which is why the examples below use PageArray::render() method to produce a simple list of results. This will be added later on, as a part of the same module or a separate Markup module. There's also no fancy JS API or anything like that (yet).
      This is an early release, so be kind – I got the find feature working last night (or perhaps this morning), and some final tweaks and updates were made just an hour ago 😅
      GitHub repository: https://github.com/teppokoivula/SearchEngine Modules directory: https://modules.processwire.com/modules/search-engine/ Demo: https://wireframe-framework.com/search/ Usage
      Install SearchEngine module. Note: the module will automatically create an index field install time, so be sure to define a custom field (via site config) before installation if you don't want it to be called "search_index". You can change the field name later as well, but you'll have to update the "index_field" option in site config or module settings (in Admin) after renaming it.
      Add the site search index field to templates you want to make searchable. Use selectors to query values in site search index. Note: you can use any operator for your selectors, you will likely find the '=' and '%=' operators most useful here. You can read more about selector operators from ProcessWire's documentation.
      Options
      By default the module will create a search index field called 'search_index' and store values from Page fields title, headline, summary, and body to said index field when a page is saved. You can modify this behaviour (field name and/or indexed page fields) either via the Module config screen in the PocessWire Admin, or by defining $config->SearchEngine array in your site config file or other applicable location:
      $config->SearchEngine = [ 'index_field' => 'search_index', 'indexed_fields' => [ 'title', 'headline', 'summary', 'body', ], 'prefixes' => [ 'link' => 'link:', ], 'find_args' => [ 'limit' => 25, 'sort' => 'sort', 'operator' => '%=', 'query_param' => null, 'selector_extra' => '', ], ]; You can access the search index field just like any other ProcessWire field with selectors:
      if ($q = $sanitizer->selectorValue($input->get->q)) { $results = $pages->find('search_index%=' . $query_string . ', limit=25'); echo $results->render(); echo $results->renderPager(); } Alternatively you can delegate the find operation to the SearchEngine module as well:
      $query = $modules->get('SearchEngine')->find($input->get->q); echo $query->resultsString; // alias for $query->results->render() echo $query->pager; // alias for $query->results->renderPager() Requirements
      ProcessWire >= 3.0.112 PHP >= 7.1.0 Note: later versions of the module may require Composer, or alternatively some additional features may require installing via Composer. This is still under consideration – so far there's nothing here that would really depend on it, but advanced features like stemming most likely would.
      Installing
      It's the usual thing: download or clone the SearchEngine directory into your /site/modules/ directory and install via Admin. Alternatively you can install SearchEngine with Composer by executing composer require teppokoivula/search-engine in your site directory.
    • By teppo
      MarkupMenu is a markup module for generating menu trees. When provided a root page as a starting point, it generates a navigation tree (by default as a HTML "<ul>" element wrapped by a "<nav>" element) from that point onwards. If you've also provided it with current (active) page, the menu will be rendered accordingly, with current item highlighted and items rendered up to that item and its children (unless you disable the "collapsed" option, in which case the full page tree will be rendered instead).
      Modules directory: https://modules.processwire.com/modules/markup-menu/ GitHub repository: https://github.com/teppokoivula/MarkupMenu Usage
      As a markup module, MarkupMenu is intended for front-end use, but you can of course use it in a module as well. Typically you'll only need the render() method, which takes an array of options as its only argument:
      echo $modules->get('MarkupMenu')->render([ 'root_page' => $pages->get(1), 'current_page' => $page, ]); Note: if you omit root_page, site root page is used by default. If you omit current_page, the menu will be rendered, but current (active) page won't be highlighted etc.
      A slightly more complex example, based on what I'm using on one of my own sites to render a (single-level) top menu:
      echo $modules->get('MarkupMenu')->render([ 'current_page' => $page, 'templates' => [ 'nav' => '<nav class="{classes} menu--{menu_class_modifier}" aria-label="{aria_label}">%s</nav>', 'item_current' => '<a class="menu__item menu__item--current" href="{item.url}" tabindex="0" aria-label="Current page: {item.title}">{item.title}</a>', ], 'placeholders' => [ 'menu_class_modifier' => 'top', 'aria_label' => 'Main navigation', ], 'include' => [ 'root_page' => true, ], 'exclude' => [ 'level_greater_than' => 1, ], ]); Note: some things you see above may not be entirely sensible, such as the use of {menu_class_modifier} and {aria_label} placeholders. On the actual site the "nav" template is defined in site config, so I can define just these parts on a case-by-case basis while actual nav markup is maintained in one place.
      Please check out the README file for available render options. I'd very much prefer not to keep this list up to date in multiple places. Basically there are settings for defining "templates" for different parts of the menu (list, item, etc.), include array for defining rules for including in the menu and exclude array for the opposite effect, classes and placeholders arrays for overriding default classes and injecting custom placeholders, etc. 🙂
      MarkupMenu vs. MarkupSimpleNavigation
      TL;DR: this is another take on the same concept. There are many similarities, but also some differences – especially when it comes to the supported options and syntax. If you're currently using MarkupSimpleNavigation then there's probably no reason to switch over.
      I'd be surprised if someone didn't draw lines between this module and Soma's awesome MarkupSimpleNavigation. Simply put I've been using MSN (...) for years, and it's been great – but there are some issues with it, particularly in the markup generation area, and it also does some things in a way that doesn't quite work for me – the xtemplates thing being one of these. In some ways less about features, and more about style, I guess 🙂
      Anyhow, in MarkupMenu I've tried to correct those little hiccups, modernise the default markup, and allow for more flexibility with placeholder variables and additional / different options. MarkupMenu was built for ProcessWire 3.0.112+ and with PHP 7.1+ in mind, it's installable with Composer, and I have a few additional ideas (such as conditional placeholders) still on my todo list.
      One more small(ish) difference is that MarkupMenu supports overriding default options via $config->MarkupMenu. I find myself redefining the default markup for every site, which until now meant that each site had a wrapper function for MarkupSimpleNavigation (to avoid code / config repetition), and this way I've been able to leave that out 🙂
      Requirements
      ProcessWire >= 3.0.112 PHP >= 7.1.0 If you're working on an earlier version of ProcessWire or PHP, use MarkupSimpleNavigation instead.
    • By teppo
      Hey folks!
      I'm happy to finally introduce a project I've been working on for quite a while now: it's called Wireframe, and it is an output framework for ProcessWire.
      Note that I'm posting this in the module development area, maily because this project is still in rather early stage. I've built a couple of sites with it myself, and parts of the codebase have been powering some pretty big and complex sites for many years now, but this should still be considered a soft launch 🙂
      --
      Long story short, Wireframe is a module that provides the "backbone" for building sites (and apps) with ProcessWire using an MVC (or perhaps MVVM – one of those three or four letter abbreviations anyway) inspired methodology. You could say that it's an output strategy, but I prefer the term "output framework" since in my mind the word "strategy" means something less tangible. A way of doing things, rather than a tool that actually does things.
      Wireframe (the module) provides a basic implementation for some familiar MVC concepts, such as Controllers and a View layer – the latter of which consists of layouts, partials, and template-specific views. There's no "model" layer, since in this context ProcessWire is the model. As a module Wireframe is actually quite simple – not even nearly the biggest one I've built – but there's still quite a bit of stuff to "get", so I've put together a demo & documentation site for it at https://wireframe-framework.com/.
      In addition to the core module, I'm also working on a couple of site profiles based on it. My current idea is actually to keep the module very light-weight, and implement most of the "opinionated" stuff in site profiles and/or companion modules. For an example MarkupMenu (which I released a while ago) was developed as one of those "companion modules" when I needed a menu module to use on the site profiles.
      Currently there are two public site profiles based on Wireframe:
      site-wireframe-docs is the demo&docs site mentioned above, just with placeholder content replaced with placeholder content. It's not a particularly complex site, but I believe it's still a pretty nice way to dig into the Wireframe module. site-wireframe-boilerplate is a boilerplate (or starter) site profile based on the docs site. This is still very much a work in progress, but essentially I'm trying to build a flexible yet full-featured starter profile you can just grab and start building upon. There will be a proper build process for resources, it will include most of the basic features one tends to need from site to site, etc. --
      Requirements and getting started:
      Wireframe can be installed just like any ProcessWire module. Just clone or download it to your site/modules/ directory and install. It doesn't, though, do a whole lot of stuff on itself – please check out the documentation site for a step-by-step guide on setting up the directory structure, adding the "bootstrap file", etc. You may find it easier to install one of the site profiles mentioned above, but note that this process involves the use of Composer. In the case of the site profiles you can install ProcessWire as usual and download or clone the site profile directory into your setup, but after that you should run "composer install" to get all the dependencies – including the Wireframe module – in place. Hard requirements for Wireframe are ProcessWire 3.0.112 and PHP 7.1+. The codebase is authored with current PHP versions in mind, and while running it on 7.0 may be possible, anything below that definitely won't work. A feature I added just today to the Wireframe module is that in case ProcessWire has write access to your site/templates/ directory, you can use the module settings screen to create the expected directories automatically. Currently that's all, and the module won't – for an example – create Controllers or layouts for you, so you should check out the site profiles for examples on these. (I'm probably going to include some additional helper features in the near future.)
      --
      This project is loosely based on an earlier project called pw-mvc, i.e. the main concepts (such as Controllers and the View layer) are very similar. That being said, Wireframe is a major upgrade in terms of both functionality and architecture: namespaces and autoloader support are now baked in, the codebase requires PHP 7, Controllers are classes extending \Wireframe\Controller (instead of regular "flat" PHP files), implementation based on a module instead of a collection of drop-in files, etc.
      While Wireframe is indeed still in a relatively early stage (0.3.0 was launched today, in case version numbers matter) for the most part I'm happy with the way it works, and likely won't change it too drastically anytime soon – so feel free to give it a try, and if you do, please let me know how it went. I will continue building upon this project, and I am also constantly working on various side projects, such as the site profiles and a few unannounced helper modules.
      I should probably add that while Wireframe is not hard to use, it is more geared towards those interested in "software development" type methodology. With future updates to the module, the site profiles, and the docs I hope to lower the learning curve, but certain level of "developer focus" will remain. Although of course the optimal outcome would be if I could use this project to lure more folks towards that end of the spectrum... 🙂
      --
      Please let me know what you think – and thanks in advance!
×
×
  • Create New...