Document query fragments
litwol - July 1, 2009 - 22:32
| Project: | Privatemsg |
| Version: | 6.x-1.x-dev |
| Component: | Documentation |
| Category: | task |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed |
Description
Our query layer is very flexible and offers many possibilities. That flexibility comes at the price of having all query pieces together so it is easier to understand.
For that reason i think we need to document every single piece of query building fragments. We should be very thorough and mention not only what kind of data it adds, what kind of impact it has on the bigger picture but also mention any gotchas that we have learned while using it.
Marking this as normal priority for *now*. This is certainly a high priority towards 1.0 release and especially for d7 branch when we hve to rewrite all the queries using DBTNG.
#1
First version, please review.
I tried to add anything special I could remember abour our queries.
#2
<?php+ // MIN() does not have a useful meaning except that it helps to correctly
+ // aggregate the thread on PostgreSQL.
$fragments['select'][] = 'MIN(pm.subject) as subject';
?>
Except it sort of does - in privatemsg 5.x, each message could have a separate subject, and technically this can also be achieved in privatemsg 6.x too. a common prefix for replies is "Re: ". since R is more than half way through the alphabet, MIN works correctly a majority of the time to get the "correct" thread subject.
<?php+ // Select number of messages in the thread if enabled.
?>
"Select number of messages in the thread if the count is set to be displayed." ?
<?php+ // Only count new *and* undeleted messages of that user.
?>
"Only count new messages that have not been deleted" ?
<?php+ * @param $names
+ * Which names are already part of the existing search string and should be excluded.
?>
I don't think we should list the rationale here for why they are excluded - others may wish to use the query for other reasons? so simple "A list of names to be excluded from the matches" or something like that may be better.
<?php+ // The lowest value is higher than 0 if all recipients have deleted a message·
?>
mistaken character at the end?
#3
Yeah, except I do not count "most of the time, it does what we expect" as a useful meaning :) And that is only true for english. For example, the german tranlation of "RE:" is "AW:". And A is pretty much the first character we have :)
Yep, makes sense. I've seen you are already doing that in the filter_autocomplete query but I forgot to change this.
#4
Updated, I also forgot to add the changes in privatemsg_filter.module.
#5
Documentation looks good.
#6
Commited to 6.x-1.x-dev. There are so many changes in that area in D7 that it does not make much sense to port this to D7, so setting to fixed.
#7
Automatically closed -- issue fixed for 2 weeks with no activity.