ProcessWire Cheatsheet

[Soma]

Yeah your right, but I'm working hard on it ...

Can you try again , just updated improved live search version.

--

Thanks for your feedback and ideas. I will certainly consider some of those.

[apeisa]

Can you try again , just updated improved live search version.

Oh yes, now it works like a charm! Thanks Soma.

[Soma]

Oh yes, now it works like a charm! Thanks Soma.

Cool, glad it works better now! Thanks.

I just changed the toggle behaviour... and it's inline now. Also changed descr font to monospace default.

[diogo]

nice soma! it's more practical like this.

[Soma]

Thanks diogo

I've just commited major update. Cleaned up some and added new features.

- Added index collumn on left side

- You can now toggle sections using the index

- Also toggle show/hide all description of a category when clicking on blue titles.

- It resets if you click on the table somehwere (white space)

Hope you guys like the changes.

--

I noticed that in mozilla, the live search filtering wasn't working after the changes i've done to it.

I figured mozilla has no innerText, which is very practical to get content of a node but not subnodes. I had to use textContent, which returns all text including subnodes, so the search filter doesn't work as good as in other Browsers. May I find a way to work around it.

[ryan]

Soma, this is really great. Just keeps getting better and better. It's so useful. Would you mind if I added this to the PW API section? I also have a few comments:

I would drop $page->pageNum (deprecated).

$page is missing some functions like render(), removeStatus(), isHidden() ... I'm guessing the cheat sheet is missing them because the online docs might be too, so this is something I may need to add. If it's helpful to you for me to add them first, I'll be glad to do that.

Seeing the API docs like this makes me think of some things I should add to the API, like a $page->isPublished() function.

WireArray now has insertBefore and insertAfter function. The WireArray::has() function can also accept an item of the type that it holds, i.e. $a->has($object)

I wonder if PageArray might be useful to have in addition to WireArray. PageArray is the one people are more likely to interact with (and it's a type of WireArray, but with some added capabilities).

I kind of think $templates and $template should be split? Right now they are one group.

I'm confused by some of the items in the Selector Properties section. I'm thinking some of them don't belong there and may not actually work as selector properties. Instead, i'm thinking something like this (below) and calling out that they are Build-In Page Selector Properties: ?

limit=n
start=n
end=n
sort=field
include=all 
include=hidden 
check_access=0 
children.count=n
parent=id
parent=$page 
parent=/path/to/page/
path=/path/to/page/
template=name
template=$template
created=timestamp
modified=timestamp

...maybe something like this too?
any_field=any value
any_field>any value
any_field<any value
any_field>=any value
any_field<=any value
any_field!=any value
any_text_field=any value
any_text_field*=any value
any_text_field~=any value
any_text_field%=any value
any_text_field^=any value
any_text_field$=any value

In the "Selector Status" section, I recommend listing "check_access=0" rather than (or in addition to) check_access=1". that's because check_access=0 is the one you are most likely to use, as =1 is usually assumed.

MarkupPager and MarkupPageFields are modules and wonder if they should be left off?

I'm loving this cheatsheet!! Thanks again for your great work here.

[Soma]

Thanks Ryan! Glad you like it. What do you mean put on API page? A link? No problem go for it. I rather see this as a official reference page wen the team will manage.

I'm looking through your comments and implements those as soon as possible.

As you can guess all what's there (except a only a few) are copied from the API pages. So if somethings not there it's most likely not on the API pages. If you don't mind adding them and note them to a text file, so I could easily look through them and add them.

My plans:

• Make this as useful as it can get; complete, comprehensive list of all most basic and useful API stuff.
  
• So my idea is, this is a working prototype. I see this pretty soon to be a PW app! ( Fun! ;D) So from there PW team could add and manage themself.
  
• Make color codes for example to distinct get/set methods/properties is something I was thinking about and would like to do it but I'm not very save in that area when it comes to descide what is what. I would love if you could lend some time and may at some point implement it. If this would be a PW app, it would be easy.
  
• Change layout to floated cols and may have media queries to adapt layout to screensize (nice to have)
  

My questions/comments:

WireArray

Here I wasn't sure, it looks like PageArray is the same? So I thought I'll just put WireArray for now.

Selectors

Here I'm really happy if you can help out getting them right. I wasn't sure how and what to put there. I'll have a go with you input.

$templates $template

Those are very confusing to me and may others too. While there is now:

$page

$pages

$fields

$field

$templates

$template

...

You mean to separate them?

Confusing may be that there's no "$field" variable, and also not a "$template" variable... those are meant to be in real like $page->template and $page->field_name. Or when one uses: $field = $fields->get(name); echo $field->name;

I would like to have this more clear to new users, as this was what also confused me a little.

General API

It's great to see an overview of the "whole" API and I'm also surprized that there are still some I didn't know or know well, and some are still not there it seems. Also one may start to question why isn't there an $users $roles $permissons var?

Thanks

[ryan]

So my idea is, this is a working prototype. I see this pretty soon to be a PW app! ( Fun! ) So from there PW team could add and manage themself.

This sounds awesome!

Make color codes for example to distinct get/set methods/properties is something I was thinking about and would like to do it but I'm not very save in that area when it comes to descide what is what. I would love if you could lend some time and may at some point implement it. If this would be a PW app, it would be easy.

Great ideas, definitely just let me know anything I can do.

Change layout to floated cols and may have media queries to adapt layout to screensize (nice to have)

That would be great on mobile devices (if people use mobile devices for this sort of thing). I want to do the same thing for the main PW site and PW basic site profile.

Here I wasn't sure, it looks like PageArray is the same? So I thought I'll just put WireArray for now.

What you put in there with the most recent update looks great.

Confusing may be that there's no "$field" variable, and also not a "$template" variable... those are meant to be in real like $page->template and $page->field_name. Or when one uses: $field = $fields->get(name); echo $field->name;

Since there isn't actually a variable called $template or $field, I think it's best to label them in a manner that isn't literal and indicates it applies to any individual item of that type, i.e.

$any_template->name
$any_field->save(); 
etc. 

For singular items of a type that do have a literal placeholder in the API (like $page and $user) then I think maybe it's better to use the literal $page or $user, even though all those properties/methods still apply to any $page or $user.

Also one may start to question why isn't there an $users $roles $permissons var?

Actually they are all there in the API already. There just hasn't been time to add them to the docs. They also weren't quite as high of a priority because they are just filters on top of the $pages API var that enforce pages with a specific template or parent. But I should add these to the API docs... it should be easy since they are all basically the same in terms of the methods they provide.

[Soma]

The WireArray::has() function can also accept an item of the type that it holds, i.e. $a->has($object)

Can you explain a little more about this and Wire/PageArrays in general?

What exactly is the difference between PageArray and WireArray? I learned to use new PageArray(), to fill it with pages using import or add and do further manipulation.

[formmailer]

Keeps getting better and better, Soma. Great work!

Would it be an idea to add a link to the online docs with examples for each "group", eg. http://processwire.com/api/variables/page/ for the $page section. Maybe something like:

$Page (Online documentation and examples)

I think the examples are very useful, especially for new users.

/Jasper

[vknt]

Nice work Soma! 

[ryan]

Can you explain a little more about this and Wire/PageArrays in general? What exactly is the difference between PageArray and WireArray? I learned to use new PageArray(), to fill it with pages using import or add and do further manipulation.

WireArray is what PW uses for collections of items of a given type like: Page, Template, Field, Fieldtypes, Modules, etc. It can act like a regular PHP array, but can also do a lot more. When a class descends from WireArray, it just overrides methods that define what type is held in the WireArray and what key is used as the index for the array. Like your cheatsheet noted, the primarily difference between PageArray and WireArray is that PageArray includes some helper methods for managing pagination. But of course, a PageArray won't accept anything in it other than Pages. PageArray is what is returned by any PW function that is designed to return more than one page at a time.

Btw, I added a cheatsheet link in the API page. I've set it up to cache from http://somatonic.github.com/ProcessWireCheatsheet/ once per hour, so if you make updates there, they should appear here as well.  I want to feature the cheatsheet more prominently in the API/documentation, but just wanted to get it in there asap and focus on how best to highlight it on the new site. My thought is that once people are introduced to what the API is, the cheatsheet will be the most heavily used part of the API docs (I know it will be for me).

Thanks,

Ryan

[slkwrm]

Wow! This is great, Soma! Haven't been here for a while, guys. Hope I'll find a way to come here more frequently.

[Soma]

Thanks Ryan for adding it!

Great, now after working on it the last couple days, I haven't really come to see how useful and great this is already...

Good idea having a "simple/advanced" option would be great. Just not sure what would go where. I think I would need some help here deciding.

As for undocumented functions and such. I didn't even started to look at what else there is to be found in the codebase, I just added all from the API pages. But there's already a couple things added that are not in the docs yet. Now looking at the code and seeing more and more that I discover I'm a little confused to what's intended to be used and what not, which are left out on purpose or by accident... or not have made it in yet. Also since I'm not very experienced in  OO PHP and still not have the complete understanding how everything works together in PW core yet, I would be very happy to have you Ryan help me out there as much as you can. Though the nice thing is I experienced a boost in my understanding while doing this cheatsheet, as I'm now trying stuff out and looking at core more and again.

BTW I discovered a method in Template: hasField(name|id|Field) . Which I didn't know but found could be useful to know. Just as an example. I added it to the cheatsheet in the next update.

[Pete]

I just used the CheatSheet for the first time last night - I'd gone from an HTML template to an almost-completed website in 2 hours!

This is a testament to how well this cheatsheet is laid out as much as it is to ProcessWire's ease-of-use, but the CheatSheet saved me having to look around for things and every minute saved soon adds up

[Soma]

Great, I'm glad it was helpful for you. Thanks for sharing your experience!

BTW I'm just working on a update with some things removed and some things added. Ryan helped some to double check everything is right and he made suggestion to move some parts or make them as an advanced mode that can be turned on or off.

I think I'll have it ready this weekend.

[ryan]

This is a testament to how well this cheatsheet is laid out as much as it is to ProcessWire's ease-of-use, but the CheatSheet saved me having to look around for things and every minute saved soon adds up

I totally agree. I've always just used the code itself as my API reference, and it is SO much easier to just keep a window open to the cheatsheet.

[Soma]

I've done major update, just commited.

- some restructuring, adds and removes

- minor tweaks overall, typos, ordering

- added "advanced" mode

ADVANCED mode: Mainly it started with only "System Configurations" being advanced, but I added many of the more advanced functions overall to the advanced mode. I don't know if it really is the thing to go, but I thought why not try to have very simple and basic version so it would fit on a matchbox . So they're my guess on to what would be the more advanced stuff, and I had kinda hard time to decide what to do and how. After long back and forth I decided to just give it a go and see what people think.

It will be cached on http://processwire.com/api/cheatsheet.

Or avaiable also on http://somatonic.github.com/ProcessWireCheatsheet/

[formmailer]

Looks very good, Soma!

It gets better and better, even when you think it can't get any better.

[Soma]

Thanks formmailer, you're too kind! Glad you like it.

[ryan]

Looking fantastic Soma!!

You went further with the number of items hidden in 'advanced' than I was originally thinking, but now that I see it, I like it, and it makes sense. Creating, modifying and saving items really is more of an advanced thing, so I think your selection of what should go where is very well crafted.

When in 'simple' mode: what do you think about all the sections that have advanced items ending with a tiny 'more' link or something like that? That way, one could look at all the $page options (for instance) without expanding all the advanced options for everything else. It would also make it clear that there is more depth to the cheatsheet for someone that might miss, or not understand what the 'advanced' option is at the top.

I'm thinking these options below might fit better under 'advanced'?

$page

$page->next;  (because one has to be careful with next/prev and large groups of pages)

$page->prev;

$page->next();

$page->prev();

$page->setOutputFormatting();

WireArray

$a->getArray()      (because rarely used)

$a->getKeys()

$a->getValues()

Selectors:

start=n          (used more by system than user)

end=n          (rarely used)

include=all

include=hidden

check_access=0

children.count=n

created=timestamp    (because these were advanced in $page section)

modified=timestamp

created_users_id=int

modified_users_id=int

$user

$user->pass  (because only useful for setting value)

$input

$input->get["name"]    (because no need to list 3 ways of same thing in 'simple' mode)

$input->post["name"]

$input->cookie["name"]

$session

$session->getAll()    (because rarely used)

Lastly, what do you think about having the direct access get/set mentioned in $page like it is in $session? Maybe people already assume this, but I wasn't sure.

$session->$name = $value
$value = $session->$name

[Soma]

You went further with the number of items hidden in 'advanced' than I was originally thinking, but now that I see it, I like it, and it makes sense. Creating, modifying and saving items really is more of an advanced thing, so I think your selection of what should go where is very well crafted.

Thanks for the kind words. Glad you like it. I also like it and thought long time about it. Happy it get's recognized ;D

When in 'simple' mode: what do you think about all the sections that have advanced items ending with a tiny 'more' link or something like that? That way, one could look at all the $page options (for instance) without expanding all the advanced options for everything else. It would also make it clear that there is more depth to the cheatsheet for someone that might miss, or not understand what the 'advanced' option is at the top.

Good idea, I also worry about not being recognized by some. I'll give it a try.

I'm thinking these options below might fit better under 'advanced'?

$page

$page->next;   (because one has to be careful with next/prev and large groups of pages)

$page->prev;

$page->next();

$page->prev();

$page->setOutputFormatting();

WireArray

$a->getArray()       (because rarely used)

$a->getKeys()

$a->getValues()

Selectors:

start=n          (used more by system than user)

end=n           (rarely used)

include=all

include=hidden

check_access=0

children.count=n

created=timestamp     (because these were advanced in $page section)

modified=timestamp

created_users_id=int

modified_users_id=int

$user

$user->pass   (because only useful for setting value)

$input

$input->get["name"]    (because no need to list 3 ways of same thing in 'simple' mode)

$input->post["name"]

$input->cookie["name"]

$session

$session->getAll()    (because rarely used)

That would make sense I think. Well I thought judging by "used rarely" not always fits. I always worry about useful functions "rearely used" not being recognized when using simple mode. But I still also think having as few as basic as possible, will not overhelm the user on first sight.  – I'll move them to advanced mode.

Lastly, what do you think about having the direct access get/set mentioned in $page like it is in $session? Maybe people already assume this, but I wasn't sure.

$session->$name = $value
$value = $session->$name

There's a few such things that came to mind. Like this you mention here. For sure I will gladly add it.

I think such things, mainly taken for granted by us experienced users, are dangerous to assume the users/new users will digg it. I remember not recognizing some things at first and getting confused a little.

On the other hand it can get confusing for not so experienced php coders to have too many different ways to the same. I know of co-workers that don't like such things.

What you guys think?

[ryan]

I think direct access is kind of assumed, just because you'll see it in nearly any code example you come across for ProcessWire. But maybe it wouldn't hurt to add it, as it's only 2 short lines (see below). But I'm happy either way.

<?php

$value = $page->any_field;    // same as $page->get('any_field'); 
$page->any_field = $value;    // same as $page->set('any_field', $value); 

[diogo]

If it says explicitly that it does the same thing, can't be confusing. I would say it's good to show that people can use both.

Soma, how about making the menu position:fixed? I think it might make it more comfortable.

edit: Although you would have to deconstruct all the table for this 

[Soma]

If it says explicitly that it does the same thing, can't be confusing. I would say it's good to show that people can use both.

Soma, how about making the menu position:fixed? I think it might make it more comfortable.

edit: Although you would have to deconstruct all the table for this 

Not sure about this. I thought about it too, but didn't feel it's needed. I mainly use search function or the left index, I never find myself scrolling really.