path: root/doc/ref/javascript.texi

@node Javascript
@chapter Javascript


@node arbitary_kv
@section arbitary_kv.js

@node binders
@section binders.js

@node clock
@section clock.js

@node date_time
@section date_time.js

@node dragable
@section dragable.js

@node input_list
@section input_list.js

@node jcal
@section jcal.js

@node lib
@section lib.js

General procedures which in theory could be used anywhere.

@defvar xcal
The xml namespace name for xcalendar, which is
``urn:ietf:params:xml:ns:icalendar-2.0''.
@end defvar


@node Default prototype extensions
@subsection Default prototype extensions

HTMLElement extensions

@defmethod HTMLElement addEventListener name proc
Replace the default @code{addEventListener} with a version that stores
all listeners in the dictionary @var{listeners}.
@end defmethod

@defivar HTMLElement listeners
Dictionary of all registered listeners to this element.
Keys are taken from @code{addEventListener}.
@end defivar

@defmethod DOMTokenList find regexp
Finds the first element of the DOMTokenList whichs value matches
the supplied regexp. Returns a pair of the index and the value.
@end defmethod

@defmethod Object format args ...
Returns a string representation of the given object.
Allows extending for custom types,
@ref{date-format}
@end defmethod

@node General
@subsection General

@defun zip args ...
Takes a list of lists, and returns a single list of tuples.
@example
» zip([1,2,3,4,5], "Hello")
← [[1,'H'],[2,'e'],[3,'l'],[4,'l'],[5,'o']]
@end example
@end defun

@defun makeElement name [attr=@{@}]
Creates a new DOM element of type @var{name}, with all keys in
@var{attr} transfered to it. For example, the equivalent of
@example
<input type='number'/>
@end example
would be
@verbatim
values.push(makeElement('input', {
    type: 'number',
}));
@end verbatim
.
@end defun

@defun round_time time fraction
TODO
@end defun

@defun date_to_percent date
Retuns how far along the date specified by @var{date} is, between 0
and 100, where 00:00 maps to 0, and 23:59 to ~100.
@end defun

@defun gensym [pxrefix='gensym']
Generates a new string which is (hopefully) globally unique.
Compare with @code{gensym} from Lisp.
@end defun

@defun setVar str val
Set the CSS var @var{str} to @var{val} on the root element.
@end defun

@defun asList thing
Ensures that @var{thing} is a list. Returning it outright if it
already is one, otherwise wrapping it in a list.
@end defun

@node Date
@subsection Date

Some extensions to the builtin class ``Date'' is made.

@defivar Date utc
Boolean indicating if the given timestamp is in UTC or local time.
true means UTC.
@end defivar

@defivar Date dateonly
Boolean indicating if the time component of the Date object should be disregarded.
@end defivar

@defun parseDate str
Takes a string @var{str}, which should be in ISO-8601 date-format, and
returns a javascript Date object.
@end defun

@defun copyDate date
Creates a new instance of the given Date @var{date}, also transfers my
custom fields.
@end defun

@defun to_local date
@anchor{to_local}
Returns a Date object (which may be new) which is guaranteed in local
time.
This means that the @var{utc} field is @code{false}, and that
@code{to_local(current_time())} should show what your wall-clock shows.
@end defun

@defmethod Date format str args ...
@anchor{date-format}
Formats a Date object according to the format specification @var{str}.
Keeping with Guile each format specifier starts with a ~.

@c table formatting borrowed from Gulie Reference (SRFI-19 Date to string)
@multitable {MMMM} {MMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM}
@item @nicode{~~} @tab literal ~
@c Almost all fields are left padded. How do I signify this
@c with a single footnote?
@item @nicode{~Y} @tab year, left-padding with zeroes.
@item @nicode{~m} @tab month number, left padded with zeroes.
@item @nicode{~d} @tab day of month.
@item @nicode{~H} @tab hour
@item @nicode{~M} @tab minute
@item @nicode{~S} @tab second
@item @nicode{~Z} @tab 'Z' if Date is UTC, otherwise nothing

@item @nicode{~L} @tab Converts the date to local time
(@pxref{to_local}) (doesn't modify source object). Outputs nothing
@end multitable
@end defmethod

@defun format_date date str
Equivalent to @code{(@var{date}).format(@var{str})}.
@c TODO link
@end defun


@node popup
@section popup.js

@node rrule
@section rrule.js

@node script
@section script.js

@dfn{Main} for my javascript, and also currently dumping ground for stuff.

@deftp {class} EventCreator

@defmethod EventCreator create_empty_event
@end defmethod

@defmethod EventCreator create_event_down intended_target
@end defmethod

@defmethod EventCreator create_event_move pos_in [round=1] [wide_element=false]
@end defmethod

@defmethod EventCreator create_event_finisher callback
@end defmethod

@end deftp

@defun place_in_edit_mode event
@end defun

@c window.onload is here in source file

@defun get_property event field default_value
Returns the @emph{value} slot of given field in @var{event}, creating it if needed.

@itemize
@item
@var{el}: the event to work on

@item
@var{field}: name of the field

@item
@var{default_value}: default value when creating

@item
@var{bind_to_ical} should this property be added to the icalendar subtree?
@end itemize
@end defun

@defun bind_properties el [wide_event=false]
  Properties are icalendar properties.

  p['name'] to get and set value (also updates any connected slots)

  p['_value_name'] for raw value
  p['_slot_name'] for connected slots, Vector of pairs, where the
                  car should be a reference to the slot, and the
                  cdr a procedure which takes a slot and a value
                  and binds the value to the slot.
@end defun

@node server_connect
@section server_connect.js

@node types
@section types.js

Collection of type information for calendar data.

@defvar all_types
Name of all valid icalendar types.

    text, uri, binary, float, integer, date-time, date, duration,
    period, utc-offset, cal-address, recur, boolean,
@end defvar

@defvar property_names
All known names properties (top level keys) can have.
Such as ``calscale'', ``dtstart'', ...
@end defvar

@defvar valid_fields
Which property fields each component can hold.

@verbatim
{ 'VCALENDAR': ['PRODID', 'VERSION', 'CALSCALE', 'METHOD'],
    ...
}
@end verbatim
@end defvar

@defvar valid_input_types
Which types are valid to store under each property.
If multiple values are an option for that property, then
the list of possibilities will contain a sub-list (see example).

@verbatim
{ 'DTSTART': ['date', 'date-time'],
  'CATEGORIES': [['text']],
  ...
}
@end verbatim
@end defvar