dhtmlxscheduler:toc [DHX documentation]

dhtmlxScheduler

dhtmlxScheduler is a JavaScript calendar component that allows you to display and manage any kind of events and appointments through a simple and intuitive Ajax-based interface. The calendar supports Day, Week, Month, Year, and Agenda Views, and also provides the possibility to create schedules for multiple resources (people, offices, product items, etc). There are server side samples for different platforms.

There are special calendar plugins for WordPress and Joomla CMS.

More than 60 code samples, included in dhtmlxScheduler package, show you how to use different features of the calendar and simplify the learning curve of the component. You may check some online demos on Scheduler Samples page

  • What's new
  • Migration from older version
  • Common problems
  • Known issues

Main modes

  • User Interface
  • Initialization
  • Configuration and Templates
  • Events (inner events of scheduler)
  • Server Side Integration and Printing
  • Date operations
  • API Reference

Extensions

  • Recurring events
  • Units view and Timeline view
  • Agenda, Year and Map views
  • Behaviors, Limits, Collisions

Customization

  • Styling
  • Details form
  • Custom views
  • Using mini-calendar
  • Some non-trivial use-cases
  • External Drag & Drop
  • Localization

Plugins for CMS

  • WordPress
  • Joomla!
Copyright © 1998-2009 DHTMLX LTD.
All rights reserved.


dhtmlxscheduler:what_s_new [DHX documentation]

What's new

2.3

Major changes

  1. Map view was added (details)
  2. Cell mode for Timeline view was added (details)
  3. Tree mode for Timeline view was added (details)
  4. Tooltips for all views were added(details)
  5. Abbility to create new events by double click or by drag-and-drop in Timeline mode
  6. Abbility to move events by drop-and-drag in Timeline mode
  7. Abbility to create new events by external drag and drop (details)

Minor changes

  • Week-number format option was added (details)
  • full_day configuration option added (details)
  • event_duration and auto_end_date configuration options added (details)
  • Multiselect section for details form (details)
  • Checkbox, combo, radio - sections for details form (details)
  • Preventing events collisions for recurring events
  • extra parameters were added to timeline-related handlers
  • api of mini-calendar extension extended (details)
  • custom form implementation simplified (details)

Fixes

  • incorrect processing of specific iCal datasources
  • incorrect event rendering for overlapping events

2.2

Major changes

  1. Export to XML, iCal, JSON added (details)
  2. Printing to PDF (details)
  3. Loading from JSON data was added (details)
  4. Collision detection extension was added (details)
  5. Date-scale limitation extension was added (details)
  6. Mini-calendar extension was added (details)
  7. Timeline view was added (details)
  8. Auto-fetching option lists from the server (details)

Minor changes

  1. hotkeys and some element's sizes are configurable now
  2. step-like scrolling in the units view details
  3. Arabic, Hungarian, Indonesia, Polish, Slovenian locales were added details
  4. 18 new samples were added

Bug fixes

  1. many time-shifting related bugs
  2. problems with recurring events in the Agenda view
  3. problems with recurring events in the Year view

2.1

Major changes

  1. Agenda view was added details
  2. Year view was added details
  3. Bunch of small extension was added
  4. SkinBuilder for the scheduler was added
  5. Count of samples was doubled

Full list of updates

  • agenda view
  • year view
  • small extensions
  • onEventSave event is added
  • onSchedulerResize event is added
  • Finnish and Dutch locales are added
  • Chinese locale is added
  • Portuguese translation is added for scheduler
  • time_picker tempalte is introduced
  • event_date tempalte is introduced
  • incorrect layout in case of multi-week events (#808)
  • incorrect rendering of editor in IE6
  • incorrect event-bar size in complex dynamic patterns
  • error during js commands against non-visible events
  • incorrect processing of time_step if it was defined as string (#788)
  • unnecessary scrolls in IE (#776)
  • incorrect end date of week scale label (#621)
  • incorrect drag on item, which is in adding process (#782)
  • incorrect placing multi-day events inside of unit view (#784)
  • setting end date lesser than start date (#781)
  • issue with incorrect processing of unknown css is fixed
  • incorrect outlining in Chrome and Safari
  • incorrect position of lightbox on scrollable page
  • summer|winter time transition is fixed
  • fixed issue with multi_day zone rendering while deleting|adding events
  • problem with incorrect recurring view, after resize in edit mode, is fixed
  • event editor doesnt close if “onClick” event is disabled (#617)
  • incorrect processing of 12AM while parsing the string to date

2.0

Major changes

  1. Added support of Recurring events
  2. Added ability to create Units view
  3. Multi-day events can be seen in Day and Week mode ( scheduler.config.multi_day = true; )
  4. Month view can auto-size to prevent data overflow
  5. Added ability to create custom views

Full list of updates

  • (upd)2-way loading cache and 2-way prefetching in dyn. loading mode
  • (upd)clearAll reset loading cache
  • (upd)dblclick_create option added
  • (upd)debug version correctly shows responses of dataprocessor
  • (upd)event can't be created by right button click anymore
  • (upd)format of dyn. loading dates moved to config
  • (upd)if new event creation through d-n-d was started, while previously created event not saved yet - correct confirmation sequence will be executed
  • (upd)images of main tabs updated
  • (upd)locales for recurring events is added
  • (upd)multi day events are styled
  • (upd)onClick event of scheduler is blockable now, and occurs in both editable and readonly modes
  • (upd)onEventCreated receives correct native event object
  • (upd)position of main container changed to relative
  • (upd)possibility of filtering
  • (upd)scheduler correctly process first_hour, last_hour settings , if they was defined as strings
  • (upd)scroll_hour config option added
  • (upd)shift-enter key creates new line in textarea editor
  • (upd)updated to connector 1.x
  • (upd)way of event coping changed
  • (upd)when current view changed - currently active editor is closed ( default closing sequence is executed ) (#407, #404)
  • (add)ability to create custom daily views
  • (add)ability to create custom view
  • (add)ability to create unit view
  • (add)ability to define css classes for days of week|month added
  • (add)ability to show multi-day events on weekly and daily views added
  • (add)adjustable height of event bars
  • (add)auto-height in month view
  • (add)config.readonly added
  • (add)correct lightbox in case of multiline event text
  • (add)extra inner events added
  • (add)getEvents method added
  • (add)onContextMenu event added
  • (add)onEventAdded will not fire while loading
  • (add)onTemplatesReady event added
  • (add)optional loading bar added
  • (add)property extension added
  • (add)recurring event can be switched back to normal state
  • (add)separate css class for item in drag state added
  • (add)support of recurring events added
  • (add)update_render option added
  • (fix)auto x-scroll during text focusing disabled (#410)
  • (fix)debug alert for incorrect xml blocked by default
  • (fix)double border of recurring editor removed
  • (fix)fixed bug in recurring module (IE7 compatibility )
  • (fix)fixed error in repeating by fixed day of week
  • (fix)fixed error with missed error in recurring form
  • (fix)fixed error with style changes of event, after dp. response
  • (fix)fixed error with updating serie of events, one of which was deleted in different time scale
  • (fix)fixed incorrect am|pm time formatting
  • (fix)fixed incorrect end date, while creating date by d-n-d in month view
  • (fix)fixed incorrect event positioning, when start or end time exceeds time limits of scale (#371)
  • (fix)fixed incorrect filter name processing
  • (fix)fixed incorrect icon on details view in IE6 (#393)
  • (fix)fixed incorrect issue with end date calculation , when few recurring events created one by one (#441)
  • (fix)fixed incorrect mouse coordinates , when we have outer scroll in IE
  • (fix)fixed incorrect positioning in case of custom daily view
  • (fix)fixed incorrect processing of details_on_dblclick option
  • (fix)fixed incorrect processing of end-repeat-date parameter (#422)
  • (fix)fixed incorrect rendering of events which created on border of weekly view (#434)
  • (fix)fixed incorrect rendering of initial creation in unit view (#408)
  • (fix)fixed incorrect repeating in case of day-workday mode (#416)
  • (fix)fixed incorrect transposition of week-days repeating
  • (fix)fixed incorrect y-scale size for small hour size (#383)
  • (fix)fixed issue with deleting seria with modified events out of view
  • (fix)fixed issue with description form corruption because of very long title (#412)
  • (fix)fixed issue with getEvents and non-recurring events
  • (fix)fixed issue with incorrect cursor state for disabled events (#384, #385)
  • (fix)fixed issue with incorrect month-day transposition (#428)
  • (fix)fixed issue with incorrect property setters|getters
  • (fix)fixed issue with incorrect restoring of d-n-d after mouse was moved out of window borders (#376)
  • (fix)fixed issue with rec-type selection in IE ( GUI ) #362
  • (fix)fixed mouse cursor twitching during event resize (#380)
  • (fix)fixed problem with deleting sub-events in series
  • (fix)fixed problem with drag over day borders
  • (fix)fixed problem with incorrect bar positioning in month view
  • (fix)fixed problem with incorrect calculation days in first weak in case of repeating
  • (fix)fixed problem with long events in day view
  • (fix)fixed problem with new non-rec event creation
  • (fix)fixed problem with rendering in dyn.loading mode
  • (fix)fixed typo in unit-view sample
  • (fix)fixed unnecessary scroll in editor in IE (#392)
  • (fix)incorrect position of events in daily multi-day view
  • (fix)incorrect selection bar position in case of multi-day mode enabled (#398)


dhtmlxscheduler:loading_from_json [DHX documentation]

Loading from JSON

Loading from an object

scheduler.config.xml_date="%Y-%m-%d %H:%i";
scheduler.init('scheduler_here',new Date(2009,6,1),"week");
scheduler.parse([
    { start_date:"2009-7-1 6:00", end_date:"2009-7-1 8:00", text:"Some text"},
    { start_date:"2009-7-2 6:00", end_date:"2009-7-2 8:00", text:"Some text"}
],"json");

Loading from a file

scheduler.config.xml_date="%Y-%m-%d %H:%i";
scheduler.init('scheduler_here',new Date(2009,5,1),"week");
scheduler.load("data.json","json");


dhtmlxscheduler:faq [DHX documentation]

Common problems and questions

Scheduler doesn't render correctly

Check styles of the scheduler container. It must have a valid size in pixels of percents. If size defined in percents - be sure that parent container has some height settings as well.

When scheduler placed directly in body , you need to have next css style, to use percent based height correctly

    html, body{
        margin:0px;
        padding:0px;
        height:100%; /*mandatory*/
        overflow:hidden;
    }
Scheduler renders in IE incorrectly

Be sure that you page use a full doctype. Scheduler can work correctly in standard mode of IE6, IE7 and IE8. Scheduler not purposed to be used with quirks mode of IE.

Multi day events are not rendered in daily and weekly views

Can be enabled by adding next line

  scheduler.config.multi_day = true;
Scheduler fails to init with custom view activated (custom views)

Custom view must be defined on moment of initialization, if you want to use it as default one. On other hand, default templates will be initialized only after scheduler initialization, and can't be used for new view creating before that moment. To catch the moment, when templates are ready and active mode is not set yet - you can use onTemplatesReady event.

          scheduler.attachEvent("onTemplatesReady",function(){
                 //here, you can place code for custom view creation
          })
          scheduler.init(container, date, "custom view name");


dhtmlxscheduler:known_issues [DHX documentation]

Known issues

Problems, which are described below, are related to the scheduler 2.3

Problem: in case of Brazil timezone, during summer time shift, scheduler can render double days ( so far, there was only few reports from users of Brazil-version of Windows, problem doesn't appear for any other type of OS )
Symptom: double days in month view
Affected versions: all versions
Patch: http://support.dhtmlx.com/x-files/scheduler_2_1/brazil_patch.zip
Patch need to be included on the page after other js files.


dhtmlxscheduler:user_interface [DHX documentation]

GUI of scheduler

Overview

dhtmlxScheduler is a user-friendly event scheduler component which allows you to present and schedule any event such as board meeting, business lunch, conference call, family reunion, movie night, or any other group event. You are allowed to create, edit, delete and drag-and-drop events in the scheduler.

dhtmlxScheduler manipulation is quite easy. Let’s begin.

First of all you should know that dhtmlxScheduler is able to schedule events for days, weeks and months. To set your time mode, you should select one of three available modes in the time mode panel located on the right side of the calendar panel.

Backward/forward arrows on the left side of the calendar panel allow you to move within calendar dates. Today button enables you to turn to the current date. The selected date period is specified behind today button. Hours scale is located on the left side of the scheduler.

Creating a New Event

To create a new event, double click on desired date field. After that “New event” window appears.

Here you can enter the event name and set start and end time of the event. To save the event in the calendar, click Save button on the bottom left corner of the window. If you would like to escape this window without saving the event, click Cancel.

One more way to create a new event is to press the left button of the mouse and drag date area to define the date period of the event. This can be done in Day, Week or Month views.

Editing Event

To change the event details, click on the event box. A small bar will appear on the left of the event box. Click the appropriate button to edit event name or details, or delete the event.

When you click Details button, a window with event details appears. It's the same window as you've seen when you created an event - here you can change event description and time period. To call this window, you can also double-click on the necessary event box.

To change event date and time, you can also drag the event box in Week/Month View to the necessary date field. In Day View you can change the event time by dragging the event box and changing its size.

Setting a Multiday Event

There is a possibility to set a multiday event. You can do it in “New event” window when you set start and end dates of the event.

Drag-and-Drop in dhtmlxScheduler

dhtmlxScheduler supports drag-and-drop, thus you are allowed to create events or move the existing ones within calendar area accordingly to your needs.

Deleting an Event

There are two ways to delete an event:

  1. Click the appropriate button in the left bar of the event.
  2. Call Details window and click Delete button on the bottom right corner.


dhtmlxscheduler:initialization [DHX documentation]

Initialization

Requirements

  • Any of supported browsers;
  • HTML page in standard mode ( any correct doctype ).

Includes

    <script src="codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="codebase/dhtmlxscheduler.css" type="text/css" charset="utf-8">

Initialization

    <div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
        <div class="dhx_cal_navline">
            <div class="dhx_cal_prev_button">&nbsp;</div>
            <div class="dhx_cal_next_button">&nbsp;</div>
            <div class="dhx_cal_today_button"></div>
            <div class="dhx_cal_date"></div>
            <div class="dhx_cal_tab" name="day_tab" style="right:204px;"></div>
            <div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
            <div class="dhx_cal_tab" name="month_tab" style="right:76px;"></div>
        </div>
        <div class="dhx_cal_header">
        </div>
        <div class="dhx_cal_data">
        </div>
    </div>

Now the scheduler object can be initialized. Unless other dhtmlx components , scheduler is static object (only one instance can exist on the page). You can use name dhtmlXScheduler or just scheduler to point to the object.

       scheduler.init('scheduler_here',null,"week");
       scheduler.load("events.xml");

When loading data from connector or any other dynamical source, it may be necessary to issue one more command - describe in which format data will be provided. In case of MySQL database it will be

       scheduler.config.xml_date="%Y-%m-%d %H:%i";
       scheduler.init('scheduler_here',null,"week");
       scheduler.load("connector.php");

Starting from scheduler 2.2, it possible to use an alternative db-less data saving method.


dhtmlxscheduler:export [DHX documentation]

Export data from the scheduler

Base prepartions

To activate such functionality you need to include dhtmlxscheduler_serialize.js

<script src='codebase/ext/dhtmlxscheduler_serialize.js'></script>

Export to XML

You may use the toXML method to serialize scheduler data to xml string:

var xml = scheduler.toXML(); //xm string

Export to JSON

It is also possible to get scheduler events in JSON format. Use toJSON in this case:

var json_string = scheduler.toJSON(); //json string

Warning - method returns json string, not object. If you need an object - use getEvents method

Export to iCal

Serialization to iCal string requires toICal method. The next command and both methods, that are described above, can be used at any moment of time.

var ical_string = scheduler.toICal();

Attributes in serialization

The following technique is not applicable for the iCal format.

By default export will include only standard attributes(properties)

  1. id
  1. text
  1. start_date - format of seriaization is defined by scheduler.config.xml_date
  1. end_date

If you need to include some custom attributes, you can redefine data_attributes method, in simplest case it will look as

scheduler.data_attributes = function(){

    return [

        ["id"],["text"],["date_start"],["date_end"],

        ["custom_attribute"]

    ];

};

Basically, the method defines the list of attirubute names.

But you can define the formatting function, which describes how attribute data needs being processed before serialization.

It can be useful for dates those need converting before to be placed in XML

scheduler.data_attributes = function(){

return [

    ["id"],

    ["text"],

    ["start_date",scheduler.templates.xml_format],

    ["end_date",scheduler.templates.xml_format]];

}

Serializing recurring events

Below technique is not applicable for the iCal format.

If you are using “recurring” extension, you need to define extra attributes, which are used by recurring events

scheduler.data_attributes = function(){

    var empty = function(a){ return a||""; }

    return [["id"],

            ["text"],

            ["start_date",scheduler.templates.xml_format],

            ["end_date",scheduler.templates.xml_format],

            ["rec_type",empty],

            ["event_length",empty],

            ["event_pid",empty]];

}

DB-less data saving

Serialization allows to implement the simple routine of data saving, which doesn't require DB - data will be stored in XML file.

(1) Firstly, you need to include serialization extension

<script src='codebase/ext/dhtmlxscheduler_serialize.js'></script>

(2) The next step - place hidden form for data saving

<form id="xml_form" action="xml_writer.php" method="post" target="hidden_frame" accept-charset="utf-8">

    <input type="hidden" name="data" value="" id="data">

</form>

(3) Then you need to place “Save” button on the page

<input type="button" name="save" value="save" onclick="save()" style="right:300px; width:80px; position:absolute; top:1px;">

function save(){

    var form = document.getElementById("xml_form");

    form.elements.data.value = scheduler.toXML();

    form.submit();

}

(4) on server side, you just need to write the data in an existent file. xml_writer.php could be as follows:

<?php

    file_put_contents("./data.xml",$_POST["data"]);

?>

the empty data.xml is:

<data></data>

That is all, now scheduler can be loaded from data.xml, pressing “save” button will serialize the current state of the scheduler to xml and save back to the file.

So on next loading the scheduler will load events those have been saved previously.

Related samples

In the scheduler package you can find ready samples:

  • dhtmlxScheduler\samples\04_export\01_serialize_xml.html
  • dhtmlxScheduler\samples\04_export\02_serialize_json.html
  • dhtmlxScheduler\samples\04_export\03_serialize_ical.html
  • dhtmlxScheduler\samples\04_export\05_serialize_recurring.html

Troubleshooting

If, during data saving, you encounter unwanted data escaping (\” in the saved data) - be sure that “magic_quotes” is disabled in php configuration.


dhtmlxscheduler:api_reference [DHX documentation]

dhtmlxScheduler API Methods

Core

  • addEvent - adds new event
  • attachEvent - attaches an event handler to Scheduler
  • changeEventId - changes event id
  • clearAll - clears all data in scheduler.
  • deleteEvent - deletes existing event
  • detachEvent - removes an event handler
  • editStop - switches from editing mode to normal mode, disable editor if it's open
  • edit - edits event
  • endLightbox - used as part of custom lightbox form implementation
  • getEventEndDate - returns end date of event
  • getEventStartDate - returns start day of event
  • getEventText - returns event text
  • getEvent - returns event object by id
  • getEvents - returns collection of events, which occurs in defined period
  • getLabel - returns label text by option's id and property name (ver. 2.3+)
  • getState - returns details about current state of the scheduler (ver. 2.3+)
  • init - init scheduler
  • load - loads data in scheduler
  • parse - load self from JSON object or XML string
  • select - selects event
  • setCurrentView - sets the current mode and displayed date
  • setEventEndDate - sets end date of event
  • setEventStartDate - sets start date of event
  • setEventText - sets event text
  • setLoadMode - sets auto-loading mode
  • setLightboxSize - update size of details form
  • showLightbox - shows details form for the event
  • startLightbox - used as part of custom lightbox form implementation
  • resetLightbox - forces lightbox form re-creation
  • uid - returns unique ID ( unique inside current scheduler, not GUID )
  • unselect - unselects event
  • updateEvent - forces event updating

Units view

  • createUnitsView - create units view

Timeline view

  • createTimelineView - create timeline view

Tree-Timeline view

  • openSection - opens specified section (ver. 2.3+)
  • closeSection - closes specified section (ver. 2.3+)
  • openAllSections - opens all sections (ver. 2.3+)
  • closeAllSections - closes all sections (ver. 2.3+)
  • addSection - adds new section to specified parent section (ver. 2.3+)
  • deleteSection - deletes specified section (ver. 2.3+)
  • getSection - returns section object by id (ver. 2.3+)

Expand behavior

  • expand - switch to full screen mode
  • collapse - collapse back to normal size

Mini-calendar extension

  • renderCalendar - crate mini-cal
  • destroyCalendar - destroy mini-cal
  • isCalendarVisible - check is popup minical visible
  • markCalendar - mark some date in mini-cal
  • unmarkCalendar - unmark some date in mini-cal
  • updateCalendar - updates minicalendar view (ver. 2.3+)
  • linkCalendar - links minicalendar to scheduler (ver. 2.3+)

Serialize extension

  • toPDF - convert to the PDF
  • toXML - serialize self to XML string
  • toJSON - serialize self to JSON string
  • toICal - serialize sefl to iCal format

Recurring events extension

  • getRecDates - returns all occurrences of a recurring event (ver. 2.3+)


dhtmlxscheduler:addEvent [DHX documentation]

addEvent(start_date, end_date, text, id, data)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

adds a new event

  • start date - date object or string;
  • end date - date object or string;
  • text;
  • id - optional, will be auto-generated if skipped;
  • other data - hash.
   scheduler.addEvent("16-03-1984","19-03-1984","Some");
//or
   scheduler.addEvent("16-03-1984","19-03-1984","Some","some id",{custom_data:"some data"});
//or
   scheduler.addEvent({
          start_date: "16-03-1984",
          end_date: "19-03-1984",
          text:"Some",
          custom_data:"some data"
   });

scheduler.config.api_date used to parse incoming dates


dhtmlxscheduler:attachEvent [DHX documentation]

attachEvent (evName, evHandler)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

adds any user-defined handler to available events

  • evName - name of the event;
  • evHandler - user-defined event handler.
              scheduler.attachEvent(evName, evHandler);

Several handlers can be attached to one and the same event, and all of them will be executed.

Note: the names of the events are case-insensitive.


dhtmlxscheduler:changeEventId [DHX documentation]

changeEventId(old_id, new_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

change event id

  • old id;
  • new id.


dhtmlxscheduler:clearAll [DHX documentation]

clearAll()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

clear all data in scheduler


dhtmlxscheduler:deleteEvent [DHX documentation]

deleteEvent(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

delete existing event

  • event id


dhtmlxscheduler:detachEvent [DHX documentation]

detachEvent (id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

removes an event handler

  • id - event id
              scheduler.detachEvent(id);


dhtmlxscheduler:editStop [DHX documentation]

editStop(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

switch from editing mode to normal mode, disable editor if it's open

  • event id


dhtmlxscheduler:edit [DHX documentation]

edit(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

edit event

  • event id


dhtmlxscheduler:endLightbox [DHX documentation]

endLightbox(mode, custom_form)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

Method will hide custom form, remove modal cover, and exec after-saving operations if necessary. Can be used as part of custom lightbox form.

  • result of edit operation, false - cancel, true - data need to be saved
  • html container of the form, optional
     scheduler.endLightbox(false);
     //or
     scheduler.endLightbox(true, document.getElementById("my_form"));


dhtmlxscheduler:getEventEndDate [DHX documentation]

getEventEndDate(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

return end date of event by id

  • event id


dhtmlxscheduler:getEventStartDate [DHX documentation]

getEventStartDate(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

return start date of event by id

  • event id


dhtmlxscheduler:getEventText [DHX documentation]

getEventText(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

returns text of event by id

  • event id.


dhtmlxscheduler:getEvent [DHX documentation]

getEvent(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

return event object by id

  • event id


dhtmlxscheduler:getEvents [DHX documentation]

getEvents(from, to)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

returns collection of events, which occurs in defined period

  • from {date object}
  • to {date object}

method will return an array of event objects, which started before *to* date, and finished after from date.

    var evs = scheduler.getEvents(new Date(2009,1,10),new Date(2009,1,25));
    for (var i=0; i<evs.length; i++)
          alert(evs[i].text);


dhtmlxscheduler:getLabel [DHX documentation]

getLabel(property, key)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

returns label text by option's id and property name

  • property — map_to parameter of the option
  • key — option's id

For example, following code was used to create select:

var sections=[
    {key:1, label:"James Smith"},
    {key:2, label:"John Williams"},
    {key:3, label:"David Miller"},
    {key:4, label:"Linda Brown"}
];
scheduler.config.lightbox.sections=[
    {name:"description", height:130, map_to:"text", type:"textarea" , focus:true},
    {name:"custom", height:23, type:"select", options:sections, map_to:"section_id" },
    {name:"time", height:72, type:"time", map_to:"auto"}
]

To get “Linda Brown” label one should use:

scheduler.getLabel("section_id", 4)


dhtmlxscheduler:getState [DHX documentation]

getState()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

returns object with details about current state of the scheduler

  • mode — current scheduler's mode, e.g. “week”, “month”
  • date — current date which is shown in scheduler
  • min_date — events are rendered from this date on the current view
  • max_date — events are rendered till this date on the current view
  • editor_id — editor id if it is present
  • lightbox_id — lightbox id if it is present

Note: scheduler's behavior can not be changed by modifying this object.

For example, function can be used the following way:

if (scheduler.getState.mode == "month") {
    // custom logic
}


dhtmlxscheduler:init [DHX documentation]

init(contaner_id, date, mode)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

initialize scheduler

  • container id - id or object of html container, inside which the scheduler will be created
  • date - js date object, initial date in scheduler, optional - current date will be used by default
  • mode - name of default mode as string ( “month”,”day”,”week” ), optional - “week” by default

Method must be called only once.


dhtmlxscheduler:load [DHX documentation]

load(url, callback)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

load data from external file

  • url - server side url ( may be a static xml or server side script which outputs data as XML )
  • callback - callback method, optional

Supported data formats

   scheduler.load("data.xml");
   scheduler.load("data.php",function(){
          alert("data loaded");
   });
   scheduler.load("data.ical","ical"); //loading data in ical format
   scheduler.load("data.json","json"); //loading data in ical format


dhtmlxscheduler:parse [DHX documentation]

parse(data, type)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

load data from client side resource

  • url - string or object , which represents data
  • type - data type, can be “json” for loading from json object
   scheduler.parse("<data>...</data>");
   scheduler.parse([
    { start_date:"2009-7-1 6:00", end_date:"2009-7-1 8:00", text:"Event 1"},
    { start_date:"2009-7-2 6:00", end_date:"2009-7-2 8:00", text:"Event 2"}
   ],"json");


dhtmlxscheduler:select [DHX documentation]

select(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

select event

  • event id


dhtmlxscheduler:setCurrentView [DHX documentation]

setCurrentView(date, mode)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

sets the current mode and displayed date

  • date - date object, which defines current view date;
  • mode - string, current view mode;
    • day;
    • week;
    • month.


dhtmlxscheduler:setEventEndDate [DHX documentation]

setEventEndDate(event_id, end_date)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js set end date for event

  • event id;
  • new end date ( date object ).


dhtmlxscheduler:setEventStartDate [DHX documentation]

setEventStartDate(event_id, start_date)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

set start date for event

  • event id;
  • new start date ( date object ).


dhtmlxscheduler:setEventText [DHX documentation]

setEventText(event_id, text)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

set text for event

  • event id;
  • new text.


dhtmlxscheduler:setLoadMode [DHX documentation]

setLoadMode(mode)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

set auto-loading mode

  • mode-string:
    • day;
    • week;
    • month;
    • year.


dhtmlxscheduler:setLightboxSize [DHX documentation]

setLightboxSize()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

force lightbox auto-sizing, can be used to update lightbox size after hiding|showing some section

    scheduler.setLightboxSize();


dhtmlxscheduler:showLightbox [DHX documentation]

showLightbox(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

shows details form for the event

  • event id
     scheduler.showLightbox("some_id");


dhtmlxscheduler:startLightbox [DHX documentation]

startLightbox(event_id, custom_form)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

Method can be used as start part of custom lightbox form, it will block scheduler and show provide html container at center of the screen. The pair endLightbox command can be used to hide the custom lightbox form.

  • event id
  • html element of custom form
     scheduler.startLightbox("some_id");
     //or
     scheduler.startLightbox("some_id", document.getElementById("my_form"));


dhtmlxscheduler:resetLightbox [DHX documentation]

resetLightbox()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

command erases already created lightbox form, so next time, when it will be required, scheduler regenerate new form based on scheduler.config.lightbox

     scheduler.resetLightbox();

Command can be used if you need to change the configuration of the lightbox form dynamically.


dhtmlxscheduler:uid [DHX documentation]

uid()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

return unique ID (unique inside the current scheduler, not GUID)


dhtmlxscheduler:unselect [DHX documentation]

unselect(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

unselect event

  • event id - optional, if not provided , then currently selected event will be unselected


dhtmlxscheduler:updateEvent [DHX documentation]

updateEvent(event_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler.js

force event updating

  • event id
    scheduler.getEvent("someId").text = "new text"; //change data of event
    scheduler.updateEvent("someId"); // render updated event


dhtmlxscheduler:createUnitsView [DHX documentation]

createUnitsView(configuration)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_units.js

create a units view

Method accepts only one parameter - configuration object

scheduler.createUnitsView({
    name:"unit",
    property:"section_id",
    list:
        [	{key:1, label:"Section A"},
            {key:2, label:"Section B"},
            {key:3, label:"Section C"},
            {key:4, label:"Section D"}	],
    size:10,
    step:5
});
  • name - name of view
  • map_to - name of event property, to which view will be mapped
  • list - data structure, which contains info about x-scale of units view
  • size - optional, count of units on the screen ( if real count exceeds this value, scroll buttons will be shown )
  • step - step of scrolling


dhtmlxscheduler:createTimelineView [DHX documentation]

createTimelineView(configuration)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_timeline.js

create a timeline view

Method accepts only one parameter - configuration object

scheduler.createTimelineView({
     name:		"timeline",
     x_unit:	"minute",
     x_date:	"%H:%i",
     x_step:	30,
     x_size:	24,
     x_start:	16,
     x_length:	48,
     y_unit:
         [	{key:1, label:"Section A"},
            {key:2, label:"Section B"},
            {key:3, label:"Section C"},
            {key:4, label:"Section D"}	],
     y_property:"section_id",
     render:	"bar"
});
Parameters of createTimelineView
  • name - name of mode, same as name of the tab in html template ( you can have few different timelines, with different name , at the same time )
  • render - need to be set as “bar”, this parameter is reserved for future updates

X scale

  • x_unit - size of units on X scale ( can be minute, hour, day, week, month, year )
  • x_step - size of single scale step ( size defined in “x_unit”s)
  • x_size - how must steps need to be shown
  • x_start - value of minimal step
  • x_length - how much x_step need to be used to fill the whole day ( it is necessary only if you are using minute or hour as x_unit )

Y scale

  • y_property - name of event's property
  • y_unit - list of options for the property


dhtmlxscheduler:openSection [DHX documentation]

openSection(section_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

opens specified section in current Timeline-Tree view.

  • section id

For example, if Timeline-Tree view used the following snippet:

scheduler.createTimelineView({
        ...
    y_unit: [
        {key:10, label:"Web Testing Dep.", open: false, children: [
            {key:20, label:"Elizabeth Taylor"},
            {key:30, label:"Managers", open: false, children: [
                {key:40, label:"John Williams"},
                {key:50, label:"David Miller"}
            ]},
            {key:60, label:"Linda Brown"},
            {key:70, label:"George Lucas"}
        ]},
        {key:80, label:"Kate Moss"},
        {key:90, label:"Dian Fossey"}
    ],
        ...
});

Then to open “Web Testing Dep.” folder execute:

scheduler.openSection(10);


dhtmlxscheduler:closeSection [DHX documentation]

closeSection(section_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

closes specified section in current Timeline-Tree view.

  • section id

For example, if Timeline-Tree view used the following snippet:

scheduler.createTimelineView({
        ...
    y_unit: [
        {key:10, label:"Web Testing Dep.", open: true, children: [
            {key:20, label:"Elizabeth Taylor"},
            {key:30, label:"Managers", open: true, children: [
                {key:40, label:"John Williams"},
                {key:50, label:"David Miller"}
            ]},
            {key:60, label:"Linda Brown"},
            {key:70, label:"George Lucas"}
        ]},
        {key:80, label:"Kate Moss"},
        {key:90, label:"Dian Fossey"}
    ],
        ...
});

Then to close “Managers” folder execute:

scheduler.closeSection(30);


dhtmlxscheduler:openAllSections [DHX documentation]

openAllSections()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

opens all sections in current Timeline-Tree view.

scheduler.openAllSections();


dhtmlxscheduler:closeAllSections [DHX documentation]

closeAllSections()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

closes all sections in current Timeline-Tree view.

scheduler.closeAllSections();


dhtmlxscheduler:addSection [DHX documentation]

addSection(section_object, parent_section_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

adds section to specified parent section in current Timeline-Tree view.

  • section object
  • parent section id

Note: if section is added to the root then null should be specified as parent_section_id.

Returns true if section was added successfully and false in other cases, e.g. incorrect parent_section_id was specified.

For example, if Timeline-Tree view used the following snippet:

scheduler.createTimelineView({
        ...
    y_unit: [
        {key:10, label:"Web Testing Dep.", open: false, children: [
            {key:20, label:"Elizabeth Taylor"},
            {key:30, label:"Managers", open: false, children: [
                {key:40, label:"John Williams"},
                {key:50, label:"David Miller"}
            ]},
            {key:60, label:"Linda Brown"},
            {key:70, label:"George Lucas"}
        ]},
        {key:80, label:"Kate Moss"},
        {key:90, label:"Dian Fossey"}
    ],
        ...
});

Then to add another section to Managers folder execute:

scheduler.addSection( {key: 100, label: "Alice Green" }, 30);


dhtmlxscheduler:deleteSection [DHX documentation]

deleteSection(section_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

deletes specified section in current Timeline-Tree view.

  • section id

Note: if deleted section is a folder then all it's children will be deleted as well.

Returns true if section was deleted successfully and false in other cases, e.g. incorrect section_id was specified.

For example, if Timeline-Tree view used the following snippet:

scheduler.createTimelineView({
        ...
    y_unit: [
        {key:10, label:"Web Testing Dep.", open: false, children: [
            {key:20, label:"Elizabeth Taylor"},
            {key:30, label:"Managers", open: false, children: [
                {key:40, label:"John Williams"},
                {key:50, label:"David Miller"}
            ]},
            {key:60, label:"Linda Brown"},
            {key:70, label:"George Lucas"}
        ]},
        {key:80, label:"Kate Moss"},
        {key:90, label:"Dian Fossey"}
    ],
        ...
});

Then to delete section “Linda Brown” execute:

scheduler.deleteSection(60);


dhtmlxscheduler:api_method_dhtmlxscheduler_getsection [DHX documentation]

closeSection(section_id)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_treetimeline.js

returns section object by id in current Timeline-Tree view.

  • section id

For example, if Timeline-Tree view used the following snippet:

scheduler.createTimelineView({
        ...
    y_unit: [
        {key:10, label:"Web Testing Dep.", open: true, children: [
            {key:20, label:"Elizabeth Taylor"},
            {key:30, label:"Managers", open: true, children: [
                {key:40, label:"John Williams"},
                {key:50, label:"David Miller"}
            ]},
            {key:60, label:"Linda Brown"},
            {key:70, label:"George Lucas"}
        ]},
        {key:80, label:"Kate Moss"},
        {key:90, label:"Dian Fossey"}
    ],
        ...
});

Then to get “Managers” section execute:

scheduler.getSection(30);

Following object would be returned:

{
    key: 30,
    label: "Managers",
    open: true,
    level: 1,
    children: [
        {
            key: 40,
            label: "John Williams",
            level: 2
        },
        {
            key: 50,
            label: "David Miller",
            level: 2
        }
    ]
}


dhtmlxscheduler:expand [DHX documentation]

expand()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_expand.js

expands scheduler to the full screen view

    scheduler.expand();


dhtmlxscheduler:collapse [DHX documentation]

collapse()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_expand.js

collapses expanded scheduler back to normal size

    scheduler.collapse();


dhtmlxscheduler:renderCalendar [DHX documentation]

renderCalendar(configuration)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

The only parameter - configuration object

    scheduler.renderCalendar({
        container:"for_calendar"
        date:some_date,
        navigation:true,
        handler:function(date,calendar){
        }
    });
  • container - optional, html container, inside each calendar will be rendered; can be ID of html element or HTML object
  • position - optional, defines position of calendar; can be a set of coordinates or ID of html object
  • date - date, which will be shown in calendar
  • nativation - boolean, enables or disables month navigation buttons
  • handler - onclick handler, receives clicked data and calendar object

method returns calendar object, which can be used as parameter for destroyCalendar, markCalendar, unmarkCalendar

scheduler.renderCalendar({
    container:"for_calendar",
    date:new Date()
});
scheduler.renderCalendar({
    position:"some_id",
    date:new Date()
});
scheduler.renderCalendar({
    position: { left: 100, top: 50 },
    date:new Date()
});


dhtmlxscheduler:destroyCalendar [DHX documentation]

destroyCalendar(calendar)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

destroies, previously created, mini-calendar

Parameters:

  • calendar - optional, calendar's object, when called without parameters attempts to destroy last created containerless calendar
    scheduler.destroyCalendar();
    //or
    var calendar = scheduler.renderCalendar(...);
    ...
    scheduler.destroyCalendar(calendar);


dhtmlxscheduler:isCalendarVisible [DHX documentation]

isCalendarVisible()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

returns true, when container-less calendar is shown

    var check = scheduler.isCalendarVisible();


dhtmlxscheduler:markCalendar [DHX documentation]

markCalendar(calendar, date, css)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

Adds css styling from specified date

This will work for mini-calendar only, not for the scheduler !

  • calendar - calendar object
  • date - date object, defines date which need to be marked
  • css - optional, css class which will be used for marking
    scheduler.markCalendar(calendar, new Date(2010,3,1), "my_style");


dhtmlxscheduler:api_method_dhtmlxscheduler_unmarkcalendar [DHX documentation]

markCalendar(calendar, date, css)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

Removes css styling from specified date

This will work for mini-calendar only, not for the scheduler !

  • calendar - calendar object
  • date - date object, defines date which need to be unmarked
  • css - optional, css class which was used for marking
    scheduler.unmarkCalendar(calendar, new Date(2010,3,1), "my_style");


dhtmlxscheduler:updateCalendar [DHX documentation]

updateCalendar(calendar, new_date)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

update mini-calendar, by changing currently visible date

Parameters:

  • calendar - calendar object, which was created by renderCalendar
  • new_date - new date, which need to be rendered in mini-calendar
    var calendar = scheduler.renderCalendar(...);
    ...
    scheduler.updateCalendar(calendar, new Date(2009,1,1));


dhtmlxscheduler:linkCalendar [DHX documentation]

linkCalendar(calendar, shift)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_minical.js

After such command, each time when date is changed in scheduler , it will be changed in mini-calendar as well

Parameters:

  • calendar - calendar which was created with renderCalendar call
  • shift - allows to define how date in mini-calendar will differ from one in scheduler
    var calendar = scheduler.renderCalendar(...);
    scheduler.linkCalendar(calendar);
    //next month
    scheduler.linkCalendar(calendar, function(date){
        return scheduler.date.add(date, 1, "month");
    });


dhtmlxscheduler:api_method_dhtmlxscheduler_topdf [DHX documentation]

toICal(url, mode)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_pdf.js

Convert current view to PDF ( can be used for printing )

  • url - url of server side part of PDF converter
  • mode - optional, color mode, can be “color”,”gray”,”bw”
    scheduler.toPDF("./service/generate.php","color");


dhtmlxscheduler:toXML [DHX documentation]

toXML()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_serialize.js

Return data from the scheduler, as XML string

    var str = scheduler.toXML();

Custom attributes can be configured if necessary.

Can be used with recurring events


dhtmlxscheduler:toJSON [DHX documentation]

toJSON()

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_serialize.js

Return data from the scheduler, as JSON string ( not an object! )

    var str = scheduler.toJSON();

Custom attributes can be configured if necessary.


dhtmlxscheduler:toICal [DHX documentation]

toICal(header)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_serialize.js

Return data from the scheduler, as ICal string

  • header - optional text string, which will be used as calendar's name
    var str = scheduler.toICal();
    //or
    var str = scheduler.toICal("My calendar");

Custom attributes are not supported.


dhtmlxscheduler:getRecDates [DHX documentation]

getRecDates(event_id, maximum_number)

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_recurring.js

  • event_id — id of the recurring event
  • maximum_number — maximum number of the occurrences which will be returned (by default 1000)

Returns all occurrences of a recurring event as array of objects with following properties:

  • start_date
  • end_date

For example, there is an recurring event (id: 22) which happens every 2 days from 14.00 till 15.00 on 12.10.2010 for 3 occurrences total, to get all occurrences of this event execute:

var dates = scheduler.getRecDates(22);

Dates variable will hold following array:

[
    {
      start_date: Tue Oct 12 2010 14:00:00 GMT+0300 (E. Europe Daylight Time),
      end_date: Tue Oct 12 2010 15:00:00 GMT+0300 (E. Europe Daylight Time)
    },
    {
      start_date: Tue Oct 14 2010 14:00:00 GMT+0300 (E. Europe Daylight Time),
      end_date: Tue Oct 14 2010 15:00:00 GMT+0300 (E. Europe Daylight Time)
    },
    {
      start_date: Tue Oct 16 2010 14:00:00 GMT+0300 (E. Europe Daylight Time),
      end_date: Tue Oct 16 2010 15:00:00 GMT+0300 (E. Europe Daylight Time)
    }
]


dhtmlxscheduler:units_view [DHX documentation]

Units view

Starting from dhtmlxScheduler 2.0 it possible to create a view, where x-scale is based on some property of events (on only on time).

At first, an additional js file needs being included.

    <script src="codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="codebase/dhtmlxscheduler.css" type="text/css" charset="utf-8">

    <script src="codebase/dhtmlxscheduler_units.js" type="text/javascript" charset="utf-8"></script>

After that you need to define the collection, which will be used for x-scale creation

    var sections=[
        {key:1, label:"Section A"},
        {key:2, label:"Section B"},
        {key:3, label:"Section C"},
        {key:4, label:"Section D"}
    ];

then define name of the tab and the property of events for mapping ( starting from scheduler 2.2 it's possible to load the list of sections from server side )

    scheduler.createUnitsView({
        name:"unit",
        property:"section_id",
        list:sections
    });
  • unit - any string , will be used in tab name on the next step
  • section_id - the name of event property, which holds info for x-position
  • sections - the collection that has been defined on the previous step

And finally add the new tab to html layout and register the tab label

  scheduler.locale.labels.unit_tab = "Unit"
    <div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
    <div class="dhx_cal_tab" name="unit_tab" style="right:280px;"></div>

So, you'll get the additional tab, which will shows events per sections

samples/sample_units_view.html contains a live sample

Units Scrolling

If you have too many units, you can enable step-like scrolling, by using

scheduler.createUnitsViw({
    name:"unit",
    property:"section_id",
    list:sections,
    size:10,
    step:5
});

Two additional parameters are

  • size - defines how much units must be shown on the screen
  • step - defines scroll step


dhtmlxscheduler:recurring_events [DHX documentation]

Recurring events

Interface

Starting from version 2.0, scheduler supports recurring events. To enable such functionality you need to include two additional files

  • dhtmlxscheduler_recurring.js
  • dhtmlxscheduler_recurring.css
    <script src="codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="codebase/dhtmlxscheduler.css" type="text/css" charset="utf-8">

    <script src="codebase/dhtmlxscheduler_recurring.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="codebase/dhtmlxscheduler_recurring.css" type="text/css" charset="utf-8">

All other initialization goes same as for normal scheduler.

As result you will have the “Details form” similar to next

“Enabled”|”Disabled” button at right corner of section allow enable|disable recurring for the event. In-section editor allow to choose type of event repeating and date when repeating will end.

Format of date in “end by” field, can be controlled by

  • scheduler.config.repeat_date (possible values)

If you plan to add a custom fields to the details form , be sure to check specific of form customization when recurring events are used

Server side integration

DB need to have next additional fields

  1. rec_type - varchar[64]
  2. event_length - long int
  3. event_pid - int

So connector , will look similar to next

           $scheduler->render_table("events_rec","event_id","start_date,end_date,text,rec_type,event_pid,event_length");

As in normal case, in addition to mandatory fields, any extra data can be extracted from DB.

rec_type

This data will be set automatically through scheduler interface

type of recurring encoded in string [type]_[count]_[count2]_[day]_[days]#[extra]

  • type - type of repeating “day”,”week”,”week”,”month”,”year”
  • count - how much intervals of “type” come between events
  • count2 and day - used to define day of month ( first Monday, third Friday, etc )
  • days - comma separated list of affected week days
  • extra - this info is not necessary for calculation, but can be used to correct presentation of recurring details

For example:

  • day_3___ - each three days
  • month _2___ - each two month
  • month_1_1_2_ - second Monday of each month
  • week_2___1,5 - Monday and Friday of each second week
  • none - special type value, which is used by deleted events from the serie (it will not be rendered in grid , but block recurring of repeated event in defined time)

event_length

length of event in seconds ( in case of recurring event, end data shows the moment when recurring will be finished, so separate field is necessary to store actual length )

event_pid

it possible to delete or change some events in serie - in such case, for each update, separate record created , which will point to master id , by using this field

The xml for recurring event will look as

<event id="some">
    <start_date> start date of recurring period , start date of first event in the period as well </start_date>
    <end_date> end date of recurring period </start_date>
    <text> text of event </text>
    <rec_type> recurring type </rec_type>
    <event_length> length of event in seconds </event_length>
    <event_pid>  0 for master events, or ID of master event for sub-events </event_pid>
</event>

In addition to extra fields, some logic need to be added to server side controller. ( you can check samples/reccuring_events/events_rec.php for example )

  1. if event with rec_type==none wad inserted - response must have “deleted” status
  2. if event with rec_type was updated or deleted - all records with event_pid equal to the master id must be deleted
  3. if event with event_pid value was deleted - it need to be updated with rec_type “none” instead of deleting.
    function delete_related($action){
        global $scheduler;

        $status = $action->get_status();
        $type =$action->get_value("rec_type");
        $pid =$action->get_value("event_pid");
        //when serie changed or deleted we need to remove all linked events
        if (($status == "deleted" || $status == "updated") && $type!=""){
            $scheduler->sql->query("DELETE FROM events_rec WHERE event_pid='".$scheduler->sql->escape($action->get_id())."'");
        }
        if ($status == "deleted" && $pid !=0){
            $scheduler->sql->query("UPDATE events_rec SET rec_type='none' WHERE event_id='".$scheduler->sql->escape($action->get_id())."'");
            $action->success();
        }

    }
    function insert_related($action){
        $status = $action->get_status();
        $type =$action->get_value("rec_type");

        if ($status == "inserted" && $type=="none")
            $action->set_status("deleted");
    }

    $scheduler->event->attach("beforeProcessing","delete_related");
    $scheduler->event->attach("afterProcessing","insert_related");


dhtmlxscheduler:settings_format [DHX documentation]

Date formatting

Any date configuration command accepts the next elements:

  • %d - day as number ( with leading zero );
  • %j - day as number;
  • %D - abbreviated name of the day;
  • %l - full name of the day;
  • %W - ISO-8601 week number of year, weeks starting on Monday; 1)
  • %m - month as number ( with leading zero );
  • %n - month as number;
  • %M - abbreviated name of the month;
  • %F - full name of the month;
  • %y - year as number (2 digits);
  • %Y - year as number (4 digits);
  • %h - hours (12);
  • %H - hours (24);
  • %i - minutes;
  • %s - seconds; 2)
  • %a - am or pm;
  • %A - AM or PM.
1) version 2.3+
2) version 2.1+


dhtmlxscheduler:agenda_view [DHX documentation]

Agenda view

View allows to see the list of oncoming events

Related sample: samples/03_extensions/03_agenda_view.html

Steps to enable

  • include
   <script src="../../codebase/ext/dhtmlxscheduler_agenda_view.js"></script>
   <link rel="stylesheet" href="../../codebase/ext/dhtmlxscheduler_ext.css" type="text/css">
  • add to the template
<div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
    <div class="dhx_cal_navline">
    ...
        <div class="dhx_cal_tab" name="agenda_tab" style="right:280px;"></div>

GUI details

Clicking on the “details” icon will open “details” form ( if readonly mode is not enabled )

Customization options

  • first column, event's date, uses scheduler.templates.agenda_time template
  • second column, event's text, uses scheduler.templates.agenda_text templates

Both templates can be redefined to ouput data or text in a custom format.

If you want to start agenda not from current date, but from some other date, just add the next option

scheduler.config.agenda_start = new Date(2010,1,1); //or any other desired date

Configuring agenda

required step if you want to use agenda with recurring events

You can define start and end time of agenda view as

scheduler.config.agenda_start = new Date(); //now
scheduler.config.agenda_end = scheduler.date.add(new Date(), 1, "month"); //1 month from a current date

Localization

Extension add 3 new labels , which need to be added to locale

scheduler.locale.labels.agenda_tab = "Agenda";
scheduler.locale.labels.date = "Date";
scheduler.locale.labels.description = "Description";


dhtmlxscheduler:year_view [DHX documentation]

Year view

View allows to see the list of oncoming events

Related sample: samples/03_extensions/04_year_view.html

Steps to enable

  • include
   <script src="../../codebase/ext/dhtmlxscheduler_year_view.js"></script>
   <link rel="stylesheet" href="../../codebase/ext/dhtmlxscheduler_ext.css" type="text/css">
  • add to the template
<div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
    <div class="dhx_cal_navline">
    ...
        <div class="dhx_cal_tab" name="year_tab" style="right:280px;"></div>

GUI details

Dates which have some events marked by event's color. Hovering over such date will show tooltip with list of all events, you can click on the “details” icon inside the tooltip to open “details” form ( if readonly mode is not enabled )

Customization options

Matrix of month defined by

scheduler.config.year_x = 4;
scheduler.config.year_y = 3;

you can define different layout of month by changing those values.

There are 4 new templates

  • scheduler.templates.year_date - defines the date label on the header line
  • scheduler.templates.year_month - defines header for each month block
  • scheduler.templates.year_scale_date - defines date number for each day
  • scheduler.templates.year_tooltip - defines text of event , which will be visible inside a tooltip

Localization

Extension adds 1 new labels , which need to be added to locale

scheduler.locale.labels.year_tab = "Year";


dhtmlxscheduler:behaviors [DHX documentation]

Behaviors of scheduler

Starting from version 2.1, dhtmlxscheduler includes few small extension which allow to change behavior of the scheduler in some way.

Multiple sources

Related sample: samples/03_extensions/13_multisource.html

File to include: ext/dhtmlxscheduler_multisource.js

Expected effect: scheduler will be able to use multiple source file for loading operations, including dyn. loading from multiple sources.

    scheduler.load(["first/source/some.xml","second/source/other.xml"]);

The count of sources is not limited, so you can use as many sources inside the single load command as necessary.

Keyboard navigation

Related sample: samples/03_extensions/07_navigation_plugin.html

File to include: ext/dhtmlxscheduler_key_nav.js

Expected effect: scheduler will react on “right” and “left” keys by scrolling to the next or previous time period ( next day, next week or next month, according to the currently active view )

Save state in cookie

Related sample: samples/03_extensions/08_cookies_plugin.html

File to include: ext/dhtmlxscheduler_cookie.js

Expected effect: scheduler will save its current state ( mode, and date ) in a cookies, so when same page will be opened next time, it will show it in the same state as was before page closing.

Save state in URL

Related sample: samples/03_extensions/10_url_date_plugin.html

File to include: ext/dhtmlxscheduler_url.js

Expected effect: scheduler will save its current state ( mode, and date ) in a URL, so when same page will be opened next time, it will show it in the same state as was before page closing. In addition to saving functionality, it adds the ability to provide links for specific date in scheduler.

Fullscreen view

Related sample: samples/03_extensions/05_expand_plugin.html

File to include: ext/dhtmlxscheduler_expand.js, ext/dhtmlxscheduler_ext.css

Expected effect: scheduler will have expand icon at the right corner, clicking on which will change it size to “full screen”. Second click will restore an original size.

Dates as links

Related sample: samples/03_extensions/06_links_plugin.html

File to include: ext/dhtmlxscheduler_active_links.js, ext/dhtmlxscheduler_ext.css

Expected effect: day labels in month view will become a links , clicking on which will switch scheduler to the dayly view.

HTML templates

Related sample: samples/03_extensions/09_html_templates_plugin.html

File to include: ext/dhtmlxscheduler_html_templates.js

Expected effect: adds ability to define templates directly in html code

Instead of

    scheduler.templates.event_text=function(start, end, event){
             return "<a href='http://some.com/details.php?for="+event.id+"'>"+event.text+"</a>";
    }

You can use just

<div class="template:event_text">
        <a href='http://some.com/details.php?for={event.id}'>{event.text}<a>
</div>

Readonly view

Related sample: samples/03_extensions/12_readonly_form.html

File to include: ext/dhtmlxscheduler_readonly.js, , ext/dhtmlxscheduler_ext.css

Expected effect: scheduler will be able to show details form in readonly state.

readonly state can be triggered globally

scheduler.config.readonly_form = true;

or for specific events only

scheduler.getEvent(id).readonly = true;


dhtmlxscheduler:pdf [DHX documentation]

Export to PDF

Installation

Grab the latest package from http://www.dhtmlx.com/docs/download/dhtmlxscheduler-to-pdf.zip

Unpack it somewhere under the web root ( you will need to enable php for this installation )

Necessary includes

On the scheduler page you need to include one more extension

<script src="codebase/ext/dhtmlxscheduler_pdf.js"></script>

In older versions of scheduler this file can be missing in the codebase folder, in such a case you may use the dhtmlxscheduler_pdf.js from the latest package.

Printing triggering

To export scheduler data to PDF you just need to add the button on the page, which will call the toPDF method. The parameter of toPDF method is the url of the script, which has been installed previously:

<input type="button" name="save" value="save"
onclick="scheduler.toPDF('path/to/folder/generate.php')"
style="right:300px; width:80px; position:absolute; top:1px;">

Configuring service

Client side options

The only thing, which can be controlled on client side is color-map of image. You can choose between

  1. “color” - full color printing, used by default
  2. “gray” - print in shades of black and white
  3. “bw” - uses only black and white colors
  4. “custom” - can be used to enabled custom color map ( will require php coding, check below )
  scheduler.toPDF('path/to/folder/generate.php','gray');

Server side options

generate.php contains a code, similar to the next

$scPDF = new schedulerPDF();
$scPDF->printScheduler($xml);

You can apply some custom configuration options , before executing printScheduler

Size of elements

// header height of day container in month mode
$scPDF->monthDayHeaderHeight = 6;
 // header height in month mode
$scPDF->monthHeaderHeight = 8;
 // height of month name container in year mode
$scPDF->yearMonthHeaderHeight = 8;
 // height of row in agenda mode
$scPDF->agendaRowHeight = 6;
 // height of header in day and week mode
$scPDF->dayTopHeight = 6;
 // width of left scale in day and week mode
$scPDF->dayLeftWidth = 16;

Font size

 // font size settings
$scPDF->monthHeaderFontSize = 9;
$scPDF->monthDayHeaderFontSize = 8;
$scPDF->monthEventFontSize = 7;
$scPDF->yearHeaderFontSize = 8;
$scPDF->yearFontSize = 8;
$scPDF->agendaFontSize = 8;
$scPDF->dayHeaderFontSize = 7;
$scPDF->dayScaleFontSize = 8;
$scPDF->dayEventHeaderFontSize = 7;
$scPDF->dayEventBodyFontSize = 7;
$scPDF->todayFontSize = 11;

Custom colors ( be sure to use “custom” as name of color map on client side )

$scPDF->lineColor = '586A7E';
$scPDF->bgColor = 'C2D5FC';
$scPDF->dayHeaderColor = 'EBEFF4';
$scPDF->dayBodyColor = 'FFFFFF';
$scPDF->dayHeaderColorInactive = 'E2E3E6';
$scPDF->dayBodyColorInactive = 'ECECEC';
$scPDF->headerTextColor = '2F3A48';
$scPDF->textColor = '2F3A48';
$scPDF->eventTextColor = '887A2E';
$scPDF->eventBorderColor = 'B7A543';
$scPDF->eventColor = 'FFE763';
$scPDF->todayTextColor = '000000';
$scPDF->scaleColorOne = 'FCFEFC';
$scPDF->scaleColorTwo = 'DCE6F4';
$scPDF->yearDayColor = 'EBEFF4';
$scPDF->yearDayColorInactive = 'd6d6d6';

Header and Footer

It possible to define custom header and footer for each page.

  • create images with names as “header.png” and “footer.png”
  • copy those images to the same folder where generate.php resides
  • on client side , change code call as
    scheduler.toPDF(url, "color", true, true);

As result you will have content of “header.png” and “footer.png” as header and footer on all pages in the generated pdf file.

Error reporting

If output of PDF file is failed, there must be file named as “error_report_xxxx.xml”, please send this file with any bug-reports.

If output doesn't fail, but still has some problems, you can edit generate.php and change

    $debug = false;

as

    $debug = true;

As result, there will be a new file saved, with name as “debug_xxxxx.xml” - please send it with related error report.


dhtmlxscheduler:collisions [DHX documentation]

Preventing events collisions

In many use-cases you may need to limit count of events per time slot, for example - deny creation of the second event if one event has been already defined at that time. To automate such a task the “collision” extension can be used.

To activate extension you need to include the related js file

<script src="codebase/ext/dhtmlxscheduler_collision.js"></script>

Actually that is all. From that point scheduler won't allow to create a new event or move any existent event to the timezone which is occupied by another one.

If you need to have more than one event per a time slot, you can set the collision_limit property:

scheduler.config.collision_limit = 2; //allows 2 events per a time slot

If attempt to create an event in the occupied time slot is detected, the scheduler will generate onEventCollision event

With recurring events, the extension works from version 2.3+.

Limiting date-scale

This extension allows to limit active dates ( a user won't be able to see the dates outside defined date or to create events during not-active dates )

To activate extension you need to include the dhtmlxscheduler_limit.js file

<script src="codebase/ext/dhtmlxscheduler_limit.js"></script>

and define the range:

scheduler.config.limit_start = new Date(-3999,0,0);
scheduler.config.limit_end   = new Date( 3999,0,0);

If the scheduler detects an attempt to create an event with non-allowed date, onLimitViolation event will be generated.

If you need to block not only event creation, but viewing as well , you can use

scheduler.config.limit_view  = true;

With recurring events, the extension works from version 2.3+.


dhtmlxscheduler:onEventCollision [DHX documentation]

onEventCollision Event

Parameters:

  • ev - event which creates collision
  • evs - collection of events, which already occupies the same time-slot
  scheduler.attachEvent("onEventCollision", function (ev, evs){
       //any custom logic here
  });

Event is called when user attepts to create event ( or modify some existing event ) inside already occupied time slot.

Returning false from event will allow collision situation.


dhtmlxscheduler:onLimitViolation [DHX documentation]

onLimitViolation Event

Parameters:

  • none
  scheduler.attachEvent("onLimitViolation", function (){
       //any custom logic here
  });

Event is called , when user attepts to create event ( or modify some existing event ) outside of allowed date limits


dhtmlxscheduler:minicalendar [DHX documentation]

Table of Contents
    • Mini calendar
      • Basics
      • Navigation line
      • Alternative time section
      • Templating

Mini calendar

Basics

Mini calendar provides ability to render a small month view in any html container on a page. It has an optional “on-date-selected” handler and can be used to simplify date selection or for some other tasks.

For all next use-cases you need to include on the page the following files:

   <script src='./codebase/ext/dhtmlxscheduler_minical.js' type="text/javascript" charset="utf-8"></script>
   <link rel="stylesheet" href="./codebase/ext/dhtmlxscheduler_ext.css" type="text/css" media="screen" title="no title" charset="utf-8">

The scheduler will provide two basic methods

//show mini calendar
var calendar = scheduler.renderCalendar({
    container:"some_id",
    date:new Date(),
    handler:function(date,calenda){
        do_something();
    }
});
...
//remove mini calendar
scheduler.destroyCalendar(calendar);

Starting from version 2.3, minicalendar provides two more useful methods

//after next command, mini calendar will always show and mark currently visible date range in scheduler
scheduler.linkCalendar(calendar);

//next command will change date of mini-calendar without destroying existing html objects
//so it will preserve all handlers and styles
scheduler.updateCalendar(calendar, new Date(2010,5,1));

Navigation line

To show the mini calendar in the scheduler header you can add the following lines in the HTML template

<div class="dhx_cal_navline">
    ...
    <div class="dhx_cal_date"></div>
    <div class="dhx_minical_icon" id="dhx_minical_icon" onclick="show_minical()">&nbsp;</div>

and in JS code

   function show_minical(){
      if (scheduler.isCalendarVisible())
         scheduler.destroyCalendar();
      else
         scheduler.renderCalendar({
            position:"dhx_minical_icon",
            date:scheduler._date,
            navigation:true,
            handler:function(date,calendar){
               scheduler.setCurrentView(date);
               scheduler.destroyCalendar()
            }
         });
   }

Alternative time section

It possible use mini calendar in the details form for date_start and date_end selection. To achieve such an effect you can apply “calendar_time” section type:

      scheduler.config.lightbox.sections = [
         { name:"description", height:200, map_to:"text", type:"textarea" , focus:true },
         { name:"time", height:72, type:"calendar_time", map_to:"auto" }
      ];

Templating

//top label of calendar
scheduler.templates.calendar_month =  scheduler.date.date_to_str("%F %Y");
//week label of calendar
scheduler.templates.calendar_scale_date =  scheduler.date.date_to_str("%D");


dhtmlxscheduler:timeline [DHX documentation]

Timeline view

In timeline view, vertical scale presents event holders, while vertical scale is a configurable time-scale.

The view has 3 modes:

  1. Bar mode
  2. Cell mode
  3. Tree mode

To init this view, regardless of mode type, you need to make the following steps firstly:

1. Include extra files

<script src='./codebase/ext/dhtmlxscheduler_timeline.js' type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="./codebase/ext/dhtmlxscheduler_ext.css" type="text/css" media="screen" title="no title" charset="utf-8">

2. Add new tab to the html template

<div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
<div class="dhx_cal_tab" name="timeline_tab" style="right:280px;"></div>
<div class="dhx_cal_tab" name="month_tab" style="right:76px;"></div>

Then,define the desired mode.

Bar mode

In this mode, events look like lines.

To init such mode you need to

  • define parameters of timeline
scheduler.createTimelineView({
         name:		"timeline",
         x_unit:	"minute",
         x_date:	"%H:%i",
         x_step:	1,
         x_size:	15,
         y_unit:[
              {key:1, label:"James Smith"},
          {key:2, label:"John Williams"},
          {key:3, label:"David Miller"},
          {key:4, label:"Linda Brown"}
         ],
         y_property:"section_id",
         render:	"bar"
});
  • init scheduler
scheduler.init('scheduler_here',new Date(2009,5,30),"timeline");

Cell mode

In cell mode, events 'fill' with colour full cells.

To init such mode you need to

  • define parameters of timeline
scheduler.createTimelineView({
         name:	"matrix",
         x_unit:	"day",
         x_date:	"%d %M",
         x_step:	1,
         x_size:	15,
         y_unit:[
              {key:1, label:"Elizabeth Taylor"},
          {key:2, label:"Linda Brown"},
          {key:3, label:"George Lucas"},
          {key:4, label:"John Williams"}
         ],
         y_property:"section_id",
});
  • init scheduler
scheduler.init('scheduler_here',new Date(2009,5,30),"matrix");

Hierarchical Data Structure (tree mode)

This is a novelty of 2.3 version. The feature makes possible to group names by creating multilevel folders. In addition to more convenient represantion, it allows you to specify an event not only for individual event holder but also for the whole folder (any level).

To init such mode you need to

  • include one more extra file
<script src='../../codebase/ext/dhtmlxscheduler_treetimeline.js' type="text/javascript" charset="utf-8"></script>
  • define parameters of timeline
scheduler.createTimelineView({
     section_autoheight: false,
     name:	"timeline",
     x_unit: "minute",
     x_date: "%H:%i",
     x_step: 30,
     x_size: 24,
     x_start: 16,
     x_length: 48,
     y_unit:[
              {label:"Web Testing Dep.", open: false, children: [
              {key:2, label:"Elizabeth Taylor"},
          {label:"Managers", open: false, children: [
              {key:4, label:"John Williams"},
              {key:5, label:"David Miller"}
           ]},
          {key:6, label:"Linda Brown"},
          {key:7, label:"George Lucas"}
           ]},
           {key:8, label:"Kate Moss"},
           {key:9, label:"Dian Fossey"}
         ],
     y_property: "section_id",
     render: "tree",
     folder_events_available: false,
     dy:60
});
  • init scheduler
scheduler.init('scheduler_here',new Date(2009,5,30),"timeline");

Except of monstrosity list of parameters, used in createTimelineView, it seems rather simple.

Parameters of createTimelineView

  • name - the name of a view, the same as the name of the tab in html template ( you can have few different timeline, with different name , at the same time )
  • render - the name of a mode (“bar”, “cell” or “tree”). This parameter is reserved for future updates
  • section_autoheight - assigns automatic height adjustment of the cells
  • dy - the minimal height of cells (if section_autoheight parameter has value 'false', the height of the cells will be equal to dy, otherwise the height of the cells will be increase to fill all free space).

'Tree mode' personality:

  • folder_events_available - need to be set as “true”, if you want to have the possibility to specify an event not only for individual event holder but also for the whole folder (any level).
  • folder_dy - the height of folders in pixels (nonapplicable for cells with folder names)

X scale

  • x_unit - size of units on X scale ( can be minute, hour, day, week, month, year )
  • x_step - size of single scale step ( size defined in “x_unit”s)
  • x_size - how must steps need to be shown
  • x_start - value of minimal step
  • x_length - how much x_step need to be used to fill the whole day ( it is necessary only if you are using minute or hour as x_unit )

Time scale from 8AM to 8PM, with 30 minutes step

{
    x_unit:"minute",
    x_step:"30",
    x_size:"24",  // (8PM - 8AM)/30min
    x_start:"16", // 8AM/30min
    x_length:"48" // 24/30min
}

Time scale for two next days with 2hours step

{
    x_unit:"hour",
    x_step:2,
    x_size:24  // 2days/2hours
}

Y scale

  • y_property - name of event's property
  • y_unit - list of options for the property

Templating

All templates need to be redefined after createTimelineView call

In below snippets, you need to replace “timeline” with actual view name

css class for x-scale header

scheduler.templates.timeline_scalex_class = function(date){
           if (date.getDay()==0 || date.getDay()==6)  return "yellow_cell";
           return "";
         }

format of date in the x-scale

scheduler.templates.timeline_scale_date=function(date){
            var format = scheduler.date.date_to_str("%D, %d.%m.%Y");
            return format(date);
        }

Starting with version 2.3, you can create new events in timeline view by double click or drag-and-drop commands. Drag-and-drop command also allows to move existing events within calendar area.


dhtmlxscheduler:map_view [DHX documentation]

Map view

The view contains Google Map and allows to display events location on it.

Related sample: samples/03_extensions/19_map_view.html

Steps to enable

  • include
<script src="http://maps.google.com/maps/api/js?sensor=false" type="text/javascript"></script>
<script src="../../codebase/ext/dhtmlxscheduler_map_view.js" type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="../../codebase/ext/dhtmlxscheduler_ext.css" type="text/css">
  • add to the template
<div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
    <div class="dhx_cal_navline">
    ...
        <div class="dhx_cal_tab" name="map_tab" style="right:280px;"></div>

GUI details

To edit: click on the 'details' icon at the left of event description (if readonly mode is not enabled).
To create: double click on the empty cell or on the desired location on the map.
To overview: click on the event icon on the map.

Customization options

  • first column, event's date, uses scheduler.templates.map_time template
scheduler.templates.map_time = function(start,end,event){
       return scheduler.templates.day_date(start)+" &ndash; "+scheduler.templates.day_date(end);
}
  • second column, event's text, uses scheduler.templates.map_text templates
scheduler.templates.map_text = function(event){
    return event.text;
}

Both templates can be redefined to ouput data or text in a custom format.

Data requirements

In order that the app runs correctly, your database must include the columns for the following information:

  • the location of an event
  • the latitude of an event location
  • the longitude of an event location

If you don't have such columns, create them, for example, with names: 'location', 'lat' and 'lng'.

Make sure that your .php file conform to your database data.

Configuring map

  • Date column width {integer}
scheduler.xy.map_date_width = 188
  • Description column width {integer}
scheduler.xy.map_description_width = 400;
  • If the locations of events have no latitude and longitude values in the database, you can activate the following option and the coordinates will be defined automatically during event loading {boolean}
scheduler.config.map_resolve_event_location = true;
  • Initial position of the map {object}
    • lat - latitude position
    • lng - longitude position
scheduler.config.map_initial_position = new google.maps.LatLng(lat, lng);
  • You can also set the map position in case of the event hasn't got associated coordinates (lookup query returns nothing) {object}
scheduler.config.map_error_position = new google.maps.LatLng(lat, lng);
  • Maximum width of the info window (marker's tooltip) on the map {integer}
scheduler.config.map_infowindow_max_width = 300;
  • Map type {takes one of the predifened values}
    • HYBRID - displays a transparent layer of major streets on satellite images.
    • ROADMAP - displays a normal street map.
    • SATELLITE - displays satellite images.
    • TERRAIN - displays maps with physical features such as terrain and vegetation.
scheduler.config.map_type = google.maps.MapTypeId.ROADMAP;
  • Initial zoom {integer}
scheduler.config.map_inital_zoom = 1;
  • Some browsers open up the opportunity to determine your location. And if you add this codeline, such opportunity will be offered during map loading {boolean}
scheduler.config.map_resolve_user_location = true;
  • Zoom that will be used to show your location if you agree to a browser offer to show it {boolean}
scheduler.config.map_zoom_after_resolve = 15;
  • Template that is used to set date format in information window on the map
scheduler.templates.marker_date=scheduler.date.date_to_str("%Y-%m-%d %H:%i");
  • Template that is used to set text in the information window on the map
scheduler.templates.marker_text=function(start, end, event){
    return "<div><b>"+event.text+"</b><br/><br/>"+event.event_location+"<br/><br/>"+scheduler.templates.marker_date(start)+" - "+scheduler.templates.marker_date(end)+"</div>";
}

Localization

Extension adds 4 new labels , which may be added to locale

scheduler.locale.labels.map_tab = "Map"; // name of the map tab
scheduler.locale.labels.section_location = "Location"; // name of the location section in lightbox
scheduler.locale.labels.marker_geo_success = "It seems you are here."; // message in info window in case of successful geolocation response
scheduler.locale.labels.marker_geo_fail = "Sorry, could not get your position using geolocation."; // message in info window in case of unsuccessful geolocation response


dhtmlxscheduler:settings_config [DHX documentation]

Configuration options

Details of date formatting convention

Configuring layout elements and hotkeys

Configuring 'details form'

Date configuration

  • scheduler.config.default_date - {string} header of day and week views;
  • scheduler.config.month_date - {string} header of month view;
  • scheduler.config.week_date - {string} subheader, days of week in month view;
  • scheduler.config.day_date - {string} subheader, day label in day and week views;
  • scheduler.config.hour_date - {string} vertical scale for day and week views;
  • scheduler.config.month_day - {string} each day block in month view;
  • scheduler.config.api_date - {string} used to set dates in events using api methods.
  • scheduler.config.xml_date - {string} used to define format of data in data xml

Scales

  • scheduler.config.hour_size_px - {numeric} height of 1 hour in pixels;
  • scheduler.config.time_step - {numeric} minimal date size step in minutes;
  • scheduler.config.start_on_monday - {boolean} if true week starts from Monday ( if false, week start from Sunday);
  • scheduler.config.first_hour - {numeric} hour from which day and week scales start;
  • scheduler.config.last_hour - {numeric} hour from which day and week scales end.
  • scheduler.config.limit_time_select - {boolean} adjust time selects to first ahd last hour settings
  • scheduler.config.scroll_hour - {numeric} hour which will be at top of screen, after view mode update

Control

  • scheduler.config.readonly - {boolean} if set to true - events in scheduler can't be created|changed|deleted; 1)
  • scheduler.config.show_loading - {boolean} shows the progress during data loading, useful for dynamic loading mode
  • scheduler.config.drag_resize - {boolean} allows resizing events by dnd;
  • scheduler.config.drag_move - {boolean} allows moving events by dnd;
  • scheduler.config.drag_create - {boolean} allows creating new events by dnd;
  • scheduler.config.dblclick_create - {boolean} allows creating new events by double click;
  • scheduler.config.edit_on_create - {boolean} shows form on new event creation;
  • scheduler.config.details_on_create - {boolean} uses extended form on new event creation by drag or by dbl-click (option doesn't affect monthly view - where details form is the only way to change data);
  • scheduler.config.details_on_dblclick - {boolean} uses extended form on event double-click (double-click on existing event).

Others

  • scheduler.config.server_utc - {boolean} if enabled component will convert server side dates from utc to local timezone, and backward during data sending to server;
  • scheduler.config.positive_closing - {boolean} if outside click occurs during form edit, then form will be saved and event will be updated.
  • scheduler.config.update_render - {boolean} if set to true - each time when item updated - all view will be refreshed instead of updated item only (it allows smooth size recalculation but much more cpu consuming)
  • scheduler.config.multi_day - {boolean} enables rendering of multi-day events in daily and weekly views
  • scheduler.config.full_day - {boolean} if set to true - entry fields in 'Time period' section of details form are blocked, and time period is set as a full day from 0.00am the current cell data to 0.00am next day.2)
  • scheduler.config.event_duration - {integer} used to set the initial duration of the event. 3)
  • scheduler.config.auto_end_date - {boolean} if set to true - when you change start event time or date, the end event time and date will be changed automatically in order to make the event duration value 60 minutes 4)

Selection Menus

  • scheduler.config.icons_edit=[“icon_save”,”icon_cancel”] - this collection stores buttons which are visible in edit menu;
  • scheduler.config.icons_select=[“icon_details”,”icon_edit”,”icon_delete”] - this collection stores buttons which are visible in selection menu.
1) version 1.1+
2) , 3) , 4) version 2.3+


dhtmlxscheduler:configuration_in_deep [DHX documentation]

Configuration tips

Change size of some elements

//height of top area with navigation buttons and tabs
scheduler.xy.nav_height=22;

//height of event bars in month view
scheduler.xy.bar_height=20;

//expected width of scrollbar
scheduler.xy.scroll_width=18;

//width of y-scale
scheduler.xy.scale_width=50;

//height of x-scale
scheduler.xy.scale_height=20;

//width of selection menu on the day|week views
scheduler.xy.menu_width=25;

/* Following options are available only with dhtmlxscheduler_map_view.js on Map tab */
// width of date column
scheduler.xy.map_date_width = 180;
// width of event description column
scheduler.xy.map_description_width = 400;

If you don't need selection menus, you can fully disable them and reuse available space by using

scheduler.config.details_on_dblclick = true;

scheduler.attachEvent("onClick",function(){ return false; });

scheduler.xy.menu_width = 0;

Change hotkeys

//confirm edit operation - Enter

scheduler.keys.edit_save = 13;

//reject edit operation - Escape

scheduler.keys.edit_cancel = 27;


dhtmlxscheduler:details_form [DHX documentation]

Details form

The structure of the details form can be defined by using the following configuration function:

scheduler.config.lightbox.sections=[
    { name:"description", height:50, map_to:"text", type:"textarea", focus:true },
    { name:"location", height:43, map_to:"event_location", type:"textarea"  },
    { name:"time", height:72, type:"time", map_to:"auto"}
]
  • name - the name of the appropriate section in the form
  • height - the height of the appropriate section
  • map_to - refers to the database field connected with the section
  • type - specifies the section type
  • options - elements that will be represented in the section (for the Timiline view only)

Let's consider a little other variation:

scheduler.config.lightbox.sections=[
        {name:"description", height:130, map_to:"text", type:"textarea" , focus:true},
        {name:"custom", height:23, type:"select", options:sections, map_to:"section_id"},
        {name:"time", height:72, type:"time", map_to:"auto"}
]

You see, in the second section we specify the name as 'custom'.
When we act this way, we can set predefined 'custom' data that will be represented in the appropriate section.

The code with the predefined data should be the following:

scheduler.locale.labels.section_custom="Section";
    ...
scheduler.createTimelineView({
    name:	"timeline",
        ...
    y_unit:	sections,
    y_property:	"section_id",
    render:"bar"
});

var sections=[
    {key:1, label:"James Smith"},
    {key:2, label:"John Williams"},
    {key:3, label:"David Miller"},
    {key:4, label:"Linda Brown"}
];

So now, in the second section, we will have the list with event holders:


dhtmlxscheduler:settings_templates [DHX documentation]

Templates

Overview

Templates are formatting functions, normally you don't need to define anything, they will be auto-created according to default settings_config. But if you want to change how some elements of scheduler is rendered - this is the way.

Some samples of templates usage, can be checked at custom styling article

Date formatting Templates

Templates from this group receives only one parameter - date which need to be formatted. The xml_format is backward template, it converts string to date.

  var format = scheduler.date.date_to_str("%H:%i");
  scheduler.templates.hour_scale=function(date){
     return format(date);
  }
  • scheduler.templates.day_date - date in header of day view;
  • scheduler.templates.week_date - date in header of week view;
  • scheduler.templates.month_date - date in header of month view;
  • scheduler.templates.day_scale_date - date in sub-header of day view;
  • scheduler.templates.week_scale_date - date in sub-header of week view;
  • scheduler.templates.month_scale_date - days of week on month view;
  • scheduler.templates.month_day - date in header of cell in month view;
  • scheduler.templates.hour_scale - y-scale on day and week views;
  • scheduler.templates.time_picker - date at the select box from description window;
  • scheduler.templates.xml_date - str to date parser used to convert data from XML;
  • scheduler.templates.xml_format - date to str converter used to send data back to server;
  • scheduler.templates.api_date - template used for date in events.

Event Templates

Template from this group are used to format data of events. They are returns string and receives the next parameters.

  • start date;
  • end date;
  • event object
  scheduler.templates.event_text=function(start,end,event){
   return "Text:<b> "+event.text+"</b><br>"+"Descr."+event.details;
  }
  • scheduler.templates.event_header - defines text label in header of event (date);
  • scheduler.templates.event_text - defines text in middle part of event (text);
  • scheduler.templates.event_bar_date - defines date for event bars in month view;
  • scheduler.templates.event_bar_text - defines text for event bars in month view.
  • scheduler.templates.lightbox_header - defines top line of lightbox window.

Styling template

Template which controls css styling of some element. The string, returned from the template, will be uses as css class for related element.

  • scheduler.templates.event_class - css class of the event ( incoming parameters are the same as for Event Templates )
  • scheduler.templates.month_date_class - css class of day block in month view ( incoming parameters are the same as for Date Templates )
  • scheduler.templates.week_date_class - css class of day block in week view ( incoming parameters are the same as for Date Templates )

Extensions

Tooltip text

  • scheduler.templates.tooltip_text - text in tooltip

Agenda

  • scheduler.templates.agenda_time - time part of agenda table
  • scheduler.templates.agenda_text - text part of agenda table

Year

  • scheduler.templates.year_month - label of month in a year view
  • scheduler.templates.year_date - date of date in a year view
  • scheduler.templates.year_scale_date - label of week scale in a year view

Timeline

{timeline} need to be replaced with name of timeline mode ( if you not sure what is the name - just remove curl brackets )

  • scheduler.templates.{timeline}_scale_date - value in the x-scale
  • scheduler.templates.{timeline}_scale_label - value in the y-scale
  • scheduler.templates.{timeline}_scalex_class - css in the x-scale
  • scheduler.templates.{timeline}_scaley_class - css in the y-scale
  • scheduler.templates.{timeline}_cell_class - css for each cell
  • scheduler.templates.{timeline}_cell_value - value for each cell 1)
  • scheduler.templates.{timeline}_date - time range date at top of the view
  • scheduler.templates.{timeline}_tooltip - text in cell-tooltip 2)

Map

  • scheduler.templates.map_time - time part of events table
  • scheduler.templates.map_text - text part of events table
  • scheduler.templates.marker_text - text in the marker info window
  • scheduler.templates.marker_date - dates in the marker info window

Templates map

Day view

Week view

Month view

Edit form

Agenda view

Year view

Timeline view

Map view

1) , 2) cell mode only


dhtmlxscheduler:events [DHX documentation]

Events

  • onClick - occurs when the user clicks the left mouse button on an event
  • onDblClick - occurs when the user dbl-clicks on an event
  • onBeforeDrag - occurs when the user start move|resize operation 2.1+
  • onContextMenu - occurs when the user clicks the right mouse button inside scheduler
  • onMouseMove - occurs when the user move mouse button other scheduler
  • onEventAdded - occurs when the user adds a new event
  • onEventChanged - occurs after editing an event and saving changes (after clicking on edit and save buttons in event bar or in details window)
  • onBeforeEventDelete - blockable, occurs after user clicks on delete button (in event bar or in details window)
  • onBeforeViewChange - current view change initiated
  • onViewChange - current view changed
  • onXLS - xml loading started
  • onXLE - xml loading ended
  • onBeforeLightbox - details form opening
  • onLightbox - details form was opened
  • onAfterLightbox - details form closing
  • onEventSave - save button of details form
  • onEventCancel - cancel button of details form

Technical events

  • onEventCreated - event creation process started ( dbl-click , or drag-create )
  • onBeforeEventChanged - event was changed by drag-n-drop, but before data saving
  • onEventLoading - event loaded from xml
  • onTemplatesReady - templates of scheduler are initialized
  • onEventIdChange - id of event changed
  • onSchedulerResize - size of scheduler was changed
  • onOptionsLoad - triggered after loading options lists from the server side

Extensions

  • limit extension
    • onLimitViolation - triggered when invalid date creating attempt was detected
  • collisition extension
    • onEventCollision - triggered after loading options lists from the server side
  • timeline extension
    • onXScaleClick - single click on cell in the X-scale
    • onXScaleDblClick - double click on cell in the X-scale
    • onYScaleClick - single click on cell in the Y-scale
    • onYScaleDblClick - double click on cell in the Y-scale
    • onCellClick - click on data cell
    • onCellDblClick - dbl-click on data cell
  • map extension
    • onLocationError - occurs when location can't be resolved to coordinates
  • drag-in extension
    • onExternalDragIn - occurs when some item dragged in scheduler from outside


dhtmlxscheduler:onClick [DHX documentation]

onClick Event

Parameters:

  • id of event;
  • native event object.
  scheduler.attachEvent("onClick", function (event_id, native_event_object){
       //any custom logic here
  });

Event is blockable, if non-true value returned from custom method, default reaction will be blocked ( by default selection bar will appear )


dhtmlxscheduler:onDblClick [DHX documentation]

onDblClick Event

Parameters:

  • id of event;
  • native event object.
  scheduler.attachEvent("onDblClick", function (event_id, native_event_object){
       //any custom logic here
  });

Event called when dbl-click on some scheduler's event is occured


dhtmlxscheduler:onBeforeDrag [DHX documentation]

onBeforeDrag Event

Event was introduced in dhtmlxScheduler 2.1 and not applicable to older versions.

Parameters:

  • id of event;
  • drag mode - can be “move”,”resize”,”create”
  • native event object.
  scheduler.attachEvent("onBeforeDrag", function (event_id, mode, native_event_object){
       //any custom logic here
       return true;
  });

Event called when mouse pressed inside a scheduler on the element, which can be dragged.

For “create” mode, id value is not provided ( new event is not created yet )

Event is blockable, returning false will block related action.


dhtmlxscheduler:onContextMenu [DHX documentation]

onContextMenu Event

Parameters:

  • id of event;
  • native event object.
  scheduler.attachEvent("onContextMenu", function (event_id, native_event_object){
       //any custom logic here
  });

Event called when right mouse button was clicked in the scheduler.

If click was on the event - event_id will contain id of event, or null value in other case.


dhtmlxscheduler:onMouseMove [DHX documentation]

onMouseMove Event

Parameters:

  • id of event;
  • native event object.
  scheduler.attachEvent("onMouseMove", function (event_id, native_event_object){
       //any custom logic here
  });

Event called when mouse hovered other scheduler. event_id parameter may be empty, if there is no event under the mouse pointer.


dhtmlxscheduler:onEventAdded [DHX documentation]

onEventAdded Event

onClick event can call a user-defined handler (if there is any) and pass the following parameters:

  • id of event;
  • event object.
  scheduler.attachEvent("onEventAdded", function(event_id,event_object){
                    //any custom logic here
          });


dhtmlxscheduler:onEventChanged [DHX documentation]

onEventChanged Event

Event occurs after editing an event and saving changes (after clicking on edit and save buttons in event bar or in details window) This event calls user-defined handlers (if there are any) and passes the following parameters:

  • id of event;
  • event object.
 scheduler.attachEvent("onEventChanged", function(event_id,event_object){
                    //any custom logic here
          });


dhtmlxscheduler:onBeforeEventDelete [DHX documentation]

onBeforeEventDelete Event

This event calls user-defined handlers (if there are any) and passes the following parameters:

  • id of event;
  • event object.
  scheduler.attachEvent("onBeforeEventDelete", function(event_id,event_object){
                    //any custom logic here
          });


dhtmlxscheduler:onBeforeViewChange [DHX documentation]

onBeforeViewChange Event

Parameters:

  • old mode - string
  • old date - js date object
  • new mode - string
  • new date - js date object
  scheduler.attachEvent("onViewChange", function (old_mode, old_date, mode , date){
       //any custom logic here
  });

Blockable, event is called, each time before changing current view


dhtmlxscheduler:onViewChange [DHX documentation]

onViewChange Event

Parameters:

  • new mode - string
  • new date - js date object
  scheduler.attachEvent("onViewChange", function (mode , date){
       //any custom logic here
  });

Event is called, each time after changing of current view


dhtmlxscheduler:onXLS [DHX documentation]

onXLS Event

Parameters:

 none
  scheduler.attachEvent("onXLS", function (){
       //any custom logic here
  });

Event is called , each time after xml loading started.


dhtmlxscheduler:onXLE [DHX documentation]

onXLE Event

Parameters:

none
  scheduler.attachEvent("onXLE", function (){
       //any custom logic here
  });

Event is called , each time after xml loading finished.


dhtmlxscheduler:onBeforeLightbox [DHX documentation]

onBeforeLightbox Event

Parameters:

  • id of event;
  scheduler.attachEvent("onBeforeLightbox", function (event_id){
       //any custom logic here
  });

Event is blockable, if non-true value returned from custom method, default reaction will be blocked ( opening of details form )


dhtmlxscheduler:onLightbox [DHX documentation]

onLightbox Event

Parameters:

  • id of event;
  scheduler.attachEvent("onLightbox", function (event_id){
       //any custom logic here
  });

Event occurs after opening lightbox, good place if you want to customize something in the lightbox.


dhtmlxscheduler:onAfterLightbox [DHX documentation]

onAfterLightbox Event

Parameters: none

  scheduler.attachEvent("onAfterLightbox", function (){
       //any custom logic here
  });

Event called after details form closing


dhtmlxscheduler:onEventSave [DHX documentation]

onEventSave Event

onEventSave event can call a user-defined handler (if there is any) and pass the following parameters:

  • id of event;
  • hash of event's data
  • flag of new event

Event is blockable and can be used for validation

    scheduler.attachEvent("onEventSave",function(id,data,is_new_event){
        if (!data.text) {
            alert("Text must not be empty");
            return false;
        }
        if (!data.text.length<20) {
            alert("Text too small");
            return false;
        }
        return true;
    })


dhtmlxscheduler:onEventCancel [DHX documentation]

onEventCancel Event

Parameters:

  • id of event;
  • flag of new event
  scheduler.attachEvent("onEventCancel", function(event_id, is_new_event){
                    //any custom logic here
  });

Called after pressing cancel button in “Details” form.


dhtmlxscheduler:onEventCreated [DHX documentation]

onEventCreated Event

Parameters:

  • id of event;
  • DOM event object.
  scheduler.attachEvent("onEventCreated", function(event_id,event_object){
                    //any custom logic here
          });


dhtmlxscheduler:onBeforeEventChanged [DHX documentation]

onBeforeEventChanged Event

Parameters:

  • scheduler's event object;
  • native HTML event;
  • flag, which shows is it new event or update of already existing one.
  scheduler.attachEvent("onBeforeEventChanged", function(event_object, native_event, is_new){
       //any custom logic here
       return true;
  });

Event occurs when new “event” was added or existing one changed, by drag-n-drop action.

Beware that parameter of event is “event” object, not “event” id ( because newly created events may not have ID yet )

Event is blockable, returning false from handler will prevent data update.


dhtmlxscheduler:onEventLoading [DHX documentation]

onEventLoading Event

Parameters:

  • event object.
  scheduler.attachEvent("onEventLoading", function(event_object){
                    //any custom logic here
          });

Blockable


dhtmlxscheduler:onTemplatesReady [DHX documentation]

onTemplatesReady Event

Parameters: none

  scheduler.attachEvent("onTemplatesReady", function(){
                    //any custom logic here
  });

Event informs that templates of scheduler is ready - good place for custom view creation.


dhtmlxscheduler:onEventIdChange [DHX documentation]

onEventIdChange Event

Parameters:

  • old id
  • new id
  scheduler.attachEvent("onEventIdChange", function(old_event_id,new_event_id){
                    //any custom logic here
  });

Normally, it occurs after receiving confirmation for insert operation. ( changing client side ID to DB's ID )


dhtmlxscheduler:onSchedulerResize [DHX documentation]

onSchedulerResize Event

Parameters: none

  scheduler.attachEvent("onSchedulerResize", function(){
                    //any custom logic here
  });

Event informs that size of scheduler was changed and data area need to be repainted. Normally you need not care about this event, it can be usefull only if you creating some custom view mode.


dhtmlxscheduler:onOptionsLoad [DHX documentation]

onOptionsLoad Event

Parameters:

  • none
  scheduler.attachEvent("onOptionsLoad", function (){
       //any custom logic here
  });

Event is called , when options collection was loaded from a server ( before data xml parsing )


dhtmlxscheduler:onXScaleClick [DHX documentation]

onXScaleClick Event

Parameters:

  • index - index of scale's cell
  • value - label(date object) of cell in question
  • e - native event object
  scheduler.attachEvent("onXScaleClick", function (index, value,e){
       //any custom logic here
  });

Event occurs when user is clicking on x-scale , inside a timeline view


dhtmlxscheduler:onXScaleDblClick [DHX documentation]

onXScaleDblClick Event

Parameters:

  • index - index of scale's cell
  • value - label(text content) of cell in question
  • e - native event object
  scheduler.attachEvent("onXScaleDblClick", function (index, value, e){
       //any custom logic here
  });

Event occurs when user is doble-clicking on x-scale , inside a timeline view


dhtmlxscheduler:onYScaleClick [DHX documentation]

onYScaleClick Event

Parameters:

  • index - index of scale's cell
  • value - label(text content) of cell in question
  • e - native event object
  scheduler.attachEvent("onYScaleClick", function (index, value, e){
       //any custom logic here
  });

Event occurs when user is clicking on y-scale , inside a timeline view


dhtmlxscheduler:onYScaleDblClick [DHX documentation]

onYScaleDblClick Event

Parameters:

  • index - index of scale's cell
  • value - label(text content) of cell in question
  • e - native event object
  scheduler.attachEvent("onYScaleDblClick", function (index, value, e){
       //any custom logic here
  });

Event occurs when user is dbl-clicking on y-scale , inside a timeline view


dhtmlxscheduler:onCellClick [DHX documentation]

onCellClick Event

Parameters:

  • x_index - index of scale's cell
  • x_index - index of scale's cell
  • x_value - index of scale's cell
  • y_value - label(text content) of cell in question
  • e - native event object
  scheduler.attachEvent("onCellClick", function (x_index, y_index, x_value, y_value, e){
       //any custom logic here
  });

Event occurs when user is clicking on data cell, inside a timeline view


dhtmlxscheduler:onCellDblClick [DHX documentation]

onCellDblClick Event

Parameters:

  • x_index - index of scale's cell
  • x_index - index of scale's cell
  • x_value - index of scale's cell
  • y_value - label(text content) of cell in question
  • e - native event object
  scheduler.attachEvent("onCellDblClick", function (x_index, y_index, x_value, y_value, e){
       //any custom logic here
  });

Event occurs when user is dbl-clicking on data cell, inside a timeline view


dhtmlxscheduler:onLocationError [DHX documentation]

onLocationError Event

Parameters:

  • id - id of event
  scheduler.attachEvent("onLocationError", function (id){
          alert("Bad location");
  });

Event can be used to provide custom reaction, when user has create an event with incorrect|empty location
It possible to return a Point object from the event, which will be used for geo-location of the event.


dhtmlxscheduler:onExternalDragIn [DHX documentation]

onExternalDragIn Event

Parameters:

  • id - id of event
  • source - source html object, which was dragged in the scheduler
  • e - native DOM event object
  scheduler.attachEvent("onExternalDragIn", function (id, source){
         scheduler.getEvent(id).text = source.innerHTML;
         return true;
  });

Event can be used to customize newly created event ( which is a result of drag-in operation )
Blockable, if event returns false - dragged in element will not produce a new event


dhtmlxscheduler:custom_styling [DHX documentation]

Custom Styling

Related topics

  • Scheduler Appearance
  • Tooltips

Introduction to Templates

Scheduler allows you to set appearance of its events. Meanwhile you can change displaying parameters for all events at once, as well, you can set dynamic rules to diversify events appearance accordingly to their data.

The appearance of each event is defined by three templates:

  • scheduler.templates.event_header - sets the way of displaying event header (by default, event date);
  • scheduler.templates.event_text - sets text in the middle of an event bar;
  • scheduler.templates.event_class - sets css class which will be assigned to an event.

As in month-view, events are displayed differently, set of templates is called otherwise:

  • scheduler.templates.event_bar_date - sets data for events with specified event start;
  • scheduler.templates.event_bar_text - sets text in the middle of an event bar;
  • scheduler.templates.event_class - sets css class which will be assigned to an event.

All templates are functions which get three parameters:

  • start date;
  • end date;
  • event object.

More details about templates

Redefining Appearance

The simplest way to redefine events appearance - using event_class:

scheduler.templates.event_class=function(start,end,event){
    if (start < (new Date())) //if date in past
          return "past_event"; //then set special css class for it
}

Actually all events, with start date sooner than the current time, will have “past_event” class. We are allowed to add styles to the page to select them visually.

    /*event in day or week view*/
    .dhx_cal_event.past_event div{
        background-color:purple !important;
        color:white !important;
    }
    /*multi-day event in month view*/
    .dhx_cal_event_line.past_event{
        background-color:purple !important;
        color:white !important;
    }
    /*event with fixed time, in month view*/
    .dhx_cal_event_clear.past_event{
        color:purple !important;
    }

as you can see, we are using common classes of scheduler plus to our new css class to define rules specific for each element.

Data format of scheduler allows to support additional fields, thus you have an opportunity to set a new field, event type, for example, and assign different styles to different event types.

       $scheduler->render_table("events","event_id","start_date,end_date,event_name,type");
<data>
  <event id="2">
    <start_date>2009-05-24 00:00:00</start_date>
    <end_date>2009-06-08 00:00:00</end_date>
    <text>French Open</text>
    <type>1</type>
  </event>
scheduler.templates.event_class=function(start,end,event){
    switch ( event.type ){
          case "1" : return "some_event";
          case "2" : return "other_event";
    }
}

Now you have just to assign styles for some_event and other_event, to make each event time display differently.

Redefining Content

As well as styles, you are allowed to set the way an event is displayed on the page.

scheduler.templates.event_text=function(start,end,event){
        return "Text:<b> "+event.text+"</b><br>"+"Descr."+event.details;
}

as you can see, any HTML can be used inside events, which allows to considerably change description appearance.

scheduler.templates.event_header=function(start,end,event){
        return (event.important?"<img src='important.gif' />":"")+scheduler.templates.hour_scale(start);
}

scheduler.templates.event_bar_text=function(start,end,event){
        var text = event.text.substr(0,20);
        return "<span title='"+event.text+"'>"+text+"</span>";
}


dhtmlxscheduler:styling_scheduler [DHX documentation]

Scheduler Appearance

Tabs

Scheduler appearance is defined by HTML template - if inside there are some unnecessary buttons, you can simply remove them from template.

    <div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
        <div class="dhx_cal_navline">
            <div class="dhx_cal_date"></div>
            <div class="dhx_cal_tab" name="day_tab" style="right:204px;"></div>
            <div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
        </div>
        <div class="dhx_cal_header">
        </div>
        <div class="dhx_cal_data">
        </div>
    </div>

Hiding all tabs

You need to change style of @dhx_cal_navline element inside template, and change the height settings of scheduler

    <div id="scheduler_here" class="dhx_cal_container" style='width:100%; height:100%;'>
        <div class="dhx_cal_navline" style="display:none">
          scheduler.xy.nav_height = 0;

Size of scales

Height of x-scale

      scheduler.xy.scale_height = 40; //height of x-scale

Width of y-scale

      scheduler.xy.scale_width = 100; //width of y-scale

Custom size of event bars

<style type=“text/css” media=“screen”>

.dhx_cal_event_line {
    height:33px;
}

</style>

    scheduler.xy.bar_height = 40; //space reserved for single bar


dhtmlxscheduler:styling_tooltips [DHX documentation]

Tooltips

Here you can find all necessary information to use tooltips in your application.
Firstly, add the following files:

<script src='../../codebase/ext/dhtmlxscheduler_tooltip.js' type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="../../codebase/ext/dhtmlxscheduler_ext.css" type="text/css" media="screen" title="no title" charset="utf-8">

Configuration and customization options

  • Css class name of the tooltip. So you can create tooltips with different classnames depending on the event.
dhtmlXTooltip.config.className = 'dhtmlXTooltip tooltip';
  • Timeout in ms before tooltip will be displayed
dhtmlXTooltip.config.timeout_to_display = 50;
  • Right margin (if positive) to the cursor's position
dhtmlXTooltip.config.delta_x = 10;
  • top margin (if positive) to the cursor's position
dhtmlXTooltip.config.delta_x = 60;
  • Template for the text that will be represent in the tooltip
scheduler.templates.tooltip_text = function(start,end,event) {
return "<b>Event:</b> "+event.text+"<br/><b>Start date:</b> "+scheduler.templates.tooltip_date_format(start)+"<br/><b>End date:</b> "+scheduler.templates.tooltip_date_format(end);
}
  • Template for the date format of the tooltip text
scheduler.templates.tooltip_date_format=scheduler.date.date_to_str("%Y-%m-%d %H:%i");


dhtmlxscheduler:custom_details_form [DHX documentation]

Custom "details" form

Structure of details form

Header of details form - text defined by next templates

    scheduler.templates.event_header
    scheduler.templates.event_bar_text

Sections below defined through scheduler.config.lightbox.sections, default configuration is the next

    lightbox:{
        sections:[	{name:"description", height:200, map_to:"text", type:"textarea" , focus:true},
                {name:"time", height:72, type:"time", map_to:"auto"}	]
    }

Sections is an array, which represent the sections inside the form

  • name - name of the section , based on section name its label will be taken from locale collection. For example, for “time” section , label will be taken as scheduler.locale.section_time
  • height - height of section
  • map_to - property maped to the editor
  • type - type of editor
  • focus - if set to true, related field will receive focus on form showing

Types of editors

  • textarea - represented by textarea
  • time - start and end date selectors
  • select - select checkboxes
  • multiselect - multiselect checkboxes
  • checkbox - single checkbox in the section header
  • radio - set of radiobuttons
  • combo - DHTMLX Combo component as select
{name:"reccuring", height:21, type:"select", map_to:"rec_type", options:[
        {key:"", label:"Do not repeat"},
        {key:"day", label:"Each day"},
        {key:"week", label:"Each week"},
        {key:"month", label:"Each month"}
]},

Mapping DB fields to the form

On server side, just add some field to the list of data fields

   $scheduler->render_table("events_rec","event_id","start_date,end_date,text,rec_type");

If you are generating xml by custom code, just add subtag to the event as

   <event id='50' >
    <start_date><![CDATA[2009-06-10 00:00:00]]></start_date>
    <end_date><![CDATA[2009-06-12  00:00:00]]></end_date>
    <text><![CDATA[New event]]></text>
    <rec_type><![CDATA[ some value ]]></rec_type>
   </event>

Now on client side, you can use the same name in the map_to attribute of event

    {name:"reccuring", map_to:"rec_type" ...

Custom editors

Final code can be checked at samples/sample_custom_editor.html

To create your own custom section, you need to define new object in the next way

    scheduler.form_blocks["my_editor"]={
        render:function(sns){ //sns - section configuration object
            return "html code of editor here";
        },
        set_value:function(node,value,ev){
            //node - html object related to html defined above
            //value - value defined by map_to property
            //ev - event object
            ... code to set value to the element ...
        },
        get_value:function(node,ev){
            //node - html object related to html defined above
            //event object
            return "current value from editor";
        },
        focus:function(node){
            //node - html object related to html defined above
            ...code to set focus to the element...
        }
    }

Make sure that you don't use short closing syntax for tags inside the html code returned by the “render” function, since that might cause parsing problems in the browser:

     render:function(){
          return "<div id='box'/>";// this is WRONG
     }

Instead use opening and closing tags syntax:

     render:function(){
          return "<div id='box'></div>";// recommended
     }

In real life it may look as

    scheduler.form_blocks["my_editor"]={
        render:function(sns){
            return "<div class='dhx_cal_ltext' style='height:60px;'>Text&nbsp;<input type='text'><br/>Details&nbsp;<input type='text'></div>";
        },
        set_value:function(node,value,ev){
            node.childNodes[1].value=value||"";
            node.childNodes[4].value=ev.details||"";
        },
        get_value:function(node,ev){
            ev.location = node.childNodes[4].value;
            return node.childNodes[1].value;
        },
        focus:function(node){
            var a=node.childNodes[1]; a.select(); a.focus();
        }
    }
    scheduler.config.lightbox.sections=[
        { name:"description", height:200, map_to:"text", type:"my_editor" , focus:true},
        { name:"time", height:72, type:"time", map_to:"auto"}
    ]

Making section readonly

Can be done by customizing set_value method of related section object

    scheduler.form_blocks.textarea.set_value=function(node,value,ev){
        node.firstChild.value=value||"";
        node.firstChild.disabled = ev.disabled; // or just = true; to disable for all events
    }

Making section hidden for some events

Can be done by customizing set_value method of related section object

    scheduler.form_blocks.textarea.set_value=function(node,value,ev){
        node.firstChild.value=value||"";
        var style = ev.some_property?"":"none";
        node.style.display=style; // editor area
        node.previousSibling.style.display=style; //section header
        scheduler.setLightboxSize(); //correct size of lightbox

    }

Replacing with custom form

Just redefine showLightbox method with any custom one

    scheduler.showLightbox = function(id){
         // id - id of event
         ... code to show any custom form ...
    }

There are two helper methods - startLightbox and endLightbox , which you can use to simplify custom form implementation. Assuming that you have #custom_form html container somewhere on the page, you can use

                var custom_form = document.getElementById("custom_form");

        scheduler.showLightbox = function(id){
            var ev = scheduler.getEvent(id);
            scheduler.startLightbox(id, custom_form );
            ...'here you need to set values in the form'...
                        //document.getElementById("some_input").value = ev.text;
        }
        //need to be attached to the save button
        function save_form() {
            var ev = scheduler.getEvent(scheduler.getState().lightbox_id);

            ...'here you need to retrieve values from the form'...
                        //ev.text = document.getElementById("some_input").value;

            scheduler.endLightbox(true, custom_form);
        }
        //need to be attached to the cancel button
        function close_form(argument) {
            scheduler.endLightbox(false, custom_form);
        }

Button in section header

It possible to have a custom button in section header, to create it just add a button property to section object

    {name:"description", height:130, map_to:"text", type:"textarea" , focus:true, button:"help"}
    scheduler.locale.labels.button_help="Help label";
    scheduler.form_blocks.textarea.button_click=function(index, src, sec, data){
             //called on button click
             // index - index of section
             // sec - html element of section header
             // sec - html element of section editor
    }

You can define image used for the button through next css class

  .dhx_custom_button_help{
       background-image:url(imgs/but_help.gif);
  }

Setting duration for events

The initial duration can be activated by the single line:

scheduler.config.event_duration = 60;

But if you want that after changing start event time or date, the end event time and date will be changed automatically to make the event duration value 60 minutes, you must add the following:

scheduler.config.auto_end_date = true;

Full day event

You can add the possibility of setting full day events in 'timeline' view. For this you just need to add the next codeline:

scheduler.config.full_day  = true;

Now Full Day checkbox will be displayed in the right top of the Time period section. After selection, all entry fields of the section will be blocked, and the event duration will be set as a full day from 0.00am the current cell data to 0.00am next day.

Recurring events

In case of recurring events, form configuration looks like

[
    {name:"description", height:130, map_to:"text", type:"textarea" , focus:true},
    {name:"recurring", height:115, type:"recurring", map_to:"rec_type", button:"recurring"},
    {name:"time", height:72, type:"time", map_to:"auto"}
]

You may add any extra section, but need to preserve both recurring and time sections. It is important that time section is placed after recurring section.


dhtmlxscheduler:multiselect [DHX documentation]

Multiselect

requires ext/dhtmlxscheduler_multiselect.js

Depending on your needs you can place multiselect checkboxes horizontally or vertically, use static or dynamic loading.

{ name:"fruitselect",
  height:100,
  map_to:"fruit_id",
  type:"multiselect",
  options: scheduler.serverList("fruit_id"),
  script_url: 'php/events_multiselect_options.php',
  vertical:"true"
},
  • name - the editor's name
  • height - the height of an editor
  • map_to - the property maped to an editor
  • type - the editor's type
  • options - the elements that will be represented in an editor
  • script_url - url containing options data
  • vertical - vertical placement

Some words about loading.
In static case, all event parameter options store as an individual field in the database and you can use this field for building your own logic later. It gives additional possibilities but forces to make more queries for loading all the options.
In dynamic case, nothing additional is stored. Options are loaded as necessary. It decreases amount of queries but disables building any logic.

On server side you need to have code similar to next

    require_once ('../../../codebase/connector/scheduler_connector.php');
    require_once('../../../codebase/connector/crosslink_connector.php');
    require_once ('../../common/config.php');

    $res=mysql_connect($server, $user, $pass);
    mysql_select_db($db_name);

    $cross = new CrossOptionsConnector($res);
    $cross->options->render_table("user","user_id","user_id(value),username(label)");
    $cross->link->render_table("event_user","event_id", "user_id,event_id");

    $scheduler = new SchedulerConnector($res);
    $scheduler->set_options("user_id", $cross->options);
    $scheduler->render_table("events_ms","event_id","start_date,end_date,event_name,details");

As you can see, it differs from default init by next options

  • cross-link connector php file is included
  • CrossOptionsConnector connector initialized, it takes two tables, one - where options stored, second - where relations stored.
  • set_options used to link cross-link connector to the scheduler


dhtmlxscheduler:checkbox [DHX documentation]

Checkbox

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_editors.js

This type of editor creates a single checkbox in the header of the section. Body of the section is not displayed.

Here's the code snippet of how it could be added:

scheduler.config.lightbox.sections=[
    // other sections
    { name:"checkme", map_to:"single_checkbox", type:"checkbox", checked_value: "registered", unchecked_value: "not_registered" }
];

Following options are used:

  • name - name of the editor
  • map_to - property of the event maped to the editor
  • type - editor's type
  • checked_value - optional, this value will be returned if checkbox is checked. By default true is used.
  • unchecked_value - optional, this value will be returned if checkbox is unchecked. By default false is used.

Example of how such editor looks like:


dhtmlxscheduler:radio [DHX documentation]

Radio

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_editors.js

This type of editor creates a set of radio buttons to choose from. Buttons may be aligned vertically or horizontally. checkbox in the header of the section. Body of the section is not displayed.

Here's the code snippet of how it could be added:

var pizza_size = [
    { key: 1, label: 'Small' },
    { key: 2, label: 'Medium' },
    { key: 3, label: 'Large' }
];

scheduler.config.lightbox.sections=[
    // other sections
    { name:"selectme", height: 48, options: pizza_size, map_to:"radiobutton_option", type:"radio", vertical: true }
];

Following options are used:

  • name - name of the editor
  • height - height of an editor
  • options - elements which will be displayed in the editor
  • map_to - property of the event maped to the editor
  • type - type of the editor
  • vertical - vertical placement (true/false), by default false

Example of how such editor looks like:


dhtmlxscheduler:combo [DHX documentation]

Combo

Required library edition: This method works with any edition of DHTMLX library
Required library file: dhtmlxscheduler_editors.js; dhtmlxcombo.css, dhtmlxcommon.js, dhtmlxcombo.js

This type of editor creates a select box using DHTMLX Combo component.

Here's the code snippet of how it could be added:

var snacks = [
    { key: 5, label: 'Pineapple' },
    { key: 6, label: 'Chocolate' },
    { key: 7, label: 'Chips' },
    { key: 8, label: 'Apple pie' }
];

scheduler.config.lightbox.sections=[
    // other sections
    { name:"snack", options: snacks, map_to:"combo_select", type:"dhtmlx_combo", image_path: "../../../dhtmlxcombo/codebase/imgs/", filtering: true, script_path: "../../php/complete.php", cache: true }
];

Following options are used:

  • name - name of the editor
  • options - elements which will be displayed in the editor
  • map_to - property of the event maped to the editor
  • type - editor's type
  • image_path - path to the DHTMLX Combo images
  • filtering - optional, toggles auto filtering support (options will be filtered as you type)
  • script_path - optional, path to the server script which will handle the filtering
  • cache - optional, enable/disable caching of script responses (using “true” recommended)

Note that it's possible to use only client-side filtration without using server scripts. Set filtering option to true and remove script_path and cache. For additional information check DHTMLX Combo filtering page.

Example of how such editor looks like:


dhtmlxscheduler:custom_views [DHX documentation]

Custom views in dhtmlxScheduler

Required steps

dhtmlxScheduler provides 3 default views

  • month
  • week
  • day

It possible to add custom views ( without any modifications in source code )

To add new view, the next steps need to be executed

  1. add new button to html template
  2. define method, which will return start of period for provided date
  3. define method, which will return end of period for provided date
  4. define method, which describe how custom period can be added
  5. define formats of x and y scale for custom view

Work week view

Final code, can be checked in samples/sample_custom_view.html

add new button to html template
    <div class="dhx_cal_tab" name="day_tab" style="right:204px;"></div>
    <div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
        <div class="dhx_cal_tab" name="workweek_tab" style="right:280px;"></div>
    <div class="dhx_cal_tab" name="month_tab" style="right:76px;"></div>
    scheduler.locale.labels.workweek_tab = "W-Week"

the name attribute of tab container defines name of new mode, workweek in our case

define method, which will return start of period for provided date
    scheduler.date.workweek_start = scheduler.date.week_start;

We are reusing logic of default week view.

define method, which will return end of period for provided date
    scheduler.date.get_workweek_end=function(date){
            return scheduler.date.add(date,5,"day");
    }

The end date of workweek is in 5 days after its start.

define method, which describe how custom period can be added
    scheduler.date.add_workweek=function(date,inc){
            return scheduler.date.add(date,inc*7,"day");
    }

As you can see, in difference with previous method, with one adds 7 days, so we get a date of next work week start.

define formats of x and y scale for custom view
    scheduler.templates.workweek_date = scheduler.templates.week_date;
    scheduler.templates.workweek_scale_date = scheduler.templates.week_scale_date;

Scale settings copied from weekly view.

All above result in new view

Decade view

Final code, can be checked in samples/sample_custom_view.html

add new button to html template
    <div class="dhx_cal_tab" name="day_tab" style="right:204px;"></div>
    <div class="dhx_cal_tab" name="week_tab" style="right:140px;"></div>
            <div class="dhx_cal_tab" name="decade_tab" style="right:345px;"></div>
    <div class="dhx_cal_tab" name="month_tab" style="right:76px;"></div>
    scheduler.locale.labels.decade_tab = "Decade"

the name attribute of tab container defines name of new mode, decade in our case

define method, which will return start of period for provided date
    scheduler.date.decade_start = function(date){
        var ndate = new Date(date.valueOf());
        ndate.setDate(Math.floor(date.getDate()/10)*10+1);
        return this.date_part(ndate);
    }

Round current date to nearest decade start.

define method, which will return end of period for provided date

Because for decade end of period and start of next one is the same date, we just skip this step

define method, which describe how custom period can be added
    scheduler.date.add_decade=function(date,inc){
            return scheduler.date.add(date,inc*10,"day");
    }
define formats of x and y scale for custom view
    scheduler.templates.decade_date = scheduler.templates.week_date;
    scheduler.templates.decade_scale_date = scheduler.templates.week_scale_date;

Scale settings copied from weekly view.

All above result in new view

Setting custom view as default one

You can use the name of custom view as third parameter of init command, but you need to be sure that on moment of init call, the view related methods are already defined. In above code snippets those methods are based on default one which is available only after view creating

To break this cross dependency , the “onTemplatesReady” event can be used

scheduler.attachEvent("onTemplatesReady",function(){
    //place here the code for custom view
        scheduler.date.workweek_start...
})
scheduler.init("scheduler_here",null,"workweek");


dhtmlxscheduler:date_formats [DHX documentation]

Date Converters

You can generate a date convert function as follows:

var convert = scheduler.date.date_to_str("%format%");
some_string = convert( date_object );

Backward convertion can be achieved as follows:

var convert = scheduler.date.str_to_date("%format%");
date_object = convert( date_as_string );

Both functions can be used in UTC variation

//convert date object in local time to string in UTC time
var convert = scheduler.date.date_to_str("%format%",true);
//convert string in UTC time to date object in local time
var convert = scheduler.date.str_to_date("%format%",true);

Date arithmetic

var new_date = scheduler.date.add(date,increment,unit);

//next month
var new_date = scheduler.date.add(date,1,"month");

//previous week
var new_date = scheduler.date.add(date,-1,"week");

Supported units are: day, week, month, year, hour, minute


dhtmlxscheduler:tips [DHX documentation]

Useful solutions for dhtmlxScheduler

Get next event

    var evs = scheduler.getEvents(new Date(), new Date(9999,1,1);
    //evs - list of all oncoming events
    evs.sort(function(a,b){ return (a.start_date > b.start_date ? 1 : -1); });
    //evs[0] - nearest oncoming event

Recurring events - drag all sequence

Add the next code before scheduler initialization

        scheduler.attachEvent("onBeforeEventChanged",function(dev){
            var parts = this._drag_id.toString().split("#");
            if (parts.length > 1) {
                this._drag_id= parts[0];
                var ev = this.getEvent(parts[0]);
                ev._end_date = ev.end_date;
                ev.start_date = dev.start_date;
                ev.end_date = dev.end_date;
            }
            return true;
        });

Multiple users

Relates samples : samples/shared_events

While there is no such concept as different calendars, you can use multiple data feeds in the same scheduler to mimic such behavior.

   //load two data feeds
   scheduler.load("events_shared.php?user=1");
   scheduler.load("events_shared.php?user=2");
   scheduler.config.readonly = true;

and on server side

$scheduler->render_sql("select * from events_shared where event_type=1 AND userId = ".$user_id,"event_id","start_date,end_date,text,event_type,userId");

With such approach it possible to load and show data from multiple sources. userId in above code used just for sample purpose - it may be any different set of rules in your case.

The same code can be used in more complex scenario - see all, edit only own events

   //enable saving for first data feed
   var dp = new dataProcessor("events.php?user=1");
   dp.init(scheduler);

   //allow edit operations only for own events
   function allow_own(id){
    var ev = this.getEvent(id);
    return ev.userId == 1;
   }
   scheduler.attachEvent("onClick",allow_own);
   scheduler.attachEvent("onDblClick",allow_own);

   //default properties of new event
   scheduler.attachEvent("onEventCreated",function(id){
      var ev = this.getEvent(id);
      ev.userId = 1; //just for rendering on client, will not affect server data
   });


dhtmlxscheduler:localization [DHX documentation]

Localization

Included locales

scheduler include localization for next languages

Language | Common locale | Recurring events form
Arabic | sources/locale_ar.js | not translated
English | default | default
Catalan | sources/locale_cn.js | not translated
Chinese | sources/locale_cn.js | sources/locale_recurring_cn.js
Czech | sources/locale_cs.js | sources/locale_recurring_cs.js
Dutch | sources/locale_nl.js | not translated
Finnish | sources/locale_fi.js | sources/locale_recurring_fi.js
French | sources/locale_fr.js | sources/locale_recurring_fr.js
German | sources/locale_de.js | sources/locale_recurring_de.js
Hebrew | sources/locale_he.js | not translated
Hungarian | sources/locale_hu.js | not translated
Indonesia | sources/locale_id.js | not translated
Italian | sources/locale_it.js | sources/locale_recurring_it.js
Japanese | sources/locale_jp.js | not translated
Norwegian | sources/locale_no.js | sources/locale_recurring_nl.js
Polish | sources/locale_pl.js | sources/locale_recurring_pl.js
Portuguese | sources/locale_pt.js | sources/locale_recurring_pt.js
Russian | sources/locale_ru.js | sources/locale_recurring_ru.js
Slovenian | sources/locale_si.js | not translated
Spanish | sources/locale_es.js | sources/locale_recurring_es.js
Swedish | sources/locale_sv.js | sources/locale_recurring_sv.js
Ukrainian | sources/locale_ua.js | sources/locale_recurring_ua.js

To activate necessary locale - you need to load related js file in additional to existing ones, for example the includes for scheduler with Spanish locale will look as

<script src="../codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="../codebase/dhtmlxscheduler.css" type="text/css" title="no title" charset="utf-8">

<script src="../sources/locale_es.js" type="text/javascript" charset="utf-8"></script>

Be sure to use charset=“utf-8”, because all locales are stored as UTF-8 text.

If you are using recurring events, one more file need to be included - localized form for recurring events

<script src="../codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
<link rel="stylesheet" href="../codebase/dhtmlxscheduler.css" type="text/css" title="no title" charset="utf-8">

<script src="../sources/locale_es.js" type="text/javascript" charset="utf-8"></script>
<script src="../sources/locale_recurring_es.js" type="text/javascript" charset="utf-8"></script>

Creating custom locale

You can made a copy of sources/locale.js, which is an english version of locale, and translate all strings in it to different language - including such translated js file will change interface of app in necessary way. ( You can send such file to support@dhtmlx.com - so we will include it in next release )

scheduler.locale={
    date:{
        month_full:["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
        month_short:["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
        day_full:["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
        day_short:["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
    },
    labels:{
        dhx_cal_today_button:"Today",
        day_tab:"Day",
        week_tab:"Week",
        month_tab:"Month",
        new_event:"New event",
    icon_save:"Save",
    icon_cancel:"Cancel",
    icon_details:"Details",
    icon_edit:"Edit",
    icon_delete:"Delete",
    confirm_closing:"", //Your changes will be lost, are your sure?
    confirm_deleting:"Event will be deleted permanently, are you sure?",
    section_description:"Description",
    section_time:"Time period"
    }
}

In case of reccuring events, it require a bit more complex operation. In addition to above step, you will need to made copy of sources/repeat_template.html and translate all text messages in it to target language. After that , translated html file need to be converted in sinlge line js string

        $source = "repeat_template_".$lang[$i].".html";
        $target = "locale_recurring_".$lang[$i].".js";

        $data="";
        $data.="scheduler.__recurring_template='".preg_replace("|[\t ]+|"," ",preg_replace("|[\r\n]+|","",file_get_contents($source)))."';\n\n";
        file_put_contents(target,$data)."\n\n";

To made things simpler, if you have translated html form - you can just send it to support@dhtmlx.com - we will reply with converted js file ( and will include translation in next release )

Additional notes

  • If confirm_closing or confirm_deleting is not defined - related confirm dialog will not be shown at all (auto-confirm);
  • section_{name} refers to the section inside details form, with name:{name};
  • new_event - default text of new event.


dhtmlxscheduler:dhtmlx_components_integration [DHX documentation]

External Drag & Drop

All dhtmlx component are compatible with DhtmlxScheduler and, what is notable, they can be used for creating new events. All you need is drag-and-drop the needed data element to a cell.

Let's consider it by way of example (dhtmlxTree).
Firstly:
1. Download the dhtmlxTree package from the server and place it in a folder.
2. Include the necessary js and css files into the header of html file.

<script src='../../codebase/ext/dhtmlxscheduler_outerdrag.js' type="text/javascript" charset="utf-8"></script>
<script src='../../../dhtmlxTree/codebase/dhtmlxtree.js' type="text/javascript" charset="utf-8"></script>
<link rel='stylesheet' type='text/css' href='../../../dhtmlxTree/codebase/dhtmlxtree.css'>
<link rel="stylesheet" href="../../codebase/ext/dhtmlxscheduler_ext.css" type="text/css" media="screen" title="no title" charset="utf-8">

Then:
3. Init scherduler and tree
4. Enable drag-and-drop command.

tree.enableDragAndDrop(true);

5. Define the appropriate event:

scheduler.attachEvent("onExternalDragIn", function(id, source, event){
        var label = tree.getItemText(tree._dragged[0].id);
        scheduler.getEvent(id).text = label;
        return true;
});

Now, you can easy create new events, containing tree data - just drag and drop the desired node.


dhtmlxscheduler:server_side_integration [DHX documentation]

Server side integration

In addition to below techniques, starting from version 2.2, scheduler can load data from json and use db-less data saving.

Data loading

Scheduler can load data as in XML or iCal format

XML

     //scheduler.load(url,callback);
     scheduler.load("data.php");
<data>
    <event id="2">
        <start_date>2009-05-24 00:00:00</start_date>
        <end_date>2009-06-08 00:00:00</end_date>
        <text><![CDATA[French Open]]></text>
        <details><![CDATA[Philippe-Chatrier Court Paris, FRA]]></details>
    </event>
    <event id="3">
        <start_date>2009-06-10 00:00:00</start_date>
        <end_date>2009-06-13 00:00:00</end_date>
        <text><![CDATA[Aegon Championship]]></text>
        <details><![CDATA[The Queens Club London, ENG]]></details>
    </event>
</data>

Mandatory values:

  • start_date - format defined by scheduler.config.xml_date
  • end_date
  • text

Any other optional elements can present , they will be mapped to related event properties.

iCal

Only events with fixed start and end date supported.

     //scheduler.load(url,"ical",callback);
     scheduler.load("data.php","ical");
BEGIN:VCALENDAR
PRODID:-//Last.fm Limited Event Feeds//NONSGML//EN
VERSION:2.0
X-WR-CALNAME:Last.fm Events
X-WR-CALDESC:Event listing - supplied by http://www.Last.fm

BEGIN:VEVENT
UID:LFMEVENT-1043574
URL;VALUE=URI:http://www.last.fm/event/1043574
DTSTAMP:20090507T190000
DTSTART:20090507T190000
DTEND;VALUE=DATE:20090507
SUMMARY:Cross.B.Band
DESCRIPTION:Cross.B.Band
END:VEVENT

BEGIN:VEVENT
UID:LFMEVENT-965499
URL;VALUE=URI:http://www.last.fm/event/965499
DTSTAMP:20090507T200000
DTSTART:20090507T200000
DTEND;VALUE=DATE:20090507
DESCRIPTION:some content here
END:VEVENT

END:VCALENDAR

DTSTART, DTEND - used as start and end of event DESCRIPTION - used as text of event all attriubutes of event from iCal structure mapped to the properties of event with the same name

Connector

Scheduller includes dataProcessor and can use it to sync. with server ( if you want to implement custom server side logic you can check dataProcessor article )

        scheduler.init('scheduler_here',null,"month");
        scheduler.load("events.php?uid="+scheduler.uid());

        var dp = new dataProcessor("events.php");
        dp.init(scheduler);
    include ('dhtmlxConnector/codebase/scheduler_connector.php');

    $res=mysql_connect("localhost","root","");
    mysql_select_db("sampleDB");

    $calendar = new SchedulerConnector($res);
    $calendar->render_table("events","id","event_start,event_end,event_text","type");

The third parameter must have 3 mandatory fields:

  • event field mapped to start date;
  • event field mapped to end date;
  • event field mapped to event text.

For more details about connector usage - you can check Connectors documentation

Using connector for an options fetching

Starting from version 2.2 it possible to fetch data for the options lists automatically.

Instead of using

    scheduler.config.lightbox.sections=[
    ...
    {name:"type", height:21, map_to:"type", type:"select", options:[
        {key:1, label:"Simple"},
        {key:2, label:"Complex"},
        {key:3, label:"Unknown"},
    ]},
    ...
    ]

You can use

    scheduler.config.lightbox.sections=[
    ...
    {name:"type", height:21, map_to:"type", type:"select",
                options:scheduler.serverList("type")},
    ...
    ]

and on server side

    $scheduler = new schedulerConnector($res);
        $list = new OptionsConnector($res);
        $list->render_table("types","typeid","typeid(value),name(label)");
        $scheduler->set_options("type", $list);
    $scheduler->render_table("tevents","event_id","start_date,end_date,event_name,type");

Which will automatically load the list from the linked table.

You can check samples/01_initialization_loading/09_connector_options.html

Same can be used in the unit|matrix view

        var sections = scheduler.serverList("type");
        scheduler.createUnitsView("unit","type",sections);

samples\03_extensions\17_connector_units.html

Samples for different platforms

  • PHP - http://dhtmlx.com/docs/download/dhtmlxConnector_php.zip
  • .Net - http://dhtmlx.com/docs/download/dhtmlxConnector_net.zip
  • Java - http://dhtmlx.com/docs/download/dhtmlxConnector_java.zip
  • RubyOnRails - http://support.dhtmlx.com/x-files/samples/ruby_scheduler.zip
  • ColdFusion - http://support.dhtmlx.com/x-files/samples/connector_cf.zip

Dynamical loading

By default scheduler load all data at once. It may be problematic in case of big event collections. In such situation dynamical event loading can be used - in case of dynamical loading, scheduler will load only part of event, necessary to fill current viewable area.

    scheduler.setLoadMode("month");
    scheduler.load("some.php");

Possible values are

  • year
  • month
  • day

If setLoadMode was used , scheduler will generate calls as

    some.php?from=DATEHERE&to=DATEHERE

where DATEHERE - will be a valid date values, format of which is defined by scheduler.config.load_date (%Y-%m-%d by default)

In case of “month” mode - calendar will request data for each month ( it is clever enough, to cache already used data - so requests will be sent only once per month )

If you are using dhtmlxConnector at server side, library is aware of such use-case and can be used in dyn. mode without any additional server side settings.

Multiple sources

If you need to load data dynamically from multiple sources - it can be organized by using related extension

Loading indicator

You can include loading indicator by using

      scheduler.config.show_loading=true;

If you can change loading image to different one - just replace imgs/loading.gif with different one


dhtmlxscheduler:external_plugin:wordpress [DHX documentation]

dhtmlxScheduler for the Wordpress

http://wordpress.org/extend/plugins/event-calendar-scheduler/

Installation

  1. Upload the content of event-calendar-scheduler.zip to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress

After plugin activation, you will have a new page in your blog, with calendar on it. You can configure it through Plugins menu.

If you want to add scheduler to some other page - place the next snippet on the page or in the blog post

     [[scheduler_plugin]]

Admin panel

Admin panel can be accessed by using Plugins - Scheduler menu

Universal plugin control panel

User Interface

dhtmlxScheduler is a user-friendly event scheduler component which allows you to present and schedule any event such as board meeting, business lunch, conference call, family reunion, movie night, or any other group event. You are allowed to create, edit, delete and drag-and-drop events in the scheduler.

dhtmlxScheduler manipulation is quite easy. Let’s begin.

First of all you should know that dhtmlxScheduler is able to schedule events for days, weeks and months. To set your time mode, you should select one of three available modes in the time mode panel located on the right side of the calendar panel.

Backward/forward arrows on the left side of the calendar panel allow you to move within calendar dates. Today button enables you to turn to the current date. The selected date period is specified behind today button. Hours scale is located on the left side of the scheduler.

Events Manipulation

Creating a New Event

To create a new event, double click on desired date field. After that “New event” window appears.

Here you can enter the event name and set start and end time of the event. To save the event in the calendar, click Save button on the bottom left corner of the window. If you would like to escape this window without saving the event, click Cancel.

One more way to create a new event is to press the left button of the mouse and drag date area to define the date period of the event. This can be done in Day, Week or Month views.

Editing Event

To change the event details, click on the event box. A small bar will appear on the left of the event box. Click the appropriate button to edit event name or details, or delete the event.

When you click Details button, a window with event details appears. It's the same window as you've seen when you created an event - here you can change event description and time period. To call this window, you can also double-click on the necessary event box.

To change event date and time, you can also drag the event box in Week/Month View to the necessary date field. In Day View you can change the event time by dragging the event box and changing its size.

Setting a Multiday Event

There is a possibility to set a multiday event. You can do it in “New event” window when you set start and end dates of the event.

Drag-and-Drop in dhtmlxScheduler

dhtmlxScheduler supports drag-and-drop, thus you are allowed to move and resize a created event within calendar area accordingly to your needs.

Deleting an Event

There are two ways to delete an event:

  1. Click the appropriate button in the left bar of the event.
  2. Call Details window and click Delete button on the bottom right corner.

Full Sreen View

To expand the shceduler to the full screen view, click the button on the top right corner. Another click on this button will return the scheduler to the standard view.

Post creating form

During post creating you can use a special button to create the new event. Button will add event and place the link to it on the page.

Widget

After plugin activation you will be able to use “Upcoming events” widget

The way, how information is rendered in the sidebar can be changed by changing template in event-calendar-scheduler\sidebar.php

Sidebar

Starting from version 1.2 you can place the list of oncoming events in sidebar. To do so , you need to add the next line to the sidebar's template.

 <?php if (function_exists('scheduler_sidebar')) echo scheduler_sidebar(); ?>

Count of events on the sidebar can be configured in scheduler's settings.

If you want to adjust how info is rendered on sidebar, you can edit

wp-content\plugins\event-calendar-scheduler\sidebar.php

Export to the iCal format

Starting from version 1.2 plugin includes all necessary to export self in iCal format ( which can be loaded in Google Calendar, MS Outlook or some other desktop application. To add such possibility, just add the next link somewhere on the page ( inside post, or inside sidebar's template.

<a href='./wp-content/plugins/event-calendar-scheduler/ical.php'>Export events</a>

If you need to export only oncoming events, the link will look as

<a href='./wp-content/plugins/event-calendar-scheduler/ical.php?oncoming'>Export oncoming events</a>


dhtmlxscheduler:external_plugin:joomla [DHX documentation]

dhtmlxScheduler for Joomla!

  • Page at joomla.org: http://extensions.joomla.org/extensions/calendars-a-events/calendars/10363
  • Download link: http://www.dhtmlx.com/docs/download/joomla_com_scheduler.zip

Installation

Steps to install Scheduler module

  1. install the module
  2. go to the Admin panel, Components, Scheduler and adjust the settings
  3. go to the Menus | Main menu ( or any other menu ) and add new item “Scheduler:Default layout”

Now there should be an item in the menu which points to working scheduler page.

Admin panel

Admin panel can be accessed by using Admin panel, Components, Scheduler

Universal plugin control panel

User interface

dhtmlxScheduler is a user-friendly event scheduler component which allows you to present and schedule any event such as board meeting, business lunch, conference call, family reunion, movie night, or any other group event. You are allowed to create, edit, delete and drag-and-drop events in the scheduler.

dhtmlxScheduler manipulation is quite easy. Let’s begin.

First of all you should know that dhtmlxScheduler is able to schedule events for days, weeks and months. To set your time mode, you should select one of three available modes in the time mode panel located on the right side of the calendar panel.

Backward/forward arrows on the left side of the calendar panel allow you to move within calendar dates. Today button enables you to turn to the current date. The selected date period is specified behind today button. Hours scale is located on the left side of the scheduler.

Events Manipulation

Creating a New Event

To create a new event, double click on desired date field. After that “New event” window appears.

Here you can enter the event name and set start and end time of the event. To save the event in the calendar, click Save button on the bottom left corner of the window. If you would like to escape this window without saving the event, click Cancel.

One more way to create a new event is to press the left button of the mouse and drag date area to define the date period of the event. This can be done in Day, Week or Month views.

Editing Event

To change the event details, click on the event box. A small bar will appear on the left of the event box. Click the appropriate button to edit event name or details, or delete the event.

When you click Details button, a window with event details appears. It's the same window as you've seen when you created an event - here you can change event description and time period. To call this window, you can also double-click on the necessary event box.

To change event date and time, you can also drag the event box in Week/Month View to the necessary date field. In Day View you can change the event time by dragging the event box and changing its size.

Setting a Multiday Event

There is a possibility to set a multiday event. You can do it in “New event” window when you set start and end dates of the event.

Drag-and-Drop in dhtmlxScheduler

dhtmlxScheduler supports drag-and-drop, thus you are allowed to move and resize a created event within calendar area accordingly to your needs.

Deleting an Event

There are two ways to delete an event:

  1. Click the appropriate button in the left bar of the event.
  2. Call Details window and click Delete button on the bottom right corner.

Full Sreen View

To expand the shceduler to the full screen view, click the button on the top right corner. Another click on this button will return the scheduler to the standard view.


dhtmlxscheduler:external_plugin:universal_plugin_control_panel [DHX documentation]

Universal plugin control panel

Before changing anything, beware that settings will be applied only after pressing “Save” button. If you leave page without saving - all changes will be lost.

Settings

  • Width and height - size of scheduler on the page
  • Link - link to the page, where scheduler is placed
  • Debug mode - can be used to get detailed report when data is not loaded or not saved correctly
  • Repeat events - enables support of recurring events
  • Prevent overlapping - allow only one event in the same timeslot
  • Mini-calendar - adds mini-calendar icon on top, and calendar based edit-form.
  • Modes - list of tabs, which will be on top of scheduler

Access rights

Allows to define access level for different groups of users:

  • Add - ability to create new events
  • Edit - ability to edit existing events
  • Show - ability to see the scheduler

And set private mode:

  • off - events are public. Users see and can edit (if the appropriate check is set) all events
  • Private mode - users see and can edit (if the appropriate check is set) just self-created events
  • Private extended mode - users see all events but can edit (if the appropriate check is set) just self-created ones

Templates

You can define

  • format of dates
    • http://docs.dhtmlx.com/doku.php?id=dhtmlxscheduler:settings_format
    • http://docs.dhtmlx.com/doku.php?id=dhtmlxscheduler:settings_config
  • time scales
  • how text is rendered inside events ( which can be used to show info from custom fields )

Administration

Panel shows the list of all events in the editable grid, you can add | delete | edit | reload events here.

Custom fields

Panel allows to define custom fields, which will be linked to events.

There are two types of custom fields

  • Textarea - plain text field
  • Select list - select box with list of options

Each field can have

  • Name - the name of a field in DB ( will be created automatically )
  • Description - will be used in edit-form

Select list fields have also extra flags

  • “use as colors” - allows to define which color event will have, based on custom field value
  • “use as units” - creates an unit view based on list of options
  • “Timeline” - creates a timeline view where you can choose time-scale unit:
    • Day
    • Working Day
    • Week
    • Working week
    • Month

Depending on your needs you can choose one or both of these views.
http://docs.dhtmlx.com/doku.php?id=dhtmlxscheduler:units_view

For advanced users

For advanced users we offer extra possibility - to wide available functionality.
All you need - scheduler_include.html file (you can find it in the plugin's folder: you_wordpress/wp-content/plugins/event-calendar-scheduler/scheduler_include.html).
How does it work?
You add the desired additions to the file. Essentially, it's all. To the page the contents will be added automatically (the file is included to the page on default).


dhtmlxscheduler:migration_from_older_version [DHX documentation]

While version 3.0 is not released yet, you can check steps to be ready for Scheduler 3.0

2.2 → 2.3

  • full backward compatibility
  • Swedish locale file was renamed according to the iso 639-1
     sources/locale_se.js => sources/locale_sv.js
     sources/locale_recurring_se.js => sources/locale_recurring_sv.js

2.1 → 2.2

  • full backward compatibility
  • createUnitsView command accepts different set of parameters, but previous syntax will work as well

2.0 → 2.1

  • formatting rules was corrected, now %d and %m always return 2 digits, if you need the previous behavior you can use %j and %n accordingly
  • path to files inside the package is changed a bit
     codebase/dhtmlxgrid_recurring.js => codebase/ext/dhtmlxgrid_recurring.js
     codebase/dhtmlxgrid_recurring.css=> codebase/ext/dhtmlxgrid_recurring.css
     codebase/dhtmlxgrid_units.js => codebase/ext/dhtmlxgrid_units.js

1.0 → 2.0

  • API and data format is fully backward compatible
  • onEventChanged and onEventAdded events will not fire during data loading
  • Spanish locale renamed from locale_sp.js to locale_es.js
  • drag_create option now control only ability to create new event by dnd, creating new event by dblclick now controlled by dblclick_create


dhtmlxscheduler:scheduler_3.0 [DHX documentation]

Migration to the Scheduler 3.0

Scheduler 3.0 is not released yet
You need not change anything to work with existing version of scheduler. All described below code is supported in scheduler 2.3 , but will be deprecated in scheduler 3.0

There are few inner methods which were exposed but will not be available in scheduler 3.0

resetting lightbox

    scheduler._lightbox = null;

→

    //2.3+
    scheduler.resetLightbox();

current state

    scheduler._date
    scheduler._mode
    scheduler._min_date
    scheduler._max_date
    scheduler._editor_id
    scheduler._lightbox_id

→

    //2.3+
    scheduler.getState().date
    scheduler.getState().mode
    scheduler.getState().min_date
    scheduler.getState().max_date
    scheduler.getState().editor_id
    scheduler.getState().lightbox_id