From 5e4aa8e9aba34bb101923685c23f0f6681a12812 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Sun, 12 Dec 2021 23:29:06 +0100 Subject: Add documenttation for javascript rewrite. --- doc/ref/calp.texi | 5 + doc/ref/javascript.texi | 55 +++++------ doc/ref/javascript/arbitary_kv.texi | 3 - doc/ref/javascript/binders.texi | 57 ----------- doc/ref/javascript/clock.texi | 10 +- doc/ref/javascript/components/changelog.texi | 10 ++ doc/ref/javascript/components/date_time_input.texi | 34 +++++++ doc/ref/javascript/components/edit_rrule.texi | 10 ++ doc/ref/javascript/components/input_list.texi | 16 +++ doc/ref/javascript/components/popup_element.texi | 40 ++++++++ .../javascript/components/tab_group_element.texi | 46 +++++++++ doc/ref/javascript/components/vevent.texi | 23 +++++ doc/ref/javascript/components/vevent_block.texi | 10 ++ .../javascript/components/vevent_description.texi | 10 ++ doc/ref/javascript/components/vevent_dl.texi | 11 +++ doc/ref/javascript/components/vevent_edit.texi | 9 ++ doc/ref/javascript/date_time.texi | 41 -------- doc/ref/javascript/draggable.texi | 24 ----- doc/ref/javascript/eventCreator.texi | 15 +++ doc/ref/javascript/globals.texi | 41 ++++++++ doc/ref/javascript/input_list.texi | 51 ---------- doc/ref/javascript/jcal.texi | 5 +- doc/ref/javascript/lib.texi | 9 -- doc/ref/javascript/popup.texi | 5 - doc/ref/javascript/rrule.texi | 4 - doc/ref/javascript/script.texi | 60 ------------ doc/ref/javascript/server_connect.texi | 20 ++++ doc/ref/javascript/types.texi | 63 +++++++++++- doc/ref/javascript/vevent.texi | 108 +++++++++++++++++++++ 29 files changed, 502 insertions(+), 293 deletions(-) delete mode 100644 doc/ref/javascript/arbitary_kv.texi delete mode 100644 doc/ref/javascript/binders.texi create mode 100644 doc/ref/javascript/components/changelog.texi create mode 100644 doc/ref/javascript/components/date_time_input.texi create mode 100644 doc/ref/javascript/components/edit_rrule.texi create mode 100644 doc/ref/javascript/components/input_list.texi create mode 100644 doc/ref/javascript/components/popup_element.texi create mode 100644 doc/ref/javascript/components/tab_group_element.texi create mode 100644 doc/ref/javascript/components/vevent.texi create mode 100644 doc/ref/javascript/components/vevent_block.texi create mode 100644 doc/ref/javascript/components/vevent_description.texi create mode 100644 doc/ref/javascript/components/vevent_dl.texi create mode 100644 doc/ref/javascript/components/vevent_edit.texi delete mode 100644 doc/ref/javascript/date_time.texi delete mode 100644 doc/ref/javascript/draggable.texi create mode 100644 doc/ref/javascript/eventCreator.texi create mode 100644 doc/ref/javascript/globals.texi delete mode 100644 doc/ref/javascript/input_list.texi delete mode 100644 doc/ref/javascript/popup.texi delete mode 100644 doc/ref/javascript/rrule.texi delete mode 100644 doc/ref/javascript/script.texi create mode 100644 doc/ref/javascript/vevent.texi diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index e5c4baab..474ad3e2 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -65,7 +65,12 @@ text @footnote{Improvements welcome} @unnumbered Index @printindex cp @printindex fn +@printindex ky +@printindex pg @printindex tp @printindex vr +@unnumbered Web Components +@printindex wc + @bye diff --git a/doc/ref/javascript.texi b/doc/ref/javascript.texi index 6fbd7cdc..7510e4f5 100644 --- a/doc/ref/javascript.texi +++ b/doc/ref/javascript.texi @@ -1,35 +1,36 @@ @node Javascript @chapter Javascript -@node Concepts -@section Concepts +@c web components +@defindex wc -@subsection ``Componenents'' +@c done +@node General Stuff +@section General stuff +The frontend code has its entry-point in @code{script.ts} -@deftp {} date_time -@cindex date-time - -@ref{date_time} -@end deftp - -@deftp {} draggable -@end deftp - -@deftp {} input_list -@end deftp - -@node Reference -@section Reference -@include javascript/arbitary_kv.texi -@include javascript/binders.texi +All elements are initialized in elements.ts @include javascript/clock.texi -@include javascript/date_time.texi -@include javascript/draggable.texi -@include javascript/input_list.texi -@include javascript/jcal.texi @include javascript/lib.texi -@include javascript/popup.texi -@include javascript/rrule.texi -@include javascript/script.texi -@include javascript/server_connect.texi +@include javascript/eventCreator.texi @include javascript/types.texi +@include javascript/vevent.texi +@include javascript/globals.texi +@include javascript/server_connect.texi + +@node General Components +@section General Components +@include javascript/components/date_time_input.texi +@include javascript/components/input_list.texi + +@node VEvent Components +@section VEvent Components +@include javascript/components/vevent.texi +@include javascript/components/changelog.texi +@include javascript/components/edit_rrule.texi +@include javascript/components/popup_element.texi +@include javascript/components/tab_group_element.texi +@include javascript/components/vevent_block.texi +@include javascript/components/vevent_description.texi +@include javascript/components/vevent_dl.texi +@include javascript/components/vevent_edit.texi diff --git a/doc/ref/javascript/arbitary_kv.texi b/doc/ref/javascript/arbitary_kv.texi deleted file mode 100644 index b28c8b92..00000000 --- a/doc/ref/javascript/arbitary_kv.texi +++ /dev/null @@ -1,3 +0,0 @@ -@node arbitary_kv -@subsection arbitary_kv.js - diff --git a/doc/ref/javascript/binders.texi b/doc/ref/javascript/binders.texi deleted file mode 100644 index 0e38411b..00000000 --- a/doc/ref/javascript/binders.texi +++ /dev/null @@ -1,57 +0,0 @@ - -@node binders -@cindex binder -@cindex binders -@subsection binders.js - -The bind system allows HTML-elements to specify that they want to be -updated whenever its corresponding (vcalendar) object changes. -The bind system is currently set up in -@code{bind_properties} (@pxref{bind_properties}) -(which at the time of writing is (badly) located in @ref{script}). - -All (HTML) components with the class @code{bind} are bound. By default -the (HTML) attribute @code{data-property} is checked for a property -name, and @code{object.innerHTML} is set whenever that property field -changes. -Alternatively an (HTML) component may specify a specific binder -through the HTML attribute @code{data-bindby}, which should be the -name of a JavaScript function taking two arguments, an @TODO{event -component} -@footnote{Root ``root'' HTML component of a given calendar event -(something which @code{get_property} can be called on}, -and the component in question. - -@c Also sets up event listeners, which most doesn't do. - -Binder functions are generally placed in @file{binders.js}, and -shouldn't be called manually. - -@defun bind_recur el e -Handles recurrence rules. -Uses a sub-binder system on components with class containing -``bind-rr''. -@end defun - -@defun bind_edit el e -Cases for @code{input} and @code{textarea} elements @TODO{(should also -handle @code{select}s?)} -@end defun - -@defun bind_view el e -The same as the default binder???? -@end defun - -@defun bind_wholeday el e -Binder for the wholeday toggle button. -While CSS would suffice, this sets the disabled flags on the time -inputs, giving a better user experience. -@end defun - -@defun bind_date_time el e -@anchor{bind_date_time} -For @code{date_time} dummy component. Propagates gets and sets to -underlying input fields. - -Note: @emph{Must} be called @emph{after} @code{init_date_time}. -@end defun diff --git a/doc/ref/javascript/clock.texi b/doc/ref/javascript/clock.texi index 5c2bd954..10ab7d4e 100644 --- a/doc/ref/javascript/clock.texi +++ b/doc/ref/javascript/clock.texi @@ -1,21 +1,15 @@ @node clock @subsection clock.js -@deftp {(abstract) class} Clock +@deftp {abstract class} Clock Interface for ``things'' which wants to get updated on a human timescale. @defmethod Clock update now +@c abstract method Called every now and then, with @var{now} being the current time. @end defmethod - -All instances are expected to implement @code{update}, but are free to -implement any other methods they see fit. @end deftp -Below, only the methods (including @code{constructor} and -@code{update} which do something of note (excluding the expected)) -are noted. - @deftp {class} Timebar @extends{Clock} The (blue) vertical line which show the current time in the current day. diff --git a/doc/ref/javascript/components/changelog.texi b/doc/ref/javascript/components/changelog.texi new file mode 100644 index 00000000..d14fb84e --- /dev/null +++ b/doc/ref/javascript/components/changelog.texi @@ -0,0 +1,10 @@ +@subsection Changelog + +@deftp {Web Component for VEvent} VEventChangelog +@wcindex +@wcindex vevent-changelog +@anchor{VEventChangelog} +@code{} + +Display of a VEvents changelog. @ref{ChangeLogEntry} +@end deftp diff --git a/doc/ref/javascript/components/date_time_input.texi b/doc/ref/javascript/components/date_time_input.texi new file mode 100644 index 00000000..f26627d2 --- /dev/null +++ b/doc/ref/javascript/components/date_time_input.texi @@ -0,0 +1,34 @@ +@subsection date-time-input + +@deftp {Web Component} DateTimeInput +@wcindex +@wcindex date-time-input +@code {} + +An element for input for date-times. Similar to +@example + + +@end example +But as a single unit. + +@deftypeivar DateTimeInput boolean dateonly +Setting this to true disabled the time part of the input, and makes +any output only have date components (alternativly, the time component +set to zero). +@end deftypeivar + +@defcv {Attribute} DateTimeInput dateonly +Same data as the field dateonly, but as an attribute. Present means +true, absent means false. +@end defcv + +@deftypeivar DateTimeInput Date value +Returns current value as a Date object. +@end deftypeivar + +@deftypeivar DateTimeInput string stringValue +Returns current value as an ISO-8601 formatted string. +@end deftypeivar + +@end deftp diff --git a/doc/ref/javascript/components/edit_rrule.texi b/doc/ref/javascript/components/edit_rrule.texi new file mode 100644 index 00000000..21437863 --- /dev/null +++ b/doc/ref/javascript/components/edit_rrule.texi @@ -0,0 +1,10 @@ +@subsection Edit RRule + +@deftp {Web Component for VEvent} EditRRule +@wcindex +@wcindex vevent-edit-rrule +@code{} + +An edit form for a recurrence rule. Searches its template for elements +with @code{[name="<>"]}, and binds to those. +@end deftp diff --git a/doc/ref/javascript/components/input_list.texi b/doc/ref/javascript/components/input_list.texi new file mode 100644 index 00000000..bdc00ecb --- /dev/null +++ b/doc/ref/javascript/components/input_list.texi @@ -0,0 +1,16 @@ +@subsection input_list.js + +@deftp {Web Component} InputList +@wcindex +@wcindex input-list +@code{} + +A list of identical input fields, which forms a group. For example +useful to handle keywords. + +@deftypeivar DateTimeInput {any[]} value +The value from each element, except the last which should always be empty. +Has an unspecified type, since children:s value field might give non-strings. +@end deftypeivar + +@end deftp diff --git a/doc/ref/javascript/components/popup_element.texi b/doc/ref/javascript/components/popup_element.texi new file mode 100644 index 00000000..2b76b347 --- /dev/null +++ b/doc/ref/javascript/components/popup_element.texi @@ -0,0 +1,40 @@ +@subsection Popup + +@deftp {Web Component for VEvent} PopupElement +@wcindex +@wcindex popup-element +@code{} + +A (small) floating window containing information, which can be dragged +arround. Consists of a navigation bar with a few buttons for +controlling the window, which also works as a drag handle, along with +an area for contents, which can be resized by the user. + +Currently tightly coupled to VEvent's, since their color +profile is derived from their owning events calendar, and they have +action buttons for the event in their navigation bar. + +@deftypecv {Static Member} PopupElement {PopupElement?} activePopup +The popup which was most recently interacted with by the user. Used to +move it on top of all others, as well as sending relevant key events there. +@end deftypecv + +@defcv {Attribute} PopupElement visible +Present is the popup is currently visible, absent otherwise. +@end defcv + +@deftypeivar PopupElement boolean visible +See the attribute of the same name. +@end deftypeivar + +@defmethod PopupElement maximize +Resize the popup window to fill the current viewport (mostly). Is +probably bonud to the maximize button in the navigation bar. +@end defmethod +@end deftp + +@deftypefun PopupElement setup_popup_element VEvent +Create a new popup element for the given VEvent, and ready it for +editing the event. Used when creating event (through the frontend). +The return value can safely be ignored. +@end deftypefun diff --git a/doc/ref/javascript/components/tab_group_element.texi b/doc/ref/javascript/components/tab_group_element.texi new file mode 100644 index 00000000..7d9ca412 --- /dev/null +++ b/doc/ref/javascript/components/tab_group_element.texi @@ -0,0 +1,46 @@ +@subsection Tab Group Element + +@deftp {Web Component for VEvent} TabGroupElement +@wcindex +@wcindex tab-group +@code{} + +A group of tabs, where only one can be visible at a time. + +@c TODO which form does the HTML document have? For CSS purposes + +Each tab consists of two parts, a label which is used for selecting +it, and a tab-element, which contains the actual content. These two +should refer to each other as follows: + +@verbatim ++---------------+ +----------------+ +| TabLabel | | Tab | ++---------------+ +----------------+ +| id |<----| aria-labeledby | +| aria-controls |---->| id | ++---------------+ +----------------+ +@end verbatim + +Further information about tabs in HTML can be found here: +@url{https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Tab_Role} + +@defvr {CSS Variable} {--tabcount} +Each tab element has the style property @code{--tabcount} set to how +many tabs it has. This is mostly useful to make sure the tab context +is large enough to fit all tab labels without overflowing. +@end defvr + +@deftypemethod TabGroupElement void addTab {HTMLElement} {label: string?} {title: string?} +Adds a new tab to the group. The first parameter will make up the body +of the tab. The label is whath should be shown in the tab selector, +but defaults to the first letter of the text content of the body node. +Title is the hoover text of the label. +@end deftypemethod + +@deftypemethod TabGroupElement void removeTab {HTMLElement} +HTMLElement must be one of the tab bodies in this group. This method +removes it, along with its TabLabel. +@end deftypemethod + +@end deftp diff --git a/doc/ref/javascript/components/vevent.texi b/doc/ref/javascript/components/vevent.texi new file mode 100644 index 00000000..be53a46e --- /dev/null +++ b/doc/ref/javascript/components/vevent.texi @@ -0,0 +1,23 @@ +@subsection vevent + +@deftp {Abstract Web Component} ComponentVEvent {uid: string?} + +@c TODO what is done in the default constructor, +@c and the default connectedCallback + +This registeres itself, but doesn't redraw +We do however redraw in connectedCallback + +@deftypeivar ComponentVEvent uid uid +@end deftypeivar + +@deftypeivar ComponentVEvent {HTMLTemplateElement?} template +@end deftypeivar + +@deftypemethod ComponentVEvent void redraw (data: VEvent) +While abstract for this, @emph{must} be overridden for everyone else +@end deftypemethod +@end deftp + +Note that many of these assume that their initial children are +configured specifically, that is however not completely documented. diff --git a/doc/ref/javascript/components/vevent_block.texi b/doc/ref/javascript/components/vevent_block.texi new file mode 100644 index 00000000..1a0ef160 --- /dev/null +++ b/doc/ref/javascript/components/vevent_block.texi @@ -0,0 +1,10 @@ +@subsection VEvent Block + +@deftp {Web Component for VEvent} ComponentBlock +@wcindex +@wcindex vevent-block +@code{} +A block in our graphical view. + +Unique in that it works quite differently between the week and month view. +@end deftp diff --git a/doc/ref/javascript/components/vevent_description.texi b/doc/ref/javascript/components/vevent_description.texi new file mode 100644 index 00000000..492c8dff --- /dev/null +++ b/doc/ref/javascript/components/vevent_description.texi @@ -0,0 +1,10 @@ +@subsection VEvent Description + +@deftp {Web Component for VEvent} ComponentDescription +@wcindex +@wcindex vevent-description +@code{} + +A text representation of a VEvent. Used as the summary tab of our +popup windows, and in the sidebar. +@end deftp diff --git a/doc/ref/javascript/components/vevent_dl.texi b/doc/ref/javascript/components/vevent_dl.texi new file mode 100644 index 00000000..26bc8fd4 --- /dev/null +++ b/doc/ref/javascript/components/vevent_dl.texi @@ -0,0 +1,11 @@ +@subsection VEvent Description List + +@deftp {Web Component for VEvent} VEventDL +@wcindex +@wcindex vevent-dl +@code{} +A description list of a vevent, used for debugging. + +No guarantees are given about the contents of the data fields, more +than that they are related to the value in question. +@end deftp diff --git a/doc/ref/javascript/components/vevent_edit.texi b/doc/ref/javascript/components/vevent_edit.texi new file mode 100644 index 00000000..67e9f6b3 --- /dev/null +++ b/doc/ref/javascript/components/vevent_edit.texi @@ -0,0 +1,9 @@ +@subsection VEvent Edit + +@deftp {Web Component for VEvent} ComponentEdit +@wcindex +@wcindex vevent-edit +@code{} +Edit form for a vevent, designed for useful human interaction (and +thereby not being all-encompassing). +@end deftp diff --git a/doc/ref/javascript/date_time.texi b/doc/ref/javascript/date_time.texi deleted file mode 100644 index b2c5db92..00000000 --- a/doc/ref/javascript/date_time.texi +++ /dev/null @@ -1,41 +0,0 @@ -@node date_time -@subsection date_time.js - -@defun init_date_time -@c possibly have special index for these -@cindex dummy component -Procedure which initializes the dummy component for date-time input. -When called, finds all elements with class ``date-time'', and makes -them date-time inputs. - -@c - -The expected HTML form is -@example -
- - -
-@end example - -Each date-time gets the following fields: - -@defivar date_time value -The current date-time value as a string, -on the form @code{YYYY-mm-ddTHH:MM[:SS]} -(@code{SS} if the underlying time input has it). - -A new date-time can also be set to the field, the same format as above -is expected. -@end defivar - -@defivar date_time name -The ``name'' field of the date-time input. Since @code{name} note that -this is an addition, since name is actually invalid on non-input -components. We nevertheless use it here since we are emulating an -input element. -@end defivar - -See also @pxref{bind_date_time} - -@end defun diff --git a/doc/ref/javascript/draggable.texi b/doc/ref/javascript/draggable.texi deleted file mode 100644 index d1851ec4..00000000 --- a/doc/ref/javascript/draggable.texi +++ /dev/null @@ -1,24 +0,0 @@ -@node dragable -@subsection dragable.js - -@c TODO This text is just yanked from the old org file, along with the -@c source codes header. It should probably be rewritten. - -Manually apply =bind_popup_control= to the statusbar of a floating -"window". Nothing is required from the component, but the "window" -must have 'popup-container' ∈ =class= - -@defun bind_popup_control nav -Apply to a given component to make it draggable. -Drag area (usually a title bar) should be be the only argument. -It is REQUIRED that the object which should be moved have the class -@code{popup-container}. - -@example -
- ... -
-@end example -@end defun diff --git a/doc/ref/javascript/eventCreator.texi b/doc/ref/javascript/eventCreator.texi new file mode 100644 index 00000000..164d1335 --- /dev/null +++ b/doc/ref/javascript/eventCreator.texi @@ -0,0 +1,15 @@ +@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 diff --git a/doc/ref/javascript/globals.texi b/doc/ref/javascript/globals.texi new file mode 100644 index 00000000..5ef7a43b --- /dev/null +++ b/doc/ref/javascript/globals.texi @@ -0,0 +1,41 @@ +@node globals +@subsection globals.ts + +Different variables and values which for different reasons needs to be +global. Window Value's are those that are bound to the @code{window} +context in JavaScript, so is really always available, no opt out. + +@deftypevar {Map} vcal_objects +All VEvent objects on current page, indexed by their unique identifiers. + +A global object store. +@end deftypevar + +@deftypevar {Map} event_calendar_mapping +Mapping from VEvent unique identifier, to name of its calendar. Should +probably not be global, so refrain from using it. +@end deftypevar + +@deftypevr {Window Value} {Map} vcal_objects +The exact same object store as the regular variable of the same +name. Mostly here for human debugability. +@end deftypevr + +@deftypevr {Window Value} {@code{'month'} | @code{'string'}} VIEW +How the calendar is currently formatted. Should be set by the backend +through a simple @code{script}-tag. +@end deftypevr + +@deftypevr {Window Value} {boolean} EDIT_MODE +However editing of events is enabled or not. +Should be set by the backend through a simple @code{script}-tag. +@end deftypevr + +@deftypevr {Window Value} {string} default_calendar +Name of the calendar to assume when creating new events. +Should be set by the backend through a simple @code{script}-tag. +@end deftypevr + +@c TODO addNewEvent +@c @deftypevr {Window Value} {string} default_calendar +@c @end deftypevr diff --git a/doc/ref/javascript/input_list.texi b/doc/ref/javascript/input_list.texi deleted file mode 100644 index 65db81a4..00000000 --- a/doc/ref/javascript/input_list.texi +++ /dev/null @@ -1,51 +0,0 @@ -@node input_list -@subsection input_list.js -@cindex dummy component - -All elements with the class @code{input-list} are treated as a -collection of input fields. Uses including setting tags on calendar -entries. - -All direct children of the ``input-list'' @emph{must} have the class -@code{unit}, and one direct child @code{unit} have the class @code{final}. - -@c All elements having 'input-list' ∈ =class= - -@c Direct children must all have 'unit' ∈ =class= -@c One direct child must have 'final' ∈ =class= - -@defmethod input_list get_value - -@example -querySelectorAll('input') - .map(x => x.value) - .join(@var{joinby}) -@end example -@end defmethod - -@defivar input_list [data-]joinby - Alternative character to join by -@end defivar - -@defivar input_list [data-]bindby - replacement for get_value -@end defivar - -binds =get_value= on instances, by default returning the value -of all == tags joined by =,=. This can be overwritten with - -TODO: instead, override value? - -=addEventList('input',= is overwritten, registering the listener for all input -elements. - - - ∀ children('.input-list') => 'unit' ∈ classList(child) - -
-
-
-
- -@defun init_input_list -@end defun diff --git a/doc/ref/javascript/jcal.texi b/doc/ref/javascript/jcal.texi index 4be8d33b..997b4d59 100644 --- a/doc/ref/javascript/jcal.texi +++ b/doc/ref/javascript/jcal.texi @@ -1,4 +1,7 @@ - @node jcal @subsection jcal.js +@deftypefun Document jcal_to_xcal {JCal ...} +A document with the xcal namespace, and @code{icalendar} as its root +element. Each child is a valid xcal representation of our JCal object. +@end deftypefun diff --git a/doc/ref/javascript/lib.texi b/doc/ref/javascript/lib.texi index 8adb8621..e5b13383 100644 --- a/doc/ref/javascript/lib.texi +++ b/doc/ref/javascript/lib.texi @@ -4,11 +4,6 @@ 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 @subsubsection Default prototype extensions @@ -76,10 +71,6 @@ 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. diff --git a/doc/ref/javascript/popup.texi b/doc/ref/javascript/popup.texi deleted file mode 100644 index 2dd8f48f..00000000 --- a/doc/ref/javascript/popup.texi +++ /dev/null @@ -1,5 +0,0 @@ - - -@node popup -@subsection popup.js - diff --git a/doc/ref/javascript/rrule.texi b/doc/ref/javascript/rrule.texi deleted file mode 100644 index 5d7a7576..00000000 --- a/doc/ref/javascript/rrule.texi +++ /dev/null @@ -1,4 +0,0 @@ - -@node rrule -@subsection rrule.js - diff --git a/doc/ref/javascript/script.texi b/doc/ref/javascript/script.texi deleted file mode 100644 index a60343e4..00000000 --- a/doc/ref/javascript/script.texi +++ /dev/null @@ -1,60 +0,0 @@ - -@node script -@subsection 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] -@anchor{bind_properties} -@ref{binders} - 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 - - diff --git a/doc/ref/javascript/server_connect.texi b/doc/ref/javascript/server_connect.texi index 2f50f02d..c67f47ff 100644 --- a/doc/ref/javascript/server_connect.texi +++ b/doc/ref/javascript/server_connect.texi @@ -1,2 +1,22 @@ @node server_connect @subsection server_connect.js + +Procedures for interfacing with the backend server. + +@deftypefn {Async Function} void create_event {event: VEvent} +Packs up the given event and sends it to the server to either be +created, or simply be updated in the persistant database. + +Also does some minor updates registered components, to show that the +event is actually created. +@end deftypefn + +@deftypefn {Async Function} void remove_event {uid: uid} +Requests that the server permanently remove the event with the given +unique id from its persistant storage. + +If the server responds with a success also delete it from our local +store (@code{vcal_objects}). + +@c TODO link to our backend flow here +@end deftypefn diff --git a/doc/ref/javascript/types.texi b/doc/ref/javascript/types.texi index 73a58550..b9e6dbbf 100644 --- a/doc/ref/javascript/types.texi +++ b/doc/ref/javascript/types.texi @@ -10,12 +10,16 @@ Name of all valid icalendar types. period, utc-offset, cal-address, recur, boolean, @end defvar +@deftp {Data Type} ical_type +The union of all elements in @var{all_types}. +@end deftp + @defvar property_names All known names properties (top level keys) can have. Such as ``calscale'', ``dtstart'', ... @end defvar -@defvar valid_fields +@deftypevar {Map} valid_fields Which property fields each component can hold. @verbatim @@ -23,9 +27,9 @@ Which property fields each component can hold. ... } @end verbatim -@end defvar +@end deftypevar -@defvar valid_input_types +@deftypevar {Map>} 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). @@ -36,4 +40,57 @@ the list of possibilities will contain a sub-list (see example). ... } @end verbatim +@end deftypevar + +@deftp {Data Type} tagname +Alias of (@code{'vevent'} | @code{'string'}). +@end deftp + +@deftp {Data Type} uid +Alias of @code{'string'}. +@end deftp + +@c TODO link to the RFC +@c - RFC 7265 (jCal) + +@deftp {Data Type} JCalProperty +Alias for a record consisting of +@itemize @bullet +@item the name of the type, as a string +@item All parameters of the object, as a @code{Record} + +@deftypemethod VEventValue {[Record, ical_type, any]} @ + to_jcal {} +The return value is @emph{almost} a @code{JCalProperty}, just without +the field name. +@end deftypemethod + +@end deftp + +@deftp VEvent {properties: Map} @ + {components: VEvent[]} + +Component for a single instance of a calendar event. Almost all data +access should go through @code{getProperty} and @code{setProperty}, +with the exception of the current calendar (which is accessed directly +through @code{calendar}). Almost all changes through these interfaces +are logged, and can be viewed in @var{_changelog}. + +@deftypemethod VEvent {any?} getProperty {key: string} +Returns the value of the given property if set, or undefined otherwise. + +For the keys +@itemize +@item @code{'CATEGORIES'}, +@item @code{'RESOURCES'}, +@item @code{'FREEBUSY'}, +@item @code{'EXDATE'}, and +@item @code{'RDATE'} +@end itemize +instead returns a list list of values. +@end deftypemethod + + +@deftypemethod VEvent void setProperty {key: string} {value: any} {type: ical_type?} +Sets the given property to the given value. If type is given it's +stored alongside the value, possibly updating what is already +there. Do however note that no validation between the given type and +the type of the value is done. + +@var{value} may also be a list, but should only be so for the keys +mentioned in @var{getProperty}. + +After the value is set, @var{redraw} is called on all registered +objects, notifying them of the change. +@end deftypemethod + +@deftypemethod VEvent void setProperties {[string, any, ical_type?][]} +Equivalent to running @var{setProperty} for each element in the input +list, but only calls @var{redraw} once at the end. +@end deftypemethod + +@deftypemethod VEvent {IteratableIterator} boundProperties +Returns an iterator of all our properties. +@end deftypemethod + +@deftypeivar VEvent {ChangeLogEntry[]} {_changelog} +Every write through getProperty gets logged here, and can be +consumed. Hopefully this will one day turn into an undo system. +@ref{ChangeLogEntry}. +@end deftypeivar + +@deftypeivar VEvent {string?} calendar +The name of the calendar which this event belongs to. +@end deftypeivar + +@deftypemethod VEvent void register {htmlNode: Redrawable} +Register something redrawable, which will be notified whenever this +VEvents data is updated. +@end deftypemethod + +@deftypemethod VEvent void unregister {htmlNode: Redrawable} +Stop recieving redraw events on the given component. +@end deftypemethod + +@deftypemethod VEvent JCal to_jcal +Converts the object to JCal data. +@end deftypemethod + +@end deftp + + +@deftp {class} RecurrenceRule +@deftypemethod RecurrenceRule {Record} to_jcal +Converts ourselves to JCal data. +@end deftypemethod +@end deftp + +@deftypefun RecurrencRule xml_to_recurrence_rule {Element} +Parse a XCAL recurrence rule into a RecurrenceRule object. +@end deftypefun + +@deftypefun VEvent xml_to_vcal {Element} +Parse a complete XCAL object into a JS VEvent object. +@end deftypefun -- cgit v1.2.3