dhtmlxscheduler:toc [DHX documentation]

dhtmlxScheduler

  • What's new
  • Migration from older version
  • Common problems
  • Known issues
  • How to start? (step-by-step guide)

Main modes

  • User Interface
  • Initialization
  • Configuration and Templates
  • Events (inner events of scheduler)
  • Server Side Integration, Export to PDF and other formats
  • Synchronization with Google Calendar
  • Date operations
  • Offline storage
  • API Reference

Extensions

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

Customization

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

Special editions

  • WordPress
  • Joomla!
  • Mobile version
Copyright © 1998-2011 DHTMLX LTD.
All rights reserved.


dhtmlxscheduler:what_s_new [DHX documentation]

What's new

3.0

  1. Version of scheduler for touch phones (details)
  2. WeekAgenda view (details)
  3. Netbook friendly lightbox form (details)
  4. Cascade event display (details)
  5. Simple way to define a color for event (details)
  6. Drag and drop of the details form
  7. Custom buttons for the details form (details)
  8. Current time marker in day and week view
  9. Multiline header for timeline view
  10. Configurable work-time bounds (details)
  11. API to access lightbox values (details)

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. Ability to create new events by double click or by drag-and-drop in Timeline mode
  6. Ability to move events by drop-and-drag in Timeline mode
  7. Ability 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:migration_from_older_version [DHX documentation]

Migration from older versions

2.3 → 3.0

Public API - fully backward compatible
For private API - check Scheduler 3.0

  • File structure was changed a bit - ext/dhtmlxscheduler_ext.css and dhtmlxscheduler_recurring.css were removed (all styles now available in the dhtmlxscheduler.css)
  • Several templates arguments were changed to match the rest of them - scheduler.templates.agenda_text, scheduler.templates.map_text now use (start_date, end_date, event) as incoming parameters. Before only 'event' was used.

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


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

  1. 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.

  2. Problem: time limit set using blockTime doesn't work correctly in the Units view
    Affected versions: 3.0
    Patch: http://forum.dhtmlx.com/download/file.php?id=4139


dhtmlxscheduler:how_to_start [DHX documentation]

How to start

In this tutorial we want to consider creation of a standard scheduler that loads data from a database and save it back. The final code of the tutorial can be used as the start point while creating applications using dhtmlxScheduler.

If you already known with creation of dhtmlxScheduler integrated with server-side you can move
straight to the source code, to start use it as the foundation of your app.

The tutorial divided into 8 logical parts (steps):

Step 1:
Step 2:
Step 3:
Step 4:
Step 5:
Step 6:
Step 7:
Step 8:

Step 1. A new HTML file and required code files

Let’s start our application with creating a new HTML file and including to it the required scheduler code files.
Required code files are:

  • dhtmlxscheduler.js;
  • dhtmlxscheduler.css.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
   <title>How to start</title>
   <script src="../scheduler/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
   <link rel="stylesheet" href="../scheduler/dhtmlxscheduler.css" type="text/css" charset="utf-8">
</head>
<body>
   // your code will be here
</body>
</html>

Step 2. Related DIV elements

Before initialization of the scheduler, we should define the related DIV containers for its elements.
The standard set of 'divs' (needed for the scheduler) looks like:

<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>

Step 3. Style

To work correctly in the fullscreen mode in different browsers you should define the following style for the scheduler:

<style type="text/css" media="screen">
    html, body{
        margin:0px;
        padding:0px;
        height:100%;
        overflow:hidden;
    }
</style>

If you don't use the fullscreen mode, you haven't to specify such the style. You can set any desired style directly in the main div:

<div id="scheduler_here" class="dhx_cal_container" style='width:200px; height:300px; padding:10px;'>
...

Step 4. Initialization

After we have finished preparatory work we can move to initialization. Beware, the scheduler is a static object and can be instantiate on the page once. To refer to the scheduler you must use dhtmlxScheduler or simply scheduler.

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

Step 5. Loading data

If you run the app now, you already can see scheduler on the page. But it won’t contain any data.

To load data we must use method load().
In case of static loading we would specify there the appropriate data file (e.g. 'events.xml'), but as we will load data from database we should specify there a file realizing server-side ‘communication’. You may write full server-side by yourself, but we recommend to use dhtmlxConnector as the easiest way.
So, for our task we'll call the method as shown below:

scheduler.load("data/connector.php");// the url of the file that will process update/insert/delete operations on the server-side.

Step 6. Database structure

To be correctly processed, your database table must contain at least 3 fields:

  • start_date - (DateTime) the date when a task is scheduled to begin. The default format - ”%m/%d/%Y %H:%i”.
  • end_date - (DateTime) the date when a task is scheduled to be completed. The default format - ”%m/%d/%Y %H:%i”.
  • text - (string) the text of a task.

Besides stated, you can create any number of extra fields which then can be passed to the client-side and mapped to the lightbox.

Beware, the format of the DataTime data type is '%Y-%m-%d %H:%i' that differs from the date format expected by the scheduler ('%m/%d/%Y %H:%i'). So, to provide correct data convertion, we should change the default scheduler format. It can be achieved by setting the xml_date configuration option.
Note, any configuration options go BEFORE the initialization string, i.e.:

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

Step 7. Server-side script

Server-side script for dhtmlxScheduler is the following:

<?php
require_once("../codebase/connector/scheduler_connector.php");

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

$conn = new SchedulerConnector($res);
$conn->enable_log("temp.log");

$conn->render_table("events","id","event_start,event_end,event_text");

?>

Note, you can name table fields as you want. In any case, the scheduler interprets 3 first fields to load, as the required ones. For instance, for the code snippet above, interpretation will be as follows:

  • event_start → start_date;
  • event_end → end_date;
  • event_text →text.

Step 8. Saving data

If you run the app now, you will see the scheduler able to load data from database but unable to save it back. To ‘force’ scheduler to save data in db, we should use dataprocessor.

It’s very easy to use it. All you need is to initialize dataprocessor and attach it to the scheduler.

var dp = new dataProcessor("data/connector.php");
dp.init(scheduler);

That’s all. A standard scheduler that can load data from db and save it back is ready ( the source code of the app).
Now you may configure, change and customize it further to meet all your needs.


dhtmlxscheduler:howtostart_sourcecode [DHX documentation]

The source code of the app implementing a standard scheduler

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>How to start</title>
    <script src="../scheduler/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../scheduler/dhtmlxscheduler.css" type="text/css" charset="utf-8">

    <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>

    <style type="text/css" media="screen">
    html, body{
        margin:0px;
        padding:0px;
        height:100%;
        overflow:hidden;
    }
    </style>

</head>
<body>
    <script type="text/javascript">
       scheduler.config.xml_date="%Y-%m-%d %H:%i";
           scheduler.init('scheduler_here',null,"week");
       scheduler.load("data/connector.php");

       var dp = new dataProcessor("data/connector.php");
       dp.init(scheduler);
    </script>
</body>
</html>


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: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
  • scheduler.config.mark_now - {boolean} when it set to true, day and week view will have marker, which show current time

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 to a full day from 00.00 the current cell date untill 00.00 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)
  • scheduler.config.drag_lightbox - {boolean} when set to true lightbox can be dragged by header, it is enabled by default
  • scheduler.config.preserve_scroll - {boolean} when set to true current scroll position is preserved when navigating between dates on the same view, it is enabled by default 5)

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+
5) version 3.0+


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: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)
  • onEventDeleted - occurs after event was deleted 3.0+
  • 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
  • onLightboxButton - click on custom button in lightbox
  • 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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_oneventdeleted [DHX documentation]

onEventDeleted Event

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

Parameters:

  • id of event
scheduler.attachEvent("onEventDeleted", function(event_id){
    // custom code
});

Event is called when event in scheduler was deleted (works with or without Dataprocessor).


dhtmlxscheduler:event_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:event_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:event_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:event_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:event_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:event_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:event_onafterlightbox [DHX documentation]

onAfterLightbox Event

Parameters: none

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

Event called after details form closing


dhtmlxscheduler:event_onlightboxbutton [DHX documentation]

onLightboxButton Event

Parameters:

  • id - id of button
  • node - html element of button
  • e - native click event
  scheduler.attachEvent("onLightboxButton ", function (id, node, e){
       //any custom logic here
  });

Event called when click on custom button in the lightbox occurs ( custom buttons at the bottom of the lightbox, do not occurs for default buttons, or section buttons )


dhtmlxscheduler:event_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:event_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:event_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:event_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, unmodified_event){
       //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).

Unmodified event would be empty object in case of creating new event.

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


dhtmlxscheduler:event_oneventloading [DHX documentation]

onEventLoading Event

Parameters:

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

Blockable


dhtmlxscheduler:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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:event_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: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: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:pdf [DHX documentation]

Export to PDF

Installation

Grab the latest package from http://dhtmlx.com/x/download/regular/scheduler-pdf-php.zip .
Unpack it somewhere under the web root ( you will need to enable php for this installation ).

The Java version of the package can be found at: http://dhtmlx.com/x/download/regular/scheduler-pdf-java.zip.

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 the scheduler this file can be missed 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 a button on the page, which will call the toPDF() method. The parameter of the 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

To configure the export options you need to deal with both client- and server-sides.

Client-side

As mentioned above, for export activation you should use the method toPDF():

scheduler.toPDF(path, color, header, footer);

Parameters:

  • path - (url) the path to the php file which generates PDF-file. See details .
  • color - ('color', 'gray', 'bw', 'custom', 'fullcolor') specifies colormap.
    1. 'color' - full-color printing, default value.
    2. 'gray' - prints in shades of black and white.
    3. 'bw' - uses only black and white colors.
    4. 'custom' - can be used to enable a custom colormap ( requires php coding, see ).
    5. 'fullcolor' - actual background and text colors that are used while exporting.
  • header - (boolean, optional) defines whether a header will be added to the page. By default, false.
    See details .
  • footer - (boolean, optional) defines whether a footer will be added to the page. By default, false.
    See details .

So, to your HTML page you should add a code line that will call toPDF() method with the appropriate number of the parameters. For example, it may look like:

scheduler.toPDF('path/to/folder/generate.php','gray');

Server-side

In the code snippet above generate.php is a php file that defines export options.
The simplest sample of the file is:

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

But before executing the printScheduler() method you can apply some custom configuration options:

Size of elements:

// the height of the header of the day container in the month mode
$scPDF->monthDayHeaderHeight = 6;
 // the height of the header in the month mode
$scPDF->monthHeaderHeight = 8;
 // the height of the month name container in the year mode
$scPDF->yearMonthHeaderHeight = 8;
 // height of the row in the agenda mode
$scPDF->agendaRowHeight = 6;
 // the height of the header in the day and week mode
$scPDF->dayTopHeight = 6;
 // the width of the left scale in the 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 the 'custom' value as the name of colormap 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';

Headers and footers:

// the height of the header
$headerImgHeight = 40;
// the height of the footer
$footerImgHeight = 40;
// the path to the header image
$headerImg = './header.png';
// the path to the footer image
$footerImg = './footer.png';

Header and Footer

It's possible to define a custom header and footer for each page.
To achieve that you should make the following steps:

  • create images with the names ”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 ”header.png” and ”footer.png” images as the header and footer on all pages in the generated pdf file.

Error reporting

If output of PDF file is failed, there must be the 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 the name “debug_xxxxx.xml”. Please, send it with the related error report.


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();

Also, there is an external script for iCal import-export operations

Attributes in serialization

The following technique is not applicable for the iCal format.

By default export will include only standard attributes(properties)

  1. id
  2. text
  3. start_date - format of seriaization is defined by scheduler.config.xml_date
  4. 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:ical_export_import [DHX documentation]

iCal export/import

You have the possibility to import/export data of iCal format by using either ready-to-use utility or API methods.

Download the iCal exporter utility: http://www.dhtmlx.com/docs/download/ical2scheduler.zip

iCal exporter (Front-end)

The front-end of the utility consists of two parts: Resource configuration and Database configuration. In the first part you should set path to the data. You may do this by either choosing it from the opened dialog window (Ical file, the button “Overview”) or specifing the path mannually (Ical URL).
The second part contains the standart settings of the database which you want to save the iCal data in: host, database and table names, user's name and password. Also here you may set whether or not your old data must be deleted (Delete all data).

API Methods

Here you can find all the API methods that can be used to implement iCal export/import in an app.

Initialization

To initialize iCal exporter/importer you should use the following code:

require_once("codebase/class.php");
$export = new ICalExporter();
  • iCalendar import

You can import iCal data using the following:

setTitle($title) //sets title of ical file in toICal method
getTitle() //gets title of ical
toICal($events) //converts the information from the array or xml string to icalendar format
  • iCalendar export

You can export iCal data using the following:

toHash($ical) //converts ical string to array of events
toXML($ical) //converts ical string to XML

Examples

A number of code snippets that show how to execute iCal export/import are presented here.

  • Setting iCalendar title

The following code allows you to set the title of imported/exported iCalendar data.

$xml = file_get_contents("events_rec.xml");
require_once("codebase/class.php");
$export = new ICalExporter();
$export->setTitle("Calendar name");
$ical = $export->toICal($xml);
file_put_contents("ical.ics", $ical);
  • Array of events

It's an example of events' array that is reffered in import/export data from/to array.

$events = array(
    array(
        "id" => 1,
        "start_date" => "2010-04-05 08:00:00",
        "end_date" => "2012-04-09 09:00:00",
        "text" => "text1",
        "rec_type" => "week_2___3,5",
        "event_pid" => null,
        "event_length" => 3600
    ),

    array(
        "id" => 2,
        "start_date" => "2010-04-06 12:00:00",
        "end_date" => "2010-04-06 18:00:00",
        "text" => "text2",
        "rec_type" => "",
        "event_pid" => null,
        "event_length" => null
    ),

    array(
        "id" => 3,
        "start_date" => "2010-04-07 12:00:00",
        "end_date" => "2010-04-07 18:00:00",
        "text" => "text3",
        "rec_type" => "",
        "event_pid" => null,
        "event_length" => null
    ),

    array(
        "id" => 4,
        "start_date" => "2010-04-08 12:00:00",
        "end_date" => "2010-04-08 18:00:00",
        "text" => "text4",
        "rec_type" => "",
        "event_pid" => null,
        "event_length" => null
    )
);
  • From Array to iCal

This code you may use to export data from array to iCal.

require_once("codebase/class.php");
$export = new ICalExporter();
$ical = $export->toICal($events);
file_put_contents("ical.ics");
  • From XML to iCal

This code you may use to export data from XML to iCal.

$xml = file_get_contents("events_rec.xml");
require_once("codebase/class.php");
$export = new ICalExporter();
$ical = $export->toICal($xml);
file_put_contents("ical.ics");
  • From iCal to Array

This code you may use to export data from iCal to array.

$ical = file_get_contents("ical.ics");
require_once("codebase/class.php");
$export = new ICalExporter();
$events = $export->toHash($ical);
  • From iCal to XML

This code you may use to export data from iCal to XML.

$ical = file_get_contents("ical.ics");
require_once("codebase/class.php");
$export = new ICalExporter();
$xml = $export->toXML($ical);
file_put_contents("events_rec.xml", $xml);


dhtmlxscheduler:synchronization_with_google_calendar [DHX documentation]

Synchronization with Google Calendar

Introduction

In this chapter you'll find out how to keep Scheduler and Google Calendar in sync.
Note that the sync is 2-way, i.e. any changes you make to events in either Scheduler or Google Calendar will be reflected in both applications.

  • If you alter the same event in both applications, the latest update will sync between Scheduler and Google Calendar.
  • If you delete an event in one of the calendars, this event will be deleted from both applications.
  • You sync Scheduler with the primary Google Calendar. Events from the secondary calendars won't be synced.
  • Note, you sync all the events containing in both Google Calendar and Scheduler at once. You can't sync just some specific part of events.
  • By default, Scheduler takes the text and duration (start and end times) of the Google Calendar event. If you need you can get additional information of the event. See the details .

Getting started

First of all, to start sync, check whether the extension php_curl.dll is enabled.
If it's not, activate it by removing a semicolon from the following line in the php.ini file used by your web server:

;extension=php_curl.dll

Once you were sure that the needed extension is enabled you can move to setup.

To sync Scheduler with Google Calendar you should:

  1. Download the 'gCal_proxy_v2' package.

  2. Unzip the package into the root directory of your web server.

    Server-side:

  3. Open the '01_proxy.php' file placed at [rootFolder]\gCal_proxy\server\ in notepad.
    The file contains the standard proxy initialization code:

    <?php

$email = "";
$pass = "";
$cal = "";

include('google_proxy.php');
$calendar = new GoogleCalendarProxy($email, $pass, $cal);
//$calendar->map("location", "details");
$calendar->connect();

?>
  4. Set values for 3 variables and leave the rest of the code as it is.

    Variables that you should set values for:
    • $email - the user name of your Gmail account;
    • $pass - the password of your Gmail account;
    • $cal - the name of your Google Calendar.

      Be sure that you wrote the correct values. For example, if the name of your calendar is test@googlemail.com, the value test@gmail.com results in an error.

  5. Save the changes and close the file.

    Client-side:

  6. Open the HTML file containing the initialized scheduler. If you don't have any scheduler initialized, create a new HTML file in the root folder of your web server.

  7. Initialize scheduler in a standard way (see the details of initialization or a code example).

  8. Load events of Google Calendar to Scheduler through the load() method. Set its parameter to the path to the '01_proxy.php' file which you modified some time ago.

    scheduler.load("../gCal_proxy/server/01_proxy.php");
  9. Initialize dataprocessor, to provide 2-way sync.

    • Include one more file.

      <script src="../gCal_proxy/sample/codebase/dhtmlxdataprocessor.js" type="text/javascript" charset="utf-8"></script>
    • Take the path to the same php file '01_proxy.php' as the parameter of the constructor.

      var dp =  new dataProcessor("../gCal_proxy/server/01_proxy.php");
dp.init(scheduler);//'scheduler' is the name of the scheduler instance.

The sync is finished. You can find the ready-to-use example 'sample.html' at [rootFolder]\gCal_proxy\sample\.

Export

To export events from Google Calendar to your database, just follow these steps:

  1. Open the '03_export.php' file placed at [rootFolder]\gCal_proxy\server\ in notepad.
  2. Set values for the variables and leave the rest of the code as is.

    Variables that you should set values for:
    • $email - the user name of your Gmail account;
    • $pass - the password of your Gmail account;
    • $cal - the name of your Google Calendar;
    • $db_host - the name of your MySQL server host or IP-address;
    • $db_user - the username of your MySQL account;
    • $db_pass - the password of your MySQL account;
    • $db_name - the name of your MySQL database;
    • $db_table - the name of the database table;

  3. Save changes and close the file.
  4. Run the '03_export.php'.
  5. Once the file has been run, events from Google Calendar will be saved to the appropriate database table.

The function 'export()' returns a number of records that have been exported from Google Calendar

Import

To import events from your database to Google calendar, just follow these steps:

  1. Open the '02_import.php' file placed at [rootFolder]\gCal_proxy\server\ in notepad.
  2. Set values for the variables and leave the rest of the code as is. Variables that you should set values for are the same as in case of exporting.
  3. Save changes and close the file.
  4. Run the '02_import.php'.
  5. Once the file has been run, events from the database will be moved to the Google Calendar.

The function 'import()' returns a number of records that have been imported to Google Calendar

How to pass additional information related to the event

Google Calendar has one set of fields and Scheduler has the other. So, to sync (import or export) the event information correctly you should set mapping between the related fields of the calendars.

By default, there is the following mapping between Google Calendar and Scheduler:

Google Calendar ↔ Scheduler
id ↔ id
title ↔ text
startTime ↔ start_date
endTime ↔ end_date

Additionally, you can pass information of the following Google Calendar fields:

Field | Description
canEdit | defines whether the logged-in user can edit the current event. Possible values: '0' or '1'
created | the event creation date in gcal format
details | the event details
updated | the last update date of the event in gcal format
location | the location where the event takes place in
status | shows the current status of the event: cancelled (the event is canceled), confirmed (the event is confirmed), tentative (the event is tentatively scheduled)

To pass some additional info, follow the steps below:

Server-side:

  1. According to the desired action, open in notepad the appropriate file placed at [rootFolder]\gCal_proxy\server\: to sync - '01_proxy.php', to import - '02_import.php', to export - '03_export.php'.

  2. Map the desired fields by using the method map(). For example, if you want to get the location of the event (in addition to the text, start and end times) you should write the following line:

    $calendar->map("location", "place");
    • location - the name of the Google Calendar field;
    • place - the name of the related Scheduler field. You can write any name here.

  3. Save changes and close the file.

Client-side:

  1. Open the HTML file containing the initialized scheduler.

  2. Add to the definition of the scheduler:

    • the lightbox section:

      scheduler.config.lightbox.sections=[
                        ...
                        {name:"placeField", height:50, map_to:"place", type:"textarea"}
];

      where the map_to parameter must be set to the value specified on server-side (see above).

    • the label of the newly added section:

      scheduler.locale.labels.section_placeField = 'Place';

      where after the underscore you should specify the name of the related section.

  3. Save changes and close the file.


dhtmlxscheduler:sync_code_example [DHX documentation]

Code example

index.html

<!DOCTYPE html>
<head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
</head>
    <script src="../gCal_proxy/sample/codebase/dhtmlxscheduler.js" type="text/javascript" charset="utf-8"></script>
    <link rel="stylesheet" href="../gCal_proxy/sample/codebase/dhtmlxscheduler.css" type="text/css" media="screen" title="no title" charset="utf-8">

<style type="text/css" media="screen">
    html, body{
        margin:0px;
        padding:0px;
        height:100%;
        overflow:hidden;
    }
</style>

<script type="text/javascript" charset="utf-8">
    function init() {
        scheduler.config.multi_day = true;

        scheduler.locale.labels.section_text = 'Description';
        scheduler.locale.labels.section_details = 'Details';

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

        scheduler.config.xml_date="%Y-%m-%d %H:%i";
        scheduler.init('scheduler_here',new Date(),"week");
    }
</script>

<body onload="init();">
    <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>
</body>


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

scheduler.date.add(initial_date_object, increment, unit); // returns new date object

//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:api_reference [DHX documentation]

dhtmlxScheduler API Methods

Core

  • addEvent - adds new event
  • addEventNow - adds new event and opens lightbox form to confirm
  • 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
  • formSection - allows to get|set values in the lightbox
  • 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
  • serverList - creates or returns a named list of options
  • 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
  • updateCollection - updates named list of options

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+)

Limits extension

  • blockTime - block specified time slots


dhtmlxscheduler:api_method_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:api_method_dhtmlxscheduler_addeventnow [DHX documentation]

addEventNow(event_obj)

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

adds new event and opens lightbox form to confirm

  • event_obj - object with all event properties you wish to specify, optional
   scheduler.addEvent();
//or
   scheduler.addEvent({
          start_date: new Date(2011,5,13,15),
          end_date: new Date(2011,5,13,18),
          text: "My new event",
          custom_data: "some data"
   });


dhtmlxscheduler:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_dhtmlxscheduler_formsection [DHX documentation]

formSection(name)

Required library edition: This method works with any edition of DHTMLX library

  • name - name of lightbox section

allows to get|set values in the lightbox

    //get value
var value = scheduler.formSection('description').getValue();
    //set value
scheduler.formSection('description').setValue('abc');


dhtmlxscheduler:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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
  • new_event - if new event is used (for example if lightbox is displayed for new event or not) (ver. 3.0+)

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:api_method_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:api_method_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 - the server side url ( may be a static xml or server side script which outputs data as XML )
  • type - the type of loading data
  • 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:api_method_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:api_method_dhtmlxscheduler_serverlist [DHX documentation]

serverList(list_name, array)

Required library edition:

returns named list of options

  • name of a list
  • array of options, optional

If called only with the first parameter (list_name) then returns a list with that name (if present). It's possible to pass array as a second parameter and then list_name will be bond with that array.

// returns list of options with the name my_list
var array = scheduler.serverList("my_list");
...
// creates and returns specified list
var list = scheduler.serverList("options", [
    {key: 1, label: "John"},
    {key: 2, label: "Adam"},
    {key: 3, label: "Diane"}
]);

Such named lists are used in the updateCollection function, that's why if there is need to update collections, e.g. select options, list of units in timeline, treetimeline, units view it's a good idea to create them as a named list of options.

// with such declaration it would be possible to update options in the select element though the list named 'goods'
scheduler.config.lightbox.sections=[
    {name:"description", height:130, map_to:"text", type:"textarea" , focus:true},
    {name:"items", height:23, type:"select", options:serverList("goods", goods_array) , map_to:"section_id" },
    {name:"time", height:72, type:"time", map_to:"auto"}
];
...
// same here with the "units" list
scheduler.createUnitsView({
    name:"unit",
    property:"section_id",
    list:scheduler.serverList("units", sections),
    size:20,
    step:1
});


dhtmlxscheduler:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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.

The function should be called after the scheduler.init() call but before loading the data into Scheduler.


dhtmlxscheduler:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_dhtmlxscheduler_updatecollection [DHX documentation]

updateCollection(collection_name, new_collection)

Required library edition:

updates specified collection with the new options

  • name of the collection to update
  • new collection to use

Return true in case of successful update or false if collection was not found.

Note: function also calls onOptionsLoad event and resets lightbox.
Note: collection can be created with the serverList function.

Examples:
1. Lightbox was configured following way:

scheduler.config.lightbox.sections=[
    {name:"description", height:130, map_to:"text", type:"textarea" , focus:true},
    {name:"items", height:23, type:"select", options:serverList("goods", goods_array) , map_to:"section_id" },
    {name:"time", height:72, type:"time", map_to:"auto"}
];

To update list of items use:

scheduler.updateCollection("goods", new_goods_array);

2. Units view was created with following options:

scheduler.createUnitsView({
    name:"unit",
    property:"section_id",
    list:scheduler.serverList("units", sections),
    size:20,
    step:1
});

To update list of the displayed units use:

scheduler.updateCollection("units", new_sections_array);


dhtmlxscheduler:api_method_dhtmlxscheduler_createunitsview [DHX documentation]

createUnitsView(configuration)

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

creates a units view

Method accepts the only parameter - configuration object

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

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"}	],
        skip_incorrect:true,
    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
  • skip_incorrect - skips events which belong to none of the units. By default, false.
  • size - optional, count of units on the screen ( if real count exceeds this value, scroll buttons will be shown )
  • step - step of scrolling


dhtmlxscheduler:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_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:api_method_dhtmlxscheduler_blocktime [DHX documentation]

blockTime(date, time_points)

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

  • date — js date object, or number ( if number provided - it will be treated as day of week )
  • time_points - array of time points, or “fullday” string

Mark specified time slots as disabled, blocks new event creation in that time.

//disallow any event for specific day
scheduler.blockTime(new Date(2009,5,30), "fullday");
//disallow events from 0 till 10 hours, for specific date
scheduler.blockTime(new Date(2009,6,3), [0,10*60]);
//disallow events from 0 till 8 and from 18 till 24 hours, for saturday
scheduler.blockTime(6, [0,8*60,18*60,24*60]);
//disallow any event for specific week-day (sunday)
scheduler.blockTime(0, "fullday","weekly");


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
    <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>

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

For example:

    scheduler.config.repeat_date = "%m/%d/%Y";

List of possible values is available on the date formatting page.

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]_[day]_[count2]_[days]#[extra]

  • type - type of repeating “day”,”week”,”month”,”year”
  • count - how much intervals of “type” come between events
  • day and count2 - 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 was 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: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 (not only on time).

At first, an additional js file needs including.

    <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.createUnitsView({
    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

Skipping events

If some event belongs to none of the defined units it's presented in the first unit. Starting from the version 3.0 you have the possibility to skip such events and not to display them at all.
To do this, use the property skip_incorrect:

scheduler.createUnitsView({
    name:"unit",
    property:"section_id",
    list:sections,
        skip_incorrect:true
});

By default, the property takes the value 'false'.


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>

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 increased 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 (non-applicable to cells with folder names)
  • fit_events - if section height should be increased to fit all events in there or should it be fixed (dy property). Set to true by default. Available starting with version 3.0

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 many 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

Second x scale

This option adds another x scale to the top of the default one and serves to group time intervals on the original scale. Available with 3.0+ version.

Object with two options is used to enable second scale option:

  • x_unit - size of units on X scale ( can be hour, day, week, month, year )
  • x_date - date format which should be used for second scale, “July 01”
scheduler.createTimelineView({
    // other properties
    second_scale: { // adding such object to createTimelineView parameters enables second header
        x_unit: "day", // size of unit which should be used for second scale
        x_date: "%F %d" // would be translated to "July 01" for example
    }
});

Templating

All templates need to be redefined after createTimelineView call

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

text for the y-scale cells:

scheduler.templates.timeline_scale_label = function(section_id, section_label, section_options){
    return section_label+" (id: "+section_id+")";
};

css class for y-scale cells:

scheduler.templates.timeline_scaley_class = function(section_id, section_label, section_options){
    return "some_css_class";
};

css class for x-scale header

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

css class for second x-scale header

scheduler.templates.timeline_second_scalex_class = function(date){ /* your code here */ }

css class for timeline cells:

scheduler.templates.timeline_cell_class = function(evs, date, section){
    // evs - list of events which will be displayed in this cell
    // date - date for which cell is displayed
    // section - object with section's properties(e.g. section.key, section.label)
    return ""; // css class which will be assigned
}

format of date in the x-scale (3.0+ version)

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

format of date in the second x-scale (3.0+ version)

scheduler.templates.timeline_second_scale_date=function(date){ /* your code here */ }

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:agenda_view [DHX documentation]

Agenda view

View allows to see a 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>
  • 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 the 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 adds 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:week_agenda [DHX documentation]

Week agenda view

Week agenda is a combination of week and agenda views presenting a list of oncoming events inside a week.

Related sample: samples/03_extensions/24_week_agenda.html

Steps to enable

  • include
<script src="../../codebase/ext/dhtmlxscheduler_week_agenda.js" ></script>
  • 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="week_agenda_tab" style="right:280px;"></div>

GUI details

Selected events are highlighted. If a selected event occupies several days, all related records are highlighted.

To create a new event: double click the cell of a day which will be the holder of the creating event.
To edit, delete an event: double click the desired event to open the details form.

Customization options

  • scheduler.templates.week_agenda_event_text template specifies the text of events

    scheduler.templates.week_agenda_event_text = function(start_date, end_date, event, date, position) {
    switch(position){
        case "middle": // template for days from the second to the penultimate one of multi-day events
            return "- " + event.text;
        case "end": // template for the last day of multi-day events
            return "End: "+scheduler.templates.event_date(start_date) + " " + event.text;
        case "start": // template for the first day of multi-day events
            return "Start: "+scheduler.templates.event_date(start_date) + " " + event.text;
        default: // template for one-day events
            return scheduler.templates.event_date(start_date) + " " + event.text;
    }
};

    where

    • start_date - the start date of the event
    • end_date - the end date of the event
    • event - the event object
    • date - the date of the event
    • position - ('start', 'middle', 'end') specifies the position of a certain day in multi-day event.
      • 'start' position defines the first day of the event.
      • 'end' position defines the last day of the event.
      • 'middle' position defines days from the second to the penultimate one.
  • scheduler.templates.week_agenda_scale_date template specifies the format of date of days' cells.

    scheduler.templates.week_agenda_scale_date = function(date) {
    return scale_date_format(date);
};

    where

    • date - the date of the event

Configuring week agenda

Week agenda uses standard templates and configuration options. See details in the related chapters of the documentation: Configuration and Templates.


dhtmlxscheduler:year_view [DHX documentation]

Year view

View allows to see a 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>
  • 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: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>
  • 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 template
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 {integer}
scheduler.config.map_zoom_after_resolve = 15;
  • Template that is used to set date format for 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 for 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: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

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

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

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: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+.

Work hours limiting

In addition to the above technique, more advanced configuration can be done, to define work hours limits for specific dates ( hours in which you allow|deny new event creation )

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

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

After that you can use

//disallows any event for specific day
scheduler.blockTime(new Date(2009,5,30), "fullday");
//disallows events from 0 till 10 hours, for specific date
scheduler.blockTime(new Date(2009,6,3), [0,10*60]);
//disallows events from 0 till 8 and from 18 till 24 hours, for saturday
scheduler.blockTime(6, [0,8*60,18*60,24*60]);
//disallows any event for specific week-day (sunday)
scheduler.blockTime(0, "fullday");


dhtmlxscheduler:tooltips [DHX documentation]

Tooltips

This extension allows to create tooltips over events in the scheduler which could be used to display additional information about event without need to actually 'open' event to check it.

To activate extension you need to include the dhtmlxscheduler_tooltip.js file:

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

After that tooltips will be displayed with the default settings:

It's possible to configure and customize several parameters of the tooltip window:

dhtmlXTooltip.config.className = 'dhtmlXTooltip tooltip'; // sets the CSS classname of the tooltip window
dhtmlXTooltip.config.timeout_to_display = 50; // delay of the rendering
dhtmlXTooltip.config.delta_x = 15; // X position relative to the cursor (positive - margin to the right, negative - to the left)
dhtmlXTooltip.config.delta_y = -20; // Y position relative to the cursor (positive - above the cursor, negative - below)

Special template scheduler.templates.tooltip_text is handling what should be displayed inside tooltip, it's possible to redefine it:

var format=scheduler.date.date_to_str("%Y-%m-%d %H:%i");
scheduler.templates.tooltip_text = function(start,end,event) {
    return "<b>Event:</b> "+event.text+"<br/><b>Start date:</b> "+format(start)+"<br/><b>End date:</b> "+format(end);
};


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 solution to define different colors for events is use @color and @textColor properties in data xml. This values will be used a color of event bar and color of text in the event bar.

<data>
    <event start_date="2011-04-23" end_date="2011-04-23" text="My event" color="#00FF88" textColor="orange">
    ...

The more complex way to redefine events appearance is usage of 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

Cascade event display

Events can be displayed as a cascade. It's possible to specify how many levels there should be and margin between them.

    scheduler.config.cascade_event_display = true; // to enable cascade rendering
    scheduler.config.cascade_event_count = 4; // how many levels (maximum) should be used
    scheduler.config.cascade_event_margin = 30; // margin in px between levels


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>

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:filtration [DHX documentation]

Events Filtration

For any specified view you can set filtration function that will define which events should be displayed and which should not be. The function is called for each view.

scheduler.filter_week = function(ev_id, event){
if(event.name == 'New event')
    return false; // event will be filtered (not rendered)
    //or
    return true; // event will be rendered
}

Where, 'week' is the name of a view.

You can set either an individual function for each view or the same one for all views:

scheduler.filter_day = scheduler.filter_week = scheduler.filter_month = scheduler.filter_timeline = function(ev_id, event){
...
}


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 are defined through scheduler.config.lightbox.sections (see details here), 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.labels collection. For example, for “time” section , label will be taken as scheduler.locale.labels.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);
  }

Buttons at form's bottom

By default scheduler has 3 button at bottom - save, cancel, delete, which are configured as

scheduler.config.buttons_left=["dhx_save_btn","dhx_cancel_btn"];
scheduler.config.buttons_right=["dhx_delete_btn"];

if necessary you can remove buttons from lightbox by altering the above configuration collection. Also, you can add the custom button

scheduler.config.buttons_right = ["dhx_custom_btn_info"];
scheduler.locale.labels["dhx_custom_btn_info"] = "Info";
scheduler.attachEvent("onLightboxButton", function(button_id, node, e){
    alert(button_id);
});
.dhx_custom_btn_info{
    background-image:url('../../codebase/imgs/controls.gif');
    background-position: -2px 0px;
    width:20px;
}

Beware that lightbox configuration need to be done BEFORE scheduler.init command.

Standard buttons:

Redefined buttons:

Wide (netbook-friendly) form

You can switch form to the wide-layout, by using

scheduler.config.wide_form = true;

Result form will require much lesser vertical space and can be used for devices with small-to-medium screens ( most netbooks ), for which default lightbox can be too big.

Standard form:

Wide form:

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.

API for lightbox sections

You can use the next api to get|set values from|to lightbox sections

    //get value
var value = scheduler.formSection('description').getValue();
    //set value
scheduler.formSection('description').setValue('abc');

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 (if dynamic loading is used)
  • 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:"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:minicalendar [DHX documentation]

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>

The scheduler will provide two basic methods

//show mini calendar
var calendar = scheduler.renderCalendar({
    container:"some_id",
    date:new Date(),
    handler:function(date,calendar){
        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's possible to 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");
//date value on the event's details form
scheduler.templates.calendar_time = scheduler.date.date_to_str("%d-%m-%Y");


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: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'>

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: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_ca.js | not translated
Chinese | sources/locale_cn.js | sources/locale_recurring_cn.js
Czech | sources/locale_cs.js | sources/locale_recurring_cs.js
Danish | sources/locale_da.js | sources/locale_recurring_da.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
Greek | sources/locale_el.js | sources/locale_recurring_el.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
Turkish | sources/locale_tr.js | not translated
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 requires 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:external_plugin:wordpress [DHX documentation]

dhtmlxScheduler for the Wordpress

To use the Scheduler plugin in WordPress you should perform the following actions:

  1. ;
  2. ;
  3. .

Download links:

  • The most recent version of Wordpress;
  • The plugin package.

What's new? Version 3.0

The release 3.0 brought a number of new features to the Scheduler plugins: has fixed all bugs and problems detected since the previous version, improved the security aspects and added new configuration options.

New features:

  1. Import/Export to Google Calendar.
  2. 2 new available views: Week agenda and Map view.
  3. The possibility to hide columns in the Unit view.
  4. Special template providing the name of the event author.
  5. The possibility to show the second scale in the Timeline view.
  6. Skin styling. You can set any color scheme for your scheduler.
  7. Button Print to PDF. Now you needn't to add any additional files, just enable the related option on the control panel and the button invoking export will be added to the sheduler.
  8. Button Export to iCal. It also allows you to provide export with none extra files added.

Installing the plugin

WordPress offers the following way of adding the plugin to your page (the Google Chrome browser is used):

  • Download the Scheduler package to your local machine as a zip file;
  • From the Administration panel click on the Plugins tab;
  • Select Add New;
  • From the Workspace click on the Upload tab;
  • From the tab click the button Choose file and choose the directory to your plugin package in the opened browse window;
  • Click the button Install Now.

Activating the plugin

Once you have uploaded the plugin to your WordPress plugin directory, you should activate it from the Plugins Management page.

  • From the Administration panel click on the Plugins tab;
  • Select Plugins;
  • To turn the plugin on, click Activate in the same row as the Scheduler plugin entry.

Using the plugin

Please note, the following users groups can edit Scheduler:

  • Administrator;
  • Editor.

To add Scheduler to a post or a page you should insert the appropriate Scheduler marker:

You can insert any text before
[[scheduler_plugin]]
or after scheduler instance

The plugin provides a special button [image] in the workspace. It allows you to add events and place the links to them on the page.

Configuration

Scheduler can be configured through the admin panel available from the Plugin tab (the Scheduler entry). Read more on the topic in article Universal plugin control panel.

'Upcoming events' widget

The plugin provides a widget allowing you to present upcoming events on the page. You can get the widget from Appearance→Widgets→Upcoming events.

The appearance of the sidebar can be customizes by changing template sidebar.php placed in the package.


dhtmlxscheduler:external_plugin:joomla [DHX documentation]

dhtmlxScheduler for Joomla!

To use the Scheduler plugin in Joomla you should perform the following actions:

  1. ;
  2. .

Download links:

  • Page at joomla.org;
  • Page at dhtmlx.com.

What's new? Version 3.0

The release 3.0 brought a number of new features to the Scheduler plugins: has fixed all bugs and problems detected since the previous version, improved the security aspects and added new configuration options.

New features:

  1. Import/Export to Google Calendar.
  2. 2 new available views: Week agenda and Map view.
  3. Support of custom users groups.
  4. The possibility to hide columns in the Unit view.
  5. Special template providing the name of the event author.
  6. The possibility to show the second scale in the Timeline view.
  7. Skin styling. You can set any color scheme for your scheduler.
  8. Button Print to PDF. Now you needn't to add any additional files, just enable the related option on the control panel and the button invoking export will be added to the sheduler.
  9. Button Export to iCal. It also allows you to provide export with none extra files added.

Installing and activating the plugin

Joomla offers the following way of installing and activating the plugin to your article:

  • Download the Scheduler package to your local machine as a zip file;
  • From the Administration panel click on the Extensions tab. A dropdown list will appear;
  • In the dropdown list select Extension Manager;
  • From the tab, click the button Browse and choose the directory to your plugin package in the opened browse window;
  • Click the button Upload & Install.

Once Scheduler has been installed, it will be activated automatically.

Using the plugin

Please note, the following users groups can edit Scheduler:

  • Super user (Super administrator before 1.6 version);
  • Administrator;
  • Manager.

To add Scheduler to an article you should follow the next steps:

  • From the Administration panel click on the Menus tab. A dropdown list will appear;
  • With the help of the dropdown list, add a new menu item to the desired place. For example, select Top→Add New Menu Item.
  • In opened page Menu Manager: New Menu Item, fill in field Menu Item Type: click button Select and select Scheduler→Link to Scheduler page.
  • Set any other desired configuration options, and click button Save. A new page with Scheduler will be added to the site.

Configuration

Scheduler can be configured through the admin panel available from the Components tab (the Scheduler entry). Read more on the topic in article Universal plugin control panel.


dhtmlxscheduler:external_plugin:universal_plugin_control_panel [DHX documentation]

Universal plugin control panel

The control panel of the plugin has 8 panes:

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

Settings

The pane contains general configuration options.

  • Sizes
    • Scheduler width - the width of the scheduler on the page.
    • Scheduler height - the height of the scheduler on the page.
  • Wordpress Specific
    • Link to the Scheduler - the path to the page where the scheduler will be placed on.
    • Show blog posts as events - defines whether blog posts will be added to the scheduler as events.
  • Modes - contains available views. Check those of them which tabs you want to present in your scheduler.
  • Debug
    • Debug mode - allows you to get detailed reports when data is not loaded or not saved correctly.
  • General settings
    • Repeat events - enables support of recurring events.
    • Sunday is the first day of the week - specifies whether a week will be started from Sunday (check the option) or from Monday (leave the box unchecked).
    • Multiday events in day and week views - enables support of multi-day events.
    • Full day events - if the option is enabled then entry fields in the 'Time period' section of the lightbox while creating events will be blocked and the time period will be set to the full day from 00.00 the current cell date untill 00.00 next day.
    • Mark now - if the option is enabled then the day and week views will have marker displaying the current time.
    • Create events by single-click - allows creating new events by a single click.
    • Prevent overlapping - allows only one event in the same timeslot.
    • Expand button - adds the expand button, allowing you to view the scheduler in full screen.
    • Print to PDF - adds the button that will invoke exporting to PDF.
    • Print to iCal - adds the button that will invoke exporting to iCal.
    • Mini-calendar navigation - adds the mini-calendar control to the toolbar for setting the scheduler date.

Access rights

This is the pane for managing users rights for adding/editing/deleting events.

The pane allows you to define the 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 the 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

This pane lets you define different templates that can be used to change dispaying dates and titles in the scheduler.

You can define templates for:

  1. Dates.
    • http://docs.dhtmlx.com/doku.php?id=dhtmlxscheduler:settings_format
    • http://docs.dhtmlx.com/doku.php?id=dhtmlxscheduler:settings_config
  2. Time scales.
  3. Events
    • Render event author name - allows you to display the name of the event author.
      Once you have enabled the option - the client start to receive the login of the user created the event, in addition to the standard set: the text, the start and end dates. Also templates will be supplemented with the related text to display the author name in events.
      If you then disable the option - the login name will stop being passed and displayed in the events.

For more information of available templates and their syntax, please follow the “See more about date formats here” link in the bottom right corner of the related section.

Events administration

The pane shows the list of all events and allows you to add/edit/delete them there.

Custom fields

The pane allows you to add custom fields to the lightbox.

There are two types of custom fields:

  • Textarea - a text field.
  • Select list - a select box with the list of options.

Each field can have:

  • Name - the name of the field in DB ( will be created automatically )
  • Description - the title of the field in the lightbox.

The select list fields have some extra flags:

  • Use colors for events - allows you to define what color events will have depending on the option selected in the field.
  • Use as Units - adds the unit view based on the list of options to the scheduler.
  • Timeline type - adds the timeline view with one of the following time-scale units:
    • Day
    • Working Day
    • 3 days
    • Week
    • Working week
    • Month
    • Year
  • Timeline second scale - allows you to add the second scale to the Timeline view.

Note, you can use the hide column to not display some column in the scheduler.

Google calendar export

Provides the synchronization with Google Calendar and allows you to import to or export from Google Calendar.
Fill up the fields with account information and click the button appropriate to your needs. If the information entered by you is correct you'll see message 'Well done'.

To pass data from DHTMLX Scheduler to Google Calendar - click button 'Export'.
To pass data from Google Calendar to DHTMLX Scheduler - click button 'Import'.

Skinning

The pane is for styling the scheduler.
Select the desired color scheme (can use one of presets) and click the button 'Apply'. The scheme will be set and you can preview the gotten result in the right section.
Beware, if the option Use custom color is unchecked - your selected color won't be applied.

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:mobile [DHX documentation]

Mobile scheduler

The current documentation refers to the mobile version of the scheduler.
It was developed on base of DHTMLX Touch library to be used in apps for mobile and touch devices, such as iPhone or iPod.

Guide

  • Initialization
  • Loading & saving data
  • Configuration
    • Date configuration
    • Templates
    • Sizes of elements
    • 'Details form'
  • Styling
  • Read-only mode
  • Reccuring events
  • Offline storage
  • Localization
  • Advanced: changing the structure of the scheduler


dhtmlxscheduler:mobile_initialization [DHX documentation]

Initialization

To use the mobile scheduler in your application you should make 2 steps:

  1. .
  2. .

Included files

You need to include 2 files. They are:

<script src="codebase/dhxscheduler_mobile.js" type="text/javascript"></script>
<link rel="STYLESHEET" type="text/css" href="codebase/dhxscheduler_mobile.css">

Initialization

To initialize the component you should use the following code:

//dhx.ready() function ensures that your code will be executed as soon as the page finishes loading
dhx.ready(function(){
    //the method allows you to hide the address bar on iPhone/iPod to save the space for application
    dhx.ui.fullScreen();
    //object constructor
    dhx.ui({
        view: "scheduler",
    id: "scheduler"
    });
    // method load() lets you to populate the scheduler with data
    $$("scheduler").load("../common/mobile.xml","scheduler");
});

Related sample: samples/01_basic/01_init.html


dhtmlxscheduler:mobile_data [DHX documentation]

Loading & Saving data

Loading data

To load events to the scheduler you should use either the method load() or the method parse():

$$("scheduler_id").load("data/events.xml","xml");
//or
$$("scheduler_id").parse([
    { id:1, start_date:"2009-7-1 6:00", end_date:"2009-7-1 8:00", text:"Event 1"},
    { id:2, start_date:"2009-7-2 6:00", end_date:"2009-7-2 8:00", text:"Event 2"}
],"json");

The method load() takes 2 parameters and loads data from some external URL:

  • url - the data url.
  • type - the type of loading data: 'json', 'xml' or 'scheduler'.

The method parse() also takes 2 parameters but loads data from a data object:

  • data - the string or object, which represents data.
  • type - the type of loading data: 'json', 'xml' or 'scheduler'.

Related sample: samples/01_basic/01_init.html

Supported data types

The mandatory data fields:

  • start_date - the start date of an event in the format 'yyyy-mm-dd hh:mm:ss' (format details).
  • end_date - the end date of an event in the format 'yyyy-mm-dd hh:mm:ss' (format details).
  • text - the title of an event.

The optional data fields:

  • details - the description of an event.
  • any custom.

json

[
 { id:1, start_date:"2011-05-24 00:00:00", end_date:"2011-06-08 00:00:00", text:"French Open", details:"Philippe-Chatrier Court Paris, FRA" },
 { id:2, start_date:"2011-06-10 00:00:00", end_date:"2011-06-13 00:00:00", text:"Aegon Championship", details:"The Queens Club London, ENG" }
]

xml

<data>
    <item id="1">
        <start_date>2011-05-24 00:00:00</start_date>
        <end_date>2011-06-08 00:00:00</end_date>
        <text>French Open</text>
        <details>Philippe-Chatrier Court Paris, FRA</details>
    </item>
        ...
</data>

scheduler

<data>
    <event id="1">
        <start_date>2011-05-24 00:00:00</start_date>
        <end_date>2011-06-08 00:00:00</end_date>
        <text>French Open</text>
        <details>Philippe-Chatrier Court Paris, FRA</details>
    </event>
        ...
</data>

Saving data

The mobile scheduler lets you to save data back to DB: during initialization of the scheduler you should specify the appropriate server file in the parameter 'save' of the object constructor.

dhx.ready(function(){
    dhx.ui({
        view: "scheduler",
        id: "scheduler",
        save: "php/events.php"
    });
    $$("scheduler").load("php/events.php","scheduler");
});

If you use dhtmlxConnector, the path to its file can be set as this parameter. In this case, dhtmlxConnector will do all the server work.

Related sample: samples/01_basic/05_data_saving.html


dhtmlxscheduler:date_configuration [DHX documentation]

Date configuration

Common information

In the scheduler you are allowed to configure formats (using in dates) and sizes of the elements.

To set the desired option, just write it as it's stated in this documentation. Beware, configuration options should go before the code line with scheduler initialization.

scheduler.config.init_date = new Date(2011,5,1);
scheduler.config.day_date = "%d/%m/%Y";
//configuration options should go before the constructor
dhx.ui({
    view: "scheduler",
    id: "scheduler"
});
$$("scheduler").load("../scheduler/mobile.xml","scheduler");

Related sample: samples/01_basic/02_date_format.html

Configuration options

  • scheduler.config.calendar_date - (string) the date format for the header in the 'month' view (by default, ”%F %Y”)
  • scheduler.config.calendar_hour - (string) the format for hours in the 'start(end) date edit form' (by default, ”%h:%i”)
  • scheduler.config.init_date - (date object) the initial date of the scheduler (by default, the current date)
  • scheduler.config.item_date - (string) the format for the date in the 'list' view (by default, ”%d.%m.%Y”)
  • scheduler.config.form_all_day - (string) the format for dates of the 'start', 'end' fields in the 'Details form' in case the All day option is set (by default, ”%d-%m-%Y” )
  • scheduler.config.form_date - (string) the format for dates of the 'start', 'end' fields in the 'Details form' in case the Time option is set (by default, ”%d-%m-%Y %H:%i”)
  • scheduler.config.header_date - (string) the format for the date in the 'day' view (by default, ”%d.%m.%Y”)
  • scheduler.config.hour_date - (string) the format for the time in the 'list' view (by default, ”%h:%i”)
  • scheduler.config.multi_day - (string) the format of presenting multi-day events in the 'Details form' (by default, ”%l, %d %F %Y”)
  • scheduler.config.scale_hour - (”%H” or ”%h”) the format for the hours in the 'day' view (by default, ”%H”)
  • scheduler.config.server_utc - (boolean) the 'true' value says the scheduler to convert server side dates from utc to local timezone and backward during sending data to server;
  • scheduler.config.xml_date - (string) the date format in data files. Used by the parser to recognize dates (by default, ”%Y-%m-%d %H:%i”)

Date format

Format string can contain any separator character and any element from the following list:

  • %d - the day as a number with a leading zero ( 01 to 31 );
  • %j - the day as a number without a leading zero ( 1 to 31 );
  • %D - the day as an abbreviation ( Sun to Sat );
  • %l - the day as a full name ( Sunday to Saturday );
  • %m - the month as a number without a leading zero ( 1 to 12 );
  • %n - the month as a number with a leading zero ( 01 to 12);
  • %M - the month as an abbreviation ( Jan to Dec );
  • %F - the month as a full name ( January to December );
  • %y - the year as a two-digit number ( 00 to 99 );
  • %Y - the year as a four-digit number ( 1900–9999 );
  • %h - the hour based on the 12-hour clock ( 00 to 11 );
  • %H - the hour based on the 24-hour clock ( 00 to 23 );
  • %i - the minute as a number with a leading zero ( 00 to 59 );
  • %s - the second as a number without a leading zero ( 00 to 59 );
  • %a - displays am (for times from midnight until noon) and pm (for times from noon until midnight);
  • %A - displays AM (for times from midnight until noon) and PM (for times from noon until midnight).

For example, if you want to present 1st June 2011 as 01/06/2011, you should specify ”%d/%m/%Y”.


dhtmlxscheduler:templates [DHX documentation]

Templates

The mobile scheduler lets you define 10 templates. They can be used to change displaying dates and titles in the scheduler. Beware, templates' definitions should go before the code line with scheduler initialization.

Below you can find a list of all available templates and their default definitions.

Available templates:

  • - the template for days with events in the 'month' view.
  • - specifies an event in the 'day' view.
  • - specifies an additional css class that will be applied to the events in the lists of the 'list' and 'month' views.
  • - converts a date object to string with ”%d.%m.%Y” formatting.
  • - specifies a marker in the 'list' and 'month' views.
  • - converts a date object to string with ”%H:%i” formatting.
  • - specifies an event in the 'list' view.
  • - specifies an event in the 'month' view.
  • - specifies the default event properties. Used when a user creates new events.
  • - the template for an event in the event preview screen.

Related sample: samples/01_basic/04_templates.html

scheduler.templates.calendar_event

The template for days with events in the 'month' view.

Parameters:

  • date - the date which needs to be formatted
scheduler.templates.calendar_event = function(date){
    return date+"<div class='day_with_events'></div>";
};

scheduler.templates.day_event

Specifies an event in the 'day' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation. See details about the parameter in the related DHTMLX Touch documentation 'API method:type()'
scheduler.templates.day_event = function(obj,type){
    return obj.text;
}

scheduler.templates.event_class

Specifies an additional css class that will be applied to events in the lists of the 'list' and 'month' views.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation. See details about the parameter in the related DHTMLX Touch documentation 'API method:type()'
//The template doesn't have the default definition.
//Below you can find a usage example that illustrates how to highlight the text of the TODAY's events
<style>
.today .dhx_event_text{
      color:red !important;
}

</style>
...
scheduler.templates.event_class =  function(obj, type){
       return (dhx.Date.datePart(obj.start_date).valueOf()==dhx.Date.datePart(new Date()).valueOf())?"today":""
}

scheduler.templates.event_date

Converts a date object to string with ”%d.%m.%Y” formatting.

Parameters:

  • date - the date which needs to be formatted
scheduler.templates.event_date = function(date){
    return dhx.Date.dateToStr("%d.%m.%Y")(date);
};

scheduler.templates.event_marker

Specifies a marker in the 'list' and 'month' views.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation. See details about the parameter in the related DHTMLX Touch documentation 'API method:type()'
scheduler.templates.event_marker = function(obj,type){
       return "<div class='dhx_event_marker' style='"+scheduler.templates.event_color(obj)+"'></div>";
}

scheduler.templates.event_time

Converts a date object to string with ”%H:%i” formatting.

Parameters:

  • date - the date which needs to be formatted
scheduler.templates.event_time = function(date){
    return dhx.Date.dateToStr("%H:%i")(date);
};

scheduler.templates.event_title

Specifies an event in the 'list' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation. See details about the parameter in the related DHTMLX Touch documentation 'API method:type()'
scheduler.templates.event_title = function(obj,type){
    return "<div class='dhx_day_title'>"+scheduler.templates.event_date(obj.start_date)+"</div><div style='margin:10px'><div class='dhx_event_time'>"+scheduler.templates.event_time(obj.start_date)+"</div>"+scheduler.templates.event_marker(obj,type)+"<div class='dhx_event_text'>"+obj.text+"</div></div>";
};

scheduler.templates.month_event_title

Specifies an event in the 'month' view.

Parameters:

  • obj - the event object
  • type - the object that specifies items list presentation. See details about the parameter in the related DHTMLX Touch documentation 'API method:type()'
scheduler.templates.month_event_title = function(obj,type){
    return scheduler.templates.event_marker(obj,type)+"<div class='dhx_event_time'>"+scheduler.templates.event_time(obj.start_date)+"</div><div class='dhx_event_text'>"+obj.text+"</div>";
}

scheduler.templates.new_event_data

Specifies the default event properties. Used when a user creates new events.

scheduler.templates.new_event_data= function(){
    var hours = (dhx.Date.add(new Date(),1,"hour")).getHours();
    var start = dhx.Date.copy(this.coreData.getValue());//coreData refers to the currently selected date
    start.setHours(hours);
        var end = dhx.Date.add(start,1,"hour");
        return {start_date:start,end_date:end};
};

scheduler.templates.selected_event

The template for an event in the 'event preview' screen.

Parameters:

  • obj - the event object
scheduler.templates.selected_event = function(obj){
     var html = "", fts="", fte="";
     var start = obj.start_date;
     var end = obj.end_date;

     if(!start) return html;
     html += "<div  class='selected_event "+scheduler.templates.event_class(obj)+"' style='"+(obj.color?"background-color:"+obj.color+";":"")+(obj.fontColor||obj.textColor?"color:"+(obj.fontColor||obj.textColor):"")+"'>";
     html += "<div class='event_title'>"+obj.text+"</div>";

     if(dhx.Date.datePart(start).valueOf()==dhx.Date.datePart(end).valueOf()){
         var fd = dhx.i18n.dateFormatStr(start);
         fts = dhx.i18n.timeFormatStr(start);
         fte = dhx.i18n.timeFormatStr(end);
         html += "<div class='event_text'>"+fd+"</div>";
         html += "<div class='event_text'>"+scheduler.locale.labels.label_from+" "+fts+" "+scheduler.locale.labels.label_to+" "+fte+"</div>";
     }
     else{
         var fds = dhx.i18n.longDateFormatStr(start);
         var fde = dhx.i18n.longDateFormatStr(end);
         /*if not "all-day" event*/
         if(!(dhx.Date.datePart(start).valueOf()==start.valueOf()&&dhx.Date.datePart(end).valueOf()==end.valueOf())){
             fts = dhx.i18n.timeFormatStr(start)+" ";
             fte = dhx.i18n.timeFormatStr(end)+" ";
         }
         html += "<div class='event_text'>"+scheduler.locale.labels.label_from+" "+fts+fds+"</div>";
         html += "<div class='event_text'>"+scheduler.locale.labels.label_to+" "+fte+fde+"</div>";
     }
     if(obj.details&&obj.details!==""){
         html += "<div class='event_title'>"+scheduler.locale.labels.label_details+"</div>";
         html += "<div class='event_text'>"+obj.details+"</div>";
     }
     html += "</div>";
     return html;
};


dhtmlxscheduler:sizes_of_elements [DHX documentation]

Sizes of elements

Common information

In the scheduler you are allowed to configure formats (using in dates) and sizes of the elements.

To set the desired option, just write it as it's stated in this documentation. Beware, configuration options should go before the code line with scheduler initialization.

scheduler.xy.confirm_height = 300;
scheduler.xy.confirm_width = 300;
//configuration options should go before the scheduler constructor
dhx.ui({
    view: "scheduler",
    id: "scheduler"
});
$$("scheduler").load("../scheduler/mobile.xml","scheduler");

Dimension configuration

  • scheduler.xy.confirm_height - (integer) the height of the confirm window (by default, 231)
  • scheduler.xy.confirm_width - (integer) the width of the confirm window (by default, 250)
  • scheduler.xy.scale_width - (integer) the total width of the hour and minute columns in the 'day' view. The width is divided equally between the columns (by default, 45)
  • scheduler.xy.scale_height - (integer) the width of a row in the 'day' view (by default, 15)
  • scheduler.xy.list_tab - (integer) the width of the 'List' tab in the bottom tab bar (by default,54)
  • scheduler.xy.day_tab - (integer) the width of the 'Day' tab in the bottom tab bar (by default,54)
  • scheduler.xy.month_tab - (integer) the width of the 'Month' tab in the bottom tab bar (by default,68)
  • scheduler.xy.icon_today - (integer) the width of the 'Today' button in the bottom tab bar (by default,72)
  • scheduler.xy.icon_save - (integer) the width of the 'Save' button (by default,100)
  • scheduler.xy.icon_cancel - (integer) the width of the 'Cancel' button (by default,100)
  • scheduler.xy.icon_done - (integer) the width of the 'Done' button (by default,100)
  • scheduler.xy.icon_edit - (integer) the width of the 'Edit' button (by default,100)
  • scheduler.xy.icon_back - (integer) the width of the 'Back' button (by default,100)
  • scheduler.xy.list_height - (integer) the height of a row in the 'list' view (by default,42)
  • scheduler.xy.month_list_height - (integer) the height of a row in the 'month' view (by default,42)


dhtmlxscheduler:detailsform [DHX documentation]

Details form

Details form is intended for editing events' details.

For customizing 'Details form' you should use the 'scheduler.config.form' object. In this object you must specify all the controls you want the form to contain inside.

Into 'scheduler.config.form' you can put any DHTMLX Touch control ( read about the controls in the related DHTMLX TOUCH documentation 'Controls').
The technique and rules of defining controls are the same as for the 'elements' parameter of the form component in DHTMLX Touch.

By default, 'scheduler.config.form' looks like:

scheduler.config.form = [
        {view:"text",     id:'text',       label:scheduler.locale.labels.label_event, name:'text'},
        {view:"datetext", id:'start_date', label:scheduler.locale.labels.label_start, name:'start_date', dateFormat:scheduler.config.form_date},
        {view:"datetext", id:'end_date',   label:scheduler.locale.labels.label_end,   name:'end_date',   dateFormat:scheduler.config.form_date},
        {view:"toggle",   id:'allDay',     label:"", align: "right", value:"0", options: [
                 {value:"0",label:scheduler.locale.labels.label_time},
                 {value:"1",label:scheduler.locale.labels.label_allday}
        ]},
        {view:"textarea", id:'details',    label:labels.label_details,                name:'details',	 height:150}
];

There are 3 mandatory controls which you can't remove (you are also not allowed to change or remove their parameters 'id' as they're used in the scheduler code files) :

  • text
  • start_date
  • end_date

Two last default controls are optional and you can remove them if it's needed:

  • allDay
  • details

Related sample: samples/01_basic/06_custom_form.html


dhtmlxscheduler:mobile_styling [DHX documentation]

Styling

To customize some element of the scheduler you should redefine the needed attributes of the related css class in the <style> block of your page. The untouched attributes will take default values.

<!DOCTYPE HTML>
<html>
  <head>
    <link rel="stylesheet" href="../../codebase/dhxscheduler_mobile.css" type="text/css" media="screen" charset="utf-8">
    <script src="../../codebase/dhxscheduler_mobile.js" type="text/javascript" charset="utf-8"></script>
        <style>
          .dhx_schedulerbar{
          background:#6699FF !important;
          }
       </style>
  </head>
  <body>

   ....
</html>

In the example above we redefined only the background color. All the other attributes defined in the '.dhx_schedulerbar' class took the default values.

Related sample: samples/01_basic/09_custom_style.html

CSS classes and the related elements

Bottom Toolbar
.dhx_schedulerbar | the toolbar
.dhx_el_button input | the 'Today' button
.dhx_el_button.add input | the '+' (add) button
.dhx_schedulerbar .dhx_el_segmented | the tabbar
.dhx_schedulerbar .dhx_el_segmented .segment_0 | the first tab
.dhx_schedulerbar .dhx_el_segmented .selected.segment_0 | the first tab in the selected state
.dhx_schedulerbar .dhx_el_segmented .segment_1 | the second tab
.dhx_schedulerbar .dhx_el_segmented .selected.segment_1 | the second tab in the selected state
.dhx_schedulerbar .dhx_el_segmented .segment_N | the last tab
.dhx_schedulerbar .dhx_el_segmented .selected.segment_N | the last tab in the selected state
'List' view
.dhx_list_events_item | the items
.dhx_list_events_item .dhx_day_title | the colored label with the date of an event
.dhx_list_events_item .dhx_event_time | the container with the time of an event
.dhx_list_events_item .dhx_event_marker | the round marker displaying before the text of an event
.dhx_list_events_item .dhx_event_text | the container with the text of an event
'Day' view
.dhx_dayevents_event_item | the container with an event
.dhx_topbar | the top toolbar
.dhx_dayevents_scale_item | a single row ( including hours' and minutes' cells)
.dhx_dayevents_scale_top | the top part of an item of the scale
.dhx_dayevents_scale_bottom | the bottom part of an item of the scale
.dhx_dayevents_scale_hour | the container for hours
.dhx_dayevents_scale_minute | the container for minutes
.dhx_cal_prev_button div | the 'previous' icon on the top toolbar
.dhx_cal_next_button div | the 'next' icon on the top toolbar
.dhx_el_label | the container with the date on the toolbar
.dhx_dayevents_scale_event | a single row ( without hours and minutes cells)
'Month' view
.dhx_cal_day_num | the cell with a day
.dhx_cal_month | the top toolbar
.dhx_cal_day_num.dhx_cal_selected_day | the container with the selected day
.dhx_cal_day_num.dhx_cal_current_day | the container with the current date
.dhx_cal_day_num.dhx_cal_current_day.dhx_cal_selected_day | the container with the current date in the selected state
.dhx_cal_day_num .day_with_events | the days that have assigned events
.dhx_cal_day_num.dhx_cal_selected_day .day_with_events | the days that have assigned events in the selected state
.dhx_cal_prev_button div | the 'previous' icon on the top toolbar
.dhx_cal_next_button div | the 'next' icon on the top toolbar
.dhx_list_day_events_item | the items of the list
.dhx_list_day_events_item .dhx_event_time | the time of an event
.dhx_list_day_events_item .dhx_event_marker | the round marker of an item
.dhx_list_day_events_item .dhx_event_text | the text of an event
Events preview screen
.selected_event | the container with an event
.selected_event .event_title | the title of an event
.selected_event .event_text | the description of an event
.dhx_topbar | the top toolbar
.dhx_el_button input | the 'Edit' button
.dhx_el_button.cancel input | the 'Back' button
.dhx_el_formbutton.delete input | the 'Delete' button
Details form
.dhx_topbar | the top toolbar
.dhx_el_button input | the 'Save' button
.dhx_el_button.cancel input | the 'Cancel' button
.dhx_el_box | the style for the element container
.dhx_el_box label | the style for labels of fields (ex. “Event”,”Start”,”End”)
.dhx_el_box .dhx_inp_text | the style for text in inputs
.invalid.dhx_el_box | the style for a div with invalid data (highlighted border by default)
.invalid .dhx_inp_text | the style for an input with invalid data (highlighted text by default)
.dhx_inp_toggle_left_on | the style for the left('Time') part of the toggle in the active state
.dhx_inp_toggle_left_off | the style for the left('Time) part of the toggle in the inactive state
.dhx_inp_toggle_right_on | the style for the right('All day') part of the toggle in the active state
.dhx_inp_toggle_right_off | the style for the right('All day') part of the toggle in the inactive state
.dhx_el_textarea textarea | the textarea style (the “Notes” field)
Start(end) date edit form
.dhx_topbar | the top toolbar
.dhx_el_label | the container with the date on the toolbar
.dhx_el_button input | the 'Done' button
.dhx_el_button.cancel input | the 'Cancel' button
.dhx_cal_day_num | the cell with a day
.dhx_cal_month | the toolbar with the current month
.dhx_cal_day_num.dhx_cal_selected_day | the container with the selected day
.dhx_cal_day_num.dhx_cal_current_day | the container with the current date
.dhx_cal_day_num.dhx_cal_current_day.dhx_cal_selected_day | the container with the current date in the selected state
.dhx_cal_prev_button div | the 'previous' icon on the top toolbar
.dhx_cal_next_button div | the 'next' icon on the top toolbar
.dhx_cal_time_select | the toolbar with the time controls
.dhx_cal_time_select .dhx_hour_select | the control for setting hours
.dhx_cal_time_select .dhx_minute_select | the control for setting minutes
Confirm window
.dhx_el_bigroundbutton input | the cancel button
.dhx_el_bigbutton input | the confirm button


dhtmlxscheduler:read-only_mode [DHX documentation]

Read-only mode

The mobile scheduler can be used in 2 modes:

  • Edit (by default)
  • Read-only

To activate the read-only mode you should set the scheduler.config.readonly option to true. Beware, the option should go before the code line with scheduler initialization.

From now on, users can't modify events. The 'Add', 'Edit', 'Delete event' buttons, allowing to make it, will be hidden.

scheduler.config.readonly = true;
dhx.ready(function(){
    dhx.ui.fullScreen();
    dhx.ui({
        view: "scheduler",
        id: "scheduler"
    });
    $$("scheduler").load("../php/events.php","scheduler");
});

Related sample: samples/01_basic/10_readonly.html


dhtmlxscheduler:reccuring_events [DHX documentation]

Recurring events

Common

By default, the scheduler doesn't support recurring events. To enable such functionality you should include 2 special files instead of regular dhtmlxscheduler_mobile.js, dhtmlxscheduler_mobile.css:

  • dhxscheduler_mobile_rec.js
  • dhxscheduler_mobile_rec.css

The files support all the existing functionality of the standard scheduler + recurring events.

Once the recurring events are enabled, the details form starts look like shown below:

To set a single event with such a form, the user must choose option Never in the Repeat field.

Related sample: samples/02_recurring/01_recurring.html

Format details

A recurring event is stored in the database as a single record that contains all fields of regular events + 2 additional:

  • rec_type - defines the logic of repetition;
  • event_length - the actual time length of an event in seconds.

However, fields start_date and end_date slightly change their meaning:

  • start_date - the start date of the first event in a series in the format 'yyyy-mm-dd hh:mm:ss' (format details).
  • end_date - the end date of the last event in a series in the format 'yyyy-mm-dd 00:00:00' (format details).

For example, a recurring event that starts on January 3, 2013 at 10:00, repeats every day and ends on January 13, 2013 at 12:00 will be presented in the db as follows:

id:1,
start_date:"2013-01-03 09:00:00",
end_date:"2013-01-13 00:00:00",
text:"some_text",
details:"",
rec_type:"day____",
event_length:"7200"

Client-side gets data from the rec_type field as a string of the following format:
[type]_[count]_[day]_[count2]_[days]#[extra]

  • type - the type of repeation: 'day','week','month','year'.
  • count - the interval between events in the “type” units.
  • day and count2 - define a day of a month ( first Monday, third Friday, etc ).
  • days - the comma-separated list of affected week days.
  • extra - the extra info that can be used to change presentation of recurring details.

Examples of the rec_type data:

  • 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

    The double or triple underline indicates that the related parameters of the string are omitted.
dhx.ready(function(){
    dhx.ui.fullScreen();
    dhx.ui({ view:"scheduler", id:"scheduler"});

        var data = [
        {
            id:1,
            start_date:"2012-06-01 09:00:00",
            end_date:"2092-02-01 09:00:00",
            text:"going to the job",
            details:"",
            rec_type:"week_1___1,2,3,4,5",
            event_length:"7200"
        },
                ...
    ];

    $$("scheduler").parse(data);
});

Setting recurring events (repetition variations)

As it was mentioned above, the Repeat field allows you to set 4 different repetition steps: 'day','week','month','year'.

Customizing the 'Details' form

The recurring 'Details form' uses the same customization technique as the standard form use.

Just the 'scheduler.config.form' template for recurring events will look like:

scheduler.config.form = [
       {view:"text",     id:'text',          label:scheduler.locale.labels.label_event, name:'text'},
       {view:"datetext", id:'start_date',    label:scheduler.locale.labels.label_start, name:'start_date', dateFormat:scheduler.config.form_date},
       {view:"datetext", id:'end_date',      label:scheduler.locale.labels.label_end,   name:'end_date', dateFormat:scheduler.config.form_date},
       {view:"toggle",   id:'allDay',        label:"", align: "right",value:"0", options:[
                   {value:"0",label:scheduler.locale.labels.label_time},
                   {value:"1",label:scheduler.locale.labels.label_allday}
       ]},
       {view:"rectext",   id:'rec_type',     label:scheduler.locale.labels.recurring.repeat, readonly:true},
       {view:"textarea",  id:'details',      label:scheduler.locale.labels.label_details,    height:110},
       {view:"input",     id:'event_length', type:"hidden",}
  ];


dhtmlxscheduler:offline_storage [DHX documentation]

Offline storage

In this article we want to tell you how to make an application be accessible offline and don't depend on the state of the network.

Generally, to make an app work in the offline mode you should use the dhx.proxy component. The component allows you to send web requests via HTTP proxy and store the latest successful data files and unsuccessful web requests locally.

How does an application using dhx.proxy work?

Loading data

  • Each time data needs loading, the app passes a request to the server via proxy-server. If the server is available - data is loaded from it and cached as the latest copy. If the server is unavailable - data is loaded from the local storage.
  • Note that the local storage contains data just if the app was run with available connection to the Internet at least once.

CRUD operations

  • When a user makes a request for update, it (the request) is passed to the server via proxy-server. If the request is satisfied - it updates the latest copy. If the request isn't satisfied - it's cached in the local storage.
  • Each time a user makes a request, dhx.proxy checks presence of unsuccessful requests in the local storage. If there are any kept - they are passed to the server.
  • As soon as an unsuccessful request is satisfied - it updates the latest copy and is removed from the local storage.

To cache not only the entered data, but also the application resources (js, css files, images etc.) you may use dhx.proxy together with the ApplicationCache interface (HTML5 feature).

How to use dhx.proxy?

dhx.proxy is an easy-to-use component.
To start use it:

  • ;
  • set the dhx.proxy instance as:
    • the save parameter of the object constructor;
    • the url parameter of the load method.
var source = new dhx.proxy({
    url: "../data/events_mobile.php",
    storage: dhx.storage.session
});
dhx.ready(function(){
        dhx.ui.fullScreen();
        dhx.ui({
        view: "scheduler",
        id: "scheduler",
        save: source
    });
    $$("scheduler").load(source, "json");
});

Related sample: samples/03_offilne/01_offline.html

Initialization

dhx.proxy can be initialized in the following way:

var source = new dhx.proxy({
      url: "./data.php",
      storage: dhx.storage.session
});

The constructor takes 2 parameters:

  • url - (url) defines the path to a php file that defines server side logic.
  • storage - (dhx.storage.local, dhx.storage.session, dhx.storage.cookie) specifies the data storage type. It's an optional parameter. The default value - dhx.storage.local.


dhtmlxscheduler:mobile_localization [DHX documentation]

Localization

Basic principles

The mobile version as well as the desktop one allows you to adapt the scheduler to a particular language and region.

To localize the scheduler to some language you should know the following:

  • All locale's parameters for the mobile version are contained in the scheduler.locale.labels object and to redefine the parameters you should 'rewrite' this object.

  • For 'rewriting' you should use the technique below:

    scheduler.locale.labels = labels;

    where labels is any object variable that contains the redefined parameters.

    var labels = {
               icon_today : "...",
               ...
}

Related sample: samples/07_mobile/07_locale.html

Localization parameters for mobile scheduler

The table below presents all localization parameters available for the mobile version of the scheduler.

scheduler.locale.labels = {
    list_tab: "List",
    day_tab: "Day",
    month_tab: "Month",
    icon_today: "Today",
    icon_save: "Save",
    icon_done: "Done",
    icon_delete: "Delete event",
    icon_cancel: "Cancel",
    icon_edit: "Edit",
    icon_back: "Back",
    icon_close: "Close form",
    icon_yes: "Yes",
    icon_no: "No",
    confirm_closing: "Your changes will be lost, are your sure ?",
    confirm_deleting: "The event will be deleted permanently, are you sure?",
    label_event: "Event",
    label_start: "Start",
    label_end: "End",
    label_details: "Notes",
    label_from: "from",
    label_to: "to",
    label_allday: "All day",
    label_time: "Time"
};

Related sample: samples/01_basic/07_locale.html

Recurring events

Recurring events use the same technique but just take another locale object - scheduler.labels.recurring.

Localization parameters for recurring events:

scheduler.labels.recurring = {
    none: "Never",
    daily: "Daily",
    day: "day(s)",
    every: "Every",
    weekly: "Weekly",
    week: "week(s) on",
    each: "Each",
    on_day: "on the",
    monthly: "Monthly",
    month: "month(s)",
    month_day: "on what day of the month",
    week_day: "on what day of the week",
    yearly: "Yearly",
    year: "year(s) in",
    counters: ["the first","the second","the third", "the fourth", "the fifth"],
    never: "Never",
    repeat: "Repeat",
    end_repeat: "End repeat",
    endless_repeat: "Endless repeat",
    end_repeat_label: "Repeat will end by"
};


dhtmlxscheduler:mobile_advanced [DHX documentation]

Advanced: changing the structure of the scheduler

The mobile scheduler has a multiview-based architecture. Details see in the related DHTMLX Touch documentation 'Building app architecture'.

Please remember, you can customize just toolbars of the scheduler.

So, in this article we will concentrate your attention on toolbars. Below, you can find all the available toolbars and their default definitions.

The detail information about the toolbar you can find in the DHTMLX Touch documentation - 'Toolbar component'.

Multiview

Main multiview of the scheduler contains 3 views:

  • Event preview screen;
  • Details form;
  • Start(end) date edit form;
  • Sub-multiview (supplemented with the bottom toolbar):
    • List (doesn't contain any toolbars);
    • Day;
    • Month.

Day view

In the “Day” view, the toolbar contains navigation buttons and the label displaying the selected date.

scheduler.config.day_toolbar = [
    {view:'label', id:"prev", align:"left",   label:"<div class='dhx_cal_prev_button'><div></div></div>"},
    {view:'label', id:"date", align:"center", width:200},
    {view:'label', id:"next", align:"right",  label:"<div class='dhx_cal_next_button'><div></div></div>"}
];

Month view

In the “Month” view the toolbar is a part of calendar integrated to the view (not an individual component). So, if you want to customize this toolbar, please, refer to the related calendar documentation.

Event preview screen

Here, the toolbar contains 2 buttons: “Back” and “Edit” (the buttons are hidden in the read-only mode).

scheduler.config.selected_toolbar = [
    {view:'button', inputWidth:scheduler.xy.icon_back, id:"back", align:"left",  label:labels.icon_back, css:"cancel"},
    {view:'button', inputWidth:scheduler.xy.icon_edit, id:"edit", align:"right", label:labels.icon_edit}
];

Start(end) date edit form

The toolbar contains 2 buttons: “Cancel” and “Done” and the label displaying which date is edited: start or end
(the view is hidden in the read-only mode).

scheduler.config.date_toolbar = [
        {view:'button', id:"cancel_date", align:"left",  width:90, label:"Cancel", css:"cancel"},
        {view:'label',  id:"datetype",    align:"center"},
        {view:'button', id:"done",        align:"right", width:90, label:"Done"}
];

Details form

The toolbar of the details form has 2 buttons: “Cancel” and “Save”.

scheduler.config.form_toolbar = [
    {view:'button', inputWidth:scheduler.xy.icon_cancel, id:"cancel", align:"left",  label:labels.icon_cancel, css:"cancel"},
    {view:'button', inputWidth:scheduler.xy.icon_save,   id:"save",   align:"right", label:labels.icon_save}
];

Main bottom toolbar

Main scheduler toolbar contains 3 controls:

  • “Today” button
  • tabbar with the “List”, “Day” and “Month” tabs
  • “Add” button
scheduler.config.bottom_toolbar = [
     { view:"button",id:"today",label:labels.icon_today,inputWidth:scheduler.xy.icon_today, align:"left",width:scheduler.xy.icon_today+6},
     { view:"segmented", id:"buttons",selected:"list",align:"center",multiview:true, options:[
        {value:"list", label:labels.list_tab,width:scheduler.xy.list_tab},
        {value:"day", label:labels.day_tab,width:scheduler.xy.day_tab},
            {value:"month", label:labels.month_tab,width:scheduler.xy.month_tab}
    ]},
    { view:"button",css:"add",id:"add", align:"right",label:"&nbsp;+&nbsp;",inputWidth:42,width:50},
    { view:"label", label:"",inputWidth:42,width:50, batch:"readonly"}
];

Adding new elements to the toolbar and event handling

If you want to add some custom button to one of the mentioned toolbars, you need to redefine the structure of that toolbar.
Clicks on the default buttons are handled automatically. But for new buttons you should define “click” event handlers.

Let's assume you want to add a new button to Event Preview screen - 'Location'.

The definition of your new toolbar can be the following:

scheduler.config.selected_toolbar = [
    {view:'button', inputWidth:90, css:"cancel", id:"back",     align:"left",  label:"Back"},
    {view:'button', inputWidth:90, width:100,    id:"location", align:"right", label:"Location", click:"showLocation"}, //the new button
    {view:'button', inputWidth:70, width:70,     id:"edit",     align:"right", label:"Edit"}
];

To show the event location on a button click, you need to define some handler function, for example, as follows:

function showLocation(){
    var eventId = $$("scheduler").getCursor();
    var location = $$("scheduler").item(eventId).location;
    dhx.alert(location)
}

In the function you could be confused by method getCursor(). This method is a part of 'binding' functionality that's used by the scheduler. You can read about the mentioned functionality in the related DHTMLX Touch documentation - 'Binding'.

Related sample: samples/01_basic/06_custom_form.html

Accessing elements of the scheduler

The scheduler includes different components: lists, toolbars, a form and etc. To access any of them you can use the '$$(schedulerId).$$(componentId)' construction.

The ids of the toolbars' buttons can be found above, in the toolbars' descriptions. And here are the ids of components from the multiview of the scheduler:

  • 'event' - the 'Event preview screen' view
    • 'eventBar' - the top toolbar
    • 'eventTemplate' - the template with the data of an event
  • 'form' - the 'Details form' view
    • 'editBar' - the toolbar
    • 'editForm' - the form with the details of an event
  • 'tabViews' - the sub-multiview containing List, Day and Month views
    • 'bottomBar' - the bottom toolbar
    • 'list' - the 'List' view
    • 'day' - the 'Day' view
      • 'dayBar' - the top toolbar
      • 'dayList' - the list with events
    • 'month' - the 'Month' view
      • 'calendar' - the calendar
      • 'calendarDayEvents' - the list with events of the selected day

For example, if you want to show the 'Month' view initially, you need to call the show() method for the 'month' view and select the 'month' button of the tabbar control on the bottom toolbar:

$$('scheduler').$$('month').show();
$$('scheduler').$$('buttons').setValue('month');
  • where 'month' and 'buttons' are the ids of the appropriate components of the scheduler.

The detail information about the mentioned components you can find in the DHTMLX Touch documentation -
'Master components'.

A custom view

It's possible to add a custom view to the main multiview of the scheduler. All you need to do is to add view configuration to the scheduler.config.views array. Beware, view configuration should go before the code line with scheduler initialization.

For example, if you'd like to add a view that will contain a google map, it can be done as follows:

scheduler.config.views.push({
    view:"googlemap",
    id:"mymap"
});

Related sample: samples/01_basic/11_custom_view.html