Treatment of [un]published / [un]deleted documents by API routines

Hello MODx developers and community!

Notwithstanding the following, I gladly appreciate your eager and, after all, very successful afforts in creating a next-generation, robust and 99,999% flexible content-management system.

Reinventing the wheel tagging system, I have struggled with an annoying problem in version 0.9.6.1p2 of MODx (but, according to the changelogs not reporting a fix of that, this will also apply to 0.9.6.2, won’t it?): In some code to be applied as a template variable binding in the manager backend, I want to collect docIDs without respecting publishedness. Deleted docs shall be ignored as the default is, however. The motivation for this is, that one may want to keep a category page unpublished while development, but to have already the possibility of tag-linking against it. Hence, I want to have the code provide the checkbox options for all category page docIDs whether published or not.

As examined so far, the treatment of the document state differs between API functions. These functions control by a boolean parameter called (in their signatures) $active, $published and/or $deleted, we’ll call it just "flag" for now. The API functions divide into two classes:

• Class I: When flag is 0 (!= 1), the state (published/deleted) of the document is not a criterion. When it is (exactly) 1, data is retrieved only from published and undeleted documents. Examples: getParent(), getPageInfo()
• Class II: The flag is used directly in the data retrieval statement at last. Thus, only published documents are respected if flag is 1, unpublished ones if it is 0. Examples: getTemplateVar*(), getDocument*()

Then, the get*Children()’s:

• getDocumentChildren() belongs to class II
• getActiveChildren() belongs to class I but $active = 1 by implication as the method name suggests
• getAllChildren() does what you expect, but deleted documents are retrieved as well, what you (like me) might not wish

I had to use unrobust and ugly snippet-scope solutions to some of my problems that arose from that shortcoming:



I am looking forward to modx 2.0 - please refactor your code!

What about a default-switcher method like $modx->beware_doc_state( ACTIVE|UNPUBLISHED|DELETED ) with the constants defined as ACTIVE = 4, UNPUBLISHED = 2, DELETED = 1 thus enabling flag processing by bit operators, and the same as combined flag for the other methods to control this distinction?

Thank you,
agilero

[edit: end of post seemed to be lost]

What about a default-switcher method like $modx->beware_doc_state( ACTIVE|UNPUBLISHED|DELETED ) with the constants defined as ACTIVE = 4, UNPUBLISHED = 2, DELETED = 1 thus enabling flag processing by bit operators, and the same as combined flag for the other methods to control this distinction?

This is an interesting idea. Ditto recently added the ability to show both pub and unpub together.

You could have always done it directly in php/mysql rather than using the api. the published state and deleted state are simply database parameters. The api is just a shortcut and you can get the api code you can add it to your own snippet and edit it as needed to do pretty much whatever you need.

Sure I can write my own code. Thus, however, I must worry about future updates - the more custom hacks users add, the more can break and leave their afforts void. I prefer encouraging the developers to make all users benefit from the changes and guarantee that custom code relying on them is valid all the project’s life-cycle or until changes are replaced by some better solution.

Quote from: agilero at Oct 24, 2008, 12:44 PM

Sure I can write my own code. Thus, however, I must worry about future updates - the more custom hacks users add, the more can break and leave their afforts void. I prefer encouraging the developers to make all users benefit from the changes and guarantee that custom code relying on them is valid all the project’s life-cycle or until changes are replaced by some better solution.

This entire discussion and the ideas being discussed here was a major part of the motivation for the Revolution rewrite. If you’ll notice, many of these API functions are deprecated in Revolution alpha and will be removed in one of the first few point releases. The migration guide will describe how to convert your legacy API calls to the new approach, which gives you consistent, object-oriented access to any data structure, in the core or otherwise. This consistent approach to working with the objects is provided by the xPDO core on which Revolution has been developed. Using this approach we will be able to hide implementation or data structure changes behind the API objects, i.e. without breaking legacy code.

Here is an example for selecting Documents (referred to as Resources in Revolution):

In the meantime, you can easily isolate your custom queries or other code into functions or classes that can be easily reimplemented for Revolution, or future updates to Evolution (which will continue to see bug fix and small-scale feature releases at least through the initial releases of Revolution) that might address this issue for you. However, I would prefer not to significantly change the core API implementation at this point for 0.9.6.x/Evolution (1.x) so we do not further complicate the upgrade path to Revolution (2.x).