What Documentation / Tutorials would you like to see?

Quote from: splittingred at Nov 09, 2009, 03:09 PM

http://svn.modxcms.com/docs/display/revolution/Creating+a+3rd+Party+Component+Build+Script

So, does that mean that I need to refactor all of my code into their own classes and a similar directory structure, with resolvers, and vehicles, and assets, and documentation and all that jazz-- in order to submit the snippets, lexicon and chunks that I’ve already written from within MODx?

To be honest, if I have to do all that in order to submit code written IN the MODx framework-- moreover, if I have to _learn_ how to do all that, which would basically be learning a whole new MVC architecture from the ones I’ve used in the past (like CodeIgniter and Zend Framework)-- I’ll probably spend the time while I’m learning it invested in writing another module that packages code written in MODx Revolution such that it can be exported and uploaded. That way, I’m killing two birds with one stone: I’m learning how to write packages for MODx, and I’m submitting not only a user registration script but also a core component that facilitates development by others.

I’m just saying that if one goes to the trouble to write something of value, and to learn xPDO and Active Record in the process in order to do so, they shouldn’t _necessarily_ have to memorize (or even study, for that matter) the MODx MVC framework in its entirety in order to submit it. That’s not saying that I won’t necessarily go to the trouble; it’s simply saying that if I’m going to, I think I’d like to contribute something else of value that will ensure that other people can code from within the MODx framework and submit their work to the community. It encourages development and encourages growth of the system as a whole.

Quote from: Crates at Nov 09, 2009, 03:24 PM

So, does that mean that I need to refactor all of my code into their own classes and a similar directory structure, with resolvers, and vehicles, and assets, and documentation and all that jazz-- in order to submit the snippets, lexicon and chunks that I’ve already written from within MODx?

No, that’s just an example. That tutorial even explicitly states:

First off, let’s take a quick look at our directory structure. This isn’t always how you have to do it - this one is specifically built this way for SVN; but it’s definitely recommended, especially with the assets/components/quip/ and core/components/quip/ structures, since that makes creating the transport package much easier.

We do recommend that people put their components (via the transport vehicles) into core/components/componentname/ for non-web-accessible files (such as PHP, cfg, inc, etc) and in assets/components/componentname/. How you structure that in your development environment isn’t important, really. Just make sure you can have a target for the file resolver mentioned in that tutorial.

I’m just saying that if one goes to the trouble to write something of value, and to learn xPDO and Active Record in the process in order to do so, they shouldn’t _necessarily_ have to memorize (or even study, for that matter) the MODx MVC framework in its entirety in order to submit it.

You’re being dramatic. No one’s asking you to learn the entire MODx MVC framework. But, you’re wanting an advanced functionality with your Extra - you want it to be generically installable via remote packaging from any MODx Revolution install. I dont understand why you think that’s not going to take some learning. You’ll need to learn how Transport Packages work - by reading that tutorial - to use a Transport Package.

No one expects to be able to ride a bike without first understanding what a bike is. This is the same thing.

That’s not saying that I won’t necessarily go to the trouble; it’s simply saying that if I’m going to, I think I’d like to contribute something else of value that will ensure that other people can code from within the MODx framework and submit their work to the community. It encourages development and encourages growth of the system as a whole.

Sure; we’d definitely love for someone to write a package builder - but I warn you, there’s a lot more dependencies you’re going to run into than you’re probably expecting. You’ve got a myriad of different possible situations that could occur:
- resolvers, validators
- related objects
- related objects of related objects to an infinite nested level deep
- omitting duplicate objects in a related object progression cycle
- how to handle resolver order
- dynamic setup options
- the license file(s)
- the readme file(s)
- namespace packaging
- lexicon handling

and quite a few other issues.

Just warning you, there’s a reason a UI hasn’t been built for this (yet).

Quote from: svzanden at Nov 06, 2009, 02:28 PM

I would suggest a good end user documentation about making pages / making links / uploading movies etc... for the content editors.

Agreed. The awesome thing about MODx is that it is just amazingly powerful. Crazy, stupid, retardedly powerful. The one major hindrance to it gaining steam and adoption with any speed is easy to see from afar; it’s one of the same major shortcomings that kept Drupal in all the tech magazines and off most of the major production-capacity servers in the world, which is the learning curve for the average adopter. (Drupal 7, btw, is supposed to be balls-to-the-wall when it comes to user experience. If you’re a developer currently using or considering the usage of Drupal, check out d7ux.org -- they are doing some crazy shit with it.)

So, user experience. Yeah, I got a working site up and running with what is essentially a beta version of a program written by developers, for developers. One problem with that: almost every boss I’ve ever had wants to be able to run the whole circus if I get "hit by a bus" (and don’t ask me why they all say the same thing, because I have no idea why it has to be a bus). Drupal had that problem ever since its inception, and we started with version six’s final release. After a year of tweaking and running a slew of add-on packages, we finally produced a product that we can resell to our least tech-savvy clients as a cheap "Instant Internet Presence" that even the kids who grew up riding the short bus to school can figure out how to work.

While MODx is ridiculously strong in its potential as a framework for rapid application development, branching out and offering features that allow for easy assimilation into larger corporations where more than just the code monkeys are going to be adding content and editing user accounts... that’s gonna be key, and it’s gonna take time. Maybe like MODx version three will have that. In order for there to even _be_ a MODx three, it has to gain enough steam that it’s paying the bills for the main contributors to the project (Jay Gilmore, Shaun McCormick, Ryan Thrash, Mike McDade... okay, kidding on that last one; sorry if I’m leaving anyone out) to be able to work on it full-time and get a paycheck for doing so. I’m not pretending to speak on their behalf, but I know how this industry goes, and while opensource is great, there HAS to be some means of monetizing your efforts if you’re gonna put in that much effort for years on end.

So, my point? I am realizing that this is an incredibly long reply when I could have just said "I agree", but whatever; what’s done is done. My point is that until MODx is simple enough for grandma and that boss guy from Dilbert who most of us work for are able to use it, tutorials (especially video-based ones, or at least with lots of screenshots) are going to be KEY in getting others to adopt and recognize the value of MODx. S’alls I’m sayin’, is all.

(... seriously... why a bus? We don’t even really have buses around here.)

As most content goes, the best documentation is going to come from actual real world applications.

Someone has to go first. Then, as we all know, others will spawn new concepts and ideas.

The issue is: what do the developers working on top of the core team APIs need to know.

I have bounced back and forth multiple times through the documentation looking for simple things.

In some places the docs says something is deprecated, but no link or reference is provided to the new method or process -- I know phpdocs...

A page like Bob’s http://bobsguides.com/revolution-objects.html has helped me more than searching back and forth through http://api.modxcms.com/ and reading the source.

I am currently working on simple snippets / ajax routines for revolution which will help people develop for modx as they will simply be grabbing from the back end and displaying on the front a single item -- such as current users name etc, or an ajax’d username look-up etc.

I agree with others that modx provides an awesome and powerful framework, but at times it is HUGE to grasp and work with, because it does so much.

Simply stated, I believe its time for some of us developers who are not necessarily core developers to start leading the exploration into Revolution and tell about it as we go.

That’s a great point wshawn (and thanks for the kind words). I’ve suggested putting @see function() into the phpdocs for the deprecated functions but, unfortunately, no one has had the time to do it.

Often, it’s the people just getting their feet wet who write the best docs. It’s easy for the experienced developers to correct any mistakes, but if they write the docs, they usually leave out steps that are obvious to them but are desperately needed by newbies.

BTW, two thing in the pipeline may help. There will be a MODx book where hopefully you can find all that stuff in one place. It will have a complete guide to all important MODx objects (users, resources, snippets, templates, TVs, plugins, chunks, etc), the Manager, Permissions, PHX-like output modifiers, API reference, Object Reference, and even a PHP Primer. The first draft is getting closer to being finished (I should be working on it right now ) but it takes a while from there to get a book into print, so don’t hold your breath. Also, someday, I hope to put suggestions next to the deprecated function list at Bob’s Guides.

I have already created databases with content many developers will want: County lookup and zip_code matching with city, state, county, latitude, longitude, area code, etc.

Over the next few days, I will be experimenting with pulling this content via ajax and populating modx place holders. I just have to add an id="zip_city" or what ever id to what the place holder feeds to so I can attach jQuery to it.

The point is: once I have this working, I will get back with you and see how we can implement extending your spform.

That information can be used to assist others to building more extensions to existing packages.

I have been using an entirely new perspective with revolution. Instead of writing new snippets for everything I first look to see if something exists which can be "asked" to provide the same information. Case in point: I have took to using wayfinder to replace the ListIndexer snippet with the awesome template mechanism provided with wayfinder. There are still some things I extended ListIndexer to do (with help from others) which are lacking in wayfinder, but when combined with xpdo I believe I can simulate the rest of it.

I have already gotten Wayfinder to replace listChildSibs by using a simple template.

One snippet = lower learning curve, lighter database weight, and quicker development time.

Sounds like you are doing some very interesting and useful work.

I’m reluctant to extend SPForm because it’s designed to be a very simple contact form that works out of the box with very little effort on the user’s part. I purposely didn’t design it to be extendable because that’s what eForm is for. eForm is much more powerful and flexible than SPForm and may already do some of the things you are considering adding to SPForm so it would be a more logical target. It also has built-in hooks for extending it. In addition, a number of people have asked for a Revolution version of eForm and I don’t believe the author is interested in porting it.

You should also take a look at the Revolution snippet, FormIt (http://modxcms.com/extras/package/596), which I haven’t had time to check out. I believe it’s intended as a replacement for eForm and it’s very likely that it would be a better platform for your enhancements than SPForm.

Quote from: lossendae at Oct 04, 2009, 10:29 PM

I would really love a tutorial on how to hook up any third party application to the MODx system.
In a relatively extended way, with a case to study, showing a way to use the same login informations for both systems...

I have already done this extensively on two modx .96 sites. I simply used sessions and ModX evolution supplying the pages. In the manager I applied members to groups and docs to groups.

As each page usually ran multiple snippets, it had direct access to the session and could populate the page accordingly.

ModX handled all the administrative stuff and my snippets would populate the pages accordingly. Currently, I am the only one developing on the project and that is under a "you’ll get a percentage of the profits" type agreement. The website and concept has been valued at $25 million. I will let you know in ten years how that works out if you remind me.

I am not at liberty to discuss exact details as I do not own either of the sites, (only the code behind it) and revealing the code would be a security and intellectual property problem for my clients.

Believe it or not, I may very well have answered your question: ModX snippets, $_SESSION, document groups and user groups.

I am going to have to learn all of these steps in Revolution -- but so far what I have found is that Revo is much easier to work with the Evo once you connect the dots. I can not wait to move the entire platform to Revolution and if I could get the proper funding wouldn’t mind getting the ModX Core developers involved (read that PAID) to take over the project.

A bit more on topic:

I am currently writing very simple snippets which will introduce people to the simplicity of Revolution. I am just researching on how to go about packaging my first snippet: a 169 line snippet which will produce random images (img src=""), random image backgrounds <div style=""), or using chunks as templates. The images are pulled directly from a directory provided in the snippet call. Only 56 lines of the 169 is actual code (not white-space or comments).

Of course the output is xhtml strict compliant by default.

I believe this is in the spirit of what you are looking for.

The image snippet will be great to have.

Have you worked with MaxiGallery? It’s the snippet of choice for photo gallery management in Evo. AFAIK, no one is working on a Revo version of it or a Revo replacement for it (I could be wrong).

Photo gallery management is probably the most serious hole in the add-on collection for Revo at present.

I will have to look at it and see what I find there.

For me, photo galleries are something I will need for clients, but I have over 50,000 pictures headed to flickr and would NOT want to host them all on my site (for obvious reasons).

I have been looking into some of the other "holes" which are simple things that probably need to be shown to potential developers to get more people coding, but I am ALWAYS looking for something to get into...