Simplify output formatting when saving pages via the API

[thetuningspoon]

I'm a little embarrassed to admit that after several years of working in PW I still don't "get" output formatting in the context of saving pages and fields. 

I understand that when I get the value of a field it is automatically formatted when output formatting is on, and that I can switch this off to get the unformatted value. What I don't understand is why I need to turn off output formatting when I am saving a new value to a page. It's output formatting, not input formatting, right?

Even more befuddling to me is the fact that this often results in a fatal error if I forget to do it, crashing my site. I also have to remember to turn it back on again afterwords, or else I can introduce security flaws into my code.

I'm sure Ryan must have a reason for requiring switching output formatting off when doing a save, but if this is so important and is always required, why isn't it just baked right into the save() method? 

I know the new setAndSave() method now does this for individual fields. It would be great to have a similar method when saving an entire Page.

[Nico Knoll]

Well I think it makes sense. Take the date field for example. You define an input and an output format. But "input format" means how it is displayed in the backend - not how you really put data into it. "Output format" means how it is outputted if you call $page->datefield;

If you call "$page->datefield" you don't get the real field but the formatted output (a string) by a runtime formatter. But the field itself does not know how it's output looks like. So If you try to overwrite it the field will not know how to interpret. But if you disable of first the value you get/set is the "real" value of the field.

So just try to keep in mind to disable of before editing a page/saving fields

[thetuningspoon]

See, I get that, but I still don't get it. If what you're saying is correct, it seems like that the only time output formatting should have to be turned off is in the case that you are getting an existing value, modifying it, and setting it back to the same field. (And even then it seems this should be completely up to the dev's discretion, since they might actually want the formatted value for some reason). But most of the time when I am editing a field from the api I am completely overwriting the value with a new one, in which case we are only dealing only with input so output formatting should not be a concern.

[Soma]

It important to know. In most cases if output formatting is on, a field is a string. So you output a property containing a string that is formatted in one way or another or gering the correct language. Either through the field itself or a text formatter. Once you turn of outputformatting it may no longer a property with a string but an object that may has methods or other properties.

Most of the times this only matters on frontend context, while in modules and backend output formatting is never on unless it's explicit used or a module deals with pages that come from via a variable from a frontend template that uses a module method.

Or if you need a date as timestamp you can try it off or use getUnformatted() method.

Setting a field only needs outputformatting off if you do this in frontend context and for fields that are more complex and have outputformatting that turns an array or object into a string ready for output.

Input formatting is mostly just used as far as I know for datetime field used for inputs in a form, and has nothing to do with how you set a value via API. Could be wrong though.

[thetuningspoon]

I was just looking through the Pages::save method and it does appear that PW automatically turns off outputFormatting before it saves the fields.

So I think I understand now what's happening here a little better. It's true that outputFormatting has nothing to do with input. However, a Page object will apply outputFormatting when you call one of its fields (properties), even if the field has never been saved to the database. When a page object is later saved, the save() function loops through each field and writes it to the database. In other words, it gets its output. So outputFormatting must be turned off when it does this or it will not save the value that you actually input.

So that makes sense. But I still don't understand why PW requires ME to set of(false) if the save() method already does this. Because I very rarely need to retrieve a value from a field, modify it, and set it again. So I would appreciate it if PW didn't crash in the cases where I just want to save a new value...

Edit: Also, in those cases where I do need to retrieve an unformatted value, I would prefer if I could specifically use $page->getUnformatted('field_name'), modify the value, and then do $page->field_name = '$modifiedValue'  and $page->save() instead of having to store the current state of of(), turn it off, and then restore the previous state.