Is there useable MODx API documentation?

I found MODx functions fairly straightforward back when I worked in Evo, even if it was fairly simple and just based on a few wiki pages.

Since moving to Revo I feel much more stupid and am plagued by a huge, non-standardised array of information, documentation and complexity that I consistently feel either unable or just don't have the time to fight my way through. Judging by the volume of posts asking the sort of things I feel, I would say others have this sensation too.

It's taken me a good few weeks to settle down to a few key php functions and code arrangements to allow me to get programming and create snippets to do the things that I did before (simple MySQL queries on custom tables, generating output lists/tables etc). But obscurity in the documentation often means I end up taking shortcuts and doing things my own way, just to save time. I feel like I'm being forced more and more to use more abstract methods of doing the same thing, and I get fed up spending time having to learn new ways to do normal things, or just trying to find these ways.

For example, today I'm looking for ways to access user info.

I found $modx->user->get('username') and $modx->user->get('id'), from here http://rtfm.modx.com/revolution/2.x/administering-your-site/security/users. That's useful, but now I want to access more details of a user's group memberships etc using the same API. I go to the User Groups page via the link on that page: http://rtfm.modx.com/revolution/2.x/administering-your-site/security/user-groups. Here, there are two or three functions at the bottom of the page explaining how to assign users to groups. But that's it. Where do I find the rest of the user group API info?

I google "modx revo api" and find http://rtfm.modx.com/revolution/2.x/developing-in-modx/other-development-resources/api-reference.

That page just has a link to http://api.modx.com/revolution/2.2/. I go, and now the head-scratching starts. Files, Packages, Charts, Reports, Other Documentation. Where do I go? I try Packages. A huge list of stuff. I scroll down and find modUser. I click on that and am faced with a meaninglass page of auto-generated package and class and data type information. Not a function in sight.

So am I doing something wrong? There must be a clearer more straightforward source of rapidly-digestible API info out there ready for developers to refer to for their snippet development? Like this http://wiki.modxcms.com/index.php/Category:API_Function? It should be easy to find, easy to digest and easy to cross-reference.

Sorry to whinge, but aren't we all subscribers to the notion of intuitive user interfaces? That should include docs too. They are essential.

A few people have posted articles and tutorials, such as Bob's Guides and W. Shawn Wilkerson's site, but there really isn't any decent API documentation, certainly not any "official" documentation. And I am in agreement with you that the basic DoxBlox generated lists taken from the source code that you'll find at api.modx.com aren't very helpful. It's a big problem for anyone trying to learn MODX development.

Yes Susan.

MODx is a good CMS and framework, but I am convinced that user take-up should be far greater than my impression of it seems to be (from forum posts and available addons). The two things which I think contribute to that lack are obscure/inaccessible documentation and bugs. Both may be due to the strategy of always focussing on future developments and leaving documentation and bug-finding/fixing to others. I have used MODx for years and always spend a significant amount of time stuck on problems casued by bugs/lack of info. For example the recent "Do you really want to leave this page" issue which was both a bug and a long-overlooked feature in Revo. It's a shame.

I would like to see more solid development and testing of versions, plus integrated releases of updated docs, before work on new features. (I often see new features coming out before old problems are fixed). Then we could spend more time developing and less trouble-shooting. And a positive spin-off of that is that more of us would have the time (and confidence) to contribute addons.

Excellent points. The documentation is very difficult to navigate for people new to MODX. In fact, that's why I created Bob's Guides in the first place (see my sig).

Tooting my own horn for a moment, there is a very complete API reference in the Appendix of my book.

Digital Edition: http://bobsguides.com/modx-the-official-guide-digital-edition.html

Paper Edition: http://www.amazon.com/MODX-Official-Guide-Bob-Ray/dp/0983619409/

For quick reference, what I use most is this: http://bobsguides.com/modx-object-quick-reference.html

There is a good intro to working with MODX objects via the API here: http://bobsguides.com/revolution-objects.html (and a much more extensive section in the book).

As for your question, user groups are kind of goofy because of the many-to-many relationship between users and user groups. How you deal with that depends on which way you are going (find the groups a member belongs to vs. find the members of a particular group) and what you want to do with the information.

If you just need to see if a user is a member of a particular group or groups, you can do this (assuming that you have the user object):



or



If it's the current user may be logged in, you can use $modx->user in place of $user.

Welcome to MODX.

Hi Bob,

thanks for all that, all very useful, although I'm not really sure what to do with the quick reference page. Could that list all the available functions too?

I've got your book already, but in paper version. The digital edition sounds good, but I'm a fully paid-up memer of the global recession right now and so can't afford another $40. Do you do a multi-format deal?.... ;-)

Thanks also for the $user->isMember function calls. Almost exactly what I ended up writing from scratch yesterday! I googled the function call and found http://api.modx.com/revolution/2.2/db_core_model_modx_moduser.class.html#%5CmodUser::isMember(). So stuff can be found if you know what to search for. I do think that API documentation could be vastly improved. I used to program in Java and I loved the documentation for that; clear and easy to search, explore and use for quick reference or learning. (I just checked and looks like it's still as good since Oracle took over, though way more complex than MODx needs: http://docs.oracle.com/javase/7/docs/api/).

Hi Bob,

thanks for all that, all very useful, although I'm not really sure what to do with the quick reference page. Could that list all the available functions too?

I've got your book already, but in paper version. The digital edition sounds good, but I'm a fully paid-up memer of the global recession right now and so can't afford another $40. Do you do a multi-format deal?.... ;-)

Thanks also for the $user->isMember function calls. Almost exactly what I ended up writing from scratch yesterday! I googled the function call and found http://api.modx.com/revolution/2.2/db_core_model_modx_moduser.class.html#%5CmodUser::isMember(). So stuff can be found if you know what to search for. I do think that API documentation could be vastly improved. I used to program in Java and I loved the documentation for that; clear and easy to search, explore and use for quick reference or learning. (I just checked and looks like it's still as good since Oracle took over, though way more complex than MODx needs: http://docs.oracle.com/javase/7/docs/api/).

I'll add a task to my growing list to try and fix the API doc generation, but if someone wants to volunteer their time to work on this, I'd be most grateful.

As an aside, and also coming from a Java background, I found JavaDoc (and now PHPDoc) extremely useful—in the source. But I don't think I ever used actual generated API docs. I've been a user of JetBrains' IDE offerings for years and have never found myself in need of referring to generated documentation, as everything I need to know about the API is provided by the IDE via introspection, and in context.

An example. The processors (runProcessor("modWhatever", ...) return different formats. Some return an array, some return a JSON string, and it's very difficult to know what any given processor is going to return. This is especially awkward if you want to use a processor in an AJAX request.

Quote from: Gav at Feb 20, 2014, 04:29 AM

Hi Bob,

thanks for all that, all very useful, although I'm not really sure what to do with the quick reference page. Could that list all the available functions too?

I've got your book already . . .

Then you should have a very complete API reference (with examples) in the Appendix. It lists at least 95% of the functions/methods you would ever want to use. It starts on Page 629, hidden under the heading: "MODX API"