Food for thought

Hi everyone,

I just registered today but I’ve been observing MODX for a couple of years. Here are some remarks :

Documentation : sorry to say but this has to be the worst documentation I’ve ever seen. I’m talking about the developer part. The rest is OK. If you read the whole manual, you sure get what a snippet is, what a TV is, etc. but on the development part you’re just like WTF. Look at the namespaces page (http://rtfm.modx.com/display/revolution20/Namespaces). When I read this I’m like "Hmm OK there are some namespaces in MODX, cool". OK. BUT! Where do you use them exactly? And what’s with the example? OK it’ll let me retrieve my namespace but what do I do with it except printing its name and path... Maybe it’s good to debug but I don’t really see how it’s helping me to understand how they’re used in MODX. The thing is, there’s a lot of definitions, concepts, whatever but this is so general that we don’t get the point. Again, I’ve read the whole doc, I still have no idea on how I’ll start to develop a plugin, I mean I don’t even know how to retrieve a get parameter. Or maybe I just have to look for $_GET directly? Some frameworks encapsulate this in a object but I’m not even sure what MODX does. Point is, you’re even more confused AFTER having read the manual.

Constructive note : I’d like you to go to http://www.yiiframework.com/doc/guide/ and browse a few pages. Now I can tell you that when you read the stuff, you’re ready to code.

xPDO : this is supposed to help and speed the development time, but I’ve been looking at the docs and again I was like WTF. What’s with the amount of time and code needed to generate the models? OK I saw there’s some reverse script, but again I’ll have to copy and paste code, configure it, etc. And for this I’ll have to switch to the xPDO doc. And look what’s said : "Create a PHP file where you have access to an xPDO instance". How a beginner is ever gonna understand what he has to do? (that is, if he ever reached the page). Some frameworks indeed need some files but there are some tools bundled with the download and again better how-to’s.

Plugin development : one of the best part of the documentation is this tutorial : http://rtfm.modx.com/display/revolution20/Developing+an+Extra+in+MODX+Revolution. Kudos to Shaun. I’ve learnt more in these 3 pages than in any other part of the manual. We learn that it’s better to do an include snippet so that you can use your favorite editor. Sure, nice idea, of course it is nicer than having to wait for the browser to refresh. But hey, another extra step. Boring. And at the end, you’ll have to copy-paste your code back and change the snippet so that there’s no more include. Another thing, talking about MVC, when I’m developing, this is what I understand : the V are the chunks, the C are the snippets, and the M are the xPDO file, aren’t they? (OK maybe I’m wrong with this but I’ll go on anyway just in case. If I’m wrong forget it). Having access to the chunks and snippets is cool if you want to adjust some stuff, but why can’t we have access to the model with the editors? This is something not coherent. Again I might be wrong on this one, but it looks strange to me that you have access to some stuff with the browser and access to some other via FTP or file system.

"Framework" : I had to do a tricky form and I couldn’t use the Form plugin. So I looked at how I’d do that. At some point I would need some validators and some stuff to handle the errors. I thought, there should be something, they’re claiming everywhere that MODX is a framework. Maybe I missed it, but I found nothing. So what, I’ll have to write my own validators? Again with whatever framework this kind of stuff is just there. I’m not talking about exotic functionnality : beside displaying stuff, forms are what you do the most on a website. So is MODX gonna propose that someday? I don’t want to reinvent the wheel, and what happened with that project, I switched to a framework and did it in a few minutes. Fast and secured. Hopefully the site didn’t have much content so a CMS wasn’t really needed but for next week I have a site with tricky forms + lots of pages and I’m not sure what to do. Basically, MODX is supposed to be a framework but beside offering objects to retrieve ressources I see nothing to help web development.

OK enough for today. I’m not trying to be a hater because as I said I’ve been watching at MODX for a couple of years and it really has some great functionnalities for end-users, I definitely like it. But as a developer I just can’t take the step. I hope these remarks will be taken as constructive stuff for a better manual and API and whatever - a better MODX.

Good luck with your project next week, go with whichever framework you feel most comfortable with.
Whether it be MODX or something else.
Happy coding.

Wise words Crssp. Thanks!

If you think we didn’t know the documentation was lacking, you weren’t observing closely enough.

Please file any specific requests here: http://bugs.modx.com/projects/docs/issues The docs are what the community makes of it (and the Core Team is doing a lot of that as well) and that bugtracker is the first in a series of upcoming strategies by the core team to get the docs up to level. But people who *know* it, don’t see the things people that don’t would need. So that’s where you come in to let us know.


I must admit this is the first time I hear someone saying the MODX Docs aren’t dev-oriented though..

Are you expecting (or at all open) to how certain things like namespaces and xPDO help you, or is food for thought more just "thrown out there"?

Frameworks offer tools to build a solution, not the solution on a golden plate last time I checked... Curious what forms you couldn’t make with FormIt.

My lack of education showing again, but I’ve never quite gotten a handle on exactly what "namespaces" are. I get a vague feeling it’s sort of like a sandbox where a discrete part of an application operates, so that their variables and what-have-you don’t conflict with those of another group of functions. So if I wrote an application using Revo’s framework, I could set it in its own namespace and then if somebody else wrote another application that might be used at the same time on the same site, it would have its own namespace and the two wouldn’t interfere with each other even if they have the same variable names or function names. Or at least that’s the vague idea I have. I think I picked that up when I was studying that hot new programming language Java many years ago.

hi,

well, many things to say, i’ll try not to be too long and, most of all, say some in a rather understandable english

Exactly like you, i had been observing and trying MODx for quite a long time when i decided to make my first website with it.
The difference is i was so astonished by how it made my life so easier that from that very first one last year in april/may, i’ve made 10 sites with it that go from small jazz bands to 5/6 big companies ones here in France
But... it was and still is... with Evo . I tried Revo but switched back to Evo for a simple reason that may sound curious to Revo devs and users, like you, formerly i’m a dev and if it’s possible that Evo "framework" is a little less powerful than Revo one, it is also far less restrictive (so far...)

This being said, i must say i feel your comments a bit unfair for a few reasons.
- the docs. Well, of course, we all dream every cms or framework coming with offline docs like codeigniter ones or, at least, as good online docs as Yii ones (great fan of both frameworks) but docs are a hard work to do and i’m sure MODx devs would be happy to get some help about them
On the other hand, one of the great part of MODx docs, tips and tricks and so on are to be found here, the forum is one of the most friendly and helping one i’ve been given to see... and is full of snippets, explainations and so on

- the framework, may be the most unfair part of your comment.
You said it yourself, you were working on a website with a small amount of content and the most important part of it was apparently tied to dev and forms. maybe you made the wrong choice when choosing a cms, well, even a cmf, to do this.
I was in the same situation a few months agao and had to make a website that was more an enormous app than a real website, you know what, i made it with a framework...
Now, when you’ll have to make a "classic" website, full with rich content, a complex design, loads of js (another speciality of mine) and many peculiar modules to write to manage... peculiar content, your point of view may change...
Even Yii with its fabulous scaffolding tool won’t offer you one percent of what MODx does to organize your website AND admin for your client
- and i can’t find another cms (i’ve tried a lot before i definetely choosed MODx) that will give you that graphic freedom that easily
- and, very important to me, not messing up your code with its own print. I would say MODx is one of the very rare What You Code Is What You Get cms.
Now, yes, there may be a little less helpers and other avalaible librairies but, once more...
It’s up to us to choose the right tool for the right job and, honestly we can’t blame MODx not to do what it doesn’t claim to do, the same as if working on a full e-commerce website i used MODx just because i love it instead of prestashop (or magento if you’re crazy ) and ended in complaining because MODx is not really made for it.

- Switching to txt editor and ftp, thanks god, that’s another reason for me to stay with MODx, the ability to code outside of MODx, the way i want, using my own helpers/librairies/classes
i could say MODx hasn’t great image manipulation tool nor classes. Well, i’ve written mines and use them in every MODx website i make and that’s what i love... for my clients those tools are part of MODx admin/manager, have the MODx look and feel and everybody is happy with this, beginning with me

I’m not saying MODx is perfect (nor are the devs who keep working on it), i can understand you may have been disappointed using it for a project it was not really designed for, you’re right, the docs could be better (being an Evo evangelist i sometimes grunt when running into the not documented part of the API) but, honestly i keep thinking that once you’ll have used MODx for a project it is designed for your point of view may change... it’s really one of the greatest tools i’ve been given to work with

Didn’t i say i would try not to be too long... :p

Have swing

i sometimes grunt when running into the not documented part of the API

Any Evo API that you find not sufficiently documented, let me know and I’ll work up a tutorial for using it. Usually I only write for what catches my attention; in fact the updated article on creating plugins for Easy2Gallery only came about because somebody emailed me for help, as the old article was badly outdated and Easy2 doesn’t work that way any more.

Hi Susan,

thanks a lot for the offer (and thanks a lot for being such a nice example of what i said above about the friendly and helpful spirit here... )

you know what, sometimes, i love grunting (but i’m sure my avatar says so by itself ) and when suddenly wondering if MODx has a built in function to do something i need and rummaging into the rtfm, all those no link pink functions are a good opportunity for me to do so as i can’t say if they could be the solution or not

to be honest, it doesn’t last that long and i end finding the answer in MODx source code and, if not, i write my own function (what actually is my job...)

but, once more, thanks a lot for the offer, we all know who we can ask for help

Have swing

A namespace in itself is nothing more than a name and a related path.

But that *is* important as system settings are organized in Namespaces (defaulting to the "Core" namespace), and your actions/menu items use your namespace path to point to the right controller path. And lexicons are organized in namespaces and then topics.

If your application or addon doesn’t use system settings or actions or translated content you could probably get away with not using it.

I’ve tried to update the rtfm API pages, but I can’t make heads nor tails of the layout and how to structure the pages, so I gave it up. Most of them are documented at least somewhat on the old wiki.