.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Jifty 3pm" .TH Net::Jifty 3pm "2011-01-03" "perl v5.12.4" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Jifty \- interface to online Jifty applications .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& use Net::Jifty; \& my $j = Net::Jifty\->new( \& site => \*(Aqhttp://mushroom.mu/\*(Aq, \& cookie_name => \*(AqMUSHROOM_KINGDOM_SID\*(Aq, \& email => \*(Aqgod@mushroom.mu\*(Aq, \& password => \*(Aqmelange\*(Aq, \& ); \& \& # the story begins \& $j\->create(Hero => name => \*(AqMario\*(Aq, job => \*(AqPlumber\*(Aq); \& \& # find the hero whose job is Plumber and change his name to Luigi \& # and color to green \& $j\->update(Hero => job => \*(AqPlumber\*(Aq, \& name => \*(AqLuigi\*(Aq, \& color => \*(AqGreen\*(Aq, \& ); \& \& # win! \& $j\->delete(Enemy => name => \*(AqBowser\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Jifty is a full-stack web framework. It provides an optional \s-1REST\s0 interface for applications. Using this module, you can interact with that \s-1REST\s0 interface to write client-side utilities. .PP You can use this module directly, but you'll be better off subclassing it, such as what we've done for Net::Hiveminder. .PP This module also provides a number of convenient methods for writing short scripts. For example, passing \f(CW\*(C`use_config => 1\*(C'\fR to \f(CW\*(C`new\*(C'\fR will look at the config file for the username and password (or \s-1SID\s0) of the user. If neither is available, it will prompt the user for them. .SH "METHODS" .IX Header "METHODS" .SS "\s-1CRUD\s0 \- create, read, update and delete." .IX Subsection "CRUD - create, read, update and delete." \fIcreate \s-1MODEL\s0, \s-1FIELDS\s0\fR .IX Subsection "create MODEL, FIELDS" .PP Create a new object of type \f(CW\*(C`MODEL\*(C'\fR with the \f(CW\*(C`FIELDS\*(C'\fR set. .PP \fIread \s-1MODEL\s0, \s-1KEY\s0 => \s-1VALUE\s0\fR .IX Subsection "read MODEL, KEY => VALUE" .PP Find some \f(CW\*(C`MODEL\*(C'\fR where \f(CW\*(C`KEY\*(C'\fR is \f(CW\*(C`VALUE\*(C'\fR and return it. .PP \fIupdate \s-1MODEL\s0, \s-1KEY\s0 => \s-1VALUE\s0, \s-1FIELDS\s0\fR .IX Subsection "update MODEL, KEY => VALUE, FIELDS" .PP Find some \f(CW\*(C`MODEL\*(C'\fR where \f(CW\*(C`KEY\*(C'\fR is \f(CW\*(C`VALUE\*(C'\fR and set \f(CW\*(C`FIELDS\*(C'\fR on it. .PP \fIdelete \s-1MODEL\s0, \s-1KEY\s0 => \s-1VALUE\s0\fR .IX Subsection "delete MODEL, KEY => VALUE" .PP Find some \f(CW\*(C`MODEL\*(C'\fR where \f(CW\*(C`KEY\*(C'\fR is \f(CW\*(C`VALUE\*(C'\fR and delete it. .SS "Other actions" .IX Subsection "Other actions" \fIsearch \s-1MODEL\s0, FIELDS[, \s-1OUTCOLUMN\s0]\fR .IX Subsection "search MODEL, FIELDS[, OUTCOLUMN]" .PP Searches for all objects of type \f(CW\*(C`MODEL\*(C'\fR that satisfy \f(CW\*(C`FIELDS\*(C'\fR. The optional \&\f(CW\*(C`OUTCOLUMN\*(C'\fR defines the output column, in case you don't want the entire records. .PP \fIact \s-1ACTION\s0, \s-1ARGS\s0\fR .IX Subsection "act ACTION, ARGS" .PP Perform any \f(CW\*(C`ACTION\*(C'\fR, using \f(CW\*(C`ARGS\*(C'\fR. This does use the \s-1REST\s0 interface. .SS "Arguments of actions" .IX Subsection "Arguments of actions" Arguments are treated as arrays with (name, value) pairs so you can do the following: .PP .Vb 1 \& $jifty\->create(\*(AqModel\*(Aq, x => 1, x => 2, x => 3 ); .Ve .PP Some actions may require file uploads then you can use hash reference as value with content, filename and content_type fields. filename and content_type are optional. content_type by default is 'application/octeat\-stream'. .PP \fIvalidate_action_args action => args\fR .IX Subsection "validate_action_args action => args" .PP Validates the given action, to check to make sure that all mandatory arguments are given and that no unknown arguments are given. .PP Arguments are checked \s-1CRUD\s0 and act methods if 'strict_arguments' is set to true. .PP You may give action as a string, which will be interpreted as the action name; or as an array reference for \s-1CRUD\s0 \- the first element will be the action (create, update, or delete) and the second element will be the model name. .PP This will throw an error or if validation succeeds, will return 1. .SS "Specifications of actions and models" .IX Subsection "Specifications of actions and models" \fIget_action_spec \s-1NAME\s0\fR .IX Subsection "get_action_spec NAME" .PP Returns the action spec (which arguments it takes, and metadata about them). The first request for a particular action will ask the server for the spec. Subsequent requests will return it from the cache. .PP \fIget_model_spec \s-1NAME\s0\fR .IX Subsection "get_model_spec NAME" .PP Returns the model spec (which columns it has). The first request for a particular model will ask the server for the spec. Subsequent requests will return it from the cache. .SS "Subclassing" .IX Subsection "Subclassing" \fI\s-1BUILD\s0\fR .IX Subsection "BUILD" .PP Each Net::Jifty object will do the following upon creation: .IP "Read config" 4 .IX Item "Read config" \&..but only if you \f(CW\*(C`use_config\*(C'\fR is set to true. .IP "Log in" 4 .IX Item "Log in" \&..unless a sid is available, in which case we're already logged in. .PP \fIlogin\fR .IX Subsection "login" .PP This method is called automatically when each Net::Jifty object is constructed (unless a session \s-1ID\s0 is passed in). .PP This assumes your site is using Jifty::Plugin::Authentication::Password. If that's not the case, override this in your subclass. .PP \fIprompt_login_info\fR .IX Subsection "prompt_login_info" .PP This will ask the user for her email and password. It may do so repeatedly until login is successful. .PP \fIcall \s-1ACTION\s0, \s-1ARGS\s0\fR .IX Subsection "call ACTION, ARGS" .PP This uses the Jifty \*(L"web services\*(R" \s-1API\s0 to perform \f(CW\*(C`ACTION\*(C'\fR. This is \fInot\fR the \&\s-1REST\s0 interface, though it resembles it to some degree. .PP This module currently only uses this to log in. .SS "Requests helpers" .IX Subsection "Requests helpers" \fIpost \s-1URL\s0, \s-1ARGS\s0\fR .IX Subsection "post URL, ARGS" .PP This will post \f(CW\*(C`ARGS\*(C'\fR to \f(CW\*(C`URL\*(C'\fR. See the documentation for \f(CW\*(C`method\*(C'\fR about the format of \f(CW\*(C`URL\*(C'\fR. .PP \fIget \s-1URL\s0, \s-1ARGS\s0\fR .IX Subsection "get URL, ARGS" .PP This will get the specified \f(CW\*(C`URL\*(C'\fR with \f(CW\*(C`ARGS\*(C'\fR as query parameters. See the documentation for \f(CW\*(C`method\*(C'\fR about the format of \f(CW\*(C`URL\*(C'\fR. .PP \fImethod \s-1METHOD\s0, URL[, \s-1ARGS\s0]\fR .IX Subsection "method METHOD, URL[, ARGS]" .PP This will perform a \f(CW\*(C`METHOD\*(C'\fR (\s-1GET\s0, \s-1POST\s0, \s-1PUT\s0, \s-1DELETE\s0, etc) using the internal LWP::UserAgent object. .PP \&\f(CW\*(C`URL\*(C'\fR may be a string or an array reference (which will have its parts properly escaped and joined with \f(CW\*(C`/\*(C'\fR). \f(CW\*(C`URL\*(C'\fR already has \&\f(CW\*(C`http://your.site/=/\*(C'\fR prepended to it, and \f(CW\*(C`.yml\*(C'\fR appended to it, so you only need to pass something like \f(CW\*(C`model/YourApp.Model.Foo/name\*(C'\fR, or \&\f(CW\*(C`[qw/model YourApp.Model.Foo name]\*(C'\fR. .PP This will return the data structure returned by the Jifty application, or throw an error. .PP \fIform_url_encoded_args \s-1ARGS\s0\fR .IX Subsection "form_url_encoded_args ARGS" .PP This will take an array containing (name, value) argument pairs and convert those arguments into \s-1URL\s0 encoded form. I.e., (x => 1, y => 2, z => 3) becomes: .PP .Vb 1 \& x=1&y=2&z=3 .Ve .PP These are then ready to be appened to the \s-1URL\s0 on a \s-1GET\s0 or placed into the content of a \s-1PUT\s0. However this method can not handle file uploads as they must be sent using 'multipart/form\-date'. .PP See also /\*(L"form_form_data_args \s-1ARGS\s0\*(R" and \&\*(L"Arguments of actions\*(R". .PP \fIform_form_data_args \s-1ARGS\s0\fR .IX Subsection "form_form_data_args ARGS" .PP This will take an array containing (name, value) argument pairs and convert those arguments into HTTP::Message objects ready for adding to a 'mulitpart/form\-data' HTTP::Request as parts with something like: .PP .Vb 3 \& my $req = HTTP::Request\->new( POST => $uri ); \& $req\->header(\*(AqContent\-type\*(Aq => \*(Aqmultipart/form\-data\*(Aq); \& $req\->add_part( $_ ) foreach $self\->form_form_data_args( @args ); .Ve .PP This method can handle file uploads, read more in \*(L"Arguments of actions\*(R". .PP See also /\*(L"form_form_data_args \s-1ARGS\s0\*(R" and \&\*(L"Arguments of actions\*(R". .PP \fIjoin_url \s-1FRAGMENTS\s0\fR .IX Subsection "join_url FRAGMENTS" .PP Encodes \f(CW\*(C`FRAGMENTS\*(C'\fR and joins them with \f(CW\*(C`/\*(C'\fR. .PP \fIescape \s-1STRINGS\s0\fR .IX Subsection "escape STRINGS" .PP Returns \f(CW\*(C`STRINGS\*(C'\fR, properly URI-escaped. .SS "Various helpers" .IX Subsection "Various helpers" \fIemail_eq \s-1EMAIL\s0, \s-1EMAIL\s0\fR .IX Subsection "email_eq EMAIL, EMAIL" .PP Compares the two email addresses. Returns true if they're equal, false if they're not. .PP \fIis_me \s-1EMAIL\s0\fR .IX Subsection "is_me EMAIL" .PP Returns true if \f(CW\*(C`EMAIL\*(C'\fR looks like it is the same as the current user's. .PP \fIemail_of \s-1ID\s0\fR .IX Subsection "email_of ID" .PP Retrieve user \f(CW\*(C`ID\*(C'\fR's email address. .PP \fIload_date \s-1DATE\s0\fR .IX Subsection "load_date DATE" .PP Loads \f(CW\*(C`DATE\*(C'\fR (which must be of the form \f(CW\*(C`YYYY\-MM\-DD\*(C'\fR) into a DateTime object. .PP \fIget_sid\fR .IX Subsection "get_sid" .PP Retrieves the sid from the LWP::UserAgent object. .SS "Working with config" .IX Subsection "Working with config" \fIload_config\fR .IX Subsection "load_config" .PP This will return a hash reference of the user's preferences. Because this method is designed for use in small standalone scripts, it has a few peculiarities. .IP "\(bu" 4 It will \f(CW\*(C`warn\*(C'\fR if the permissions are too liberal on the config file, and fix them. .IP "\(bu" 4 It will prompt the user for an email and password if necessary. Given the email and password, it will attempt to log in using them. If that fails, then it will try again. .IP "\(bu" 4 Upon successful login, it will write a new config consisting of the options already in the config plus session \s-1ID\s0, email, and password. .PP \fIconfig_permissions\fR .IX Subsection "config_permissions" .PP This will warn about (and fix) config files being readable by group or others. .PP \fIread_config_file\fR .IX Subsection "read_config_file" .PP This transforms the config file into a hashref. It also does any postprocessing needed, such as transforming localhost to 127.0.0.1 (due to an obscure bug, probably in HTTP::Cookies). .PP The config file is a \s-1YAML\s0 document that looks like: .PP .Vb 4 \& \-\-\- \& email: you@example.com \& password: drowssap \& sid: 11111111111111111111111111111111 .Ve .PP \fIwrite_config_file\fR .IX Subsection "write_config_file" .PP This will write the config to disk. This is usually only done when a sid is discovered, but may happen any time. .PP \fIfilter_config [\s-1DIRECTORY\s0] \-> \s-1HASH\s0\fR .IX Subsection "filter_config [DIRECTORY] -> HASH" .PP Looks at the (given or) current directory, and all parent directories, for files named \f(CW\*(C`$self\->filter_file\*(C'\fR. Each file is \s-1YAML\s0. The contents of the files will be merged (such that child settings override parent settings), and the merged hash will be returned. .PP What this is used for is up to the application or subclasses. Net::Jifty doesn't look at this at all, but it may in the future (such as for email and password). .SH "SEE ALSO" .IX Header "SEE ALSO" Jifty, Net::Hiveminder .SH "AUTHORS" .IX Header "AUTHORS" Shawn M Moore, \f(CW\*(C`\*(C'\fR .PP Ruslan Zakirov, \f(CW\*(C`\*(C'\fR .PP Jesse Vincent, \f(CW\*(C`\*(C'\fR .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Andrew Sterling Hanenkamp, \f(CW\*(C`\*(C'\fR, .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-net\-jifty at rt.cpan.org\*(C'\fR, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net\-Jifty . .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2007\-2009 Best Practical Solutions. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.