Better tutorial for developing an Addon than Doodles?

I have been trying to follow the 'Doodles' addon tutorial to create an extra but have got stuck very early on, in fact its the "Part I : Building the Query" section thats stumped me!

Its suddenly saying '...now run your snippet ...' but hasn't explained how to do that. I assume it means call the snippet from a document - tried that but it fails with a blank page.

Altered the "return ''" to "return 'Did not load Saved Forms object'" - thats what gets returned.

Sooo - its not creating my 'Saved_Forms' object. Awesome. Also - the build schema did not return anything when i ran it - Chrome reported an Empty Response instead of the expected output. It DID build the files but there was no output to tell me anything about it.

I understand that this is meant as a comprehensive guide - the reason I chose to follow it is because I have got a huge addon to develop quite soon and thought it would give me some insight into developing on ModX but all its given me is headaches!! Its not like im a noob developer either ...

Are there any other tutorials for developing on Modx Revolution that someone can recommend? Or a book (that covers revolution obviously)?

I think the Doodles tutorial is great ... if you want to create a 'Doodles' addon!! Its not helping me understand the concepts though, of which I will need to have a thorough understanding of to complete the task ahead of me!

I've worked through the Doodles tutorial three or four times, and eventually it becomes clear what is happening. You just need to take it one step at a time and make sure that you get each step correct. For example, the recommendations to make some custom system settings.

I have worked through (step one) the Doodles tutorial six or seven times yesterday and today and it didn't become any clearer ...

I have actually written my own framework so its not like I'm stupid or anything

Could you give me a couple of pointers as to where I need to carefully study please - this is giving me such a headache!!

Its not helping that I get no/zero/nil output to help em with the debugging - I had to add my own in just to figure out that the snippet was unable to load the Saved_Forms DB Object!

@ben.duffin:

You are correct, the Doodles tutorial is a little too comprehensive with not enough explanation for the majority of addons out there. It's painful to read and follow. A lot of what you'll need to know is dependent upon what exactly your addon is going to do. Additionally, it misses out on some things.

Also the process in Doodles is different depending on how you are developing. For instance, if you are developing directly within MODx itself, additional considerations must be made, but the tutorial (nor any tutorial) doesn't tell you what they are. That said, Doodles provides a lot of good information, just not all of it is going to be useful. There's a reason why every programming class starts with "hello world".

Here are the basics:

The add-on development process consists of two entities: The add-on itself and its objects, and the package which delivers that add-on. The package is only necessary if you are going to distribute your add-on. Doodles assumes that you will, and as such lumps them into the same tutorial, as this accounts for most add-ons.

Add-on

An Add-on may be simple or complex. Simple means that it just contains MODx elements. These are easily translated into Packages and become Vehicles which are simply large arrays. The following conditions must be met if you will ever distribute your add-on. Every Add-on should have a Namespace. (I believe a given add-on can only have one). Additionally, every add-on must have a Category (There can be multiples of these). Aside from that, it comes down to placing your objects in the appropriate Namespace or Category.

Everything else that you add makes the process a little more complex. A lot of this is do to the amazing object abstraction performed within MODx. For instance, adding a Property Set is a slightly different process. Your Property Sets must be made before an Element can attach to them. These will ultimately still translate into complex Vehicles.

The process get convoluted when you start moving into Controllers. Further complicated with Custom Manager Pages or Custom Resource Classes. These typically have controllers and processors. Often they will have an alternate Schema and many supporting classes. This is where Doodles is at. It does all of this, with few supporting tutorials for just the little bits.

Understand that MODx is designed with an MVC philosophy. In general, we don't see it (because we're not supposed to). This applies to your add-ons too. The Model for your add-on is comprised of the alternate Schema as well as supporting data-oriented classes. You will only use this if you are adding to the database or changing it in anyway.

Your Controllers are the classes that interface with the data (dynamic or otherwise). Every CMP will have a Controller. Many add-ons use Controllers, as a whole, to objectify their process. These only apply to the back-end.

You View is all of your MODx content (not front-end content). This is Snippets, Plugins, etc. This is because an add-on is for MODx. While it may have display for the front-end website, that is not necessarily so.

I've skipped Processors for brevity. Ultimately you may design the entire add-on in MODx without ever having to worry about Packages until you are ready to distribute. Then you will want to know about all of the other stuff. This is where build scripts, resolvers, validators and vehicles come in.

Package

So, let's talk about the package. Packages are built, they are not the actual add-on but the mechanism by which that add-on will be added into a MODx installation. The package itself contains the content of your add-on, but also the parts needed to make that content work. These parts are Vehicles, Resolvers, and Validators. The Vehicle is typically the actual Chunk, Snippet, etc (split into a decent sized array... that must be added. A good build script will make these for you.

So, really you have to worry about Resolvers and Validators. Resolvers are run after a Vehicle has been added to MODx. They allow you to do clean up, change things around, lots of stuff. Its all done after the installation has your object. The Resolvers account for Installations, Upgrades and Uninstalls, giving you the ability to keep everything working at all times. You may have as many Resolvers as you want, each fixing or finalizing a separate consideration.

Validators are another story. Validators are run prior to the Vehicle being added. They give you the ability to check certain conditions and make sure that the system is ready for your addon. In both validators and systems, you have access to MODx to perform any of the queries and maintenance necessary for both sides. Understand that these only run when a Package is installed, updated or uninstalled. This means you really want to get your add-on working before you tie into all of this.

Putting it Together

Once you have your add-on working, and you've made your Resolvers, Validators, etc, you can begin to build the package. This is where a nice build script comes in. You have 3 choices... Make one yourself, which manually gets your objects and files, Packman which does the work, or MyComponent which is kind of in-between. PackMan can alleviate some of the process by just doing the work for you, but it has a ton of limitations. MyComponent (which is still being adjusted for better and better capability), has very few limitations, but will give you ultimate control of creating the extra build script stuff while managing getting your parts for you.

Each has their own considerations and processes. The thing you must ask yourself is what kind of add-on are you doing and therefore which solution is going to be your best avenue.

Here are other search topics that may help bridge your knowledge gaps:

Making a Custom Manager Page
Making a Custom Table (or Schema)
Making a Custom Resource Class
Contollers and Processors

When it comes down to it, the Package is really simple PHP files that all run in order. Almost all of the files are arrays. Anything else that is not an Element or other MODx entity, is included as is (classes, assets, etc.) Finally you have your glue pieces (the Resolvers and Validators) which are run before and after adding elements (respectively).

Final Note: Every Resolver is only run once.

After following your advice I seem to be doing much better - bobs guides are also proving invaluable!

Although we may want to distribute the addon in the future, for now developing it inside the core will suffice Bobs Guides has a handy little snippet that handles class creation - I have been able to get the beginnings of a CMP together - although I must say that extJS makes the whole thing veeeeery awkward to work through!

Thank you for all your in depth posts - Im sure I can find my way from here

If I crack it and get the results I am looking for perhaps I should write a post on developing an addon....

I've never liked extJs, but I must admit that it can do a lot of very nice UI things. It's just that it's the very epitome of all the worst features of working with Javascript.

I believe both Resolvers and Validators run at the point they are added to the package (and my book is wrong on this point). I've been bitten by putting a resolver too early in the package and not having other objects created later in the package available at that point.

I could be wrong, but I don't think there's any real difference between Resolvers and Validators except that Validators have the option to abort the installation.

By convention, Validators are used early on to check for necessary conditions (e.g., the existence of other extras, GD lib support, etc.), and Resolvers are used to do finishing-up operations like connecting TVs to templates, but I suspect that if you put a Validator at the end of the package and used it as a Resolver, it would work fine as long as it returned true.

@ben.duffin I agree that the Doodles tutorial is the last thing you want to see when first learning to create a transport package (though it has a lot of useful information about how to organize the files).

You've probably seen the MyComponent Tutorial at Bob's Guides, but if you can wait a bit, the new version of MyComponent will be out which is infinitely superior and much easier to use, IMO.

There's a pre-alpha version of it here: https://github.com/BobRay/MyComponent/tree/dev. Unfortunately there's no tutorial or documentation for it other than the comments in the example config file. It does work, however.

At present, it's set up to create the 'Example' extra. You could probably learn a lot by playing with it, because the output tells you everything it's doing. It's designed to run outside of MODX.

To create the Example extra:

1. Download to assets/components/mycomponent/

2. Run
assets/mycomponents/mycomponent/core/components/mycomponent/elements/snippets/bootstrap.php

3. The new extra will be in assets/mycomponents/example/

4. You'll see a bunch of stuff in the Example category in MODX and some new resources (resource1, etc.)

5. You'll see the build files in assets/mycomponents/example/_build

6. What it does is completely controlled by the project config file:
assets/components/mycomponent/_build/utilities/config/example.config.php

7. If you make changes to any of the objects in MODX and run:
assets/mycomponents/mycomponent/core/components/mycomponent/elements/snippets/exportobjects.php, the build files will be updated

8. You can run assets/mycomponents/example/_build/build.transport.php at any point after running bootstrap and it will create a new transport package in core/packages. If you go to Package Manager and select "Search Locally for Packages", you can see it in the grid and install, uninstall, or remove it.

Things are still moving around and those MyComponent paths will be incorrect soon (I think the whole of MyComponent will be moved to the core/components/mycomponent/ directory, where it would normally install).

Bootstrap and exportobjects can be run over and over. Bootstrap is completely non-destructive and won't touch any existing objects or files (but will create new ones if you put them in the project config file).

ExportObjects will rewrite the element files to match what you've done in MODX and also the build files.

build.transport.php can be run at any time to update the transport package in core/packages.

LexiconHelper will create, update, and check your lexicon files, and there are some other utilities as well, but I've probably already told you more than you want to know.

Confession: I have never created a Doodle or even done step one of the Doodles Tutorial.

One last point: Most of what I've learned about building transport packages, I learned here https://github.com/splittingred and I still refer to it all the time.

One more last point: The hardest thing about package building is to get things connected properly. Installing the objects is quite easy once you get the hang of it, but connecting TVs to Templates, Plugins to Plugin Events, Property Sets to Elements, Resources to Templates, Elements to Categories, Actions to Menus, etc. can take a while to get a handle on. The new MyComponent will do all of that for you.



------------------------------------------------------------------------------------------
PLEASE, PLEASE specify the version of MODX you are using.
MODX info for everyone: http://bobsguides.com/modx.html [ed. note: BobRay last edited this post 14 years ago.]

According to the Developing an Extra, they are not run at the same time as each other. All Resolvers are run at the same time (in order) and all Validators are run at the same time (in order). But Validators run before Vehicles are transported. And Resolvers run after Vehicles are transported.

I have verified this, actually, tonight making my second package. (I did a no-no).

In general, they have very similar operations, however. In other words, in every other way, they are pretty much exactly like each other.

Right, but if the validators and/or resolvers are attached to different vehicles, they won't run until that vehicle is installed.

If you put a vehicle->resolve at the beginning of build.transport.php and add in the resources in separate vehicles at the end, then in the resolver, using getObject() to to retrieve one of the resources will fail.

I was going to point you to a package that demonstrates this, but the Bug Tracker seems to be down right now.


------------------------------------------------------------------------------------------
PLEASE, PLEASE specify the version of MODX you are using.
MODX info for everyone: http://bobsguides.com/modx.html