Melody.js

Melody.js

Lightweight Javascript framework for fast development of large single-page applications.

Melody.Object

Includes Eventable, Cachable

This is the basic class for most other classes. It has events, caching and getters and setters.

Class methods

@attributes (attributes)

Set up the attributes of an object class. This is the first thing you should do when defining an object.

Attributes can have the following settings:

  • type (string/boolean/number/array/date/object/collection)
  • required (true/false)
  • default (value/function)
class User extends Melody.Object
  @attributes
    name: 'string'
    email:
      type: 'string'
      required: true
    active:
      type: 'boolean'
      default: true
      

@create (attributes)

Create a new instance of the class.

user = User.create(name: 'John Doe')

Instance methods

set (name, [value])

Set a single attribute and trigger observers.

user.set 'name', 'John Doe'
# triggers the 'change' and 'change:name' event

Setting the value of an object attribute.

# when you have a name attribute like:
name =
  first: "John"
  last: "Doe"
  
user.set 'name.first', 'John'
# triggers the 'change' and 'change:name' event

Set multiple attributes and trigger observers.

user.set
  name: 'John Doe'
  email: 'john@example.com'

get (name, [name...])

Get values from the object.

user.get 'name' 
# returns 'John Doe'

user.get 'name', 'email' 
# returns
# {
#   name: 'John Doe', 
#   email: 'john@example.com'
# }

# when you have a name attribute like:
name =
  first: "John"
  last: "Doe"
  
user.get 'name.first'
# returns 'John'

user.get 'something.with.a.lot.of.dots'
# returns undefined

Melody.Collection

Includes Eventable

# lets create an collection with tags
TagList extends Melody.Collection
tags = new TagList

Instance methods

all ( )

Get all values.

tags.all()
# returns an array

select (function)

The function should return true or false to determine if it returns the value.

# retrieve all 'melody' and 'javascript' tags
tags.select (tag) ->
  tag is 'melody' or tag is 'javascript'
  
# result ['melody', 'javascript']

add (value)

Add a value to an array and trigger any array observers.

tags.add 'melody'
# triggers 'change' and 'added'

remove (value)

Remove a value of an array and trigger observers.

# this function will trigger 'change' and 'removed'

Does the array contain objects? Remove it like this.

arr.remove id: '1234567890'

# or any query
arr.remove name: 'Hello there'

Or pass a record. It will be removed by its id.

arr.remove record

Or even use a function. This function must return true or false. When true, the record will be removed.

tags.remove (tag) -> tag is 'melody'

Does the array contain strings?

tags.remove 'melody'

clear ( )

Remove all items from an array.

tags.clear()
# empties the array

Melody.Model

Extends Melody.Object, includes Freezable

Class methods

@create (attributes)

Create a record and save it immediately.

user = User.create(name: 'John Doe')

# this is short for:
user = new User(name: 'John Doe')
user.save()

@find (params)

Find a record by id or an object with attributes.

# find a user with id 12
User.find '12'

# find an active user with email
User.find
  email: 'john@example.com'
  active: true
  

@all ( )

Return all records of this model

@first ( )

Return the first record

@last ( )

Return the last record

@select (function)

Retrieve records. The function should return true or false to determine if it returns the record.

# selecting all active users
User.select (user) ->
  user.active is true
  

Instance methods

save (options)

user = new User
user.save()

Melody.View

Extends Melody.Object

Class methods

--

Instance methods

render (options)

view.render()

Melody.Eventable

These can be used on class or instance level.

on (event, callback)

Observe an attribute of the instance of a model. When it changes, the callback will be fired within the specified scope. If the scope isn't defined, it will be called on the model instance itself.

user.on 'change:name', (value) -> 
  alert 'name changed to ' + value
  

once (event, callback)

The same as on(), but it the callback is removed after it has been triggered once.

user.once 'change:name', (value) -> 
  alert 'this alert will only show once'
  

off (event, callback)

Remove an event.

user.off 'change:name', callback

listenTo (target, event, callback)

Listen to events on a specified target.

userA = new User
userB = new User

userA.listenTo userB, 'change:name', (value) -> 
# triggers when userB's name changes

stopListening ([target], [event], [callback])

Stop listening to events.

# Remove all listeners
userA.stopListening()

# Stop listening to a sertain object
# This will remove all listeners for only that object
userA.stopListening(userB)

# Stop listening to a sertain event
# You need to specify the callback
userA.stopListening(userB, 'change:name', callback)