API Docs for:
Show:

Hop.Method Class

Defined in: lib/api.js:696
Module: Hop

Class used to define methods

Constructor

Hop.Method

()

Defined in lib/api.js:696

Methods

addPostCall

(
  • call
  • phase
)
chainable

Defined in lib/api.js:1064

Add a function that will be called after this call is completed

Parameters:

  • call Function

    function to be called when this call is completed, which is passed the following parameters:

    • request Object

      the ExpressJS / HTTP request object

    • input Object

      the input parameters to the call

    • err

      the resulting err from the call

    • result Object
      • the result of the call
    • next Function
      • to be called when the callback is completed, causing the next call back to be called
  • phase String

    the phase in which this function will be called (see below)

    Phases

    1. (Pre call phases)
2. **CALL**     
3. first - called before any other phases
4. data - data processing and conversion
5. event - event emission
6. cache - cache phase 
7. last - called last

Example:

api.get("load","/user/:userID").addPostCall(function(req,input,err,result,next){
    //Let's caclulate the users age:
    if(result && result.birthdate){
        result.age = User.calculateAge(result.birthdate);
    }   
    next();
},"data");

addPreCall

(
  • call
  • phase
)
chainable

Defined in lib/api.js:1118

Add a function that will be called before this call is executed

Parameters:

  • call Function

    function to be called prior to when this call is executed , which is passed the following parameters:

    • request Object

      the ExpressJS / HTTP request object

    • input Object

      the input parameters to the call

    • onComplete Function

      to be called if the function wants to short circuit and return a result

    • next Function

      to be called when the callback is completed, causing the next call back to be called

  • phase String

    the phase in which this function will be called (see below)

    Phases

    1. first - called first
2. demand - verifies that the required parameters are in place 
3. conversion - will convert the input types to the expected types
4. validation - input validation 
5. auth - authentication phase
6. event - event emission
7. cache - cache phase 
8. last - the last set of calls to be called prior to the function call
9. **CALL**     
10. (post calls)

Example:

api.get("load","/user/:userID").addPreCall(function(req,input,err,onComplete,next){
    //If we have a user allow this call to complete
    if(req && req.session && req.session.user){
        next();
    //If not return an error 
    } else {
        return onComplete("Permission denied");
    }
},"auth");

authed

() chainable

Defined in lib/api.js:884

Note that this method can only be called when there is a user in the session

This will only allow this method to be called if req.session.user exists

Example:

Hop.defineClass("UserService",UserService,function(api){
    //Only allow this method to be called if a user is in the session
    api.post("sendMsg","/user/:userId/message").authed();
});

cache

(
  • cacheFunc
)
chainable

Provided by the Cache module.

Defined in lib/cache.js:67

Specifies a cache lambda for this call.

This funciton is used to specify a cache lambda which will determine how the result is cached.

Parameters:

  • cacheFunc Function
    • when Function

      Used to indicate when this cache function was evaluated, valid values are "before" and "after"

    • cache Function

      The cache object, which is used to return an action

      • id Function
        return the result of this function to specify the result should be cached
      • id.id String
        The cache id
      • id.duration Number
        The duration in seconds to cache the result for
      • invalidate Function
        return the result of this function to specify the result should be invalidated
      • invalidate.id String
        The cache id
    • req Object

      the Express/HTTP request object

    • input Object

      the input parameters for the call

    • error Object

      the error as a result of calling this function (only valid after the call)

    • result Object

      the result of this function (only valid after the call)

Example:

Hop.defineClass("Comment",new Comment(),function(api){
    //This will cause the list to always attempt to hit the cache
    api.get("list","/comment").cacheId("/comment/list/:start/:size").demand("start").demand("size").defaults({start:0, size:25});
    api.del("delete","/comment/:commentId").cacheInvalidate("/comment/:commentId").demand("commentId");
    api.get("load","/comment/:commentId").cache(function(when,cache,req,input,err,result){
        if(Hop.hasUser(req)){
            var userId = Hop.User.id(req);
            //If we have a user, and that user is the one who posted the comment don't show a cached copy
            if(userId == input.userId){
                return false;
            }
        } else return cache.id("/comment/:commentId",60*5);
    }).demand("commentId");
    api.post("update","/comment/:commentId").cacheInvalidate("/comment/:commentId").demand("commentId");
});

cacheId

(
  • cacheId
  • duration
  • attempt
)
chainable

Provided by the Cache module.

Defined in lib/cache.js:36

Specifies a cache Id to use for storing the result of this call.

This funciton is used to specify a cache id for the result causing the result to be associated with the id.

The specified cache ID will attempt to substitude variables in the id with those from the input, or from the user.

Parameters:

  • cacheId String

    the id for the cached item

  • duration Number

    that the number of seconds result will be cached for

  • attempt Force

    to force the client side to cache the result for the specified duration, this will essentially mean the client side will not request the item again until expiration

cacheInvalidate

(
  • cacheId
)
chainable

Provided by the Cache module.

Defined in lib/cache.js:10

Specifies a cache Id to invalidate.

This function is used to delete an item from the cache, so for example on an HTTP DEL command it may be desirable to delete an associated cache object.

The specified cache ID will attempt to substitude variables in the id with those from the input, or from the user.

Parameters:

  • cacheId String

    the id for the cached item

defaultValues

(
  • defaults
)
chainable

Defined in lib/api.js:803

Specify the default values for this call

These values will be copied into the input if no existing value is found.

Parameters:

  • defaults Object

demand

(
  • name
  • desc
)
chainable

Defined in lib/api.js:852

Demand a parameter for a call

Parameters:

  • name String

    of parameter

  • desc String

    description of parameter

Example:

api.post("create","/user/profile/").demand("email","Email address");

demandFile

() chainable

Defined in lib/api.js:1034

Demand a file be provided for this method.

Example:

api.post("create","/user/profile/").demandFile("avatar","Users avatar image");

demands

(
  • name
)
chainable

Defined in lib/api.js:834

Specify a number of demands for for a call

Parameters:

  • name String

    name of parameter (+)

Example:

api.post("create","/user/profile/").demands("email","name","password");

depricated

() chainable

Defined in lib/api.js:1176

Indicate that this method call has been depricated

emit

() chainable

Provided by the Event module.

Defined in lib/event.js:444

Alias to emitAFter

emitAfter

(
  • channel
  • onEmit
)
chainable

Provided by the Event module.

Defined in lib/event.js:394

Emit an event after calling this method

  • The channel will have variables provided by the input parameters substituted into it.

Parameters:

  • channel String

    The channel to emit the event on

  • onEmit Function

    The function which determines what is emitted

    • req Object

      The Express/HTTP request object

    • input Object

      The input object

    • err Object

      The error resulting from calling the method

    • result Object

      The result of calling the method

Example:

api.post("processFile","/process/").emitAfter("/user/:userId",function(req,input,err,result){
    //Emit an event to the specified channel
    this.emit({err: err, result:result});
}).demand("userId");

emitBefore

(
  • channel
  • onEmit
)
chainable

Provided by the Event module.

Defined in lib/event.js:346

Emit an event prior to calling this method

  • The channel will have variables provided by the input parameters substituted into it.

Parameters:

  • channel String

    The channel to emit the event on

  • onEmit Function

    The function which determines what is emitted

    • req Object

      The Exbeforess/HTTP request object

    • input Object

      The input object

Example:

api.post("send","/message/send").emitBefore("/user/:to",function(req,input){
    //Emit an event to the specified channel
    this.emit({msg: input.msg, from: input.from});
}).demand("msg").demand("from").demand("to");

findMethod

() String static

Defined in lib/api.js:733

Find a method by name

Returns:

String: The name of the method

Example:

Hop.defineClass("UserService",function(api){
    api.get("load","/user/:userID")

});
var method = Hop.Method.findMethod("UserService.load");
Hop.log(method.getMethod()); //returns UserService.load

getMethod

() String

Defined in lib/api.js:758

Get the name of the method

This will get the name of the method

Returns:

String: The name of the method

Example:

Hop.defineClass("UserService",function(api){
    api.get("load","/user/:userID")

});
var method = Hop.Method.findMethod("UserService.load");
Hop.log(method.getMethod()); //returns UserService.load

getPath

() String

Defined in lib/api.js:784

Get the full url for the method

This will get the full path for the url for the method.

Returns:

String: The URL for the method

inputModel

(
  • model
  • What
)
chainable

Defined in lib/model.js:376

Use a model for the output

Parameters:

  • model String

    Name of the model that is returned

  • What Class

    the model is returned as (Array is the only valid value)

Example:

//Returns an array of vehicles
api.get("list","/vehicles").outputModel("Vehicle",Array);

inputModel

(
  • model
  • What
)
chainable

Defined in lib/model.js:347

Use a model for the input

Parameters:

  • model String

    Name of the model that is used as an input

  • What Class

    the model is inputted as (Array is the only valid value)

longPoll

() chainable

Defined in lib/api.js:979

Indicate this function performs longPolling

Example:

api.get("status","/server/:serverID/status").longPoll();

model

(
  • inputObject
  • [outputModel]
)
chainable

Defined in lib/model.js:289

Use a model for both input and output

Models are used to provide meta data for both UI and api generation

Parameters:

  • inputObject Object

    Input model

  • [outputModel] Object optional

    Output model

    • Models require a field called _name which specifies the name of the model
    • Models can have the following fields on types:
      • type - The class name of the type, valid values are ( String, Number, Array, Object, Date, Boolean )
      • subtype - A subtype for the field "ID", "Float", "JSON", "IDRef", "Tags"
      • regex - A regex used to validate the fields
      • regexMsg - A message which is displayed when the regex is not matched
      • title - A title for the field, for UI purposes
      • desc - A description of the field for UI purposes
      • values - An array or object which contains possible values for this field

Example:

Hop.defineModel("User",function(model){
    model.field("name").string().regex(/[A-Za-z]{3,10}/,"Usernames must be between 3 - 10 characters long and can only contain A-Z  and a-z");
    model.field("id").integer().ID();
    model.field("email").string().title("Email");
});

Hop.defineClass("User",new User(),function(api){
    api.post("create","/user").useModel("User");
    api.get("list","/user").inputModel(SearchModel).outputModel(UserModel);
});

noCache

() chainable

Defined in lib/api.js:995

Indicate this function should avoid caching

Example:

api.post("create","/user/profile/").noCache();

optional

(
  • name
  • desc
)
chainable

Defined in lib/api.js:961

Optional parameter for a call

Parameters:

  • name String

    of parameter

  • desc String

    description of parameter

Example:

api.post("create","/user/profile/").optional("phoneNumber","Phone Number");

optionalFile

() chainable

Defined in lib/api.js:1049

Specify that a file may optionally be provided as an input to this call.

Example:

api.post("create","/user/profile/").optionalFile("avatar","Users avatar image");

optionals

(
  • name
)
chainable

Defined in lib/api.js:816

Specify a number of optionals for for a call

Parameters:

  • name String

    of parameter (+)

Example:

api.post("create","/user/profile/").optionals("email","name","password");

requireRole

()

Provided by the User module.

Defined in lib/user.js:84

Indicates that a user is required to call this function.

Example:

Hop.defineClass("UserService",function(api){
    //This will cause this function to return "Permission denied" unless a user is found via Hop.User.hasRole();
    api.get("view","/admin/user/:userID").requireRole("admin");
});

requiresUser

()

Provided by the User module.

Defined in lib/user.js:67

Indicates that a user is required to call this function.

Example:

Hop.defineClass("AccountService",function(api){
    //This will cause this function to return "Permission denied" unless a user is found via Hop.User.exists();
    api.get("/account/:accountID").requireUser();
});

returnsBoolean

() chainable

Defined in lib/model.js:405

This call returns a boolean value

returnsNumber

() chainable

Defined in lib/model.js:445

This call returns a number value

returnsString

() chainable

Defined in lib/model.js:418

This call returns a string value

returnsString

() chainable

Defined in lib/model.js:431

This call returns a file

secure

() chainable

Defined in lib/api.js:911

Note that this method can only be called using https

sendCSRFToken

() chainable

Defined in lib/api.js:927

Include the express CSRF token in the response headers for this method

The CSRF token is utilized to prevent cross site request forgery attacks, and is a middleware component for express.

See here for information: http://www.senchalabs.org/connect/middleware-csrf.html

By default HopJS will attempt to utilize the CSRF functionality in express if it is enabled, but some clients require a means to access the CSRF token, hence this function will will send the csrf token in the headers as 'x-crsf-token'

The primary usage for this function is with secure login functions

Example:

Hop.defineClass("UserService",UserService,function(api){
    api.post("login","/login").demands("username","password").sendCSRFToken();
});

usage

(
  • usage
)
chainable

Defined in lib/api.js:870

Describe this method

Parameters:

  • usage String

    text describing the function for documentation purposes