Actions & Triggers integration
| Project: | User Referral |
| Version: | 6.x-1.x-dev |
| Component: | Code |
| Category: | support request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
Hi,
I'd like to integrate referral with Drupal's core Actions and Triggers modules. If the changes are welcome, I'll contribute a patch that will:
1) Create an Action that calls referral_admin_flag(). The "flag" feature in referral is pretty generic and can fit into an app's business rules in numerous ways. Allowing the flag to be set by a Drupal Action opens several possibilities. The patch would add a "hook_action_info()" function and move the db_query part of referral_admin_flag() into it's own function (away from the drupal_set_message and drupal_goto).
2) Create a hook that allows other modules to take action when a referral sign-up occurs and tell Triggers about the hook. _referral_user_save() will be modified to call module_invoke_all('referral',...). I'll also implement hook_hook_info() to tell Triggers about this hook new.
Thanks
Ryan
#1
#2 I agree with. Let us do it.
For #1, I get the drift of it, but it would help if you list one or two actual use cases to help me visualize it more.
#2
Sure,
a) A drupal admin uses the 'flag' field to keep track of which referrals are eligible for a payment or reward. A referral only becomes eligible after some event occurs (the user has reached a certain status, paid for a membership, completed a survey, etc). The occurrence of this event would trigger the "flag referral" action.
b) A module allows a company to transfer money to users for their referrals that they generate. This fictional module exposes an Event called "User has been paid". Drupal admin can wire the "User has been paid" trigger to the "Flag referral" action. Saves him the trouble of having to manually find that referral and flag it.
If exposing flags to actions doesn't feel right, I'll leave it out - no biggie. There are other ways to skin this cat.
#3
Sounds like useful use cases.
But does that mean the flag field can have values other than 1 and 0? Or does 1 mean different things in different sites?
If so, then those meaning will be up to the site and/or modules that update it. I am fine with that, provided that we have a way to tell what each one means. Not sure if another table with value, description would be overkill or what.
#4
I've been mulling this over for a couple of hours. Both of the use-cases I came up with would require custom modules. I think it's wrong to try and shoehorn their tracking requirements into referral's "flag" field. The data would become cumbersome to maintain. If a module needs to present a report about "eligible referrals", it would be cleaner if it simply joined it's data with user referral data.
Referral's 'flag' feature is simple and serves a purpose. I don't think it needs to be complicated. I'm going to forgo creating an Action for it.
I think the hook & trigger invocation is still useful. I've attached a patch that adds the hook (module_invoke_all()).
As for exposing the hook as a trigger, I left it out and pasted the 2 additional functions required below. I've tested them, they work, and they can go anywhere in referral.module. I didn't include it in the patch because of an minor issue with trigger.module I'd like to see some feedback on :-/ http://drupal.org/node/338774 ... triggers is starting to look like uncharted territory ...
<?php
/*
* Implementation of hook_hook_info()
*/
function referral_hook_info() {
return array(
'referral' => array(
'referral' => array(
'new' => array(
'runs when' => t('After a user\'s referral has resulted in a new account creation'),
),
),
),
);
}
/*
* Implemenation of hook_referral()
*/
function referral_referral($new_uid, $referrer_uid) {
if(module_exists('trigger')) {
$aids = _trigger_get_hook_aids('referral');
$context = array(
'hook' => 'referral',
'op' => '',
'new_uid' => $new_uid,
'referrer_uid' => $referrer_uid
);
// act on referrer user object.
$object = user_load($referrer_uid);
actions_do(array_keys($aids), $object, $context);
}
}
?>
#5
Using a field of a module is not wrong in and of itself. It just has to be done clearly and cleanly via APIs. An example for this is the signup module. Around it there are modules using its API to extend it in many ways (e.g. Signup Status, Signup Pay for a node, Signup reports, ...etc).
So, I am not against the idea, just want it to be done cleanly and clearly.
Anyway, regarding the hook_referral() patch, I like it and I committed it. I also took out all the userpoints conditional code and created a new module from that using the new hook! Really neat! Thanks.
#6
The Triggers bug I referred to won't get attention until d7. The bug is more just a coding style thing, cuz it has to call a function that's prefixed with an underscore (a "private" function: _trigger_get_hook_aids())
This code is safe to include in referral.module, and won't impact anything if Triggers is not enabled.
#7
Attached is a module that exposes hook_referral to the triggers interface. It's really not that useful unless you have Actions on your system that will work for "any" type of hook, or specifically to the referral hook. The default "Send email" action in D6 is locked down to certain hooks like hook_user and hook_comment.
If you want the referral trigger to use the actions that are locked to hook_user, then the referral module would need to create a new $op for hook_user (like $op=='referral'). It would do this instead of creating it's own hook (hook_referral).
So the attached files are only useful if you're capable of writing actions, or are otherwise using actions that are available to any hook.
#8
OK, I will include it.
But can you summarize what you said to something that I can put in a README.txt for that new module?
This will avoid frequent questions from users.
#9
We need to give some more consideration to replacing hook_referral with hook_user & op = referral. Doing so would make the triggers usable with existing core actions. I'll check it out when I can clear up a little bit of time.
Cheers
#10
This is how it would be done:
<?phpif (db_affected_rows()) {
$account = user_load(array('uid' => $cookie['uid']));
$referred_user = array('#uid' => $uid);
module_invoke_all('user', 'referral', $referred_user, $account);
}
?>
Anything else?
While I like this from a purely technical point of view, I feel it is hackish in nature. It will not be in the documentation for hook_user for one.
Also, in Drupal 7, there is no longer a hook_user, rather
hook_user_delete(),hook_user_view(), ...etc. Not that this will stop it from working. We can douser_module_invoke('referral', ...)still.So, as an experiment, I committed the above code and modified the referral_userpoints accordingly.
They should be in the tarball in an hour or so.
Testing appreciated ...
#11
I got a few "Newbie" questions:
1) How can I use those patches/module in order to:
A. Send greeting email to a user who referred someone (I understand how to send this kind of email to the reffered user but not to the user who reffered the new user)
(by "how can I use" I mean - step-by-step "tutorial" for those without coding skills...)
2) Currently, I don't understand how to "lift" one flag at a time (for example - user A and B registered through user C. now - only user A paid. so, I want to give user C information about who paid/didn't pay..) Do this make any sense?
3) Maybe we can create a video tutorials on how to use this module and the other options. (I don't mind making it and host it, as long as I will finally understand all the feature regarding this/integrated modules)
one more thing - I must say that all of those people that contribute and help each other are GREAT, thank you.
#12
I got the idea to use a new $op from the Pro Drupal Dev book, where the author does something similar to make a nodeapi action for $op = 'archive'. Unfortunately, it turns out that the "Send email" action in system.module is not just restricting itself to hook_user, but also to certain ops.
Fortunately, however, I discovered hook_action_info_alter(). Since I was forced to use this, it's probably best to revert your change so that the hook is again hook_referral() - sorry 'bout that. The attached re-roll of referral_triggers.module is written to hook_referral.
For README:
Referral will invoke a Drupal Trigger after a referral generates a signup. Visit 'admin/build/trigger/referral' to assign an action to the trigger. The only core Drupal action that is available to the trigger is "Send e-mail" action. Note that you must first configure an Action before you can assign it to a Trigger.
@kbahey, the Action/Triggers api feels incomplete & restrictive in D6. For example, the "Send email" action *expects* to be called only with user or node objects - I just kind of "massaged" the referral trigger to make it think it's actually working with a node object. If you decide that it's just not worth supporting this code going forward, then just don't publish it. I wrote "Experimental" in the module's .info description.
On a side node, the Rules module would probably be a lot more flexible - but that's a topic for another day :-)
#13
If it was me, I would not have used triggers/rules at all, and just coded a custom mail action.
But anyway, I reverted the code back to hook_referral(), and committed the new module.
Let us see if that works for those who need it.
#14
Hi.
Is it possible to send email to the user who reffered the new register user? (Currently, I understand how to automaticly send email to the NEW user, but I don't know how to automaticly send gretting email to the user who actually reffered the new user).
#15
That's the way this works. It sends an email to the referrer.
#16
How?
I made a new action: send email, and I have an option to either type an email address OR use %author..
I tried both of the methods with no luck.
#17
Using %author should send the email to the referring user, not the new referred user. Can you please double-check the email addresses you are using for your tests, and detail exactly how you have set this up? I'm unable to duplicate the problem.
Thanks
#18
You are right,
That works with %author
Thanks
#19
Can this be used also in drupal 5?
#20
#21
Don't change stuff to critical when nothing is broken.
Porting can happen if someone needs it and submits a patch or someone funds it.
#22
no, sorry. BTW - this is hardly critical...
#23
please don't change the version of the issue in the tracker - it will confuse people who are interested in the development. Open a new ticket if you have an issue with another version.
#24
sorry about that. won't do that again.
#25
Automatically closed -- issue fixed for two weeks with no activity.