The main purpose of this document is to show documentation of independent parts which may be used to create your own modules properly and quickly.
We called our application world
. Therefore interface of communication with application looks like this:
app.world.say('message_to_world', attachmentInMessage)
# `attachmentInMessage` may be anything
See Modules to understand how to listen this messages.
You have the opportunity to listen to what the world says manually:
app.world.listen('what_messages_you_want_to_listen', listener)
listener = (attachmentInMessage) ->
# `attachmentInMessage` is something that has been attached to message
But this interface is not recommended. They stay global because it is used to listen messages properly by modules.
Basic module:
app.Module.create
body: (app, $) ->
constructor: ->
Use onDocumentReady
method to initialize your module when DOM has completely loaded:
app.Module.create
body: (app, $) ->
constructor: ->
onDocumentReady: true
Modules doesn't know about each other. But sometimes one module have to share some data with other module.
Let's look at an example. First module will wait user click and after it should say to second module: {clicked: 'a'}
.
In our approach you can not say specific module. But you can say to the world and hope that some module will hear.
First module:
app.Modules.create
body: (app, $) ->
constructor: ->
$.document.on('click', 'a', @_handler)
_handler: (e) ->
msg =
content: 'clickable'
attachment:
clicked: e.target.tagName
app.world.say(msg.content, msg.attachment)
e.preventDefault()
Second module:
app.Modules.create
body: (app, $) ->
constructor: ->
handler_clickable: (attachment) ->
attachment.clicked
# {clicked: 'A'}
export:
clickable: 'handler_clickable'
Method export
in second module telling to the world what this module can hear. In this example second module can hear messages named clickable
and invoke method handler_clickable
as soon as heard.
Utilities uses if you need to make alias for frequently used functions or make API for complex structure.
There are written utilities:
Send ajax request to route:
route =
name: 'save_data'
obj: {dest: 'text'}
# `ajaxData` is what you send to jQuery.ajax function
ajaxData =
# type described in router
data:
content: 'test message to send it to `save_data` router with `dest: text`'
app.utils.ajax route.name, route.obj, ajaxData
If you don't want to send ajax request via router you can use ajax_plain
utility.
ajaxData =
type: 'post'
data:
content: 'test message to send it to /save_data/text'
app.utils.ajax_plain '/save_data/text', ajaxData
If you want to store some data in location.hash
use hash
utility:
orders_hash = app.utils.hash('orders')
orders_hash.add(52) # location.hash == '#&orders[52]'
orders_hash.add(54) # location.hash == '#&orders[52,54]'
orders_hash.remove(52) # location.hash == '#&orders[54]'
If you want to get array of data use .getArray()
:
orders_hash.getArray()
# [54]
If you want to store collection, use .setArray()
:
orders_hash.setArray([50, 51, 52])
# location.hash == '#&orders[50,51,52]'
You can setup separator of items in hash:
hash_options =
array_separator: '-'
orders_hash = app.utils.hash('orders', hash_options)
...and now your items in location.hash
will be stored like #&orders[50-51-52]
.
Use human names if you will check keyCode
of pressed key on the keyboard. For example:
app.utils.key.Enter # => 13
Usecase of it:
input_keyup = (e) ->
if e.keyCode is app.utils.key.Enter
e.preventDefault()
$.document.on('keyup', 'input', input_keyup)
Available names of keys: Enter
, Esc
, Space
, ArrowLeft
, ArrowTop
, ArrowRight
, ArrowDown
.
Router is not so popular in use. Most often used by internals parts of the framework.
For example in routes you write:
route_name: ['/route/url/:id', 'get']
Then you need to get the url string:
route =
name: 'route_name'
obj: {id: 10}
app.utils.router.url(route.name, route.obj)
# => '/route/url/10'
Or you need to get the route object:
route =
name: 'route_name'
obj: {id: 10}
app.utils.router.parse(route.name, route.obj)
# => ['/route/url/10', 'get']
Used to redirect or open url in new tab.
For example in routes file you write:
route_name: ['/route/url/:id', 'get']
Then you need to open this route:
route =
name: 'route_name'
obj: 10
app.utils.url(route.name, route.obj).open()
If you want to open route in new tab:
app.utils.url(route.name, route.obj).open('_blank')
In case you need to update or change third-party libraries and frameworks use patches.
There are written patches:
Add progress
event for jQuery ajax method.
ajaxObject =
type: 'put'
progress: (e) ->
if e.lengthComputable
# Get percent of loading
percent = (e.loaded / e.total) * 100
success: successCallback
$.document # jQuery wrapper for `document`
$.window # jQuery wrapper for `window`