Class: Magnolia

Inherits:
Object
  • Object
show all
Defined in:
lib/magnolia/magnolia.rb

Defined Under Namespace

Classes: Mark, MissingData, RequestError, Tag

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key) ⇒ Magnolia

This must be called before any of the other methods can be used. It sets a class variable named api_key which all the other class methods use when making requests.

Example

Magnolia.new('yourgreatsuperapikey')



62
63
64
 
# File 'lib/magnolia/magnolia.rb', line 62

def initialize(api_key)
  Magnolia.set_api_key(api_key)
end

Class Method Details

.add(mark = {}) ⇒ Object Also known as: create

Examples

Magnolia.add(:title        => 'Addicted To New', 
            :description  => 'A great site!',
            :url          => 'http://addictedtonew.com/',
            :private      => 'false',
            :tags         => 'cool dude, lame tag, addicting',
            :rating       => 5)

Options

:url          - A URL string. Must be valid (required)
:title        - A title string (optional)
:description  - A description string (optional)
:private      - The bookmark’s privacy status; either 'true' or 'false' (optional)
:tags         - A list of tags. This will completely replace any existing tags for each specified bookmark (optional)
:rating       - An integer representing a star rating; 1-5 (optional)

Return Value

Returns an array containing the added mark

Raises:



167
168
169
170
 
# File 'lib/magnolia/magnolia.rb', line 167

def add(mark = {})
  raise MissingData, 'The url must be included to add a mark.' unless mark.include? :url
  create_marks_from_xml(make_request('bookmarks_add', mark))
end

.delete(marks = {}) ⇒ Object Also known as: destroy

Examples

delone      = Magnolia.delete(:id => 'java')
delmultiple = Magnolia.delete(:id => 'java,perl,someotherid')
deldiff     = Magnolia.destroy(:id => 'someid')

Options

:id - The short name for one or more bookmarks; seperate multiples with commas (required)

Return Value

Nuttin



186
187
188
 
# File 'lib/magnolia/magnolia.rb', line 186

def delete(marks = {})
  make_request('bookmarks_delete', marks)
end

.get(marks = {}) ⇒ Object Also known as: find

This method is basically like a Ruby on Rails find method. Pass it a short name (which is basically an id) or comma-seperated short names and it will return each mark that is found. Because it is similar to rails find method, I have aliased it.

Examples

getone      = Magnolia.get(:id => 'rubyonrails')
getmultiple = Magnolia.get(:id => 'rubyonrails,ruby,someotherid')

If you like Ruby on Rails and think find is a more appropriate name for the method, feel free to use it.

getdiff     = Magnolia.find(:id => 'id1')

Options

:id - The short name for one or more bookmarks; seperate multiples with commas (required)

Return Value

Returns an array of Marks.

Raises:



140
141
142
143
 
# File 'lib/magnolia/magnolia.rb', line 140

def get(marks = {})
  raise MissingData, 'The id must be included in order to know which bookmarks to get.' unless marks.include? :id
  create_marks_from_xml(make_request('bookmarks_get', marks))
end

.search(options = {}) ⇒ Object

This method searches for bookmarks that match certain criteria provided by you. Ma.gnolia named this method bookmarks_find but I thought it was more appropriately named search.

Examples

latest  = Magnolia.find(:person => 'jnunemaker') # will find my last ten bookmarks
recent  = Magnolia.find(:person => 'jnunemaker', :limit => 20) # will find my last 20 bookmarks
nice    = Magnolia.find(:person => 'jnunemaker', :tags => 'nice', :limit => 5) # will find my last 5 bookmarks tagged 'nice'

Let’s get a bit trickier. Below will rescue from a request error such as not enough information or person not found, etc.

begin
  marks = Magnolia.search(:person => 'jnunemaker')
  marks.each do |mark|
    puts mark.title, " #{mark.id}"
  end
rescue Magnolia::RequestError => msg
  puts msg
end

Options

:tags   - Multiple tags are treated as an AND search; seperate multiples with commas
:person - Multiple screen names are treated as an ‘OR’ search; seperate multiples with commas
:group  - Multiple groups are treated as an ‘OR’ search; seperate multiples with commas
:rating - Only bookmarks rated this value or higher will be returned
:from   - Only bookmarks created after this date time will be returned
:to     - Only bookmarks created before this date time will be returned
:url    - Only return bookmarks with this url
:limit  - A maximum number of bookmarks to return from search

Return Value

Returns an array of Marks.



106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/magnolia/magnolia.rb', line 106

def search(options = {})
  params = { :tags => nil,
        :person => nil,
        :group => nil,
        :rating => nil,
        :from => nil,
        :to => nil,
        :url => nil,
        :limit => 10 }
  params.update(options)

  create_marks_from_xml(make_request('bookmarks_find', params))
end

.set_api_key(api_key) ⇒ Object

Sets the api key for all requests



68
69
70
 
# File 'lib/magnolia/magnolia.rb', line 68

def set_api_key(api_key)
  @@api_key = api_key
end

.tags_add(mark = {}) ⇒ Object Also known as: add_tags

Examples

Magnolia.tags_add(:id => 'rubyonrails', :tags => 'fast,simple')

You can also use add_tags if tags_add seems backwards.

Magnolia.add_tags(:id => 'rubyonrails', :tags => 'fast,simple')

Options

:id     - One or more bookmark short names to which the specified tags should be added
:tags   - Tags to be added to the specified bookmarks

Return Value

Nuttin

Raises:



235
236
237
238
239
 
# File 'lib/magnolia/magnolia.rb', line 235

def tags_add(mark = {})
  raise MissingData, 'The id must be included in order to know which bookmark to add tags to.' unless mark.include? :id
  raise MissingData, 'The tags must be included that you want to add.' unless mark.include? :tags
  make_request('bookmarks_tags_add', mark)
end

.tags_delete(mark = {}) ⇒ Object Also known as: delete_tags

Examples

Magnolia.tags_delete(:id => 'java', :tags => 'cool,fun')

You can also use add_tags if tags_add seems backwards.

Magnolia.add_tags(:id => 'id1', :tags => 'newtag1,newtag2')

Options

:id     - One or more bookmark short names to which the specified tags should be added
:tags   - Tags to be added to the specified bookmarks

Return Value

Nuttin

Raises:



257
258
259
260
261
 
# File 'lib/magnolia/magnolia.rb', line 257

def tags_delete(mark = {})
  raise MissingData, 'The id must be included in order to know which bookmark to add tags to.' unless mark.include? :id
  raise MissingData, 'The tags must be included that you want to add.' unless mark.include? :tags
  make_request('bookmarks_tags_delete', mark)
end

.tags_find(mark = {}) ⇒ Object Also known as: find_tags

Examples

tags = Magnolia.tags_find(:person => 'jnunemaker')
tags.each do |tag|
  puts tag.name
end

You can also use the alias of find_tags if it makes more sense to you

tags = Magnolia.find_tags(:person => 'jnunemaker')

Options

:person - The person whose tags you would like to find

Return Value

An array of Tag objects

Raises:



310
311
312
313
314
 
# File 'lib/magnolia/magnolia.rb', line 310

def tags_find(mark = {})
  raise MissingData, 'The person (screen name) is required.' unless mark.include? :person
  root = make_request('tags_find', mark)
  create_tags_from_xml(root)
end

.tags_replace(mark = {}) ⇒ Object Also known as: replace_tags, rename_tags, tags_rename

Examples

Magnolia.tags_replace(:id => 'languages', :old => 'java', :new => 'rubyonrails')

You can also use any of these below if you don’t like tags_delete

Magnolia.replace_tags(:id => 'languages', :old => 'java', :new => 'rubyonrails')
Magnolia.rename_tags(:id => 'languages', :old => 'java', :new => 'rubyonrails')
Magnolia.tags_rename(:id => 'languages', :old => 'java', :new => 'rubyonrails')

Options

:id     - One or more bookmark short names to which the specified tags should be added
:old    - Existing tag to be replaced
:new    - New tag to replace existing tag

Return Value

Nuttin

Raises:



282
283
284
285
286
287
 
# File 'lib/magnolia/magnolia.rb', line 282

def tags_replace(mark = {})
  raise MissingData, 'The id must be included in order to know which bookmark to rename tags for.' unless mark.include? :id
  raise MissingData, 'The old tag is required.' unless mark.include? :old
  raise MissingData, 'The new tag is required.' unless mark.include? :new
  make_request('bookmarks_tags_replace', mark)
end

.update(mark = {}) ⇒ Object Also known as: edit

Examples

Magnolia.update(:id           => 'someid',
              :title        => 'Addicted To New', 
              :description  => 'A great site!',
              :url          => 'http://addictedtonew.com/',
              :private      => 'false',
              :tags         => 'cool dude, lame tag, addicting',
              :rating       => 5)

Options

:id           - The short name for one bookmark (required)
:url          - A URL string. Must be valid (optional)
:title        - A title string (optional)
:description  - A description string (optional)
:private      - The bookmark’s privacy status; either 'true' or 'false' (optional)
:tags         - A list of tags. This will completely replace any existing tags for each specified bookmark (optional)
:rating       - An integer representing a star rating; 1-5 (optional)

Return Value

Returns an array containing the updated mark.

Raises:



214
215
216
217
 
# File 'lib/magnolia/magnolia.rb', line 214

def update(mark = {})
  raise MissingData, 'The id must be included in order to know which bookmark to update.' unless mark.include? :id
  create_marks_from_xml(make_request('bookmarks_update', mark))
end