NAME

RapidApp::DirectLink::Link

SYNOPSIS

  # generating a link for the user
  my $linkParams= {
    auth => { user => 5, acl => $aclForResource, },
    targetUrl => 'approot/externalUserRecap',
    stash_params => {foo=>1, bar=>2},
    sess_params => {SpecialSetting => 'blah blah'},
  };
  
  my $link= RapidApp::DirectLink::Link->new($linkParams);
  $self->c->model('DB')->createDirectLink($link);
  - or -
  my $link= $self->c->model('DB')->createDirectLink($linkParams);
  print $self->c->namespace."/DirectLink?id=".$link->linkUid;
  
  # storing a link to the database
  $self->c->model("DB::direct_link")->create({
    createDate => $link->creationDate,
    randomHash => $link->randomHash,
    params => $link->params,
  });
  
  # retrieving a link from the database
  my $uid= $self->c->request->params->{id};
  my $link= RapidApp::DirectLink::Link->new(linkUid => $uid); # parse the id string into a date and hash
  my $row= $self->c->model("DB::direct_link")->find( # get the other parameters from the database
    createDate => $link->createDate,
    randomHash => $link->randomhash
  );
  $link->contactId($row->contact_id); # set the contact_id
  $link->paramsJson($row->params);    # populate the rest of the params by applying a string of JSON

ATTRIBUTES

createDate

The date the DirectLink was created. This becomes part of the external ID string, increasing the complexity of the id to be 36^8 per calendar day. It is separated out into its own field, but part of the primary key to permit sorting the DirectLink rows by date without needing a second index on this fast-growing frequently-written table.

randomHash

The hash is simply a random number that uniquely (when combined with createDate) identifies this record. The hash is an ascii string legal for URLs, and currently 8 characters long (generated by LinkFactory, see that module for details)

auth

Auth is a hash of credentials or permissions which are granted to anyone posessing the linkUid. Typical keys for this object are a username or ID, and some sort of permissions list, or allowed roles.

These details are used by DirectLink::SessionLoader, and can be overrridden to handle whatever behavior or security the local application requires.

targetUrl

The targetUrl is the module path to which the user will be directed when they log in using this link. See DirectLink::SessionLoader

requestParams

req_params is the set of parameters which will be passed in the first request to the the module specified in targetUrl. This can be any hash of strings valid for an HTTP request. **HOWEVER**, be sure to keep this hash **SMALL** in order to reduce the space needed by DirectLink table records. If you need lots of parameters, try just putting the keys here and pulling the rest from appropriate tables when the user logs in.

req_params is mainly intended for reusing an already-written module. If you write a custom module to handle a DirectLink, consider stash_params instead.

session

sess_params is the set of parameters which will be put into the user's session when they follow this link. As usual, try to avoid using the session when the request will suffice. However, always put security-sensitive values here (i.e. anything you don't want the user to be able to alter).

stash

stash_params is the set of temporary initial parameters which will be put into the "stash", where either a controller or view or Module will make use of them to build the initial UI for the user. Note that if you use the "redirectToLink" method in your controller, you will be unable to make use of the stash, as it will vaporize before the next request. (You could, however, save the stash in the session until the next request, but that gets hachish)

The intended use case is User: request with id=2lkj3h5423ljh4 => controller/DirectLink DirectLink.pm: create user session, or append to existing DirectLink.pm: convert id to stash_params DirectLink.pm: pass to TopController->Controller(targetUrl) Some/Module.pm: use stash params to build UI.

linkUid

See METHODS

params

See METHODS

METHODS

linkUid

Calling linkUid with no parameters joins together createDate and randomHash into a UID to be used in DirectLink urls.

Calling this method with a string parameter will parse the string into those two fields, or die trying.

linkUrl

Returns handlerUrl with a id parameter of linkUid

dateFromLinkUid

This is a package-method (can also be an instance method) which returns a DateTime object representing the encoded date portion of a UID.

params

Calling params with no parameters will build and return a hash appropriate for serializing into the database.

Passing a hash to this function will overwrite any attributes which are part of 'params' (even clearing attributes which aren't set in the hash).

paramsJson

This function is a convenience method to get or set params as a JSON string.

SEE ALSO

RapidApp::DirectLink::LinkFactory

RapidApp::DirectLink::Redirector