Update of /cvs/scoop/scoop/lib/Scoop/Stories
In directory lithium.sabren.com:/tmp/cvs-serv27024/lib/Scoop/Stories
Modified Files:
Elements.pm
Log Message:
Some perlpod for Stories/Elements.pm - documenting the get_sids params.
-janra
Index: Elements.pm
===================================================================
RCS file: /cvs/scoop/scoop/lib/Scoop/Stories/Elements.pm,v
retrieving revision 1.120
retrieving revision 1.121
diff -C2 -d -r1.120 -r1.121
*** Elements.pm 11 Feb 2005 22:11:05 -0000 1.120
--- Elements.pm 6 Apr 2005 02:50:34 -0000 1.121
***************
*** 3,6 ****
--- 3,12 ----
my $DEBUG = 0;
+ =head1 Elements.pm
+
+ Story functions. Needs documentation...
+
+ =cut
+
sub displaystory {
my $S = shift;
***************
*** 524,527 ****
--- 530,534 ----
=item $S->get_sids($params)
+
=item $S->story_data($sids)
***************
*** 530,549 ****
a bit more.
! The first takes a hashref of options, and does all the permission checking and
! does a select on the stories table (joined with viewed_stories if the hotlisted
! flag is set) and returns an arrayref of story IDs. It requires you to be more
! specific than getstories() did, but because of this it doesn't try to be
! "smart" and prevent you from getting exactly what you want. The values in the
! hashref of options may be strings or arrayrefs; if arrayrefs, SQL IN() will be
! used instead of = so you can filter on multiple values at once.
! The second takes an arrayref of story IDs and checks the cache, falling through
! to the database if necessary and filling the cache, and returns an arrayref
! containing a hashref for each story (as getstories() did) including all fields
! from the stories table, the read comments and hotlist information, and the
! comment counts.
! They will generally be used together, but if you already know the SID(s) you
! want, the second one can be used alone.
=back
--- 537,677 ----
a bit more.
! $S->story_data() takes an arrayref of story IDs and checks the cache, falling
! through to the database if necessary and filling the cache, and returns an
! arrayref containing a hashref for each story (as getstories() did) including
! all fields from the stories table, the read comments and hotlist information,
! and the comment counts.
! $S->get_sids() takes a hashref of options, and does all the permission checking
! and does a select on the stories table (joined with viewed_stories if the
! hotlisted flag is set) and returns an arrayref of story IDs suitable for
! passing directly to $S->story_data(). It requires you to be more specific than
! getstories() did, but because of this it doesn't try to be "smart" and prevent
! you from getting exactly what you want.
! =over 4
!
! =head2 get_sids() parameters
!
! The hash keys listed below are recognized get_sids() options.
!
! Any of the values in the hashref may be strings or arrayrefs; if arrayrefs, SQL
! IN() will be used instead of = so you can filter on multiple values at once.
! Exceptions to this are indicated below. To not filter on any of the possible
! parameters, simply leave them unset.
!
! =item aid
!
! Fetches stories only by the user(s) whose UID(s) are given here. If both aid
! and user are provided, aid is used.
!
! =item user
!
! Fetches stories only by the user(s) whose nickname(s) are given here. If both
! aid and user are provided, aid is used.
!
! =item perm_override
!
! Turns off permission checking for disallowed sections. This is a true/false
! flag only. (True = do not check permissions)
!
! =item section
!
! The particular section(s) and subsections you want to retrieve stories from.
! This also recognizes the pseudo-section __all__ and fetches the appropriate
! sections.
!
! =item hotlisted
!
! When true, only stories that are hotlisted by the current user are fetched.
! This is a true/false flag only.
!
! =item page
!
! Which index page to return. This will generally not be used at the same time as
! limit and offset (below) as it sets them itself using the system defaults for
! maxstories. If offset is also set, page will be ignored. This cannot be an
! arrayref.
!
! =item limit
!
! The maximum number of SIDs to return. If not set, maxstories is used; if set to
! zero, removes the limit and all matching SIDs will be returned. This cannot be
! an arrayref.
!
! =item offset
!
! The number of SIDs to skip before starting to return any. If this is not set,
! the offset is calculated from the page parameter. If the page parameter is not
! set, there is no offset and SIDs are returned starting with the first one that
! matches. This cannot be an arrayref.
!
! =item sid
!
! The particular SID(s) to fetch. This is included so the permissions checking
! can be done if you know the SID already (story_data doesn't check permissions).
!
! =item tid
!
! The topic ID(s) of the stories you want.
!
! =item displaystatus
!
! The display status of the stories you want to display. Note that you must be
! explicit; if you want front page stories, you'd use a value of 0, but if you
! want to display a section page (which includes the stories posted to the front
! page but filed in that section) you would use a value of [0,1] - the arrayref
! containing both displaystatuses you want. The same goes for queued stories:
! [-2,-3] would get you stories in both the voting and edit queues.
!
! =item commentstatus
!
! The numeric comment status (read only = 1, disabled = -1, enabled = 1) of the
! stories.
!
! =item totalvotes
!
! The number of moderation votes this story received in the moderation queue.
! Note that this is an exact comparison, not a greater than/less than comparison.
!
! =item score
!
! The current (or final, for stories not in the queue) moderation score the story
! received. Note that this is an exact comparison, not a greater than/less than
! comparison.
!
! =item attached_poll
!
! The poll ID (qid) of the poll associated with the story.
!
! =item sent_email
!
! The status of the story: 1 = email was sent to the author informing them their
! story was posted or dropped; 0 = email wasn't sent (for a variety of reasons)
!
! =item edit_category
!
! The edit category of the story. This is only useful if your site is using edit
! categories (usually done only with a closed queue). See the Scoop Admin Guide
! for details on edit categories.
!
! =item where
!
! Anything you would like to add to the WHERE clause. Note that this is just
! appended to what's already there, so you should put an ' AND ' at the
! beginning. If the WHERE clause starts with ' AND ', that is removed, so better
! to put it there than leave it off.
!
! =item from
!
! Anything you would like to add to the FROM clause (such as joins to another
! table). This is appended to what's already there with a space inserted between
! the two parts. The stories table is aliased to 's' and (if the hotlisted
! parameter is true) the viewed_stories table is aliased to 'v'.
!
! =back
!
! The two functions will generally be used together, but if you already know the
! SID(s) you want, story_data() can be used alone.
=back
***************
*** 564,568 ****
my ($joined, $where, $from);
my ($disallowed_sections, $subsections, $excl_from_all);
! my @allowed_auto_fields = qw(sid tid aid time writestatus hits section displaystatus commentstatus totalvotes score rating attached_poll sent_email edit_category);
# most story table fields; some excluded because they're more suitable
# for search than get_sids
--- 692,696 ----
my ($joined, $where, $from);
my ($disallowed_sections, $subsections, $excl_from_all);
! my @allowed_auto_fields = qw(sid tid aid section displaystatus commentstatus totalvotes score attached_poll sent_email edit_category);
# most story table fields; some excluded because they're more suitable
# for search than get_sids