Symphony.

A new Extension, “EventEx” is now available for download. Comments and feedback can be left here but if you discover any issues, please post it on the issue tracker.

Typically Symphony Events have been restricted to creating and modifying entries in a single section, a conceptual limitation that, amongst other minor things, stunts the creation of complex, single-page forms. EventEx (named rather dissapointingly for its position in the programmatic hierarchy: EXtending the Event class) aims to provide more power and flexibility to user input, especially in conjunction with other utilities, especially Form Controls. One of the objectives of the system is to empower front-end developers by creating an HTML-compliant, semantic markup that harnesses as much of Symphony’s power as possible; another, arguably more pressing, influence is the tediousness of creating and interpreting complex forms without having to write large chunks of messy custom code.

EventEx specifics can get confusing, so it’s best to start with an example. Imagine a Symphony build, perhaps not so different from the one you are currently working on, which has will allow users to login and contribute to the site content. There are two kinds of users: Musicians, who can upload media files as well as comment on uploaded media files, and Fans, who can comment on media files but not upload them. It’s no so difficult to believe that you might have built a login system that identifies users, but further imagine that there are significant data storage requirements for Musicians and Fans, so they’ll require separate Symphony sections; also, for whatever reason you care to invent, the login system is most efficient when it uses a single section to lookup data, meaning that you either have to replicate the email address, password and other related fields (like a cookie token or preferences) in both sections or, more efficiently, create three sections: Users, Musicians and Fans.

Peachy, except that your user registration form has hit a glass ceiling - information is now spread beyond the scope of the fields[] array. EventEx introduces a slight syntactical change (it should be noted that EventEx does not modify existing Events) in the form markup. Where before you might have used a markup like:

<form action="" method="post">
  username: <input type="text" name="fields[name]" />
  password: <input type="text" name="fields[password]" />

  <input type="submit" name="action[create-musician]">
</form>

EventEx uses a more symbolic approach, referring to the section handle in the form control:

<form action="" method="post">
  username: <input type="text" name="musicians[name]" />
  password: <input type="text" name="users[password]" />

  <input type="submit" name="action[create-musician]">
</form>

Of course, both examples assume that both the Musicians and Users have only one required field (there’s also an issue of security, which is covered in the full documentation README.) The EventEx form above will create a new entry in each section with the details provided, which is nice but rather useless - how are the two sections going to be linked together? The most common approach is the Select Box Link field (now part of the Symphony core) which will in this case be called ‘Musician Entry’ and attached the to Users section, under the assumption that the login functionality will use it to find the associated Musician or Fan entry. A single line of markup will suffice:

<input type="hidden" name="users[musician-entry]" value="musicians[system:id]" />

When a new entry is created, the system ID is logged, and can be used to auto-populate other field values (in EventEx, ‘system:id’ is a reserved dynamic field name.) The value can actually contain any combination of string and section-handle[field-handle]s, so, imagining there’s a field called ‘Password reminder’ the the Musicians section, this would be perfectly valid and do what you’d imagine:

<form action="" method="post">
  username: <input type="text" name="musicians[name]" />
  password: <input type="text" name="users[password]" />

  <input type="hidden" name="musicians[password-reminder]" value="Your password is users[password]" />

  <input type="hidden" name="users[musician-entry]" value="musicians[system:id]" />

  <input type="submit" name="action[create-musician]">
</form>

Note that the order of the field is irrelevant from a processing perspective; there’s a two-pass system in place to ensure that order-of-approach is a trivial issue. There’s significantly more to the EventEx engine, but the only other thing that’s used ubiquitously is the redirection override. Where in regular events one might use:

<input type="hidden" name="redirect" value="/path/to/url" />

We can now use parse-redirect in a similar way, except taking into account the string parsing system noted above, it becomes more interesting:

<input type="hidden" name="parse-redirect" value="/members/musicians[name]/" />

In the case of redirects, all values are transformed into URL-friendly handles in the usual Symphony way. There are several other issues that EventEx squeals though like heated buzzsaw.

Do it to it

If your boredom threshold is high enough, your time is so worthless as to allow you freedom of actually reading the tedious text above, and you think the extension might distract you for a new precious moments between Meth hits, the GitHub URL is:

http://github.com/yourheropaul/eventex/tree/master

I read it all!

Best README ever.

Best README ever.

Agreed. For the most detailed extension documentation I have yet to come across, it was at times quite entertaining. Paul, you are my hero.

Imagine a Symphony build, perhaps not so different from the one you are currently working on, which has will allow users to login and contribute to the site content.

For this imaginary situation, would you be using a custom members registration system for musicians and fans? The yet to be released Members extension requires the latest integration branch, but this comes with the associated cost of incompatible extensions. Just wondering what your solution has been.

I’d love to put your example to good use, but wondering where to start. I have a couple scenarios I am currently working on:

A web agency

• Staff
• Partners
• Clients

A non-profit intranet

• Staff
• Volunteers
• Public

We’ve built our own user management system in this way. Each role type is a different section, and one central Users section to store the profile information (email/password). EventEx was required for the registration form whereby an entry needs to be created in both role and profile sections.

I’d personally hold out for the Members extension, I imagine it will be more full featured. Our use of EventEx to build a members system is mostly just to conquer the registration issue. All other logic (sending emails, logging in, logging out) has been custom-written.

Another recent use I found was for updating a moderation queue. Page content sits in a Content section, and each revision adds an item into a Moderation Queue section. When approved, both the Content and Moderation Queue entries need updating (setting dates, statuses etc.). EventEx provides functionality to do this through a single form/event.

Other uses:

• submitting a blog post but uploading multiple files at the same time (when each file is an entry in a related section)
• using just a single section, but using the more powerful redirect
• any situation where you need to save to more than one section!

Hallo and thank you. good victory!! I’m musician!

Looks very interesting, if I find the time I think this could be really usefull to create a memberinfo (modular like vanilla forum or pommo massmailer) database for newsletter (mass)emailing. such as been talked about OT in this markdown topic

I’m musician!

Rock on ;-)

@newnomad: Please DO NOT TALK SO LOUD about my newsletter extension plans! :-)

This is still work in progress and, as Nick Dunn said, the Members extension (which will probably released by the core team in the near future) might be very interesting as well. So I put the whole member part on hold while I am working on the mailing stuff and a seamless integration of my extension into Symphony. I am still very much engaged in client work, so even this part will probably take 3 or 4 weeks from now. I hoped to find the Members extension “ready to go” at that time.

Will it help to see the rough version of the Members extension? I’ll send it to you if this will help with the integration.

Probably yes! Please send it to the email address which you find here: http://www.michael-eichelsdoerfer.de/kontakt/. Thanks a lot!

I’d be happy to post this for everyone to play around with, but I don’t know if that’s my call to make. I’m sure the dev team wants to make sure it’s stable before releasing. Plus, it requires the latest integration branch, so it’s probably awaiting the next official release.

As I’m anxious to see what you come up with, I’ll just send it to you. For that matter, though, I’m sure Nick and Paul would want to take a look as well.

Check your inbox.

Ok, I get an error when I install this Extension.

Fatal error: Class 'extension_eventex' not found in   /nfs/c02/h03/mnt/29224/domains/nicktoye.co.uk/html/symphony/lib/toolkit/class.extensionmanager.php on line 245

I have installed all the other dependent extensions.

Anyone else got this error?

Great work, Paul. I’ve been looking forward to checking this out for a while. Is it just me or are the extension.driver.php files for EventEx and the Database Manipulator the wrong way around?

Is it just me or are the extension.driver.php files for EventEx and the Database Manipulator the wrong way around?

Yes, they were - how disturbing. They’re fixed now, not that it actually matters if they can be installed or not seeing as they’re just utility files, but it would cause my documentation to be inaccurate, and I certainly can’t go changing that now can I?

Any idea why I am getting a Fatal error?

Did the latest update of the extension.driver.php files fix this for you? Both EventEx and Database Manipulator.

Yes seems to be working now. Cheers.

Can EventEx be used to populate section but also emailing the details of the filled in form to admin?

As the markup is a little different I wondered if it had any effect on the resulting submitted data to use for an email template?