Pages Web Service (ServicePages)

[ryan]

Awhile back, I made an Ajax API for querying pages in the admin via the ProcessPageSearch module. It is used by [for example] the PageAutocomplete Inputfield. I thought this capability would be useful on the front-end too, so this module brings it to the front-end as a page in your site that you can put wherever you want to. The way you use it is exactly the same as the one in ProcessPageSearch, but this one is a little more strict, given that it's publicly available on the front-end. By "more strict" I mean that you have to define what you want to allow in terms of input and output in the module's configuration.

The web service takes it's query from GET variables in the URL and returns results in JSON format. It installs a page called /service-pages/ in your site, and you are welcome to move that page wherever you want.

Here is the official page at modules.processwire.com:
http://modules.processwire.com/modules/service-pages/

Once installed, you should view the /service-pages/ page that it installs because it outputs detailed instructions and examples on how to use it in your own projects. But here's a few excerpts from what you'll find on that instructions page:

Input

The /service-pages/ page can be queried with GET variables in the URL to return JSON-format results. The query string should follow a ProcessWire selector format ([field][operator][value]), but modified a bit for use in a URL query string. Here are a few format examples:

Specify a single value:
?field=value

Specify multiple fields and values to match:
?field1=value1&field2=value2&field3=value3

Specify multiple fields where at least one must match the value. Note use of "," rather than "|", something we had to settle for to make it work as a URL key:
?field1,field2,field3=value

Specify one field with multiple possible values (it's fine to use "|" as a separator here):
?field=value1|value2|value3

Note that unlike regular ProcessWire selectors, multiple field=value sets are split with an ampersand "&" rather than a comma ",".


Allowed Values
The allowed values for field are set with the module configuration. You may also specify the following modifier keyword=value pairs:

• sort=[field] (Specify field name to sort results by)
• debug=1 (Enables debug mode producing human readable output)
• limit=[n] (Specify the max number of pages to return)
• start=[n] (Specify the result number to start with)
• include=hidden (Include pages that are 'hidden')

Allowed operators
The operator demonstrated by the "=" sign in the examples above may be replaced with any of the following operators in the query string:

= Equal to
!= Not equal to
< Less than
> Greater than
<= Less than or equal to
>= Greater than or equal to
*= Contains the exact word or phrase
~= Contains all the words
%= Contains the exact word or phrase (using slower SQL LIKE)
^= Contains the exact word or phrase at the beginning of the field
$= Contains the exact word or phrase at the end of the field

As an example, this ProcessWire selector:
template=property, body*=luxury, bedrooms>5, bathrooms<=3

...would be specified as a query string to this web service like this:
?template=property&body*=luxury&bedrooms>5&bathrooms<=3

Allowed templates
For security, the search will only be performed on pages using templates that are defined in the module's configuration.

Output

The returned value is a JSON format string in the following format (populated with example values):
 

{
selector: "title*=something, template=basic-page, limit=50",
total: 2,
limit: 50,
start: 0,
matches: [
    {
    id: 1002,
    parent_id: 4525,
    template: "basic-page",
    path: "/test/hello/",
    name: "hello"
    }, 
    {
    id: 1005,
    parent_id: 4525,
    template: "basic-page",
    path: "/test/contact/",
    name: "Contact Us"
    }
  ]
}

Each of the 'matches' values will also include all the fields you have specified to appear with the ServicePages module configuration.

If an error in the query prevented it from being performed, a JSON string in this format will be returned:
 

{
errors: [
    "Error message 1",
    "Error message 2 (if there was one)",
    "And so on..."
    ]
}

The web service honors user view permissions. As a result, if you are accessing this service from a superuser account, you are likely to get pages that others users may not see. Superusers get an "include=all" automatically, unless you override it with an "include=hidden".

Returned field values
The following field values will be returned for all matched pages:

• id (integer)
• parent_id (integer)
• template (string)
• path (string)
• name (string)

Any other fields may be included from the module's configuration screen.

Pagination
To paginate, simplify add a "page[n]" url segment to the request URL, i.e.
/service-pages/page2/?template=basic-page&sort=name

[Soma]

Thanks Ryan for the module! Sooo many new things to test out I run out of time.

[ryan]

One other thing about this module that's maybe interesting from a module development standpoint: It installs a page (/service-pages/), and the template for that page loads and runs the ServicePages module when it is viewed. So it installs the means to run itself, and it's not autoload. I might be wrong, but can't think of another module that does this, and maybe it's a good pattern. At least, I thought it was fun when building it. I've been thinking about building a module starter kit that includes skeletons for various types of modules and install/uninstall patterns (ready to build from), and this type of pattern would be one among a few others.

[Adam Kiss]

^ +1 for the patterns thing; that will make the 'module' section of documentation instantly over 9000

[Nico Knoll]

Hey,

how can I give "guest" the right to use this? I need it because i'm building a webservice with PW wich reloads its interface via ajax an this module's json-data

[apeisa]

Nico:I haven't tested this yet, but guests should see public data through se.

[Nico Knoll]

Doesn't matter anymore. I just build a AJAX-request page by myself

[ryan]

Nico, guest should already have access to it. That's actually the reason for this module: to bring what was previously an admin-only available service to the front-end/public side. View your /service-pages/ page when you are not logged in, and you should be able to test it as a guest. Let me know if you are unable to access it as guest?

[nik]

Ryan,

Found a tiny slip when reading through the source (ServicePages.module). At line 119 given limit is checked against hardcoded 100 instead of configuration variable maxLimit. maxLimit is used correctly to form the error string though.

Nice module, once again! Haven't used it anywhere yet, just studying to get an upcoming module of mine on the right track (ProcessHello skeleton appeared right on time too).

[ryan]

Thanks Nik! I have corrected that and push the update to GitHub.

[Frank Vèssia]

@Ryan: i got this fatal error during installation:

[b]Fatal error[/b]: Using $this when not in object context in [b]/home/public_html/site/modules/ServicePages.module[/b] on line [b]287[/b]

got it, sorry i didn't copy the php file in module folder

I'm trying to use this module but when i perform a query i get page not found...

i can see the default page with instructions but adding something like /service-pages/?template=picture&sort=-modified i get page not found

[ryan]

Make sure your ProcessWire version is up to date (but I'm assuming it is). The default/instructions page has some tools for you to test the service. When you submit those, do they work? Check also your module settings, as ServicePages limits the queries to only the templates and fields you have defined as allowed. So in your example, if you haven't allowed the "picture" template, then the request is going to fail.

[Frank Vèssia]

@ryan: of course i made all the necessary setup...the default page doesn't work, when i click submit nothing happends...page not found...

[ryan]

You mentioned earlier that you could see the instructions page. Just to make sure we're talking about the same thing: in the PW admin, you click "view" for the page titled "Pages Web Service", and you see this (the instructions page):

Then you click the second submit button, and you get a 404?

Assuming I'm right so far, what is the URL in your address bar when you see the 404?

[Frank Vèssia]

Yes, the page is that. When i click on submit i can only see a js error:

Failed to load resource: the server responded with a status of 404 (Page Not Found) http://www.domain.com/service-pages/?template=picture&sort=-modified

[ryan]

What does your ProcessWire version say? For this module, I think it has to be 2.2.5 or newer.

If you just edit the URL directly in your address bar to say: domain.com/service-pages/?template=picture -- do you still get the 404?

Is your site running from the domain root "/" or from a subdirectory?

[Frank Vèssia]

I'm running the 2.2.6.2.

Same thing if i wrote directly in the address bar...not found

Domain root

[ryan]

It's quite a mystery. When you access /service-pages/?template=picture, is it a ProcessWire 404 or an Apache 404?

You can tell the difference by going to /some-fake-url/ on your domain, and you should get the ProcessWire one (so long as the characters in the path are a-z, dash or underscore). I am hoping you are getting an Apache 404, as that would reduce the mystery a lot.

What other 3rd party modules do you have installed?

[Frank Vèssia]

The 404 comes from PW.

I'm using:

ProcessGoogleAnalytics

ModulesManager

ProcessRedirect

FiledtypeSelect

[ryan]

Are you logged in to PW or logged out? (not that it should matter, but just curious if it makes any difference here).

You might also want to enable debug mode in /site/config.php, just in case there is some PHP error that is getting suppressed. You could also look in your /site/assets/logs/errors.txt file as well.

Do you get a 404 no matter what GET variables you put in the URL? Even something like /service-pages/?aljfelkjflkfj ?

I'm at a loss to know what to try next. Is this something at a publicly-accessible URL that I could try accessing it and watching the headers in my browser? If so, PM me the URL.

[Frank Vèssia]

sent PM

[ryan]

Thanks got it (sorry, didn't see it earlier). I've logged in and don't see any red flags. However, I did find something interesting. If you add the "debug=1" param to the URL, it works:

/service-pages/?template=picture&debug=1

I can't find a reason for why it works with that and not without. I've gone through the code and nothing in ServicePages throws a 404. So it's really unclear where that 404 is coming from. I also tracked the live HTTP headers, and noticed that ServicePages "content-type: application/json" header never gets sent, meaning the 404 appears to be happening before the module is executed.

Since this module has no initialization, I'm of the opinion right now that something else is interfering with the request. I've gone through your modules and don't see anything that appears to be a problem. The only thing you might want to try is temporarily switching back to the default admin theme, just in case there is something there. Though not sure how there could be, but give it a try.

Next steps is that it may be good for me to get a look at your phpinfo(), and I can do further tests but probably need FTP or SSH if you want me to. I would modify the ServicePages module while doing the requests, which should give a much closer look at what's going on.

[kaster83]

Thanks got it (sorry, didn't see it earlier). I've logged in and don't see any red flags. However, I did find something interesting. If you add the "debug=1" param to the URL, it works:

/service-pages/?template=picture&debug=1

I can't find a reason for why it works with that and not without. I've gone through the code and nothing in ServicePages throws a 404. So it's really unclear where that 404 is coming from. I also tracked the live HTTP headers, and noticed that ServicePages "content-type: application/json" header never gets sent, meaning the 404 appears to be happening before the module is executed.

Since this module has no initialization, I'm of the opinion right now that something else is interfering with the request. I've gone through your modules and don't see anything that appears to be a problem. The only thing you might want to try is temporarily switching back to the default admin theme, just in case there is something there. Though not sure how there could be, but give it a try.

Next steps is that it may be good for me to get a look at your phpinfo(), and I can do further tests but probably need FTP or SSH if you want me to. I would modify the ServicePages module while doing the requests, which should give a much closer look at what's going on.

Hi Ryan, It is a great module! However, I also got the same problem as Sevarf2.

I have confirmed that everything should be setup, but when I clicked on "Type a URL query string here to test:", it does not have any response.

When I access my web with "service-pages/?template=basic-page&sort=-modified" it returns HTTP 500 "Internal Server Error The server encountered an internal error or misconfiguration and was unable to complete your request" but I could access the data after appended the "&debug=1". I thought the 404 page mentioned above is Sevarf2 did not setup the custom error page for HTTP 500 page.

If you need my phpinfo() or any other details, I could send those you by PM, thanks for your help!

[ryan]

Thanks Kaster83, that would be helpful for me to get a look at your phpinfo. Also what version of ProcessWire does it say in the bottom of your admin screen?

[kaster83]

Thanks Kaster83, that would be helpful for me to get a look at your phpinfo. Also what version of ProcessWire does it say in the bottom of your admin screen?

It is ProcessWire 2.2.9. And I just PMed you my phpinfo() for your reference.

Thanks a lot for your help!