API Documentation > item

Description

Shareable units of information.

Items are flexible objects that can be shared. At a minimum they have a URL, a summary and a description but a number of additional attributes can be defined using an item's meta attribute. For example, a photo or location may be attached to an item.

Methods

item.get()

roles: anonymous

Get an item by the id assigned to it by this service.

Arguments

item_id: type=string

No description

item.get_by_id()

roles: anonymous

Get an item by the id specified in the call to save()

Arguments

id: type=string

No description

item.get_share_info()

roles: organization, organization_restricted

Get a share info from a short url hash

Arguments

hash: type=string

The hash of the share url.

item.get_share_url()

roles: organization, organization_restricted

Given some general information about a share, generate a share url for a given item.

Arguments

network: type=string

The share network. E.g. facebook, twitter, etc.

item_id: type=string

The assigned global id of the item.

[ visitor_id: type=string, default=NULL ]

Algorithmically generated user id.

[ site_id: type=string, default=NULL ]

Anonymous cookie user id.

[ user_id: type=string, default=NULL ]

A third-party user id of the sharer.

[ email: type=string, default=NULL ]

Recipient email address.

[ group: type=string, default=NULL ]

A tracking/logging scope.

[ variant: type=string, default=NULL ]

Another tracking/logging scope generally used in multi-variant testing.

[ is_like: type=bool, default=false ]

True if this item is being Liked

[ source: type=string, default='button' ]

A label for the source that is generating this item URL

[ label: type=string, default=NULL ]

An optional label

item.getlist()

roles: anonymous

Like get() but pass an array of ids and get back an array of items.

Arguments

item_ids: type=array

No description

item.save()

roles: organization, organization_restricted

Save an item. Returns a click.st ID

Arguments

id: type=string

An id that is unique across all the items created by an organization.

Returns an item_id which is a value that is unique across all items in this system. The value passed in here can also be used to lookup information about an item meaning there is no need to store this service's generated id.

summary: type=string

A short description of the item. Can be purposed for a share message.

url: type=string

The location of this item on the web. Users clicking on share links will be directed here.

[ description: type=string, default=NULL ]

A detailed description of the item.

[ meta: type=array, default=NULL ]

Additional structured information about this item.

The following attributes are currently available:

  • image - A visual depiction of the item. Example: 
    {
    image: {
        alt: 'A picture of an elephant',
        href: 'http://www.example.com/elephant.png'
    }
}
  • keywords - A handful of words that describe the item, separated by commas. Example: 
    {
    keywords: 'elephant,animal,zoo'
}
  • location - A geo tag. Information can be provided at any level, i.e. it's ok to specify just a city or a just a postal code and country, etc. Example: 
    {
    location: {
        address: '123 Fake Lane',
        city: 'San Francisco',
        state: 'CA',
        country: 'United States',
        postal_code: '94115',
        
        /* Alternatively or additionally, coordinates may be provided */
        lat: 37.73,
        lng: -122.46
    }
}
  • datetime - A temporal tag. This attribute can be in just about any recognized format. Example: 
    {
    datetime: 'Thu, Feb 25, 2010 7:56 pm'
}
[ category_id: type=string, default=NULL ]

The id of a category into which this item fits. If unspecified, the default category of the organization will be used.

[ charset: type=string, default='UTF-8' ]

No description

item methods