# [v5] Mobiscroll for Angular — Full Documentation > Complete Mobiscroll v5 Angular documentation including Eventcalendar, Datepicker, Select, Popup, Forms, theming, and guides. This documentation refers to Mobiscroll version 5.35.0. This file contains all documentation content in a single document following the llmstxt.org standard. ## Getting started with Mobiscroll for Angular ## Install the CLI The first step you need to install the Mobiscroll library into your app is to install the Mobiscroll CLI. Install the Mobiscroll CLI from NPM (you'll only have to do it once). ```bash npm install -g @mobiscroll/cli ``` :::info On Windows client computers, the execution of PowerShell scripts is disabled by default. When using Powershell, to be able to install the Mobiscroll CLI you will need to set the following execution policy: ``` Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned ``` Make sure to read the message displayed after executing the command and follow the instructions. ::: ## Starting with the trial Start a free trial by entering your email address on the [Mobiscroll homepage](https://mobiscroll.com) and create your account. When asked, enter your first name, set a password and you're ready to go! ### This is how the free trial works: 1. You can try Mobiscroll for free. 2. The trial needs an active connection to Mobiscroll servers for validation. Don't worry, the licensed product will work offline with downloadable resource files. Read about the [differences between trial and licensed products](http://help.mobiscroll.com/trials/what-are-the-limitations-of-the-trial). 3. You can upgrade to the licensed product at any time during or after your trial. ### Installing a trial package To install the Mobiscroll Trial, you will need to open a terminal window in the root folder of you project and run the following command: ```bash mobiscroll config angular --trial ``` :::caution The CLI handles everything — don't do these manually - **Do not run `npm login`** — `mobiscroll config` sets up Mobiscroll's private NPM registry authentication automatically. - **Do not run `npm install @mobiscroll/...`** — the CLI adds and installs the Mobiscroll package for you. - **Do not set up a license key manually** — the CLI configures your license when you run `mobiscroll config`. ::: ## Installing from NPM To install the Mobiscroll library from NPM, you will need to open a terminal window in the root folder of you project and run the following command: ```bash mobiscroll config angular ``` :::caution The CLI handles everything — don't do these manually - **Do not run `npm login`** — `mobiscroll config` sets up Mobiscroll's private NPM registry authentication automatically. - **Do not run `npm install @mobiscroll/...`** — the CLI adds and installs the Mobiscroll package for you. - **Do not set up a license key manually** — the CLI configures your license when you run `mobiscroll config`. ::: :::info If you're working behind a proxy, additional configuration might be needed. Please check the [proxy configuration options](https://mobiscroll.com/docs/core-concepts/cli#using-the-cli-behind-a-proxy) of the CLI. ::: ## Setting up for CI/CD The config command will create a file named `.npmrc` in the project root, containing the access tokens to the Mobiscroll NPM registry. Commit this file into the repository to ensure the package will install for other team members and in CI/CD environments. When used with Yarn 2 or 3, a different file is used, named `.yarnrc.yml`. Make sure this is also added to the repository. When used with Docker, make sure to copy the `.npmrc` or `.yarnrc.yml` file together with `package.json`, to make sure that the install process will have access to the Mobiscroll NPM registry. Here's a Dockerfile example: ```bash FROM node:18.12.0 as build ENV NODE_ENV production WORKDIR /app COPY package.json package-lock.json .npmrc ./ RUN npm install COPY . . # ... ``` :::info It is recommended to set up and use [team NPM accounts](http://help.mobiscroll.com/en/articles/8095168-team-npm-accounts) instead of individual developer credentials for installing Mobiscroll. ::: ## Installing manually On the [download page](https://download.mobiscroll.com/) a custom package can be built by picking only the components, themes, languages and additional modules you need. When [building your package](http://help.mobiscroll.com/en/articles/974201-download-builder), select the required components and other resources, then hit the download button. **1. Copy Mobiscroll into your app** Extract the zip file you just downloaded, then grab the `js`, `src` and `css` folders and copy it into src/lib/mobiscroll folder of your JavaScript app. If there is no such folder available, you can create it. **2. Run the config command** Run the config command in the root folder of your app in a terminal window. ```bash mobiscroll config angular --no-npm ``` ## Use the components For the components to work, you will also need to import the css file of the installed library under the node_modules folder (at @mobiscroll/angular/dist/css/mobiscroll.min.css). If you are [using SCSS](https://sass-lang.com/), you will also find a full and a modular `.scss` file in the same directory. To test the installation, add the Eventcalendar component to your main component template (for example `app.component.html`). In case you installed the library from a downloaded package and did not include the Eventcalendar in the package, you can choose a different component as well. ### With standalone components **app.component.html** ```html {{title}} ``` **app.component.ts** ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss']. standalone: true, // highlight-next-line imports: [CommonModule, MbscModule] }) export class AppComponent { title = 'My Angular app'; // highlight-start calView: MbscEventcalendarView = { schedule: { type: 'day' } }; // highlight-end } ``` ### With modules **app.component.html** ```html {{title}} ``` **app.component.ts** ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], standalone: false, }) export class AppComponent { title = 'My Angular app'; // highlight-start calView: MbscEventcalendarView = { schedule: { type: 'day' } }; // highlight-end } ``` **app.module.ts** ```ts // highlight-next-line @NgModule({ declarations: [ AppComponent, ], imports: [ CommonModule, // highlight-next-line MbscModule, FormsModule, BrowserModule ], bootstrap: [AppComponent] }) export class AppModule { } ``` --- ## Mobiscroll for Angular Angular is a javascript framework and development platform for creating efficient and sophisticated single-page apps. Mobiscroll for Angular is a collection of native Angular UI components that help deliver great mobile apps, websites with a great user experience and get five-star app store reviews. The controls use Angular's rendering engine and change detection systems. UI components follow platform UX guidelines and can be styled with the Theme Builder for a perfect fit. :::info Supported versions Mobiscroll supports Angular version 4 and up to Angular 21 and requires TypeScript 2.2.0 or newer. ::: :::info Supported platforms Android 5+ including Android 16, iOS 9+ including iOS 26 and all major desktop browsers, including Chrome 43+, Firefox 16+, Safari 9+, Edge 12+ and Internet Explorer 11+. ::: ## Introduction The following sections help you get started and learn more on the Mobiscroll library. ## UI Components Delve right into how the individual components work and learn about their API by following the links below. ## Legacy docs If you are looking for the documentation for a specific version that you don't find in the dropdown at the top of the page, you can check our legacy documentation under [this link](https://docs.mobiscroll.com/5-29-0/). --- ## Using Mobiscroll with Ionic Installing Mobiscroll in your Ionic app takes a couple of minutes. Let's see how you can start with a simple app. Follow this guide for Ionic 2+, including Ionic 8. If interested in usage with Ionic 1, continue [reading here](https://docs.mobiscroll.com/5-25-0/angularjs/with-ionic1). ## Using the Mobiscroll CLI and NPM ### Step 1: Create an app Assuming you have node and ionic already installed (if not, you can read about it in [the Ionic docs](https://ionicframework.com/#cli)), use the CLI to create a new app. If you already have an app at hand, you can skip this step. :::info Note that it could take a couple of minutes until the app is created (depending on your internet connection and machine performance). ::: ```bash ionic start my-starter-app tabs ``` ```bash cd my-starter-app ``` ### Step 2: Install the Mobiscroll CLI Install Mobiscroll CLI from NPM. You'll only have to do this step once on a single development machine. You won't need to repeat this on other machines or production servers. ```bash $ npm install -g @mobiscroll/cli ``` ### Step 3: Configure the project using the CLI To install the Mobiscroll library from NPM, you will need to open a terminal window in the root folder of you project and run the following command: ```bash mobiscroll config angular ``` :::caution The CLI handles everything — don't do these manually - **Do not run `npm login`** — `mobiscroll config` sets up Mobiscroll's private NPM registry authentication automatically. - **Do not run `npm install @mobiscroll/...`** — the CLI adds and installs the Mobiscroll package for you. - **Do not set up a license key manually** — the CLI configures your license when you run `mobiscroll config`. ::: :::info If you're working behind a proxy, additional configuration might be needed. Please check the [proxy configuration options](https://mobiscroll.com/docs/core-concepts/cli#using-the-cli-behind-a-proxy) of the CLI. ::: The command will ask for your credentials (email and password). If you already have a mobiscroll account but you are unsure about the details, you find them on your [account page](https://mobiscroll.com/account). If you don't have an account yet, you can start a trial in no time following [these steps](./installation.md#starting-with-the-trial). :::info If you already have a license, it is recommended to set up and use [team NPM accounts](http://help.mobiscroll.com/en/articles/8095168-team-npm-accounts) instead of individual developer credentials for installing Mobiscroll. ::: ### Step 4: Importing Mobiscroll to other modules (Optional) When you have only one module (the `app.module.ts`), the previous configuration process will add an import for the Mobiscroll module there, otherwise it will ask you to choose the Modules you want to use Mobiscroll in. If you add more modules later, or decide that you need the mobiscroll components in a module you didn't add in the configuration phase, you can add the imports manually like this: ```ts title="new-module.module.ts" // ...other imports of your module @NgModule({ declarations: [YourNewPage] imports: [ IonicModule, CommonModule, FormsModule, ReactiveFormsModule, // highlight-next-line MbscModule, // <-- added the Mobiscroll Module to the imports RouterModule.forChild([{ path: '', component: YourNewPage }]) ], }) export class YourNewPageModule {} ``` ### Step 5: Let's see if Mobiscroll was installed correctly To test it let's add a simple input to the Tab1 component in the starter app. In case of an older ionic app (for example Ionic 4 or Ionic 5) you can use the home page found at: `src/app/home/home.page.html` ### Using modules **src/app/tab1/tab1.page.html** ```html Tab 1 Tab 1 // highlight-start // highlight-end ``` **src/app/tab1/tab1.page.ts** ```ts @Component({ selector: 'app-tab1', templateUrl: 'tab1.page.html', styleUrls: ['tab1.page.scss'], standalone: false, }) export class Tab1Page { // highlight-next-line public myBirthday: Date | null = null; constructor() {} } ``` **src/app/tab1/tab1.module.ts** ```ts // highlight-next-line @NgModule({ imports: [ IonicModule, CommonModule, FormsModule, ExploreContainerComponentModule, Tab1PageRoutingModule, // highlight-next-line MbscModule ], declarations: [Tab1Page] }) export class Tab1PageModule {} ``` ### Using standalone components **src/app/tab1/tab1.page.html** ```html Tab 1 Tab 1 // highlight-start // highlight-end ``` **src/app/tab1/tab1.page.ts** ```ts // highlight-next-line @Component({ selector: 'app-tab1', templateUrl: 'tab1.page.html', styleUrls: ['tab1.page.scss'], standalone: true, imports: [ IonicModule, CommonModule, FormsModule, ExploreContainerComponentModule, Tab1PageRoutingModule, // highlight-next-line MbscModule ] }) export class Tab1Page { // highlight-next-line public myBirthday: Date | null = null; constructor() {} } ``` To build the app just run the serve command in the CLI: ```bash ionic serve ``` At this point you have completed the setup. Go build great things! :::info One more thing **Setting up for CI/CD** The config command in [step 3](#step-3-configure-the-project-using-the-cli) will create a file named `.npmrc` in the project root, containing the access tokens to the Mobiscroll NPM registry. Commit this file into the repository to ensure the package will install for other team members and in CI/CD environments. If you are using Yarn or Docker, check out the [setup instructions here](./installation.md#setting-up-for-cicd). ::: --- ## Accessibility ## Overview We want our products to be fully experienced by the widest number of users including disabled users. We take accessibility pretty seriously and spent a couple of iterations on it. By adhering to standards like [WAI-ARIA](http://www.w3.org/WAI/PF/aria-practices/), [Section 508](http://www.section508.gov/), and [WCAG 2.2](https://www.w3.org/TR/WCAG/) we create accessible products that can be used well together with an assistive technology, like a screen reader. Since the technology has evolved, nowadays not only basic text-driven experiences have to be made accessible, but also other features. ## Accessibility Compliance Mobiscroll components are designed to support WCAG-based accessibility standards and can be used to build applications aligned with major public-sector accessibility frameworks worldwide. They are largely aligned with WCAG 2.2 A and AA requirements, with strong support for keyboard navigation, WAI-ARIA, and screen reader compatibility. However, full WCAG AA compliance is not yet achieved, as WCAG 1.4.3 Contrast (Minimum) is not fully supported in all cases. This known limitation is actively being addressed in upcoming releases. Mobiscroll can therefore support the development of applications targeting major global accessibility regulations, while full compliance depends on the complete application implementation and resolving this remaining gap. #### Mobiscroll can be used in applications targeting frameworks such as: - 🇪🇺 EN 301 549 (European Union) - 🇫🇷 RGAA (France) - 🇺🇸 Section 508 (United States) - 🇨🇦 AODA (Canada) As well as other WCAG-aligned national regulations: - 🇩🇪 BITV 2.0 (Germany) - 🇮🇹 Legge Stanca (Italy) - 🇪🇸 UNE 139803 (Spain) - 🇳🇱 DigiToegankelijk (Netherlands) - 🇸🇪 DOS-lagen (Sweden) - 🇩🇰 Web Accessibility Act (Denmark) - 🇫🇮 Act on Digital Services (Finland) - 🇳🇴 Universal Design of ICT (Norway) - 🇬🇧 Public Sector Accessibility Regulations (UK) - 🇯🇵 JIS X 8341-3 (Japan) - 🇮🇱 Standard 5568 (Israel) #### Compliance responsibility Mobiscroll provides accessible UI components intended to support WCAG-based development. It does not, by itself, ensure that an application is fully compliant with accessibility regulations. Organizations using Mobiscroll are responsible for: - publishing an accessibility statement - maintaining accessibility monitoring and audits - implementing accessibility governance processes - ensuring content, structure, and workflows meet accessibility requirements ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility 1.1 Text Alternatives 1.1.1 Non-text Content A Supported 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable 1.2.2 Captions (Prerecorded) A Not Applicable 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable 1.2.4 Captions (Live) AA Not Applicable 1.2.5 Audio Description (Prerecorded) AA Not Applicable 1.2.6 Sign Language (Prerecorded) AAA Not Applicable 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable 1.2.9 Audio-only (Live) AAA Not Applicable 1.3 Adaptable 1.3.1 Info and Relationships A Supported 1.3.2 Meaningful Sequence A Supported 1.3.3 Sensory Characteristics A Supported 1.3.4 Orientation AA Supported 1.3.5 Identify Input Purpose AA Supported 1.3.6 Identify Purpose AAA Supported 1.4 Distinguishable 1.4.1 Use of Color A Supported 1.4.2 Audio Control A Not Applicable 1.4.3 Contrast (Minimum) AA Not fully supported 1.4.4 Resize Text AA Supported 1.4.5 Images of Text AA Not Applicable 1.4.6 Contrast (Enhanced) AAA Not fully supported 1.4.7 Low or No Background Audio AAA Not Applicable 1.4.8 Visual Presentation AAA Supported 1.4.9 Images of Text (No Exception) AAA Not Applicable 1.4.10 Reflow AA Supported 1.4.11 Non-text Contrast AA Supported 1.4.12 Text Spacing AA Supported 1.4.13 Content on Hover or Focus AA Supported ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported 2.1.2 No Keyboard Trap A Supported 2.1.3 Keyboard (No Exception) AAA Supported 2.1.4 Character Key Shortcuts A Not Applicable 2.2 Enough Time 2.2.1 Timing Adjustable A Supported 2.2.2 Pause, Stop, Hide A Not Applicable 2.2.3 No Timing AAA Supported 2.2.4 Interruptions AAA Supported 2.2.5 Re-authenticating AAA Not Applicable 2.2.6 Timeouts AAA Not Applicable 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported 2.3.2 Three Flashes AAA Supported 2.3.3 Animation from Interactions AAA Supported 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable 2.4.2 Page Titled A Not Applicable 2.4.3 Focus Order A Supported 2.4.4 Link Purpose (In Context) A Not Applicable 2.4.5 Multiple Ways AA Not Applicable 2.4.6 Headings and Labels AA Supported 2.4.7 Focus Visible AA Supported 2.4.8 Location AAA Not Applicable 2.4.9 Link Purpose (Link Only) AAA Not Applicable 2.4.10 Section Headings AAA Not Applicable 2.4.11 Focus Not Obscured (Minimum) AA Supported 2.4.12 Focus Not Obscured (Enhanced) AAA Supported 2.4.13 Focus Appearance AAA Not fully supported 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported 2.5.2 Pointer Cancellation A Supported 2.5.3 Label in Name A Supported 2.5.4 Motion Actuation A Not Applicable 2.5.5 Target Size (Enhanced) AAA Not fully supported 2.5.6 Concurrent Input Mechanisms AAA Supported 2.5.7 Dragging Movements AA Supported 2.5.8 Target Size (Minimum) AA Supported ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility 3.1 Readable 3.1.1 Language of Page A Not Applicable 3.1.2 Language of Parts AA Not Applicable 3.1.3 Unusual Words AAA Not Applicable 3.1.4 Abbreviations AAA Supported 3.1.5 Reading Level AAA Not Applicable 3.1.6 Pronunciation AAA Not Applicable 3.2 Predictable 3.2.1 On Focus A Supported 3.2.2 On Input A Not Applicable 3.2.3 Consistent Navigation AA Not Applicable 3.2.4 Consistent Identification AA Not Applicable 3.2.5 Change on Request AAA Not Applicable 3.2.6 Consistent Help A Not Applicable 3.3 Input Assistance 3.3.1 Error Identification A Supported 3.3.2 Labels or Instructions A Supported 3.3.3 Error Suggestion AA Supported 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable 3.3.5 Help AAA Not Applicable 3.3.6 Error Prevention (All) AAA Not Applicable 3.3.7 Redundant Entry A Not Applicable 3.3.8 Accessible Authentication (Minimum) AA Not Applicable 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Supported ### WCAG compliance for each component WCAG compliance levels for each Mobiscroll component: - [Datepicker](../datepicker/accessibility#wcag-22) - [Eventcalendar](../eventcalendar/accessibility#wcag-22) - [Select](../select/accessibility#wcag-22) - [Popup](../popup/accessibility#wcag-22) - [Alerts & notifications](../notifications/accessibility#wcag-22) - [Forms](../forms/accessibility#wcag-22) ## Section 508 ### [Section 1194.21](https://www.access-board.gov/ict/#d21) - Software applications and operating systems The following table shows the level of support that Mobiscroll provides for the Section 1194.21 Criteria Supporting features Remarks (a) When software is designed to run on a system that has a keyboard product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. Supported Native html keyboard support kept where relevant, custom key bindings added where needed (b) Applications shall not disrupt or disable activated features of other products that are identified as accessibility features where those features are developed and documented according to industry standards. Applications also shall not disrupt or disable activated features of any operating system that are identified as accessibility features where the application programming interface for those accessibility features has been documented by the manufacturer of the operating system and is available to the product developer. Supported Mobiscroll does nothing to disrupt or disable activated accessibility features (c) A well-defined on-screen indication of the current focus shall be provided that moves among interactive interface elements as the input focus changes. The focus shall be programmatically exposed so that assistive technology can track focus and focus changes. Supported In some cases the browser’s native focus indicator styling is overwritten with custom styling (d) Sufficient information about a user interface element including the identity operation and state of the element shall be available to assistive technology. When an image represents a program element the information conveyed by the image must also be available in text. Supported Using WAI-ARIA,roles and attributes where applicable (e) When bitmap images are used to identify controls status indicators or other programmatic elements the meaning assigned to those images shall be consistent throughout an application’s performance. Not Applicable (f) Textual information shall be provided through operating system functions for displaying text. The minimum information that shall be made available is text content text input caret location and text attributes. Not Applicable (g) Applications shall not override user selected contrast and color selections and other individual display attributes. Not Applicbale (h) When animation is displayed the information shall be displayable in at least one non-animated presentation mode at the option of the user. Not Applicable (i) Color coding shall not be used as the only means of conveying information indicating an action, prompting a response or distinguishing a visual element. Not Applicable (j) When a product permits a user to adjust color and contrast settings a variety of color selections capable of producing a range of contrast levels shall be provided. Not Applicable (k) Software shall not use flashing or blinking text, objects, or other elements having a flash or blink frequency greater than 2 Hz and lower than 55 Hz. Supported No flashing or blinking elements are used (l) When electronic forms are used, the form shall allow people using assistive technology to access the information, field elements, and functionality required for completion and submission of the form, including all directions and cues. Supported Mobiscroll Forms are accessible to assistive technologies ### [Section 1194.22](https://www.access-board.gov/ict/#d22) - Web-based intranet and Internet information and applications The following table shows the level of support that Mobiscroll provides for the Section 1194.21 Criteria Supporting features Remarks (a) A text equivalent for every non-text element shall be provided (e.g., via “alt", “longdesc", or in element content). Supported (b) Equivalent alternatives for any multimedia presentation shall be synchronized with the presentation. Not Applicable No multimedia is used (c) Web pages shall be designed so that all information conveyed with color,is also available without color for example from context or markup. Supported (d) Documents shall be organized so they are readable without requiring an associated style sheet. Not fully supported We’re providing an UI Framework for styling content. Removing style sheets doesn’t make sense (e) Redundant text links shall be provided for each active region of a server-side image map. Not Applicable No image maps are used (f) Client-side image maps shall be provided instead of server-side image maps except where the regions cannot be defined with an available geometric shape. Not Applicable No image maps are used (g) Row and column headers shall be identified for data tables. Not Applicable No data tabels are used (h) Markup shall be used to associate data cells and header cells for data tables that have two or more logical levels of row or column headers. Not Applicable No data tabels are used (i) Frames shall be titled with text that facilitates frame identification and navigation. Not Applicable No frames are used (j) Pages shall be designed to avoid causing the screen to flicker with a frequency greater than 2 Hz and lower than 55 Hz. Supported No flashing or blinking elements are used (k) A text-only page with equivalent information or functionality shall be provided to make a web site comply with the provisions of this part, when compliance cannot be accomplished in any other way. The content of the text-only page shall be updated whenever the primary page changes. Not Applicable The developer is responsible for providing text-only content for pages that use Mobiscroll (l) When pages utilize scripting languages to display content or to create interface elements the information provided by the script shall be identified with functional text that can be read by assistive technology. Supported Mobiscroll provides keyboard navigation support and screen reader support (via ARIA attributes) (m) When a web page requires that an applet, plug-in or other application be present on the client system to interpret page content the page must provide a link to a plug-in or applet that complies with §1194.21(a),through (l). Not Supported (n) When electronic forms are designed to be completed on-line, the form shall allow people using assistive technology to access the information field elements and functionality required for completion and submission of the form including all directions and cues. Supported Mobiscroll Forms are accessible to assistive technologies (o) A method shall be provided that permits users to skip repetitive navigation links. Not Applicable (p) When a timed response is required the user shall be alerted and given sufficient time to indicate more time is required. Not Applicable ## WAI-ARIA Support WAI-ARIA is a World Wide Web Consortium specification that was designed to be a framework for web developers. This can be used in developing applications that leverage Ajax, scripting and other so called “rich application" techniques. This framework has clear specifications about steps that developers can use in order to make their applications more accessible to assistive technologies. WAI-ARIA’s role is to fill the gap between rich applications and disabled users by using additional metadata with the help of HTML element attributes that screen readers can use to reason about a control or DOM element. These attributes, like role, aria-haspopup, aria-selected and others provide vital information to screen readers, which can then be used to provide a richer level of interaction with applications and websites. Here is the complete list of WAI-ARIA attributes used by Mobiscroll: - `role="dialog"` for popups and pickers - `role="grid"` for calendar view - `role="row"` for calendar view rows - `role="gridcell"` for calendar views cells - `role="listbox"` for scroller wheels - `role="option"` for scroller wheel items - `role="button"` for button controls - `aria-live` for announcements - `aria-hidden` for elements which are not visible and should not be read by screen readers - `aria-label` for controls without text or icon buttons - `aria-selected` for indicating selected value on wheels and calendar days - `aria-multiselectable` for multiple select - `aria-disabled` for disabled items (wheel items, buttons, calendar days) ## Support Right-To-Left (RTL) Languages Only a few languages in the world use RTL text direction, but these languages cover over a billion people. Beside it’s internationalization characteristic RTL is about making user experiences more accessible for users working in Right-to-left languages like, so we are considering this as an accessibility feature as well. Mobiscroll supports RTL for every component, which can be activated with the `rtl: true` option. ## Keyboard Support Mobiscroll ensures that your users can access the full capabilities of widgets using just the keyboard. The following keyboard bindings are used by Mobiscroll: - [Datepicker](../datepicker/accessibility) - [Eventcalendar](../eventcalendar/accessibility) - [Select](../select/accessibility) - [Popup](../popup/accessibility) - [Alerts & notifications](../notifications/accessibility) - [Form components](../forms/accessibility) --- ## Mobiscroll CLI ## Overview The Mobiscroll Command Line Interface helps to install and configure the mobiscroll library into a project. :::info Requires Node.js 11 or newer. ::: ## Installation Using the node package manager (npm), the Mobiscroll CLI can be installed with the following command: ```bash $ npm install -g @mobiscroll/cli ``` :::info On Windows client computers, the execution of PowerShell scripts is disabled by default. When using Powershell, to be able to install the Mobiscroll CLI you will need to set the following [execution policy](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.3): `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` Make sure to read the message displayed after executing the command and follow the instructions. ::: ## Config Configures your current project with the Mobiscroll resources and dependencies. Use the `--version` option to define which supported main version would you like to install: ```bash title='Install the latest version' $ mobiscroll config [types] [options] ``` ```bash title='Install the latest v4 version' $ mobiscroll config [types] [options] --version=4 ``` Options: - `-t`, `--trial`: The project will be configured with the trial version. - `-n`, `--no-npm`: This option can be used if you are building a custom package with the [download builder](http://help.mobiscroll.com/en/articles/974201-download-builder). Mobiscroll resources won't be installed from npm. In this case the Mobiscroll resources must be copied manually to the `src/lib` folder from the downloaded package. - `-h`, `--help`: Output usage information. - `--proxy [url]`: Define a proxy URL which will be passed to the internal requests. - `--scss`: The project will be configured with scss styles instead of css. - `--css`: The project will be configured with css styles instead of scss. - `--legacy-peer-deps`: This option will be passed to internally executed `npm install` command. - `--version [version]`: Pass the Mobiscroll version which you want to install. It supports semver versions (`--version="4.10.7"`) and main versions (`--version="4"`). In case of main version it will install the latest package available. Types: - `angular`: Use it for configuring Angular 4+ applications. - `ionic`: Use it for configuring Ionic 2.2.0+ applications. - `javascript`: Use it for configuring JavaScript applications. Use it with frameworks like: Knockout, Ember.js... - `jquery`: Use it for configuring jQuery 1.7+ applications. - `react`: Use it for configuring React 16.2+ applications. - `vue`: Use it for configuring Vue 3+ applications. ## Login Logs you in to the Mobiscroll npm registry. (Use the `--global` flag if you want to login globally). ```bash $ mobiscroll login [options] ``` Options: - `-h`, `--help`: output usage information. ## Logout Logs you out from the Mobiscroll npm registry. (Use the `--global` flag if you want to log out globally). ```bash $ mobiscroll logout [options] ``` Options: - `-h`, `--help`: output usage information. ## Using the CLI behind a proxy If you're behind a proxy, the `mobiscroll` command might not work out of the box. There are multiple ways to solve this. 1. Using environment variables The preferred way is to set the `http_proxy` and `https_proxy` environment variables on your system. This is usually needed for other CLI commands as well which are making requests and needs to be routed through a proxy server as well. ```bash title='Mac OS / Linux' $ export http_proxy=http://myuser:mypassword@myproxy.com:1234 $ export https_proxy=http://myuser:mypassword@myproxy.com:1234 ``` This will set the environment variables for the current terminal session. To permanently set the variables, add the above lines to your user's `~/.bash_profile` or `~/.zshrc` files. ```bash title='Windows' $ setx HTTP_PROXY "http://myuser:mypassword@myproxy.com:1234" $ setx HTTPS_PROXY "http://myuser:mypassword@myproxy.com:1234" ``` The `setx` command will permanently set the environment variables. 2. Using the `--proxy` parameter The quick and dirty method without the need to modify any system configuration, is to pass the proxy address to the `mobiscroll config` command using the `--proxy` option. This will be used for any external request made to our servers or the npm registry. ```bash $ mobiscroll config [framework] --proxy http://myuser:mypassword@myproxy.com:1234 ``` --- ## Global options ## The `setOptions` function Global options can be used to set options for all components used on a page. Useful for speicifying application-wide options, like theme and locale. You can use the `setOptions` utility function to specify the global options. It can be called on initial page load or any time later. All existing component on the page will be updated with the new options, and components instantiated later will take into account the new global options. Components can override the global options with their individual options, e.g. if a component has a specific theme specified, it will override the global theme option. ```ts title="app.component.ts" // highlight-next-line setOptions, localeDe } from '@mobiscroll/angular'; // Specify options globally for all components // highlight-start setOptions({ locale: localeDe, theme: 'ios', themeVariant: 'dark', }); // highlight-end ``` ## The options service The `MbscOptionsService` is an angular service that provides options to all Mobiscroll components down the component hierarchy. ### Using modules The Mobiscroll options service can be provided from the root module to pass the options to all of the compoents. **app.module.ts** ```ts // ... // highlight-next-line @NgModule({ declarations: [ AppComponent, ], imports: [ MbscModule, FormsModule, BrowserModule ], // highlight-next-line providers: [MbscOptionsService], bootstrap: [AppComponent] }) export class AppModule { } ``` **app.component.ts** ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], standalone: false, }) export class AppComponent { // highlight-next-line constructor(protected options: MbscOptionsService) {} SwitchToIosLight() { // highlight-start this.options.setOptions({ theme: 'ios', themeVariant: 'light', }); // highlight-end } SwitchToIosDark() { // highlight-start this.options.setOptions({ theme: 'ios', themeVariant: 'dark', }); // highlight-end } } ``` **app.component.html** ```html Light theme Dark theme ``` In the above example clicking the buttons will set the theme and themeVariant and will automatically be passed on to the components, since the service is provided in the app root module. ### Using standalone components When using the (relatively) new standalone components, there are no modules defined, you can still use the `MbscOptionsService`. Here's an example on how to use it: ```ts title="app.component.ts" // ... @Component({ selector: 'app-root', standalone: true, imports: [FormsModule, MbscModule, CommonModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', // highlight-next-line providers: [MbscOptionsService], }) export class AppComponent { // highlight-next-line constructor(protected options: MbscOptionsService) { } SwitchToIosLight() { // highlight-start this.options.setOptions({ theme: 'ios', themeVariant: 'light', }); // highlight-end } SwitchToIosDark() { // highlight-start this.options.setOptions({ theme: 'ios', themeVariant: 'dark', }); // highlight-end } } ``` --- ## Instance ## Overview In object-oriented programming (OOP), an instance is a specific realization of a class. Similarly, in the scope of the Mobiscroll library, a component instance is a realization of the component class. The instantiation (the creation of objects from a class) in case of the Mobiscroll components is done by the Angular framework, and accessing the component instances are only needed in a few specific cases. ## Getting the instance ### Inside events A reference to the component instance is available in every Mobiscroll event through the `inst` property of the first argument. **component.html** ```html ``` **component.ts** ```ts // highlight-next-line @Component({ selector: 'component', templateUrl: './component.html', standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { myHandler(args: MbscEventCreateEvent) { // highlight-next-line console.log('The Eventcalendar instance:', args.inst); } } ``` ### Template references The mobiscroll directives and components are exported as 'mobiscroll' for template variables. ```html ``` ## Calling methods :::caution Calling the instance methods should be necessary only in a few selected cases. Almost every case can be solved with passing props to the component and using it's events rather than calling instance methods. Before implementing a solution, please take into consideration using props and events first. ::: All the component methods are documented on each components API section. The methods can be called on the component instances directly in the templates or inside component classes using `@ViewChild` decorators. ### Inside templates ```html title="Calling methods in the template"

Popup content

 Open ``` Then you can query the invalid days through the instance: ```ts @Component({ selector: 'component', templateUrl: './component.html', standalone: true, imports: [CommonModule, MbscModule] }) // highlight-start export class AppComponent implements AfterViewInit { @ViewChild('myCalendar') inst: Eventcalendar | null = null; // highlight-end invalidsArray: MbscDateType[] = [{ start: '2023-10-18', allDay: true, recurring: { repeat: 'weekly', weekDays: 'MO,FR,SA', interval: 1 } }]; // highlight-start ngAfterViewInit(): void { const occurences = this.inst!.getInvalids('2023-11-01', '2023-12-01'); } // highlight-end } ``` The result in this case will be an array of objects, each of them being an occurence of an invalid day in November. The `AfterViewInit` interface is required, because the `ViewChild` references will only get a value after the view was initialized. --- ## Localization ## Overview The Mobiscroll components offer comprehensive localization features, ensuring they can be seamlessly integrated into any project worldwide. These features include: - the ability to format dates and times according to regional preferences - the components allow for the customization of button labels and other interface text, making it easy to translate these elements into any language - support for right-to-left (RTL) text direction, which is essential for languages like Arabic and Hebrew These localization capabilities ensure that Mobiscroll components provide a user-friendly and culturally appropriate experience for users across different regions and languages. ## Localization options for components - [Date & time picker](/angular/datepicker/api#localization) - [Event Calendar](/angular/eventcalendar/api#localization) - [Select](/angular/select/api#localization) - [Popup](/angular/popup/api#localization) - Forms - check out the localization options under the different Form components - Localization section - [Alert](/angular/notifications/alert#localization) - [Confirm](/angular/notifications/confirm#localization) - [Prompt](/angular/notifications/prompt#localization) - [Button](/angular/forms/button#localization) - [Checkbox](/angular/forms/checkbox#localization) - [Dropdown](/angular/forms/dropdown#localization) - [Input](/angular/forms/input#localization) - [Radio button](/angular/forms/radio#localization) - [Segmented](/angular/forms/segmented#localization) - [Stepper](/angular/forms/stepper#localization) - [Switch](/angular/forms/switch#localization) - [Textarea](/angular/forms/textarea#localization) ## Localization options Here is a comprehensive list of all the localization options for Mobiscroll components. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### cancelText string Text for the button which cancels the dialog. **Default value**: `'Cancel'` ### closeText string Text for the "Close" button. **Default value**: `'Close'` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateFormatLong string Long date format, used by the agenda view and timeline day headers. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'D DDD MMM YYYY'` ### dateText string Specifies the accessibility label for the date wheel. **Default value**: `'Date'` ### dateWheels string Display order and formatting for month/day/year wheels. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. The options also controls if a specific wheel should appear or not, e.g. use `'MMMMYYYY'` to display month and year wheels only, `'MMDDD DDYYYY'` to display both day of week and date on the day wheel. If not specified, the order of the wheels will be taken from the [dateFormat](#localization-dateFormat) option, and the formatting will be defined by the [theme](#opt-theme). To display the whole date on one wheel, the format of the date should be specified between `|` characters: ```js dateWheels: '|DDD MMM D|' // Will produce 'Sun Sep 9' ``` **Default value**: `undefined` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### daySuffix string Additional string to display after the day on the wheel. **Default value**: `undefined` ### dayText string Specifies the accessibility label for the day wheel. **Default value**: `'Day'` ### eventsText string Text for the events word (plural). **Default value**: `'events'` ### eventText string Text for the event word. **Default value**: `'event'` ### filterEmptyText string Text for the empty state of the Select. The Select will show this message, when [filtering](#opt-filter) is turned on and there are no results for the searched text. **Default value**: `'No results'` ### filterPlaceholderText string Placeholder text for the filter input, when [filtering](#opt-filter) is turned on. **Default value**: `'Search'` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### groupText string Specifies the accessibility label for the group wheel, when present. **Default value**: `'Group'` ### hourText string Specifies the accessibility label for the hour wheel. **Default value**: `'Hour'` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### minuteText string Specifies the accessibility label for the minute wheel. **Default value**: `'Minute'` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### monthSuffix string Additional string to display after the month on the wheel. **Default value**: `undefined` ### monthText string Specifies the accessibility label for the month wheel. **Default value**: `'Month'` ### moreEventsPluralText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day, and there are more than one extra labels. The `{count}` inside the string will be replaced with the number of extra labels. When not specified, the [moreEventsText](#localization-moreEventsText) option will be used for both plural and singular form. **Default value**: `undefined` ### moreEventsText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day. The `{count}` inside the string will be replaced with the number of extra labels. Use the [moreEventsPluralText](#localization-moreEventsPluralText) as well, if the plural form is different. **Default value**: `'{count} more'` ### newEventText string Title for the newly created event with the [dragToCreate](#opt-dragToCreate) and the [clickToCreate](#opt-clickToCreate) action. **Default value**: `'New event'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### noEventsText string Text for empty event list. **Default value**: `'No events'` ### okText string Text for the button which closes the dialog. **Default value**: `'OK'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### quarterText string Text for quarter numbers in the timeline header. The {count} inside the string will be replaced with the number of the current quarter. **Default value**: `'Q {count}'` ### rangeEndHelp string When selecting a range, it specifies the placeholder text for the end value under the [end label](#opt-showRangeLabels). **Default value**: `'Please select'` ### rangeEndLabel string When selecting a range, it specifies the text of the [end label](#opt-showRangeLabels). **Default value**: `'End'` ### rangeStartHelp string When selecting a range, it specifies the placeholder text for the start value under the [start label](#opt-showRangeLabels). **Default value**: `'Please select'` ### rangeStartLabel string When selecting a range, it specifies the text of the [start label](#opt-showRangeLabels). **Default value**: `'Start'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### secondText string Specifies the accessibility label for the second wheel. **Default value**: `'Second'` ### selectedPluralText string Specifies the plural form of the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items. **Default value**: `'{count} selected'` ### selectedText string Specifies the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items. **Default value**: `'{count} selected'` ### setText string Text for the "Set" button. **Default value**: `'Set'` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### timeText string Specifies the accessibility label for the time wheel. **Default value**: `'Time'` ### timeWheels string Display order and formatting of the time wheels. Characters have the same meaning as in the [timeFormat](#localization-timeFormat) option. If not specified, the order of the wheels will be taken from the [timeFormat](#localization-timeFormat) option, and the formatting will be defined by the theme. To display the whole time on one wheel, the format of the time should be specified between `|` characters: ```js timeWheels: '|h:mm A|' // Will produce '9:12 AM' ``` **Default value**: `undefined` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### weekText string Text for week numbers in the timeline header. The {count} inside the string will be replaced with the number of the current week. **Default value**: `'Week {count}'` ### yearSuffix string Additional string to display after the year on the wheel. **Default value**: `undefined` ### yearText string Specifies the accessibility label for the year wheel. **Default value**: `'Year'` ## Language modules We offer and support a number of translations for the Mobiscroll library. If you don't find the language you're looking for, no problem. It's easy to create a language module that you can use. The `locale` option can be used to set the language of a component. It takes an object, that should contain the translations of the texts used in the component. The supported languages can be set directly from the mobiscroll bundle. ```html title='Locale option usage' ``` ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { // highlight-next-line myLocale = localeDe; } ``` Creating your own locale object is simple as creating an object in JavaScript. For example, the Cancel button on many Mobiscroll components uses the `cancelText` property. If you want to provide a translation for it, the locale object would look like this: ```html title='Creating a locale object' ``` ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { // highlight-start myLocale: MbscLocale = { cancelText: 'Mégse' } // highlight-end } ``` The exact properties for each component can be found [above](#localization-options-for-components). Here's a template to use for the locale object: ```ts title='Template' const myLocale = { // Core setText: 'OK', cancelText: 'Mégse', clearText: 'Törlés', selectedText: '{count} kiválasztva', // Datetime component dateFormat: 'YYYY.MM.DD.', dateFormatLong: 'YYYY. MMM. D., DDD', dayNames: ['Vasárnap', 'Hétfő', 'Kedd', 'Szerda', 'Csütörtök', 'Péntek', 'Szombat'], dayNamesShort: ['Va', 'Hé', 'Ke', 'Sze', 'Csü', 'Pé', 'Szo'], dayNamesMin: ['V', 'H', 'K', 'Sz', 'Cs', 'P', 'Sz'], dayText: 'Nap', delimiter: '.', hourText: 'Óra', minuteText: 'Perc', monthNames: ['Január', 'Február', 'Március', 'Április', 'Május', 'Június', 'Július', 'Augusztus', 'Szeptember', 'Október', 'November', 'December'], monthNamesShort: ['Jan', 'Feb', 'Már', 'Ápr', 'Máj', 'Jún', 'Júl', 'Aug', 'Szep', 'Okt', 'Nov', 'Dec'], monthText: 'Hónap', secText: 'Másodperc', timeFormat: 'H:mm', yearText: 'Év', nowText: 'Most', pmText: 'pm', amText: 'am', // Calendar component firstDay: 1, dateText: 'Dátum', timeText: 'Idő', todayText: 'Ma', prevMonthText: 'Előző hónap', nextMonthText: 'Következő hónap', prevYearText: 'Előző év', nextYearText: 'Következő év', closeText: 'Bezár', eventText: 'esemény', eventsText: 'esemény', allDayText: 'Egész nap', noEventsText: 'Nincs esemény', moreEventsText: '{count} további', } ``` --- ## Recurrence Some of the Eventcalendar and Datepicker options support recurrence rules. Recurrence rules regulate if the particular option (event, label, mark, etc.) reoccures periodically. For example the [data](../eventcalendar/api#opt-data), [colors](../eventcalendar/api#opt-colors), [labels](../eventcalendar/api#opt-labels), [marked](../eventcalendar/api#opt-labels), and [invalid](../eventcalendar/api#opt-invalid) options of the Eventcalendar or the [colors](../datepicker/api#opt-colors), [marked](../datepicker/api#opt-marked), [labels](../datepicker/api#opt-labels) and [invalid](../datepicker/api#opt-invalid) options of the Datepicker support recurrence rules through their `recurring` property. The rule can be an object or a string in `RRULE` format. ## Supported properties When specifying the recurring rule **as an object**, the following properties are supported: - `repeat`: *string* - The frequency of the recurrence. String equivalent: `FREQ`. - `'daily'` - Daily repeat - `'weekly'` - Weekly repeat - `'monthly'` - Monthly repeat - `'yearly'` - Yearly repeat - `day`: *number | Array* - The day of the month in case of monthly and yearly repeat. String equivalent: `BYMONTHDAY`. Negative numbers are calculated from the end of the month, -1 meaning the last day of the month. - `month`: *number | Array* - Specify the month in case of yearly repeat. String equivalent: `BYMONTH`. - `weekDays`: *string* - Comma separated list of the week days ('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA') for the occurrences. String equivalent: `BYDAY`. - `weekStart`: *string* - Specifies the first day of the week ('SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'). Default is 'MO'. String equivalent: `WKST`. - `pos`: *number* - Specifies the nth occurrence of the weekdays in a month in case of the monthly and yearly repeat. It also supports negative values in this case the order will be counted from the end of the month. This property depends on the repeat property. String equivalent: `BYSETPOS`. - `count`: *number* - The number of occurrences. String equivalent: `COUNT`. - `from`: *string | Date | object* - The start date of the occurrences. String equivalent: `DTSTART`. - `until`: *string | Date | object* - The end date of the occurrences. String equivalent: `UNTIL`. - `interval`: *number* - The time interval for the rule, e.g. every 3 days, or every 2 weeks. This depends on the repeat property. String equivalent: `INTERVAL`. ```javascript title="Rule specified as an object" recurring: { repeat: 'daily', count: 5, interval: 2 } ``` When specified **as a string**, the properties are separated by the `;` character. ```javascript title="Rule specified as a string" recurring: 'FREQ=DAILY;COUNT=5;INTERVAL=2' ``` ## Rule exceptions In case you would like to skip some dates from your rule, that's when the recurring exception come in handy. You can either set specific dates and/or a recurring rule as an exception, using the `recurringException` and the `recurringExceptionRule` properties. ```javascript title="Excluding exact dates from a daily repeating event" // repeats daily, every day recurring: { repeat: 'daily', interval: 1 }, // except on these dates recurringException: ['2023-07-10','2023-07-23','2023-07-28'], ``` The `recurringExceptionRule` property is usefull when there is a rule to the exception you want to enforce. For example, you want to exclude the first day of each month: ```javascript title="Excluding the first day of each month from a daily repeating event" // repeats daily, every day recurring: { repeat: 'daily', interval: 1 }, // except on the 1st day of each month: recurringExceptionRule: { repeat: 'monthly', day: 1, interval: 1 } ``` :::info In case you drag & drop an event on the calendar which is an occurrence of a recurring event, a new event will be created for the moved or resized event and the occurrence date will be added as a recurring exception to the original recurring event. ::: :::tip There is a [recurring exception configurator demo](https://demo.mobiscroll.com/scheduler/recurring-events) that can be used to experiment with the rules. Check it out on the previous link! ::: Full example **component.ts** ```ts @Component({ selector: 'component', templateUrl: './component.html', standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { public myData: MbscCalendarEvent[] = [{ start: new Date(2020, 2, 18, 9, 0), end: new Date(2020, 2, 18, 17, 0), title: 'Repeat every 2 days 5 times', // highlight-start recurring: { repeat: 'daily', count: 5, interval: 2 } // highlight-end }, { start: new Date(2020, 2, 17, 20, 0), end: new Date(2020, 2, 17, 22, 0), title: 'Football training every Monday and Wednesday', // highlight-next-line recurring: 'FREQ=WEEKLY;UNTIL=2020-06-17;BYDAY=MO,WE' }, { title: 'Pay the bills - on every first Friday of the months', // highlight-start recurring: { repeat: 'monthly', pos: 1, weekDays: 'FR', } // highlight-end } ]; } ``` **component.html** ```html ``` --- ## Accessibility(Eventcalendar) ## Keyboard Support The Eventcalendar supports different [views](./api#opt-view) for different jobs and each of these views support keyboard navigation. Focus can be moved with the `Tab` key. Focusable elements depend on the displayed view (more details below). Buttons can be triggered using the `Space` key when focused. Rendered events act like buttons. When an event is focused, the [event click](./api#event-onEventClick) event can be triggered using the `Space` or `Enter` keys. ### Calendar view Focusable elements are: * the header buttons: navigation, prev, next and today buttons * the events rendered on the calendar view * the currently selected day When the selected day is focused, the focus can be moved using the `Up`, `Down`, `Left` and `Right` arrow keys and set with the `Space` or `Enter` keys. When the popover is enabled on events, it can be toggled using the `Space` and `Esc` keys. ### Agenda Focusable elements are: * the header buttons: navigation, prev, next and today buttons * the currently selected day * the events listed in the agenda ### Scheduler Focusable elements are: * the header buttons: navigation, prev, next and today buttons * the events rendered in the scheduler ### Timeline Focusable elements are: * the header buttons: navigation, prev, next and today buttons * the events rendered on the timeline ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Supported aria-label on icon buttons, aria-hidden on decoration elements 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Not applicable - 1.3.6 Identify Purpose AAA Supported - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported in case of Scheduler and Timeline two dimensional scrolling could be necessary but these views are data tables 1.4.11 Non-text Contrast AA Supported borders 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Supported title attribute on event hover ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported D&D works with mouse and touch control but keyboard alternatives can be implemented ex. add/edit popup 2.1.2 No Keyboard Trap A Supported - 2.1.3 Keyboard (No Exception) AAA Supported D&D works with mouse and touch control but keyboard alternatives can be implemented ex. add/edit popup. In case of the Scheduler and Timeline the onCellClick event is not fired when using the keyboard 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Not applicable - 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported - 2.2.4 Interruptions AAA Not Applicable - 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Not supported Calendar view page change animation, all views navigation popup animation 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Supported event structure ex. title, time, etc. 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Supported - 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Not fully supported exception the resize handle 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Supported D&D works with mouse and touch control but keyboard alternatives can be implemented ex. add/edit popup 2.5.8 Target Size (Minimum) AA Not fully supported exception the resize handle ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility 3.1 Readable 3.1.1 Language of Page A Not Applicable 3.1.2 Language of Parts AA Not Applicable 3.1.3 Unusual Words AAA Not Applicable 3.1.4 Abbreviations AAA Supported 3.1.5 Reading Level AAA Not Applicable 3.1.6 Pronunciation AAA Not Applicable 3.2 Predictable 3.2.1 On Focus A Supported 3.2.2 On Input A Not Applicable 3.2.3 Consistent Navigation AA Not Applicable 3.2.4 Consistent Identification AA Not Applicable 3.2.5 Change on Request AAA Not Applicable 3.2.6 Consistent Help A Not Applicable 3.3 Input Assistance 3.3.1 Error Identification A Not Applicable 3.3.2 Labels or Instructions A Not Applicable 3.3.3 Error Suggestion AA Not Applicable 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable 3.3.5 Help AAA Not Applicable 3.3.6 Error Prevention (All) AAA Not Applicable 3.3.7 Redundant Entry A Not Applicable 3.3.8 Accessible Authentication (Minimum) AA Not Applicable 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Not Applicable --- ## Agenda The [Agenda](https://demo.mobiscroll.com/agenda) displays a [list of events for a given period of time](https://demo.mobiscroll.com/agenda/daily-weekly-monthly-annual-agenda#) (year, month, week or day). It can be used as a [standalone component](https://demo.mobiscroll.com/agenda/full-event-customization#) or in [combination with the calendar](https://demo.mobiscroll.com/agenda/navigate-from-external-calendar#). ## Overview The agenda supports a [configurable range listing](https://demo.mobiscroll.com/agenda/daily-weekly-monthly-annual-agenda#) along with daily, monthly and yearly presets. The capabilities like [recurring events](/angular/core-concepts/recurrence), [all-day, multi-day events](#opt-data), [responsiveness](#responsiveness) are supported by agenda. ![Agenda overview](/img/agenda-overview.png) ## Showing the Agenda ### View combination The four views - [scheduler](./scheduler), [calendar](./calendar), [timeline](./timeline), [agenda](./agenda) - can be used alone or combined with each-other to create the perfect user experience on mobile, desktop and on everything in-between. For example, you can combine [a daily agenda with a weekly calendar](https://demo.mobiscroll.com/agenda/daily-agenda-with-week-calendar#) for listing the events for the selected day. The view option will look like the following: ```html title='Daily Agenda combined with Weekly Calendar' ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { type: 'week' }, agenda: { type: 'day' } }; } ``` ### Configuring the view The Agenda view can be configured through the `view` option. Below are listed the `agenda` object properties which can help you fine-tune this view. ```html title="Example" ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { agenda: { type: 'day', size: 2 } }; } ``` ### scrollable boolean When set to `true`, makes the event listing independently scrollable. :::info There are two prerequisites for making this work: 1 - The calendar needs to be to placed inside a container which has a height. This can be either a fixed height, a height in percentage, or a flex height. When the calendar is placed directly in a container with a fixed height, it will work out of the box. If the height of the container is specified in percentage, e.g. you'd like to fill the full page height, you need to make sure that all parent elements also have `'height: 100%'` specified, up until the `body` and `html` elements, or until the closest parent which has a fixed height. If the container is inside a parent with flex layout, it will also work out of the box. 2 - The agenda needs a minimum height of 200px - the result of the container height minus the height of the calendar header minus the height of the displayed calendar rows. If the calculated height is less then 200px, the agenda will not be scrollable. ::: ### showEmptyDays boolean Display the day headers for every day in the list, even for those without events. **Default value**: `false` ### size number Specifies the number of years, months, weeks or days included in the list (depending on the specified type). **Default value**: `1` ### type "day" | "month" | "year" | "week" Sets the agenda type. If calendar is also displayed, only `'month'`, `'week'` and `'day'` values are supported. In case of month and week, the type and size should match the calendar type and size. In case of day type events on the selected calendar day will be displayed, so size will always be `1`. **Default value**: `'month'` ## Responsiveness The agenda is [fully responsive](https://demo.mobiscroll.com/eventcalendar/responsive-month-view). It adapts to the available space and fills the screen to look good everywhere. While you don't have to worry about the width the height can be manually adjusted with the [height](#opt-height) option. This specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. Use the [responsive](#opt-responsive) option to configure how the calendar behaves on different sized screens. The responsive option is equipped with five breakpoints: - `xsmall` (up to 575px), - `small` (up to 767px), - `medium` (up to 991px), - `large` (up to 1199px), - `xlarge` (from 1200px). Also, custom breakpoints can be added if necessary: - `my-custom-breakpoint: { breakpoint: 600 }` (from 600px up to the next breakpoint). :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries. ::: ```html title='Responsive configuration with the view option' ``` ```ts @Component({...}) export class MyComponent { responsiveSettings: MbscEventcalendarOptions = { xsmall: { view: { agenda: { type: 'week' } } }, medium: { view: { calendar: { type: 'week' }, agenda: { type: 'day' } } }, custom: { // Custom breakpoint, you can use multiple if needed, but each must have a unique name. breakpoint: 1000, view: { calendar: { type: 'month' }, agenda: { type: 'month' } } } } } ``` ![Agenda responsive behavior](/img/agenda-responsive.gif) ## Templating The display of Agenda can be customized with different [templating functions](#templates). ### The event Customize the events that appear on the agenda with the[eventTemplate](#template-eventTemplate) option. It should return the markup of the event. The event calendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. Check out how you can style events in [this example](https://demo.mobiscroll.com/angular/agenda/full-event-customization#) or just play with the slider below to see the differences. ### The event content Customize the event content that appears on the agenda by using the [eventContentTemplate](#template-eventContentTemplate) option. The event calendar will take care of styling and you can focus on what you show inside of the event. Check out how you can style event content in [this example](https://demo.mobiscroll.com/angular/agenda/event-content-customization#) or just play with the slider below to see the differences. ### The agenda header Customize how the header of the event calendar looks and how the components are arranged with the [headerTemplate](#template-headerTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar. While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's [building blocks](/angular/eventcalendar/templating#header-templating). These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. Check out how you can style the header in [this example](https://demo.mobiscroll.com/angular/agenda/customizing-header#) or just play with the slider below to see the differences. ### The agenda day header Customize the day headers that appear on the agenda with the [dayTemplate](#template-dayTemplate) option. It should contain the markup for the day header. Check out how you can style the day headers in [this example](https://demo.mobiscroll.com/angular/agenda/customizing-day-header#) or just play with the slider below to see the differences. ### The agenda empty state Customize the look of the empty state through [agendaEmptyTemplate](#template-agendaEmptyTemplate) function. Give a more purposeful feedback to the user and optionally add further actions to it. The template can be totally custom or dynamic based on any criteria. Check out how you can style the empty state in [this example](https://demo.mobiscroll.com/angular/agenda/empty-state#) or just play with the slider below to see the differences. ## Event order When rendering events, the following default order is applied: - All-day events are placed at the top. - Non-all-day events follow, sorted by their start times. - Events with the same start time are ordered alphabetically by their titles. To modify the default event order, you can use the `order` property of the [event data](#opt-data). If the order property does not meet your requirements, the [eventOrder](#opt-eventOrder) option can be used to further customize the ordering, which expects a function that compares two events and returns an order (-1 or 1). ## API Here is a comprehensive list of all the specific options, events and methods of the Agenda view. ### Options Explore the following API options that help you easily configure the Agenda. ### actionableEvents boolean Specifies if the events on the agenda and inside the calendar popover are actionable or not. If actionable, the event items will have hover and active states, and pointer cursor. Set to `false` when custom event rendering is used and the event list items contain other actionable elements, e.g. buttons. **Default value**: `true` ### context string | HTMLElement The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> The events for the Eventcalendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The event objects may have additional custom properties as well. The custom properties are not used by the event calendar, but they are kept and will be available anywhere the event objects are used. E.g. the [onEventClick](#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ::: :::info Use the [getEvents](#method-getEvents) method to get the events between two dates. ::: ```js data: [ { start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, color: 'red' }, { title: 'Work project', recurring: { repeat: 'daily', until: '2021-04-01' }, recurringException: ['2021-03-15', '2021-03-25'], recurringExceptionRule: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelectedDate [MbscDateType](#type-MbscDateType) Specifies the initial selected date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### eventOrder (event1: [MbscCalendarEvent](#type-MbscCalendarEvent), event2: [MbscCalendarEvent](#type-MbscCalendarEvent)) => number Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1. If not specified, the default order is: - all day events - rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title **Default value**: `undefined` ### exclusiveEndDates boolean If `true`, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. `end: '2021-07-03T00:00'` means that the event ends on 2nd of July and will not be displayed on 3rd of July. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: ### height string | number Sets the height of the component. The height of the calendar view impacts the number of labels that fit into a table cell. A "show more" label will be displayed for events that don't fit. **Default value**: `undefined` ### immutableData boolean If `true`, the Eventcalendar will work in immutable mode. In this mode the component won't update the data directly, only fire the necessary lifecycle events, where the original data can be updated manually. **Default value**: `undefined` ### max [MbscDateType](#type-MbscDateType) Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the [invalid](#opt-invalid) option with daily recurrence starting from the specific date. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the [invalid](#opt-invalid) option with daily recurrence until the specific date. **Default value**: `undefined` ### modules Array Additional modules can be added to the eventcalendar. The option receives an array of module objects. For example, the print module can be added through this option. ```js // import the print module // later on, add it to the modules array: modules: [print] ``` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed. If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01. It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is `01/16/2024`, the pages are calculated from this date, so the initial page will contain `[01/16/2024, 01/16/2024, 01/17/2024]`, the next page `[01/18/2024, 01/19/2024, 01/20/2024]` and so on. In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day. Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the [selectedDate](#opt-selectedDate) option. **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### selectMultipleEvents boolean When `true`, enables multiple event selection on the calendar. **Default value**: `false` ### selectedDate [MbscDateType](#type-MbscDateType) Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the [refDate](#opt-refDate) option. You also need to pass a handler for the [onSelectedDateChange](#event-onSelectedDateChange) event to update the selected date when the date is changed from the calendar. **Default value**: `undefined` ### selectedEvents Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Specifies the selected events on the calendar. The [onSelectedEventsChange](#event-onSelectedEventsChange) event will be fired when the selected events change from the calendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. **Default value**: `undefined` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showControls boolean Show or hide the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker. **Default value**: `true` ### showEventBuffer boolean If `true`, it will display the event buffers defined in the [event data](#opt-data). **Default value**: `true` ### showEventTooltip boolean If `false`, it will hide the native tooltip that shows up when hovering over an event. **Default value**: `true` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### width string | number Sets the width of the component. **Default value**: `undefined` ### Events The Agenda ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onEventClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventDeleted (args: MbscEventDeletedEvent, inst: EventcalendarBase) => void Triggered when an event is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The deleted event. - `events`: *Array* - The deleted events in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event was deleted. - inst - The component instance. ### onEventDoubleClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is double-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicker, if [slots](#opt-slots) are set. - `slotObj`: *MbscResource* - The resource where the event was clicker, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverIn (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event is hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event is hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event is hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverOut (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event was hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventRightClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is right-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onPageChange (args: MbscPageChangeEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscPageLoadedEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscPageLoadingEvent, inst: EventcalendarBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onSelectedDateChange (args: MbscSelectedDateChangeEvent, inst: EventcalendarBase) => void Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows. You can use this event in conjunction with the [selectedDate](#opt-selectedDate) option to customize where the Eventcalendar should navigate. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The newly selected date. - inst - The component instance. ### onSelectedEventsChange (args: MbscSelectedEventsChangeEvent, inst: EventcalendarBase) => void Triggered when an event is selected or deselected on the UI, when [multiple event selection](#opt-selectMultipleEvents) is enabled. You can also select events programmatically using the [selectedEvents](#opt-selectedEvents) option. Parameters: - args - The event argument with the following properties: - `events`: *Array* - The selected events. - inst - The component instance. ### Localization The Agenda is fully localized. This covers date and time format, button copy, rtl and more. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateFormatLong string Long date format, used by the agenda view and timeline day headers. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'D DDD MMM YYYY'` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### noEventsText string Text for empty event list. **Default value**: `'No events'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### Templates The display of the Agenda can be customized with different templating functions. ### agendaEmptyTemplate Template to customize the agenda empty state. Should contain the desired template to be used in the agenda when the events list is empty. ### agendaTemplate Template to customize agenda listing. There is a scrolling functionality of the list: when clicking on a calendar date scrolls to the date on the list as well, and scrolling the list updates the selected date on the calendar. For this functionality to work, you need to use the `mbsc-event-list-day` directive on the elements of the days in your template with the day timestamp as parameter: ```html
  • {{day.date}}
  • {{event.title}}
``` The template data is an array containing the events of the current view, grouped by day. A day object has the following properties: - `date`: String - The formatted date of the day. - `events`: Array - The list of events for the day. An event object has the following properties: - `allDay`: String - The localized all-day text in case of all day events. - `end`: String - The formatted end time, if the event is not all day. - `id`: String - The id of the event. - `isMultiDay`: Boolean - True if the event spans across multiple days. - `lastDay`: Boolean - True if it's rendered on the last day of a multiple event. - `original`: Object - The original event object. - `start`: String - The formatted start time, if the event is not all day. - `title`: String - The title of the event. - `timestamp`: Number - The timestamp of the day ### dayTemplate Customize the day cells of the calendar view and the date header in case of scheduler and timeline views. If you are looking to customize only the day cells content and don't want to bother with the styling of the event, in case of calendar and scheduler views you can use the [dayContentTemplate](#template-dayContentTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. - `isActive`: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year **Default value**: `undefined` ### eventContentTemplate Template to customize the event content that appears on the agenda and the popover. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [eventTemplate](#template-eventTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### eventTemplate Template to customize the events that appear on the agenda and the popover. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [eventContentTemplate](#template-eventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### headerTemplate Template to customize the header of the event calendar. You can use custom markup or components as well as the built in header components of the calendar. **Default value**: `undefined` ### Types ### MbscCalendarEvent Interface Properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. ### MbscDateType string | Date | object ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscEventcalendarOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## Eventcalendar API Here is a comprehensive list of all the options, events and method the Eventcalendar has. ## Options Explore the following API options that help you easily configure the Eventcalendar. ### actionableEvents boolean Specifies if the events on the agenda and inside the calendar popover are actionable or not. If actionable, the event items will have hover and active states, and pointer cursor. Set to `false` when custom event rendering is used and the event list items contain other actionable elements, e.g. buttons. **Default value**: `true` ### clickToCreate boolean | "double" | "single" Enable new event creation on click. If `true` or `'double'`, a new event will be created only with a double click and with the `'single'` value the event will be created instantly with a single click. This option will only work on desktop environment where mouse events are fired. It will also allow deleting of the focused events using the Delete or Backspace key. In touch environment a long tap should be used to create a new event and it is controlled by the [dragToCreate](#opt-dragToCreate) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### colors Array<[MbscCalendarColor](#type-MbscCalendarColor)> Specifies the color for certain dates or date ranges on the calendar. The [`MbscCalendarColor`](#type-MbscCalendarColor) type has the following properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The colored range will be considered all-day if: - the `allDay` property is explicitly set. - the `start` / `end` properties are not specified, only the `date`. ::: :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The colors can be combined with the [labels](#opt-labels) or [marked](#opt-marked) options. ::: ```js [ { date: new Date(2020, 2, 23), background: 'pink' }, { date: new Date(2020, 2, 24), background: 'green' }, { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } }, { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } } ] ``` **Default value**: `undefined` ### connections Array<[MbscEventConnection](#type-MbscEventConnection)> Specifies connections between events. On the UI events will be linked with lines and additionally arrows can be displayed to illustrate the direction of the connection. Events can have multiple connections simultaneously. An array of connection objects can be passed. The [`MbscEventConnection`](#type-MbscEventConnection) type has the following properties: - `arrow`: *boolean | "from" | "to" | "bidirectional"* - Specifies where to display arrows If `true`, the arrow will display only at the end side of the connection. - `color`: *string* - Specifies the color of the connection. - `cssClass`: *string* - Custom CSS class for the connection line for further customization. - `from`: *string | number* - The id of the event where the connection will begin - `to`: *string | number* - The id of the event where the connection will end. - `type`: *"fs" | "sf" | "ss" | "ff"* - The type of the connection. Possible values: `'fs'` - finish-to-start, `'sf'` - start-to-finish, `'ss'` - start-to-start, `'ff'` - finish-to-finish. **Default value**: `undefined` ### context string | HTMLElement The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> The events for the Eventcalendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The event objects may have additional custom properties as well. The custom properties are not used by the event calendar, but they are kept and will be available anywhere the event objects are used. E.g. the [onEventClick](#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ::: :::info Use the [getEvents](#method-getEvents) method to get the events between two dates. ::: ```js data: [ { start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, color: 'red' }, { title: 'Work project', recurring: { repeat: 'daily', until: '2021-04-01' }, recurringException: ['2021-03-15', '2021-03-25'], recurringExceptionRule: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelectedDate [MbscDateType](#type-MbscDateType) Specifies the initial selected date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### dragBetweenResources boolean If `false`, the events will not be moveable across resources, only in time. To control movement in time, use the [dragInTime](#opt-dragInTime) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragBetweenSlots boolean If `false`, the events will not be moveable across slots, only in time and resource. To control movement in time, use the [dragInTime](#opt-dragInTime) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragInTime boolean If `false`, the events will not be moveable in time. In case of the scheduler and timeline views events events can still be moved between resources. To control movement between resources, use the [dragBetweenResources](#opt-dragBetweenResources) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragTimeStep number Specifies the steps in minutes for the scheduler and timeline events during drag. **Default value**: `15` ### dragToCreate boolean If `true`, dragging on an empty cell will create a new event. It will also allow deleting of the focused events using the Delete or Backspace key. The title of the new event can be specified with the [newEventText](#opt-newEventText) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### dragToMove boolean If `true`, the events will be moveable. **Default value**: `undefined` ### dragToResize boolean If `true`, the events will be resizable. **Default value**: `undefined` ### eventDelete boolean Enables or disables event deletion. When `true`, the focused event will be deleted on pressing the Delete or Backspace keys on the keyboard. By default the event deletion depends on the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. If either of those are `true`, and no `eventDelete` option is set, then event deletion is also enabled, otherwise not. **Default value**: `undefined` ### eventOrder (event1: [MbscCalendarEvent](#type-MbscCalendarEvent), event2: [MbscCalendarEvent](#type-MbscCalendarEvent)) => number Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1. If not specified, the default order is: - all day events - rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title **Default value**: `undefined` ### eventOverlap boolean If `false`, the events cannot overlap. **Default value**: `true` ### exclusiveEndDates boolean If `true`, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. `end: '2021-07-03T00:00'` means that the event ends on 2nd of July and will not be displayed on 3rd of July. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: ### extendDefaultEvent (args: MbscNewEventData) => void | [MbscCalendarEvent](#type-MbscCalendarEvent) Use this option to set properties to the new event created with click or drag. The event creation is handled by the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. It takes a function that should return the properties for the new event. The argument object passed to this function has the following properties: - `start`: *Date* - The date when the newly created event will start. - `resource`: *string | number* - The id of the resource where the event creation started. ```js extendDefaultEvent: (args) => { return { color: args.resource === 'admin' ? 'green' : 'red', title: 'My event', }; } ``` **Default value**: `undefined` ### externalDrag boolean If `true`, external drag & drop is allowed and events can be dragged outside of the component view. **Default value**: `undefined` ### externalDrop boolean If `true`, external events can be dragged into the view. **Default value**: `undefined` ### externalResourceDrag boolean If `true`, external drag & drop is allowed and resource can be dragged outside of the component view. **Default value**: `undefined` ### externalResourceDrop boolean If `true`, external resources can be dragged into the view. **Default value**: `undefined` ### groupBy "date" | "resource" Groups the [events](#opt-data) by date or by [resource](#opt-resource). **Default value**: `'resource'` ### height string | number Sets the height of the component. The height of the calendar view impacts the number of labels that fit into a table cell. A "show more" label will be displayed for events that don't fit. **Default value**: `undefined` ### immutableData boolean If `true`, the Eventcalendar will work in immutable mode. In this mode the component won't update the data directly, only fire the necessary lifecycle events, where the original data can be updated manually. **Default value**: `undefined` ### invalid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the invalid values. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the invalid range is all day or not. - `start`: *Date | string | object* - Start of the invalid range. - `end`: *Date, string | object* - End of the invalid range. - `recurring`: *string | object* - Recurrence rule for recurring invalid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - Specifies the [resource](#opt-resources) ids for the invalid range. The invalid range will be displayed only in the specified resource. If there is no resource defined, the invalid range will be displayed in every resource. - `slot`: *string | number* - Specifies the [slot](#opt-slots) id for the invalid range. The invalid range will be displayed only in the specified slot. If there is no slot defined, the invalid range will be displayed in every slot. - `title`: *string* - Text which will be displayed for the invalid range. Only applicable for the timeline and scheduler views. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### invalidateEvent "strict" | "start-end" Specifies how to validate events against [invalid](#opt-invalid) ranges on create/move/resize: - `'strict'` - The event cannot intersect with an invalid range at all. - `'start-end' - The event start and end cannot be inside an invalid range. **Default value**: `'strict'` ### labels Array<[MbscCalendarLabel](#type-MbscCalendarLabel)> Specifies labels for calendar days. The [`MbscCalendarLabel`](#type-MbscCalendarLabel) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The labels can be combined with the [colors](#opt-colors) option. ::: ```js [ { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), text: 'Conference', color: 'red' }, { text: 'Christmas', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: undefined ### marked Array<[MbscCalendarMarked](#type-MbscCalendarMarked)> Mark certain dates on the calendar. An array containing dates, or objects with the following properties: The [`MbscCalendarMarked`](#type-MbscCalendarMarked) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The marked days can be combined with the [colors](#opt-colors) option. ::: ```js [ new Date(2020, 2, 15), new Date(2020, 2, 22), { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), color: 'red' }, { color: 'green', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: `undefined` ### max [MbscDateType](#type-MbscDateType) Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the [invalid](#opt-invalid) option with daily recurrence starting from the specific date. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the [invalid](#opt-invalid) option with daily recurrence until the specific date. **Default value**: `undefined` ### modules Array Additional modules can be added to the eventcalendar. The option receives an array of module objects. For example, the print module can be added through this option. ```js // import the print module // later on, add it to the modules array: modules: [print] ``` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed. If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01. It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is `01/16/2024`, the pages are calculated from this date, so the initial page will contain `[01/16/2024, 01/16/2024, 01/17/2024]`, the next page `[01/18/2024, 01/19/2024, 01/20/2024]` and so on. In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day. Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the [selectedDate](#opt-selectedDate) option. **Default value**: `undefined` ### resources Array<[MbscResource](#type-MbscResource)> The scheduler and timeline views can handle multiple resources. Resource grouping can be modified with the help of the [groupBy](#opt-groupBy) option. If set to `null` or `undefined`, all events will be displayed, regardless of their `resource` property. The timeline view will not display the resource column, if the resources option is not set. If set to an empty array, only those events will be displayed which are not tied to any resource. The timeline view will display an empty resource column when an empty array is passed. The timeline view can render multiple levels of hierarchy groups. Levels can be added with the help of the `children` property. The [`MbscResource`](#type-MbscResource) type has the following properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. ```js resources: [ { id: 1, name: 'Flatiron Room', color: '#f7c4b4' }, { id: 2, name: 'The Capital City', color: '#c6f1c9' }, { id: 3, name: 'Heroes Square', color: '#e8d0ef' } ] ``` **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### selectMultipleEvents boolean When `true`, enables multiple event selection on the calendar. **Default value**: `false` ### selectedDate [MbscDateType](#type-MbscDateType) Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the [refDate](#opt-refDate) option. You also need to pass a handler for the [onSelectedDateChange](#event-onSelectedDateChange) event to update the selected date when the date is changed from the calendar. **Default value**: `undefined` ### selectedEvents Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Specifies the selected events on the calendar. The [onSelectedEventsChange](#event-onSelectedEventsChange) event will be fired when the selected events change from the calendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. **Default value**: `undefined` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showControls boolean Show or hide the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker. **Default value**: `true` ### showEventBuffer boolean If `true`, it will display the event buffers defined in the [event data](#opt-data). **Default value**: `true` ### showEventTooltip boolean If `false`, it will hide the native tooltip that shows up when hovering over an event. **Default value**: `true` ### slots Array<[MbscSlot](#type-MbscSlot)> The slots, besides the [resources](#opt-resources) introduce a horizontal level of data grouping to the timeline view. If set to `null` or `undefined`, all events will be displayed, regardless of their slot property. If set to an empty array, only those events will be displayed which are not tied to any slot. The [`MbscSlot`](#type-MbscSlot) type has the following properties: - `eventDragBetweenSlots`: *boolean* - Specifies whether the event is movable across slots. - `id`: *string | number* - The id of the slot. It that can be referenced in the events/invalids/colors data. - `name`: *string* - The name of the slot that will be displayed at the top of the slot column. ```js slots: [ { id: 1, name: 'Morning shift', }, { id: 2, name: 'Afternoon shift', } ] ``` **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### view [MbscEventcalendarView](#type-MbscEventcalendarView) Configures the Eventcalendar view. Possible views: `calendar`: Configures the calendar view. Properties: - `type`: *'week' | 'month' | 'year'* (default `'month'`) - Sets the calendar type. - `size`: *number* (default `1`) - Specifies the number of displayed weeks or months. - `count`: *boolean* (default `false`) - If `true`, it will display the number of events on the days with events. - `eventDisplay`: *'fill' | 'exact'* (default 'fill') - Specifies how events are displayed. - If set to `'exact'`, events are displayed according to their start and end times. - If set to `'fill'`, events cover the entire day. - `outerDays`: *boolean* (default `false`) - Show or hide days from previous and next months. Does not apply to week view. - `labels`: *boolean | number | 'all'* (default `true`) - Enable displaying events as labels on calendar days. - If set to `true`, events will be displayed in the available space. If there are more events for a day, than the available space, a label with "more" text will be displayed, which opens a popover showing all the events for the given day. To fit more events on a day, set the calendar height to an appropriate value, using the [height](#opt-height) option. - If set to `'all'`, all the events will be displayed in the calendar cell and the row height will auto-expand based on the displayed events. The view will became scrollable if the rows overflow the available height. - Specify a number to set how many events will be displayed before the "more" button in a calendar cell. The row height will auto expand until the labels count reaches the given number and after that the "x more" button will be displayed. In the case when only one event should go in the "more" popup, that event will be displayed in the place of the "x more" button. - `popover`: *boolean* (default `undefined`) - Enable popover on days containing events. If not explicitly defined, the popover will not show up if an agenda view is also displayed. If event labels are displayed, the popover will only show up for days where the labels do not fit on the calendar, and a "more" label is present. - `popoverClass`: *string* (default `undefined`) - A custom CSS class added to the popover element. Can be used to customize the styling of the popover. - `scroll`: *'horizontal' | 'vertical'* (default `'horizontal'`) - Specifies the direction of the calendar scroll. - `weekNumbers`: *boolean* (default `false`) - Show or hide week numbers. `agenda`: Configures the agenda view. Properties: - `type`: *'day' | 'week' | 'month' | 'year'* (default `'month'`) - Sets the agenda type. If calendar is also displayed, only `'month'`, `'week'` and `'day'` values are supported. In case of month and week, the type and size should match the calendar type and size. In case of day type events on the selected calendar day will be displayed, so size will always be `1`. - `size`: *number* (default `1`) - Specifies the number of displayed years, months, weeks or days. - `scrollable`: *boolean* (default `true`) - Setting this to `true` makes the agenda independently scrollable. :::info There are two prerequisites for making this work: 1 - The calendar needs to be to placed inside a container which has a height. This can be either a fixed height, a height in percentage, or a flex height. When the calendar is placed directly in a container with a fixed height, it will work out of the box. If the height of the container is specified in percentage, e.g. you'd like to fill the full page height, you need to make sure that all parent elements also have `'height: 100%'` specified, up until the `body` and `html` elements, or until the closest parent which has a fixed height. If the container is inside a parent with flex layout, it will also work out of the box. 2 - The agenda needs a minimum height of 200px - the result of the container height minus the height of the calendar header minus the height of the displayed calendar rows. If the calculated height is less then 200px, the agenda will not be scrollable. ::: - `showEmptyDays`: *boolean* (default `false`) - When set to `true`, it will display day headers for every day in the list, even for those without events. `schedule`: Configures the scheduler view. Properties: - `type`: *'day' | 'week' | 'month'* (default `'week'`) - Sets the scheduler type. - `size`: *number* (default: `1`)- Specifies the number of displayed months, weeks or days. - `allDay`: *boolean* (default `true`) - Show or hide the all day events. - `currentTimeIndicator`: *boolean* (default `true`) - Show or hide the current time indicator. - `days`: *boolean* (default `true`) - Show or hide week days above the scheduler grid. - `startDay`: *number* (default `0`) - Specifies the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. Should not be mistaken for the [firstDay](#localization-firstDay) option, which sets the first day of the week, and, if not set, is defined by the [localization](#localization-locale). - `endDay`: *number* (default `6`) - Specifies the last visible weekday of the view. Sunday is 0, Monday is 1, etc. - `startTime`: *string* (default `'00:00'`) - Set the start time of scheduler column. Hours and minutes can be specified in the same string, example: `'09:30'`. - `endTime`: *string* (default `'24:00'`) - Set the end time of scheduler column. Hours and minutes can be specified in the same string, example: `'18:30'`. - `hideEmptyColumns`: *boolean* (default `false`) - Hide the empty columns in the scheduler view. If set to `true`, the scheduler will not display columns without events. - `hideInvalidColumns`: *boolean* (default `false`) - Hide the fully invalid columns in the scheduler view. If set to `true`, the scheduler will not display fully invalid columns. - `maxEventStack`: *'all' | 'auto' | number* - Limit the number of displayed events. When the number of overlapping events reaches the specified value, a "more" button will be displayed which opens a popover showing the rest of the events. - If it is a `number`, it specifies how many events will be displayed before the "more" button appears. - If set to `'all'`, all events will be displayed. - If set to `'auto'`, the component will decide how many events can be placed inside the column, based on the `minEventWidth` view option and the actual column width. - `minEventWidth`: *number* - Specifies the minimum event width. Will be used when `maxEventStack: 'auto'` is used. - `timeCellStep`: *number* (default `60`) - Set the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. - `timeLabelStep`: *number* (default `60`) - Set the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. - `timezones`: *Array* - Display times in multiple timezones on the time scale and time indicator. The timezones array can contain timezone strings or objects with timezone and label properties. Timezone strings must use the name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172). If no label is provided, the time column label will be UTC +/- the timezone offset. ```js timezones: ['Europe/Berlin','Europe/Bucharest'] ``` ```js timezones: [ { timezone: 'America/Chicago', label: 'CHI'}, { timezone: 'America/New_York', label: 'NY'} ] ``` `timeline`: Configures the timeline view. Properties: - `type`: *'day' | 'week' | 'month' | 'year'* (default `'week'`) - Sets the timeline type. - `size`: *number* (default: `1`)- Specifies the number of displayed years, months, weeks or days. - `resolutionHorizontal`: *'hour', 'day', 'week', 'month', 'quarter', 'year'* (default 'hour') - Sets the horizontal resolution of the timeline. In case of hourly resolution, the columns can be split to minutes (1, 5, 15, 20, 30) or merge to multiple hours (2, 3, 4, 6, 8, 12) using the `timeCellStep` and `timeLabelStep` properties. - `currentTimeIndicator`: *boolean* - Show or hide the current time indicator. Defaults to `true`, when the horizontal resolution is less than a day. - `hideEmptyRows`: *boolean* (default `false`) - Hide the empty rows in the timeline view. If set to `true`, the timeline will not display rows without events. :::info Parent resources will always be displayed, even when empty. ::: - `hideInvalidRows`: *boolean* (default `false`) - Hide the fully invalid rows in the timeline view. If set to `true`, the timeline will not display the fully invalid rows. :::info Parent resources will always be displayed, even when fully invalid. ::: - `startDay`: *number* (default `0`) - Specifies the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. Should not be mistaken for the [firstDay](#localization-firstDay) option, which sets the first day of the week, and, if not set, is defined by the [localization](#localization-locale). - `endDay`: *number* (default `6`) - Specifies the last visible weekday of the view. Sunday is 0, Monday is 1, etc. - `maxEventStack`: *'all' | number* - Limit the number of displayed events. When the number of overlapping events reaches the specified value, a "more" button will be displayed which opens a popover showing the rest of the events. - If it is a `number`, it specifies how many events will be displayed before the "more" button appears. - If set to `'all'`, all events will be displayed. - `startTime`: *string* (default `'00:00'`) - Set the start time of the timeline days. Hours and minutes can be specified in the same string, example: `'09:30'`. - `endTime`: *string* (default `'24:00'`) - Set the end time of the timeline days. Hours and minutes can be specified in the same string, example: `'18:30'`. - `timeCellStep`: *number* (default `60`) - Set the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. - `timeLabelStep`: *number* (default `60`) - Set the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. - `eventHeight`: *'variable' | 'equal'* (default 'equal') - Specifies wether the height of the events is equal or variable. :::info [Learn more about variable event heights](./timeline#variable-event-height). ::: - `eventList`: *boolean* (default `false`) - If `true`, transforms the layout into a summary view. The events are listed in the appropriate cell one after the other. - `rowHeight`: *'variable' | 'equal'* (default 'variable') - Controls the height of the timeline rows. By default rows will have variable height and will expand to accommodate the displayed events. If it is set to `'equal'`, the rows will have equal heights. - `virtualScroll`: *boolean* (default `true`) - Enable or disable virtual scroll. - `weekNumbers`: *boolean* (default `false`) - Show or hide week numbers. ```js view: { calendar: { type: 'week', size: 2 }, agenda: { type: 'week', size: 2 } } ``` ### width string | number Sets the width of the component. **Default value**: `undefined` ### zoomLevel string | number Specifies the current zoom level of the timeline view. The zoom levels can be listed using the `zoomLevels` property of the timeline inside the view option. **Default value**: `undefined` ## Events The Eventcalendar ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onCellClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event object has the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellDoubleClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is double-clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellHoverIn (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered day. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellHoverOut (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered cell. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellRightClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is right-clicked on the calendar, scheduler, or timeline grid . Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onEventClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventCreate (args: MbscEventCreateEvent, inst: EventcalendarBase) => void Triggered when an event is about to create and it is not yet rendered on its final position. Event creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The newly created event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being created. - inst - The component instance. ### onEventCreateFailed (args: MbscEventCreateFailedEvent, inst: EventcalendarBase) => void Triggered when an event creation failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - inst - The component instance. ### onEventCreated (args: MbscEventCreatedEvent, inst: EventcalendarBase) => void Triggered when an event is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - `target`: *HTMLElement* - The DOM element of the created event. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - inst - The component instance. ### onEventDelete (args: MbscEventDeleteEvent, inst: EventcalendarBase) => void Triggered when an event is about to be deleted and it is not yet removed from the view. Event deletion can be performed with delete and backspace button on an active event. Deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from of the keydown action. - `event`: *MbscCalendarEvent* - The event being deleted. - `events`: *Array* - The events being deleted in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event is being deleted. - inst - The component instance. ### onEventDeleted (args: MbscEventDeletedEvent, inst: EventcalendarBase) => void Triggered when an event is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The deleted event. - `events`: *Array* - The deleted events in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event was deleted. - inst - The component instance. ### onEventDoubleClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is double-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicker, if [slots](#opt-slots) are set. - `slotObj`: *MbscResource* - The resource where the event was clicker, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventDragEnd (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has ended. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event was dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event was dragged. - inst - The component instance. ### onEventDragEnter (args: MbscEventDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragLeave (args: MbscEventDragEvent) => void Triggered when an event is dragged out form the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragStart (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has started. Parameters: - args - The event argument with the following properties: - `action`: *'create' | 'resize' | 'move'* - The user action which triggered the event. - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event is dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. - inst - The component instance. ### onEventHoverIn (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event is hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event is hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event is hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverOut (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event was hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventRightClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is right-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventUpdate (args: MbscEventUpdateEvent, inst: EventcalendarBase) => void Triggered when an event is about to update. Update can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `oldResource`: number | string - The id of the resource from which the event was dragged. - `oldResourceObj`: *MbscResource* - The resource from which the event was dragged. - `oldSlot`: number | string - The id of the slot from which the event was dragged. - `oldSlotObj`: *MbscSlot* - The slot from which the event was dragged. - `resource`: number | string - The id of the resource where the event was dropped. - `resourceObj`: *MbscResource* - The resource where the event was dropped. - `slot`: number | string - The id of the slot where the event was dropped. - `slotObj`: *MbscSlot* - The slot where the event was dropped. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being updated. - inst - The component instance. ### onEventUpdateFailed (args: MbscEventUpdateFailedEvent, inst: EventcalendarBase) => void Triggered when an event update failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - inst - The component instance. ### onEventUpdated (args: MbscEventUpdatedEvent, inst: EventcalendarBase) => void Triggered when an event is updated and is rendered in its new position. This is where you update the event in your database or persistent storage. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `resourceObj`: *MbscResource* - The resource where the event is updated, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is updated, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - `target`: *HTMLElement* - The DOM element of the updated event. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onLabelClick (args: MbscLabelClickEvent, inst: EventcalendarBase) => void Triggered when a label is clicked on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the label was clicked. - `domEvent`: *Event* - The DOM event of the click. - `label`: *MbscCalendarLabel* - The original object of the label which was clicked, `undefined` in case of the "more" label. - `labels`: *Array* - An array containing each label object for the given day. - `target`: *HTMLElement* - The DOM element of the label. - inst - The component instance. ### onPageChange (args: MbscPageChangeEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscPageLoadedEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscPageLoadingEvent, inst: EventcalendarBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onResourceClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceCollapse (args: MbscResourceCollapseEvent, inst: EventcalendarBase) => void Triggered when a parent resource is collapsed on the timeline. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the click. - `resource`: *string | number* - The id of the collapsed [resource](#opt-resources). - `resourceObj`: *MbscResource* - The collapsed [resource](#opt-resources). - inst - The component instance. ### onResourceCreate (args: MbscResourceCreateEvent, inst: EventcalendarBase) => void Triggered when an resource is about to create and it is not yet rendered on its final position. Resource creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The newly created resource. - inst - The component instance. ### onResourceCreated (args: MbscResourceCreatedEvent, inst: EventcalendarBase) => void Triggered when a resource is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The newly created resource. - inst - The component instance. ### onResourceDelete (args: MbscResourceDeleteEvent, inst: EventcalendarBase) => void Triggered when an resource is about to be deleted and it is not yet removed from the view. Resource deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The former position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The resource being deleted. - inst - The component instance. ### onResourceDeleted (args: MbscResourceDeletedEvent, inst: EventcalendarBase) => void Triggered when a resource is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The former position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The deleted resource. - inst - The component instance. ### onResourceDoubleClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is double-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceDragEnter (args: MbscResourceDragEvent, inst: EventcalendarBase) => void Triggered when a resource is dragged into the timeline view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `resource`: *MbscResource* - The dragged resource. - inst - The component instance. ### onResourceDragLeave (args: MbscResourceDragEvent, inst: EventcalendarBase) => void Triggered when a resource is dragged out from the timeline view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `resource`: *MbscResource* - The dragged resource. - inst - The component instance. ### onResourceExpand (args: MbscResourceExpandEvent, inst: EventcalendarBase) => void Triggered when a parent resource is expanded on the timeline. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the click. - `resource`: *string | number* - The id of the expanded [resource](#opt-resources). - `resourceObj`: *MbscResource* - The expanded [resource](#opt-resources). - inst - The component instance. ### onResourceHoverIn (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceHoverOut (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceOrderUpdate (args: MbscResourceOrderEvent, inst: EventcalendarBase) => void Triggered after a resource is dragged and dropped into a new location. Resource reorder can be prevented by returning `false` from the handler function. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. Parameters: - args - The event argument with the following properties: - `index`: *Resource* - The new position of the resource within its siblings. - `oldIndex`: *Resource* - The old position of the resource within its siblings. - `oldParent`: *Resource* - The old parent resource. - `parent`: *Resource* - The parent resource. - `resource`: *Resource* - The updated resource. - `resources`: Array<*Resource*> - The entire resources array with the new order. - inst - The component instance. ### onResourceRightClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is right-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onSelectedDateChange (args: MbscSelectedDateChangeEvent, inst: EventcalendarBase) => void Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows. You can use this event in conjunction with the [selectedDate](#opt-selectedDate) option to customize where the Eventcalendar should navigate. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The newly selected date. - inst - The component instance. ### onSelectedEventsChange (args: MbscSelectedEventsChangeEvent, inst: EventcalendarBase) => void Triggered when an event is selected or deselected on the UI, when [multiple event selection](#opt-selectMultipleEvents) is enabled. You can also select events programmatically using the [selectedEvents](#opt-selectedEvents) option. Parameters: - args - The event argument with the following properties: - `events`: *Array* - The selected events. - inst - The component instance. ### onVirtualLoading (args: MbscVirtualLoadEvent, inst: EventcalendarBase) => void Triggered when a new virtual page is loaded. You can use this to load events and resources on demand while scrolling the timeline grid. Parameters: - args - The event argument with the following properties: - `viewStart`: *Date* - The date where the virtual view starts. - `viewEnd`: *Date* - The date where the virtual view end. - `resourceStart`: *number|string* - The id of the resource where the virtual view starts. - `resourceEnd`: *number|string* - The id of the resource where the virtual view ends. - `oldResourceStart`: *number|string* - The id of the resource where the previous virtual view started. - `oldResourceEnd`: *number|string* - The id of the resource where the previous virtual view ended. - `oldViewStart`: *Date* - The date where the previous virtual view started. - `oldViewEnd`: *Date*- The date where the previous virtual view ended. - inst - The component instance. ## Localization The Eventcalendar is fully localized. This covers date and time format, button copy, rtl and more. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateFormatLong string Long date format, used by the agenda view and timeline day headers. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'D DDD MMM YYYY'` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### eventText string Text for the event word. **Default value**: `'event'` ### eventsText string Text for the events word (plural). **Default value**: `'events'` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### moreEventsPluralText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day, and there are more than one extra labels. The `{count}` inside the string will be replaced with the number of extra labels. When not specified, the [moreEventsText](#localization-moreEventsText) option will be used for both plural and singular form. **Default value**: `undefined` ### moreEventsText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day. The `{count}` inside the string will be replaced with the number of extra labels. Use the [moreEventsPluralText](#localization-moreEventsPluralText) as well, if the plural form is different. **Default value**: `'{count} more'` ### newEventText string Title for the newly created event with the [dragToCreate](#opt-dragToCreate) and the [clickToCreate](#opt-clickToCreate) action. **Default value**: `'New event'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### noEventsText string Text for empty event list. **Default value**: `'No events'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### quarterText string Text for quarter numbers in the timeline header. The {count} inside the string will be replaced with the number of the current quarter. **Default value**: `'Q {count}'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### weekText string Text for week numbers in the timeline header. The {count} inside the string will be replaced with the number of the current week. **Default value**: `'Week {count}'` ## Methods These methods are actions that can be performed on a component instance. ### getEvents (start: [MbscDateType](#type-MbscDateType), end: [MbscDateType](#type-MbscDateType)) => Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Returns the [events](#opt-data) between two dates. If `start` and `end` are not specified, it defaults to the start and end days of the current view. If `end` is not specified, it defaults to start date + 1 day. Parameters: - start - Start date of the specified interval. - end - End date of the specified interval. ### getInvalids (start: [MbscDateType](#type-MbscDateType), end: [MbscDateType](#type-MbscDateType)) => Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Returns the [invalids](#opt-invalid) between two dates. If `start` and `end` are not specified, it defaults to the start and end days of the current view. If `end` is not specified, it defaults to start date + 1 day. Parameters: - start - Start date of the specified interval. - end - End date of the specified interval. ### getViewDate () => Date Returns the view date which is representing the currently displayed date on the component. ### navigateToEvent (event: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void Navigates to the specified event on the calendar. Parameters: - event - The event object. The `id`, `start` and `resource` properties (in case if resources are used in timeline or schedule views) must be present in the object. ## Templates The display of the Eventcalendar can be customized with different templating functions. ### agendaEmptyTemplate Template to customize the agenda empty state. Should contain the desired template to be used in the agenda when the events list is empty. ### agendaTemplate Template to customize agenda listing. There is a scrolling functionality of the list: when clicking on a calendar date scrolls to the date on the list as well, and scrolling the list updates the selected date on the calendar. For this functionality to work, you need to use the `mbsc-event-list-day` directive on the elements of the days in your template with the day timestamp as parameter: ```html
  • {{day.date}}
  • {{event.title}}
``` The template data is an array containing the events of the current view, grouped by day. A day object has the following properties: - `date`: String - The formatted date of the day. - `events`: Array - The list of events for the day. An event object has the following properties: - `allDay`: String - The localized all-day text in case of all day events. - `end`: String - The formatted end time, if the event is not all day. - `id`: String - The id of the event. - `isMultiDay`: Boolean - True if the event spans across multiple days. - `lastDay`: Boolean - True if it's rendered on the last day of a multiple event. - `original`: Object - The original event object. - `start`: String - The formatted start time, if the event is not all day. - `title`: String - The title of the event. - `timestamp`: Number - The timestamp of the day ### bufferAfterTemplate Template reference to fully customize the buffer area that is displayed at the end of the scheduler and timeline events. The buffer can be defined with the help of the `bufferAfter` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### bufferBeforeTemplate Template reference to fully customize the buffer area that is displayed at the start of the scheduler and timeline events. The buffer can be defined with the help of the `bufferBefore` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### cellTemplate Customize the cells of the Eventcalendar in scheduler and timeline views. The template will receive an object as context, which can be used to display custom content in the cells. Keep the cell template simple, as it will be called and rendered **very frequently** during scroll and view changes. The object passed to the template contains the following properties: - `colors`: _Array_ - The list of colors for the current cell. - `date`: _Date_ – The current cell's date. - `events`: _Array_ List of events for the current cell. - `invalids`: _Array_ - The list of invalids for the current cell. - `resource`: _MbscResource_ - The resource object of the current cell. - `slot`: _MbscSlot_ - The slot object of the rendered cell. **Default value**: `undefined` ### dayContentTemplate Customize the day cells content of the event calendar. The Eventcalendar will take care of the styling and you can focus on what you show beside the day number. If you are looking to fully customize the day (e.g. add custom hover effects) you will need to use the [dayTemplate](#template-dayTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. **Default value**: `undefined` ### dayFooterTemplate Template to customize the footer of each day for the timeline. The following day specific details are available: - `date`: _Date_ - The date of the day. - `events`: _Array_ - The list of events for the day. **Default value**: `undefined` ### dayTemplate Customize the day cells of the calendar view and the date header in case of scheduler and timeline views. If you are looking to customize only the day cells content and don't want to bother with the styling of the event, in case of calendar and scheduler views you can use the [dayContentTemplate](#template-dayContentTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. - `isActive`: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year **Default value**: `undefined` ### eventContentTemplate Template to customize the event content that appears on the agenda and the popover. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [eventTemplate](#template-eventTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### eventTemplate Template to customize the events that appear on the agenda and the popover. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [eventContentTemplate](#template-eventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### headerTemplate Template to customize the header of the event calendar. You can use custom markup or components as well as the built in header components of the calendar. **Default value**: `undefined` ### hourFooterTemplate Template to customize the footer of the hour columns on the timeline view. The following properties are available: - `date`: _Date_ - The date and time of the rendered hour. - `events`: _Array_ - The list of events for the hour. - `isActive`: _boolean_ - True for the current hour. **Default value**: `undefined` ### hourTemplate Template to customize the header of the hour columns on the timeline view. The following properties are available: - `date`: _Date_ - The date and time of the rendered hour. - `events`: _Array_ - The list of events for the hour. - `isActive`: _boolean_ - True for the current hour. **Default value**: `undefined` ### labelContentTemplate Template to customize the label contents, that appears on the calendar. The Eventcalendar will take care of styling and you can focus on what you show inside of the label. If you are looking to fully customize the label (ex. add custom hover effects) you will need to use the [labelTemplate](#template-labelTemplate) option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. **Default value**: `undefined` ### labelTemplate Customize the labels that appear on the calendar view. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the label, you can use the [labelContentTemplate](#template-labelContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. **Default value**: `undefined` ### monthFooterTemplate Template to customize the footer of the month column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered month. - `events`: _Array_ - The list of events for the month. - `isActive`: _boolean_ - True for the current month. **Default value**: `undefined` ### monthTemplate Template to customize the header of the month column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered month. - `events`: _Array_ - The list of events for the month. - `isActive`: _boolean_ - True for the current month. **Default value**: `undefined` ### quarterFooterTemplate Template to customize the footer of the quarter column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered quarter. - `events`: _Array_ - The list of events for the quarter. - `isActive`: _boolean_ - True for the current quarter. **Default value**: `undefined` ### quarterTemplate Template to customize the header of the quarter columns on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered quarter. - `events`: _Array_ - The list of events for the quarter. - `isActive`: _boolean_ - True for the current quarter. **Default value**: `undefined` ### resourceEmptyTemplate Template to customize the content of the resource column in case of an empty resource array. ```html ``` **Default value**: `undefined` ### resourceFooterTemplate Template to customize the cell content below the resource column on the timeline view. **Default value**: `undefined` ### resourceHeaderTemplate Template to customize the cell content above the resource column on the timeline view. **Default value**: `undefined` ### resourceTemplate Template to customize the resource template of the scheduler and timeline views. The following properties are available: - `resource`: _MbscResource_ - The rendered resource. - `day`: _Date_ - The date on which the resource is rendered. Available when grouping by date in the scheduler view, or when vertical day resolution is used in the timeline view. ```html
{{resource.name}}

{{resource.description}}

 ``` **Default value**: `undefined` ### scheduleEventContentTemplate Template to customize the event content that appears on the scheduler and timeline. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [scheduleEventTemplate](#template-scheduleEventTemplate) option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### scheduleEventTemplate Template to customize the events that appear on the scheduler and timeline. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [scheduleEventContentTemplate](#template-scheduleEventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### sidebarFooterTemplate Template to customize the empty cell content below the sidebar column. This template is only rendered for the timeline view, if the [sidebarTemplate](#template-sidebarTemplate) is present. **Default value**: `undefined` ### sidebarHeaderTemplate Template to customize the empty cell content above the sidebar column. This template is only rendered for the timeline view, if the [sidebarTemplate](#template-sidebarTemplate) is present. **Default value**: `undefined` ### sidebarTemplate Template to customize and add a sidebar on the right side of the timeline. The template will receive the resource object as data. This data can be used to show resource specific things on the sidebar. **Default value**: `undefined` ### slotTemplate Template to customize the slot template of the timeline view. It will receive an object as parameter that has the following properties: - `date`: _Date_ - The specific date where the slot is rendered. - `slot`: _MbscSlot_ - Data of the rendered slot. ```
{{slotdata.slot.name}}

{{slotdata.slot.description}}

 ``` **Default value**: `undefined` ### weekFooterTemplate Template to customize the footer of the week column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered week. - `events`: _Array_ - The list of events for the week. - `isActive`: _boolean_ - True for the current week. - `endDate`: _Date_ - The end date of the week. - `startDate`: _Date_ - The start date of the week. - `weekNr`: _number_ - The week number. Enumeration starts with the first week of the year. **Default value**: `undefined` ### weekTemplate Template to customize the header of the week column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered week. - `events`: _Array_ - The list of events for the week. - `isActive`: _boolean_ - True for the current week. - `endDate`: _Date_ - The end date of the week. - `startDate`: _Date_ - The start date of the week. - `weekNr`: _number_ - The week number. Enumeration starts with the first week of the year. **Default value**: `undefined` ### yearFooterTemplate Template to customize the footer of the year column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered year. - `events`: _Array_ - The list of events for the year. - `isActive`: _boolean_ - True for the current year. **Default value**: `undefined` ### yearTemplate Template to customize the header of the year column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered year. - `events`: _Array_ - The list of events for the year. - `isActive`: _boolean_ - True for the current year. **Default value**: `undefined` ## Types ### MbscCalendarColor Interface Properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscCalendarEvent Interface Properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. ### MbscCalendarInvalid Interface Properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### MbscCalendarLabel Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label ### MbscCalendarMarked Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscDateType string | Date | object ### MbscEventConnection Interface Properties: - `arrow`: *boolean | "from" | "to" | "bidirectional"* - Specifies where to display arrows If `true`, the arrow will display only at the end side of the connection. - `color`: *string* - Specifies the color of the connection. - `cssClass`: *string* - Custom CSS class for the connection line for further customization. - `from`: *string | number* - The id of the event where the connection will begin - `to`: *string | number* - The id of the event where the connection will end. - `type`: *"fs" | "sf" | "ss" | "ff"* - The type of the connection. Possible values: `'fs'` - finish-to-start, `'sf'` - start-to-finish, `'ss'` - start-to-start, `'ff'` - finish-to-finish. ### MbscEventcalendarView Interface Properties: - `agenda`: *{scrollable?: boolean, showEmptyDays?: boolean, size?: number, type?: "day" | "month" | "year" | "week"}* - Configures the agenda view. - `calendar`: *{count?: boolean, eventDisplay?: "fill" | "exact", labels?: number | boolean | "all", outerDays?: boolean, popover?: boolean, popoverClass?: string, scroll?: "horizontal" | "vertical", size?: number, type?: "month" | "year" | "week", weekNumbers?: boolean}* - Configures the calendar view. - `schedule`: *{allDay?: boolean, currentTimeIndicator?: boolean, days?: boolean, endDay?: number, endTime?: string, hideEmptyColumns?: boolean, hideInvalidColumns?: boolean, maxEventStack?: number | "all" | "auto", minEventWidth?: number, size?: number, startDay?: number, startTime?: string, timeCellStep?: number, timeLabelStep?: number, timezones?: Array, type?: "day" | "month" | "week"}* - Configures the scheduler view. - `timeline`: *{columnWidth?: MbscTimelineColumnWidth, currentTimeIndicator?: boolean, endDay?: number, endTime?: string, eventHeight?: "variable" | "equal", eventList?: boolean, hideEmptyRows?: boolean, hideInvalidRows?: boolean, maxEventStack?: number | "all", resolution?: "day" | "hour" | "month" | "year" | "week" | "quarter", resolutionHorizontal?: "day" | "hour" | "month" | "year" | "week" | "quarter", resolutionVertical?: "day", resourceReorder?: boolean, rowHeight?: "variable" | "equal", size?: number, startDay?: number, startTime?: string, timeCellStep?: number, timeLabelStep?: number, type?: "day" | "month" | "year" | "week", virtualScroll?: boolean, weekNumbers?: boolean, zoomLevels?: { [key:string]: MbscTimelineZoomLevel }}* - Configures the timeline view. ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResource Interface Properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. The `MbscResource` supports custom properties in the form: ``` [x:string]: any ``` ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscEventcalendarOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscSlot Interface Properties: - `eventDragBetweenSlots`: *boolean* - Specifies whether the event is movable across slots. - `id`: *string | number* - The id of the slot. It that can be referenced in the events/invalids/colors data. - `name`: *string* - The name of the slot that will be displayed at the top of the slot column. The `MbscSlot` supports custom properties in the form: ``` [x:string]: any ``` ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## Blocked out dates You can show blocked out time ranges with the [`invalid`](./api#opt-invalid) option. By default the events and the blocked out dates will be displayed on the view even if there is collision. The [`invalid`](./api#opt-invalid) option supports the following formats: JavaScript Date objects, ISO8601 strings or moment object. These formats can be passed directly to the array in which case the whole day will be disabled or as an object where the blocked out ranges can be customized with the following properties: `allDay`, `start`, `end`, `title`, `recurring`. Custom properties can also be passed to the invalid object which will also be passed to the life-cycle events and this can help with the identification/validation of the invalids. If an event interacts with an invalid range the event will be reverted to it's original position and the [`onEventUpdateFailed`](./api#event-onEventUpdateFailed) event will be fired. (If the [`dragToMove`](./api#opt-dragToMove) or the [`dragToResize`](./api#opt-dragToResize) options were used.) If a newly created event collides with a blocked out date the event won't be created and the [`onEventCreateFailed`](./api#event-onEventCreateFailed) event will be fired. (If the [`dragToCreate`](./api#opt-dragToCreate) option was used) ```javascript title="Invalid array example with various properties" const invalid = [ /* Passing exact dates will block out the entire day */ new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // string moment("2020-12-25"), // moment object /* Block out date range passed as an object */ { // multi day range with date string start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', type: 'day-off' // custom property }, { // multi day range with date object allDay: true, start: new Date(2021, 2, 7, 10, 10), end: new Date(2021, 2, 9, 20, 20), title: 'Conference for the whole team', type: 'conference' // custom property }, { // multi day time range with recurring and time string start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', type: 'lunch' // custom property } ]; ``` ![Eventcalendar blocked out dates](/img/blocked-out-dates.gif) --- ## Third party calendar integration ## Overview The Calendar Integration is an optional plugin, that includes synchronization with your Google and Outlook calendar services. It can be installed and used with the Mobiscroll Event Calendar as described below. :::info Currently, the calendar integration plugins cannot be used in Chrome extensions, because the CSP rules do not allow loading scripts from 3rd party domains. ::: ## Installing the Calendar Integration Plugin When your Mobiscroll package is created with the [Download Builder](https://download.mobiscroll.com) and you have access to the Calendar Integration, you can choose to include it in the built package. In this case you will need to make sure you checked the Calendar Integration before downloading the package from the download page. After installing your downloaded package, the Calendar Integration will be available for import. When you're using the full Mobiscroll package from NPM, then you have the possibility to install the Calendar Integration as an additional package (also from NPM). In this case, after successfully using the [Mobiscroll CLI](https://docs.mobiscroll.com/cli) to configure the project, you will have to install the `@mobiscroll/calendar-integration` package from npm. Use the following command: ```bash npm install @mobiscroll/calendar-integration ``` ## Google calendar integration The Google Calendar Integration is a part of the third party calendar integrations plugin that manages the synchronization with your Google calendar services. ### Public google calendars The public google calendar integration allows you to load events from a public calendar without user authentication. Calling the `init` function will do the necessary initializations for the third party. After the init, you can list the events from the public calendar. ```ts @Component({...}) export class MyComponent implements OnInit { myEvents: MbscCalendarEvent[] = []; ngOnInit() { // init google client googleCalendarSync.init({ apiKey: 'YOUR_API_KEY', onInit: () => { googleCalendarSync.getEvents( 'PUBLIC_CALENDAR_ID', new Date(2022, 1, 1), new Date(2022, 3, 0) ).then((events) => { this.myEvents = events; }); }, }); } } ``` :::info The public google calendar integration only supports reading events. Writing, updating, or deleting events requires the private calendar integration described below. ::: ### Private google calendars The private google calendar integration allows your app to connect with google calendar services for reading and managing events. Once initialized, users can sign in with their google account, view their calendars and events, and create, update, or delete events based on their granted permissions. ### Key details - **User presence required** The user must be in front of the computer and logged in for synchronization to happen. Sync is handled through client-side code. - **User-driven updates** Calendar syncing takes place when the user is logged in and interacting with the application. This approach gives users full control over when and how their data is synchronized. - **Active session required** To update or fetch events, the user needs to be logged in and have the application open. This means that changes made while the user is active — such as adding, editing, or deleting events — will be reflected in their connected calendar. - **Server-side actions** Server-generated events or background updates won't automatically appear in the connected calendar. To sync those changes, the user must be signed in and running the client-side integration. ### Login and sync flow Follow these steps to set up and use the calendar integration correctly: 1. **User initiates sign-in** Start the sign-in process from the browser using the Mobiscroll Calendar Integration SDK. 2. **User authenticates and grants permissions** The user logs in and accepts the requested calendar permissions. 3. **Connection established** Once authenticated, Mobiscroll can read and write events between your app and the connected calendar — as long as the user is active in the browser. 4. **Sync while the user is active** Event synchronization happens only while the user is logged in and the client-side code is running. 5. **Next sync also requires presence** Each new synchronization (for example, when fetching updated events or pushing new ones) requires the user to be logged in and active in the app. Calling the `init` function will do the necessary initializations for the third party. For this step you need to use an API key and a client ID. After the `init`, you can sign in, list your calendars and events and create, update or delete the events on the calendars you have permission to. ```js @Component({...}) export class MyComponent implements OnInit { myEvents: MbscCalendarEvent[] = []; ngOnInit() { // init google client googleCalendarSync.init({ apiKey: 'YOUR_API_KEY', clientId: 'YOUR_CLIENT_ID', onSignedIn: () => { googleCalendarSync.getEvents( ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'], new Date(2022, 1, 1), new Date(2022, 3, 0) ).then((events) => { this.myEvents = events; }); }, onSignedOut: () => { this.myEvents = []; }, }); } } ``` ### Server side tokens By default the authentication happens entirely on the client side. However, since the introduction of the new [Google Identity Services](https://developers.google.com/identity/gsi/web), the received access token, which ensures access to the user's calendars, is only valid for an hour. After expiry, the user will be prompted again for consent. You can refresh an access token without prompting the user for permission, but this needs to be done server side. To enable this, in the init config object set the auth option to `'server'`, and specify the `authUrl` and `refreshUrl` pointing to your server endpoints. The `authUrl` endpoint will receive a POST request, containing a unique authorization code. To exchange an authorization code for an access token, send a POST request to the https://oauth2.googleapis.com/token endpoint and set the following parameters: * `client_id` - The client ID obtained from the Google API Console Credentials page. * `client_secret` - The client secret obtained from the Google API Console Credentials page. * `code` - The received authorization code. * `grant_type` - This field's value must be set to `authorization_code`. * `redirect_uri` - This field's value must be set to `postmessage`. ``` title="A sample request" POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& client_secret=your_client_secret& redirect_uri=postmessage& grant_type=authorization_code ``` ``` title="A sample response" { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3599, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" } ``` Return the received response from the request. The `refreshUrl` endpoint will also receive a POST request, containing the refresh token, received earlier. To refresh an access token, send a POST request to the https://oauth2.googleapis.com/token endpoint and set the following parameters: * `client_id` - The client ID obtained from the Google API Console Credentials page. * `client_secret` - The client secret obtained from the Google API Console Credentials page. * `refresh_token` - The received refresh token. * `grant_type` - This field's value must be set to `refresh_token`. ``` title="A sample request" POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=your_refresh_token& grant_type=refresh_token ``` ``` title="A sample response" { "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3599, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned" } ``` Return the received response from the request. #### Complete example A complete example with Node.js, ASP.NET and PHP **Node.js** ```js // Client googleCalendarSync.init({ auth: 'server', authUrl: 'http://example.com/auth', clientId: 'YOUR_CLIENT_ID', refreshUrl: 'http://example.com/refresh', }); // Server const http = require('http'); const https = require('https'); const YOUR_CLIENT_ID = 'YOUR_CLIENT_ID'; const YOUR_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'; function getToken(type, codeOrToken, callback) { const postData = 'client_id=' + YOUR_CLIENT_ID + '&' + 'client_secret=' + YOUR_CLIENT_SECRET + '&' + (type === 'refresh' ? 'grant_type=refresh_token&' + 'refresh_token=' + codeOrToken : 'grant_type=authorization_code&' + 'code=' + codeOrToken + '&' + 'redirect_uri=postmessage&' + 'code_verifier=' ) const postOptions = { host: 'oauth2.googleapis.com', port: '443', path: '/token', method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Content-Length': Buffer.byteLength(postData) } }; const postReq = https.request(postOptions, function (response) { response.setEncoding('utf8'); response.on('data', d => { callback(d); }); }); postReq.on('error', (error) => { console.log(error) }); // Post the request with data postReq.write(postData); postReq.end(); } function getPostData(req, callback) { let body = ''; req.on('data', (data) => { body += data; }); req.on('end', () => { const parsed = new URLSearchParams(body); const data = {} for (const pair of parsed.entries()) { data[pair[0]] = pair[1]; } callback(data); }); } function checkCSRF(req, res) { // Check if CSRF header is present if (req.headers['x-requested-with'] === 'XmlHttpRequest') { return true; } // Otherwise end the request res.statusCode = 500; res.end(); return false; } function sendResponse(res, data) { // Set the headers in case of CORS request res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With'); // Send data res.end(data); } const server = http.createServer(function (req, res) { if (req.method === 'OPTIONS') { // Handle preflight request (in case of CORS request) res.setHeader('Access-Control-Allow-Origin', '*'); // Use your own domain instead of the '*' res.setHeader('Access-Control-Allow-Headers', 'X-Requested-With'); res.end(); } else if (req.url.startsWith('/auth')) { // Handle auth if (checkCSRF(req, res)) { getPostData(req, (data) => { // Exchange auth code to access token (on sign in) getToken('auth', data.code, (token) => { sendResponse(res, token); }); }); } } else if (req.url.startsWith('/refresh')) { // Handle refresh if (checkCSRF(req, res)) { getPostData(req, (data) => { // Exchange refresh token to access token (on access token expiry) getToken('refresh', data.refresh_token, (token) => { sendResponse(res, token); }); }); } } }); server.listen(8080); ``` **ASP.NET** ```csharp class HttpServer { public static HttpListener listener; public static string url = "http://localhost:8080/"; private static readonly HttpClient client = new HttpClient(); public static Dictionary GetKeyValuePairs(string data) { return data.Split('&') .Select(value => value.Split('=')) .ToDictionary(pair => pair[0], pair => pair[1]); } public static void SendResponse(HttpListenerRequest request, HttpListenerResponse resp, string type) { if (!request.HasEntityBody) { resp.Close(); } Stream body = request.InputStream; StreamReader reader = new StreamReader(body, request.ContentEncoding); string codeOrToken = type == "auth" ? GetKeyValuePairs(reader.ReadToEnd())["code"] : GetKeyValuePairs(reader.ReadToEnd())["refresh_token"]; string postData = "client_id=" + YOUR_CLIENT_ID + "&" + "client_secret=" + YOUR_CLIENT_SECRET + "&" + (type == "refresh" ? "grant_type=refresh_token&" + "refresh_token=" + codeOrToken : "grant_type=authorization_code&" + "code=" + codeOrToken + "&" + "redirect_uri=postmessage&" + "code_verifier="); // Set the headers in case of CORS request resp.AppendHeader("Access-Control-Allow-Origin", "*"); resp.AppendHeader("Access-Control-Allow-Headers", "X-Requested-With"); // Post the request with data FormUrlEncodedContent content = new FormUrlEncodedContent(GetKeyValuePairs(postData)); HttpResponseMessage response = client.PostAsync("https://oauth2.googleapis.com/token", content).Result; if (response.IsSuccessStatusCode) { HttpContent responseContent = response.Content; string responseString = responseContent.ReadAsStringAsync().Result; byte[] buffer = Encoding.UTF8.GetBytes(responseString); // Get a response stream and write the response to it resp.ContentLength64 = buffer.Length; Stream output = resp.OutputStream; output.Write(buffer, 0, buffer.Length); output.Close(); } else { Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase); } resp.Close(); } public static bool CheckCSRF(HttpListenerRequest req, HttpListenerResponse resp) { // Check if CSRF header is present if (req.Headers["x-requested-with"] == "XmlHttpRequest") { return true; } // Otherwise end the request resp.StatusCode = 500; resp.Close(); return false; } public static async Task HandleIncomingConnections() { bool runServer = true; // Handling requests while (runServer) { HttpListenerContext ctx = await listener.GetContextAsync(); HttpListenerRequest req = ctx.Request; HttpListenerResponse resp = ctx.Response; if (req.HttpMethod == "OPTIONS") { // Handle preflight request (in case of CORS request) resp.AppendHeader("Access-Control-Allow-Origin", "*"); // Use your own domain instead of the '*' resp.AppendHeader("Access-Control-Allow-Headers", "X-Requested-With"); resp.Close(); } else if (req.Url.ToString().Contains("/auth")) { // Handle auth if (CheckCSRF(req, resp)) { SendResponse(req, resp, "auth"); } } else if (req.Url.ToString().Contains("/refresh")) { // Handle refresh if (CheckCSRF(req, resp)) { SendResponse(req, resp, "refresh"); } } } } public static void Main() { // Create a Http server and start listening for incoming connections listener = new HttpListener(); listener.Prefixes.Add("http://localhost:8080/"); listener.Start(); // Handle requests Task listenTask = HandleIncomingConnections(); listenTask.GetAwaiter().GetResult(); // Close the listener listener.Close(); } } ``` **PHP** ```php function checkCSRF() { // Check if CSRF header is present if ($_SERVER['HTTP_X_REQUESTED_WITH'] === 'XmlHttpRequest') { return true; } // Otherwise end the request header("HTTP/1.1 500 Internal Server Error"); return false; } function sendResponse($type) { // Set the headers in case of CORS request header('Access-Control-Allow-Origin: *'); header('Access-Control-Allow-Headers: X-Requested-With'); // The data you want to send via POST $post_data = [ "client_id" => $YOUR_CLIENT_ID, "client_secret" => $YOUR_CLIENT_SECRET, "grant_type" => $type === 'refresh' ? "refresh_token" : "authorization_code", "refresh_token" => $type === 'refresh' ? $_POST['refresh_token'] : "", "code" => $type === 'refresh' ? "" : $_POST['code'], "redirect_uri" => "postmessage", "code_verifier" => "" ]; // url-ify the data for the POST $data_string = http_build_query($post_data); // Open connection $ch = curl_init(); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/x-www-form-urlencoded', 'Content-Length: ' . strlen($data_string), )); // Set the url, number of POST vars, POST data curl_setopt($ch, CURLOPT_URL, "https://oauth2.googleapis.com/token"); curl_setopt($ch, CURLOPT_PORT, 443); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); // SSL options are set for testing purposes curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); // So that curl_exec returns the contents of the cURL; rather than echoing it curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Execute post $result = curl_exec($ch); if (curl_errno($ch)) { print curl_error($ch); } echo $result; curl_close($ch); } if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { // Handle preflight request (in case of CORS request) header('Access-Control-Allow-Origin: *'); // Use your own domain instead of the '*' header('Access-Control-Allow-Headers: X-Requested-With'); } else if (htmlspecialchars($_GET["action"]) === 'auth') { // Handle auth if (checkCSRF()) { sendResponse('auth'); } } else if (htmlspecialchars($_GET["action"]) === 'refresh') { // Handle refresh if (checkCSRF()) { sendResponse('refresh'); } } ``` ### API Configuration options ### apiKey string The API Key obtained from the Google API Console Credentials page. ### auth "server" | "client" When set to `'server'`, server-side endpoints must be implemented to get the auth access token from Google. ### authUrl string Server side endpoint for receiving an access token from Google on sign in, when the `auth` option is set to `'server'`. ### clientId string The client ID obtained from the Google API Console Credentials page. ### gapi any The gapi object, if already loaded. If not specified, the library will load it. ### gis any The Google Identity Services client library, if already loaded. If not specified, the library will load it. ### refreshUrl string Server side endpoint for receiving a new access token from Google on expiry, when the `auth` option is set to `'server'`. ### scopes string Specify custom scopes for Google authentication. The default scopes are `'https://www.googleapis.com/auth/calendar.events.public.readonly https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events.owned'` ### timezone string If specified, the event dates will be returned in this timezone. ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) The timezone plugin, needed if timezone is specified. The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - Events ### onInit () => void Callback executed when the library is initialized and ready to use. ### onSignedIn () => void Callback executed when the user signed in. ### onSignedOut () => void Callback executed when the user signed out. Methods ### addEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (addedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Adds an event to the specified calendar. ```js title="Example usage" googleCalendarSync.addEvent( 'MY_CALENDAR_ID', { start: new Date(2022, 1, 15, 12), end: new Date(2022, 1, 16, 14), title: 'My new event', googleEvent: { description: 'My new event description' } }); ``` Parameters: - calendarId - The ID of the calendar - event - The event to add. You can pass Google specific event properties through the `googleEvent` property. The rest of custom properties will be passed to the `extendedProperties` field. - callback - Callback function which is executed when the request is complete. Receives the added event. ### deleteEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (deletedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Removes an event in the specified calendar. Parameters: - calendarId - The ID of the calendar - event - The event to delete - callback - Callback function which is executed then the request is complete. Receives the deleted event. ### getCalendars (callback: (calendars: Array) => void ) => Promise Queries the available calendars of the signed in user. Calls the callback function, if specified. Parameters: - callback - A callback function to call with the calendars as parameters, when the query finished. ### getEvents (calendarIds: string | Array, start: Date, end: Date, callback: (events: Array<[MbscCalendarEvent](#type-MbscCalendarEvent)>) => void ) => Promise Queries the events of the specified calendars between two dates. Parameters: - calendarIds - Array of the calendar IDs. - start - Start date of the specified interval. - end - End date of the specified interval. - callback - Callback function which is executed then the request is complete. Receives the list of events as parameter. ### init (config: MbscGoogleCalendarSyncConfig) => void Makes the necessary initializations for the 3rd party. Triggers the `onInit` event when the initialization is ready, if specified. Parameters: - config - The configuration object for the calendar integration ### isSignedIn () => boolean Checks if the user is signed in or not. ### signIn () => Promise If the user is not signed in, starts the sign in flow. On success, triggers the `onSignedIn` event. ### signOut () => Promise If the user is signed in, signs out. On success triggers the `onSignedOut` event. ### updateEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (updatedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Updates an event in the specified calendar. ```js title="Example usage" googleCalendarSync.updateEvent( 'MY_CALENDAR_ID', { start: new Date(2022, 1, 20, 10), end: new Date(2022, 1, 11, 15), title: 'My updated event', id: 1, googleEvent: { description: 'My updated event description' } }); ``` Parameters: - calendarId - The ID of the calendar - event - The event to update. You can pass Google specific event properties through the `googleEvent` property. The rest of custom properties will be passed to the `extendedProperties` field. - callback - Callback function which is executed then the request is complete. Receives the updated event. ## Outlook calendar integration The Outlook Calendar Integration is a part of the third party calendar integrations plugin that manages the synchronization with your Outlook calendar services. ### Outlook calendars Calling the `init` function will do the necessary initializations for the third party. For this step you need to use a [client ID](https://docs.microsoft.com/en-us/graph/auth-v2-user). After the init, you can sign in, list your calendars and events and create, update or delete the events on the calendars you have permission to. ```js @Component({...}) export class MyComponent implements OnInit { myEvents: MbscCalendarEvent[] = []; ngOnInit() { // init outlook client outlookCalendarSync.init({ clientId: 'YOUR_CLIENT_ID', onSignedIn: () => { outlookCalendarSync.getEvents( ['MY_FIRST_CALENDAR_ID', 'MY_SECOND_CALENDAR_ID'], new Date(2022, 1, 1), new Date(2022, 3, 0) ).then((events) => { this.myEvents = events; }); }, onSignedOut: () => { this.myEvents = []; }, }); } } ``` ### API Configuration options ### clientId string The client ID obtained from the Outlook web app. ### msal any The Microsoft Authentication Library, if already loaded. If not specified, the library will load it. ### msalClient any The instance of the client application, if already loaded. If not specified, the library will load it. ### pageSize number The maximum number of events to retrieve with one request. Default value is `1000`. ### redirectUri string The location where the authorization server sends the user once the app has been successfully authorized. Default value is `'http://localhost:3000'`. ### timezone string If specified, the event dates will be returned in this timezone. ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) The timezone plugin, needed if timezone is specified. The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - Events ### onInit () => void Callback executed when the library is initialized and ready to use. ### onSignedIn () => void Callback executed when the user signed in. ### onSignedOut () => void Callback executed when the user signed out. Methods ### addEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (addedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Adds an event to the specified calendar. ```js title="Example usage" outlookCalendarSync.addEvent( 'MY_CALENDAR_ID', { start: new Date(2022, 1, 15, 12), end: new Date(2022, 1, 16, 14), title: 'My new event', outlookEvent: { isReminderOn: true, } }); ``` Parameters: - calendarId - The ID of the calendar - event - The event to add. You can pass Outlook specific event properties through the `outlookEvent` property. - callback - Callback function which is executed when the request is complete. Receives the added event. ### deleteEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (deletedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Removes an event in the specified calendar. Parameters: - calendarId - The ID of the calendar - event - The event to delete - callback - Callback function which is executed then the request is complete. Receives the deleted event. ### getCalendars (callback: (calendars: Array) => void ) => Promise Queries the available calendars of the signed in user. Calls the callback function, if specified. Parameters: - callback - A callback function to call with the calendars as parameters, when the query finished. ### getEvents (calendarIds: string | Array, start: Date, end: Date, callback: (events: Array<[MbscCalendarEvent](#type-MbscCalendarEvent)>) => void ) => Promise Queries the events of the specified calendars between two dates. Parameters: - calendarIds - Array of the calendar IDs. - start - Start date of the specified interval. - end - End date of the specified interval. - callback - Callback function which is executed then the request is complete. Receives the list of events as parameter. ### init (config: MbscOutlookCalendarSyncConfig) => void Makes the necessary initializations for the 3rd party. Triggers the `onInit` event when the initialization is ready, if specified. Parameters: - config - The configuration object for the calendar integration ### isSignedIn () => boolean Checks if the user is signed in or not. ### signIn () => Promise If the user is not signed in, starts the sign in flow. On success, triggers the `onSignedIn` event. ### signOut () => Promise If the user is signed in, signs out. On success triggers the `onSignedOut` event. ### updateEvent (calendarId: string, event: [MbscCalendarEvent](#type-MbscCalendarEvent), callback: (updatedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)) => void ) => Promise Updates an event in the specified calendar. ```js title="Example usage" outlookCalendarSync.updateEvent( 'MY_CALENDAR_ID', { start: new Date(2022, 1, 20, 10), end: new Date(2022, 1, 11, 15), title: 'My updated event', id: 1, outlookEvent: { isReminderOn: false, } }); ``` Parameters: - calendarId - The ID of the calendar - event - The event to update. You can pass Outlook specific event properties through the `outlookEvent` property. - callback - Callback function which is executed when the request is complete. Receives the updated event. --- ## Working with recurring events ## Querying recurring events The Calendar Integration when queries recurring events from the Google or the Outlook calendar, it will receive individual event occurences for the given period of time. So every event arrives as an individual event. The Mobiscroll Eventcalendar won't know about the recurrence in these cases. To tell whether these events are part of a recurring set or not, you need to check the properties of the event. 1. The google event has the `event.googleEvent.recurringEventId` field set in case of recurring events - which is the ID of the original recurring event. 2. The outlook event has the `event.outlookEvent.type` field set to `occurrence` in case of a recurring events, otherwise the type is `singleInstance` ## Creating recurring events When you want to create a recurring event through the Mobiscroll Eventcalendar, you can do so by setting the `recurrence` field to the RRULE before sending it to the Google or Outlook calendar. For example: ```html title='Create a recurring event in a Google calendar' ``` ```ts @Component({...}) export class MyComponent { // ... myHandler(args) { const event = args.event; event.googleEvent = { recurrence: ['RRULE:FREQ=WEEKLY;BYDAY=TH;COUNT=4'], // ...other google specific properties } // then send it to Google googleCalendarSync.addEvent('MY_CALENDAR_ID', event); } // ... } ``` When this is done, the [getEvents](./calendar-integrations.md#method-google-getEvents) function will return the individual occurences of the recurring set, the same way it is described [above](#querying-recurring-events). ## Updating a single recurring instance To update a single occurence of a recurring event, you can drag it on the Eventcalendar UI (when the [dragToMove](../api#opt-dragToMove) option is enabled). Since the events you get from the calendar integrations are individual occurences, updating one will not update the whole set of recurring events. So updating a single instance of the recurring set is the default behavior. ## Deleting a recurring instance As mentioned above in the [query section](#querying-recurring-events), by default you get the recurring event occurences as single individual events, when querying events from Google or Outlook calendars. Deleting a single event instance will only remove that single instance from the set. ## Updating a recurring event To update the whole recurring set or parts of it (for example: this and following events), you will need to use direct API calls to the Google or Outlook calendars themselves, since this is not supported by the Calendar Integrations currently. Here's a link for a more detailed description on [how to update recurring events with the Google Calendars](https://developers.google.com/calendar/api/guides/recurringevents). For Outlook recurring events check out the [Outlook schedule recurring events guide](https://learn.microsoft.com/en-us/graph/outlook-schedule-recurring-events). --- ## Calendar Use the [Event Calendar](https://demo.mobiscroll.com/eventcalendar) as a traditional [month view](https://demo.mobiscroll.com/eventcalendar/desktop-month-view#) or combine it with an agenda as a [week view](https://demo.mobiscroll.com/agenda/daily-agenda-with-week-calendar#). The events can be rendered as [labels](https://demo.mobiscroll.com/eventcalendar/event-labels#) or in a [popover](https://demo.mobiscroll.com/eventcalendar/event-popover#) that is shown on day click. ## Overview The Calendar view supports everything from [single to multiple week views](https://demo.mobiscroll.com/eventcalendar/month-week-view#) all the way to [month grids](https://demo.mobiscroll.com/eventcalendar/quarter-year-view#) with various ways to render events. The capabilities like [recurring events](/javascript/core-concepts/recurrence), [all-day, multi-day events](#opt-data), [responsiveness](#responsiveness) are supported by the Event Calendar. ![Event Calendar overview](/img/event-calendar-overview.png) ## Showing the Calendar ### View combination The four views - [scheduler](./scheduler), [calendar](./calendar), [timeline](./timeline), [agenda](./agenda) - can be used alone or combined with each-other to create the perfect user experience on mobile, desktop and on everything in-between. For example, you can choose to [render an agenda below the calendar](https://demo.mobiscroll.com/agenda/daily-agenda-with-week-calendar#) broken up into days ordered chronologically. The view option will look like the following: ```html title='Weekly Calendar combined with Daily Agenda' ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { type: 'week' }, agenda: { type: 'day' } }; } ``` ### Configuring the view The Calendar view can be configured through the `view` option. Below are listed the `calendar` object properties which can help you fine-tune this view. ```html title="Example" ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { labels: true, type: 'week', size: 2 } }; } ``` ### count boolean If `true`, it will display the number of events on the days with events. **Default value**: `false` ### eventDisplay "fill" | "exact" Specifies how events are displayed. - If set to `'exact'`, events are displayed according to their start and end times. - If set to `'fill'`, events cover the entire day. **Default value**: `'fill'` ### labels number | boolean | "all" Enable displaying events as labels on calendar days. - If set to `true`, events will be displayed in the available space. If there are more events for a day, than the available space, a label with "more" text will be displayed, which opens a popover showing all the events for the given day. To fit more events on a day, set the calendar height to an appropriate value, using the [height](#opt-height) option. - If set to `'all'`, all the events will be displayed in the calendar cell and the row height will auto-expand based on the displayed events. The view will become scrollable if the rows overflow the available height. - Specify a number to set how many events will be displayed before the "more" button in a calendar cell. The row height will auto expand until the labels count reaches the given number and after that the "x more" button will be displayed. In the case when only one event should go in the "more" popup, that event will be displayed in the place of the "x more" button. **Default value**: `true` ### outerDays boolean Show or hide days from previous and next months. Hiding only works for type: 'month'. **Default value**: `false` ### popover boolean Enable popover on days containing events. If not explicitly defined, the popover will not show up if an agenda view is also displayed. If event labels are displayed, the popover will only show up for days where the labels do not fit on the calendar, and a "more" label is present. **Default value**: `undefined` ### popoverClass string A CSS class that's added to the popover element. Can be used to customize the styling of the popover on a calendar basis. ### scroll "horizontal" | "vertical" Specifies the direction of the calendar scroll. Can be 'horizontal' or 'vertical' **Default value**: `'horizontal'` ### size number Specifies the number of displayed weeks/months. **Default value**: `1` ### type "month" | "year" | "week" Specifies the calendar type **Default value**: `'month'` ### weekNumbers boolean Show or hide week numbers. **Default value**: `false` ## Responsiveness The Event Calendar is [fully responsive](https://demo.mobiscroll.com/eventcalendar/responsive-month-view). It adapts to the available space and fills the screen to look good everywhere. While you don't have to worry about the width the height can be manually adjusted with the [height](#opt-height) option. This specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. Use the [responsive](#opt-responsive) option to configure how the calendar behaves on different sized screens. The responsive option is equipped with five breakpoints: - `xsmall` (up to 575px), - `small` (up to 767px), - `medium` (up to 991px), - `large` (up to 1199px), - `xlarge` (from 1200px). Also, custom breakpoints can be added if necessary: - `my-custom-breakpoint: { breakpoint: 600 }` (from 600px up to the next breakpoint). :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries. ::: ```html title='Responsive configuration with the view option' ``` ```ts @Component({...}) export class MyComponent { responsiveSettings: MbscEventcalendarOptions = { xsmall: { view: { calendar: { type: 'week' }, agenda: { type: 'day' } } }, custom: { // Custom breakpoint, you can use multiple if needed, but each must have a unique name. breakpoint: 600, view: { calendar: { labels: true }} } } } ``` ![Event Calendar responsive behavior](/img/event-calendar-responsive.gif) ## Templating The display of Calendar can be customized with different [templating functions](#templates). ### The event label and their content There are two approaches you can take: - Customize the label contents, that appears on the calendar - for this you will want to use the [labelContentTemplate](#template-labelContentTemplate) option. The Event Calendar will take care of styling and you can focus on what you show inside of the label. - Customize the labels that appear on the Calendar view - use the [labelTemplate](#template-labelTemplate) option. The Event Calendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. Check out how you can style labels and their content in [this example](https://demo.mobiscroll.com/angular/eventcalendar/customize-label-look-and-feel#) or just play with the slider below to see the differences. ### The event in popover and their content The events can be customized in two ways: - Customize the event content that appears on the popover - by using the [eventContentTemplate](#template-eventContentTemplate) option. The Event Calendar will take care of styling and you can focus on what you show inside of the event. - Customize the events that appear on the popover - with the [eventTemplate](#template-eventTemplate) option. It should return the markup of the event. The Event Calendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. Check out how you can style events and their content in [this example](https://demo.mobiscroll.com/angular/eventcalendar/customize-event-popover#) or just play with the slider below to see the differences. ### The event calendar header Customize how the header of the Event Calendar looks and how the components are arranged with the [headerTemplate](#template-headerTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar. While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's [building blocks](/angular/eventcalendar/templating#header-templating). These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. Check out how you can style the header in [this example](https://demo.mobiscroll.com/angular/eventcalendar/customizing-header#) or just play with the slider below to see the differences. ## Event order The rendered event order is determined by the following two concepts: 1. Event data order 2. Event layout The combination of these concepts results in the final rendered event order. ### Event data order The sequence in which events are processed before being passed to the layout algorithm. The default ordering rules are as follows: 1. All-day events are placed at the top. 2. Non-all-day events follow, sorted by their start times. 3. Events with the same start time are further ordered alphabetically by their titles. This default order can be modified using the `order` property in the event [event data](#opt-data). The order property takes precedence over the default rules. If two events have the same order value, the default rules apply. For more complex ordering requirements, the [eventOrder](#opt-eventOrder) option can be used. This option accepts a function that compares two events and returns an order (-1 or 1). ### Event layout The event layout process determines the visual positioning and dimensions of events. This is a built-in functionality and cannot be altered externally. The layout algorithm processes the sorted event list and calculates each event's position and size. The algorithm follows these steps: 1. The first event is placed in the first position of the event track. 2. If two or more events overlap in their start/end times, the later event is placed in the next event track, positioned below to the previous event. 3. If a subsequent event does not overlap with any already added events, it is placed back in the first event track. 4. This process continues until all events are positioned within their respective rows. ## API Here is a comprehensive list of all the specific options, events and methods of the Event Calendar view. ### Options Explore the following API options that help you easily configure the Event Calendar. ### actionableEvents boolean Specifies if the events on the agenda and inside the calendar popover are actionable or not. If actionable, the event items will have hover and active states, and pointer cursor. Set to `false` when custom event rendering is used and the event list items contain other actionable elements, e.g. buttons. **Default value**: `true` ### clickToCreate boolean | "double" | "single" Enable new event creation on click. If `true` or `'double'`, a new event will be created only with a double click and with the `'single'` value the event will be created instantly with a single click. This option will only work on desktop environment where mouse events are fired. It will also allow deleting of the focused events using the Delete or Backspace key. In touch environment a long tap should be used to create a new event and it is controlled by the [dragToCreate](#opt-dragToCreate) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### colors Array<[MbscCalendarColor](#type-MbscCalendarColor)> Specifies the color for certain dates or date ranges on the calendar. The [`MbscCalendarColor`](#type-MbscCalendarColor) type has the following properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The colored range will be considered all-day if: - the `allDay` property is explicitly set. - the `start` / `end` properties are not specified, only the `date`. ::: :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The colors can be combined with the [labels](#opt-labels) or [marked](#opt-marked) options. ::: ```js [ { date: new Date(2020, 2, 23), background: 'pink' }, { date: new Date(2020, 2, 24), background: 'green' }, { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } }, { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } } ] ``` **Default value**: `undefined` ### context string | HTMLElement The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> The events for the Eventcalendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The event objects may have additional custom properties as well. The custom properties are not used by the event calendar, but they are kept and will be available anywhere the event objects are used. E.g. the [onEventClick](#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ::: :::info Use the [getEvents](#method-getEvents) method to get the events between two dates. ::: ```js data: [ { start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, color: 'red' }, { title: 'Work project', recurring: { repeat: 'daily', until: '2021-04-01' }, recurringException: ['2021-03-15', '2021-03-25'], recurringExceptionRule: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelectedDate [MbscDateType](#type-MbscDateType) Specifies the initial selected date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### dragInTime boolean If `false`, the events will not be moveable in time. In case of the scheduler and timeline views events events can still be moved between resources. To control movement between resources, use the [dragBetweenResources](#opt-dragBetweenResources) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragToCreate boolean If `true`, dragging on an empty cell will create a new event. It will also allow deleting of the focused events using the Delete or Backspace key. The title of the new event can be specified with the [newEventText](#opt-newEventText) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### dragToMove boolean If `true`, the events will be moveable. **Default value**: `undefined` ### dragToResize boolean If `true`, the events will be resizable. **Default value**: `undefined` ### eventDelete boolean Enables or disables event deletion. When `true`, the focused event will be deleted on pressing the Delete or Backspace keys on the keyboard. By default the event deletion depends on the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. If either of those are `true`, and no `eventDelete` option is set, then event deletion is also enabled, otherwise not. **Default value**: `undefined` ### eventOrder (event1: [MbscCalendarEvent](#type-MbscCalendarEvent), event2: [MbscCalendarEvent](#type-MbscCalendarEvent)) => number Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1. If not specified, the default order is: - all day events - rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title **Default value**: `undefined` ### eventOverlap boolean If `false`, the events cannot overlap. **Default value**: `true` ### exclusiveEndDates boolean If `true`, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. `end: '2021-07-03T00:00'` means that the event ends on 2nd of July and will not be displayed on 3rd of July. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: ### extendDefaultEvent (args: MbscNewEventData) => void | [MbscCalendarEvent](#type-MbscCalendarEvent) Use this option to set properties to the new event created with click or drag. The event creation is handled by the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. It takes a function that should return the properties for the new event. The argument object passed to this function has the following properties: - `start`: *Date* - The date when the newly created event will start. - `resource`: *string | number* - The id of the resource where the event creation started. ```js extendDefaultEvent: (args) => { return { color: args.resource === 'admin' ? 'green' : 'red', title: 'My event', }; } ``` **Default value**: `undefined` ### externalDrag boolean If `true`, external drag & drop is allowed and events can be dragged outside of the component view. **Default value**: `undefined` ### externalDrop boolean If `true`, external events can be dragged into the view. **Default value**: `undefined` ### height string | number Sets the height of the component. The height of the calendar view impacts the number of labels that fit into a table cell. A "show more" label will be displayed for events that don't fit. **Default value**: `undefined` ### immutableData boolean If `true`, the Eventcalendar will work in immutable mode. In this mode the component won't update the data directly, only fire the necessary lifecycle events, where the original data can be updated manually. **Default value**: `undefined` ### invalid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the invalid values. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the invalid range is all day or not. - `start`: *Date | string | object* - Start of the invalid range. - `end`: *Date, string | object* - End of the invalid range. - `recurring`: *string | object* - Recurrence rule for recurring invalid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - Specifies the [resource](#opt-resources) ids for the invalid range. The invalid range will be displayed only in the specified resource. If there is no resource defined, the invalid range will be displayed in every resource. - `slot`: *string | number* - Specifies the [slot](#opt-slots) id for the invalid range. The invalid range will be displayed only in the specified slot. If there is no slot defined, the invalid range will be displayed in every slot. - `title`: *string* - Text which will be displayed for the invalid range. Only applicable for the timeline and scheduler views. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### invalidateEvent "strict" | "start-end" Specifies how to validate events against [invalid](#opt-invalid) ranges on create/move/resize: - `'strict'` - The event cannot intersect with an invalid range at all. - `'start-end' - The event start and end cannot be inside an invalid range. **Default value**: `'strict'` ### labels Array<[MbscCalendarLabel](#type-MbscCalendarLabel)> Specifies labels for calendar days. The [`MbscCalendarLabel`](#type-MbscCalendarLabel) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The labels can be combined with the [colors](#opt-colors) option. ::: ```js [ { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), text: 'Conference', color: 'red' }, { text: 'Christmas', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: undefined ### marked Array<[MbscCalendarMarked](#type-MbscCalendarMarked)> Mark certain dates on the calendar. An array containing dates, or objects with the following properties: The [`MbscCalendarMarked`](#type-MbscCalendarMarked) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The marked days can be combined with the [colors](#opt-colors) option. ::: ```js [ new Date(2020, 2, 15), new Date(2020, 2, 22), { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), color: 'red' }, { color: 'green', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: `undefined` ### max [MbscDateType](#type-MbscDateType) Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the [invalid](#opt-invalid) option with daily recurrence starting from the specific date. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the [invalid](#opt-invalid) option with daily recurrence until the specific date. **Default value**: `undefined` ### modules Array Additional modules can be added to the eventcalendar. The option receives an array of module objects. For example, the print module can be added through this option. ```js // import the print module // later on, add it to the modules array: modules: [print] ``` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed. If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01. It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is `01/16/2024`, the pages are calculated from this date, so the initial page will contain `[01/16/2024, 01/16/2024, 01/17/2024]`, the next page `[01/18/2024, 01/19/2024, 01/20/2024]` and so on. In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day. Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the [selectedDate](#opt-selectedDate) option. **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### selectMultipleEvents boolean When `true`, enables multiple event selection on the calendar. **Default value**: `false` ### selectedDate [MbscDateType](#type-MbscDateType) Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the [refDate](#opt-refDate) option. You also need to pass a handler for the [onSelectedDateChange](#event-onSelectedDateChange) event to update the selected date when the date is changed from the calendar. **Default value**: `undefined` ### selectedEvents Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Specifies the selected events on the calendar. The [onSelectedEventsChange](#event-onSelectedEventsChange) event will be fired when the selected events change from the calendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. **Default value**: `undefined` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showControls boolean Show or hide the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker. **Default value**: `true` ### showEventBuffer boolean If `true`, it will display the event buffers defined in the [event data](#opt-data). **Default value**: `true` ### showEventTooltip boolean If `false`, it will hide the native tooltip that shows up when hovering over an event. **Default value**: `true` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### width string | number Sets the width of the component. **Default value**: `undefined` ### Events The Event Calendar ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onCellClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event object has the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellDoubleClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is double-clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellHoverIn (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered day. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellHoverOut (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered cell. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellRightClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is right-clicked on the calendar, scheduler, or timeline grid . Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onEventClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventCreate (args: MbscEventCreateEvent, inst: EventcalendarBase) => void Triggered when an event is about to create and it is not yet rendered on its final position. Event creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The newly created event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being created. - inst - The component instance. ### onEventCreateFailed (args: MbscEventCreateFailedEvent, inst: EventcalendarBase) => void Triggered when an event creation failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - inst - The component instance. ### onEventCreated (args: MbscEventCreatedEvent, inst: EventcalendarBase) => void Triggered when an event is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - `target`: *HTMLElement* - The DOM element of the created event. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - inst - The component instance. ### onEventDelete (args: MbscEventDeleteEvent, inst: EventcalendarBase) => void Triggered when an event is about to be deleted and it is not yet removed from the view. Event deletion can be performed with delete and backspace button on an active event. Deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from of the keydown action. - `event`: *MbscCalendarEvent* - The event being deleted. - `events`: *Array* - The events being deleted in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event is being deleted. - inst - The component instance. ### onEventDeleted (args: MbscEventDeletedEvent, inst: EventcalendarBase) => void Triggered when an event is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The deleted event. - `events`: *Array* - The deleted events in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event was deleted. - inst - The component instance. ### onEventDoubleClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is double-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicker, if [slots](#opt-slots) are set. - `slotObj`: *MbscResource* - The resource where the event was clicker, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventDragEnd (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has ended. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event was dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event was dragged. - inst - The component instance. ### onEventDragEnter (args: MbscEventDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragLeave (args: MbscEventDragEvent) => void Triggered when an event is dragged out form the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragStart (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has started. Parameters: - args - The event argument with the following properties: - `action`: *'create' | 'resize' | 'move'* - The user action which triggered the event. - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event is dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. - inst - The component instance. ### onEventHoverIn (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event is hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event is hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event is hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverOut (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event was hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventRightClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is right-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventUpdate (args: MbscEventUpdateEvent, inst: EventcalendarBase) => void Triggered when an event is about to update. Update can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `oldResource`: number | string - The id of the resource from which the event was dragged. - `oldResourceObj`: *MbscResource* - The resource from which the event was dragged. - `oldSlot`: number | string - The id of the slot from which the event was dragged. - `oldSlotObj`: *MbscSlot* - The slot from which the event was dragged. - `resource`: number | string - The id of the resource where the event was dropped. - `resourceObj`: *MbscResource* - The resource where the event was dropped. - `slot`: number | string - The id of the slot where the event was dropped. - `slotObj`: *MbscSlot* - The slot where the event was dropped. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being updated. - inst - The component instance. ### onEventUpdateFailed (args: MbscEventUpdateFailedEvent, inst: EventcalendarBase) => void Triggered when an event update failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - inst - The component instance. ### onEventUpdated (args: MbscEventUpdatedEvent, inst: EventcalendarBase) => void Triggered when an event is updated and is rendered in its new position. This is where you update the event in your database or persistent storage. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `resourceObj`: *MbscResource* - The resource where the event is updated, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is updated, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - `target`: *HTMLElement* - The DOM element of the updated event. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onLabelClick (args: MbscLabelClickEvent, inst: EventcalendarBase) => void Triggered when a label is clicked on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the label was clicked. - `domEvent`: *Event* - The DOM event of the click. - `label`: *MbscCalendarLabel* - The original object of the label which was clicked, `undefined` in case of the "more" label. - `labels`: *Array* - An array containing each label object for the given day. - `target`: *HTMLElement* - The DOM element of the label. - inst - The component instance. ### onPageChange (args: MbscPageChangeEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscPageLoadedEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscPageLoadingEvent, inst: EventcalendarBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onSelectedDateChange (args: MbscSelectedDateChangeEvent, inst: EventcalendarBase) => void Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows. You can use this event in conjunction with the [selectedDate](#opt-selectedDate) option to customize where the Eventcalendar should navigate. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The newly selected date. - inst - The component instance. ### onSelectedEventsChange (args: MbscSelectedEventsChangeEvent, inst: EventcalendarBase) => void Triggered when an event is selected or deselected on the UI, when [multiple event selection](#opt-selectMultipleEvents) is enabled. You can also select events programmatically using the [selectedEvents](#opt-selectedEvents) option. Parameters: - args - The event argument with the following properties: - `events`: *Array* - The selected events. - inst - The component instance. ### Localization The Event Calendar is fully localized. This covers date and time format, button copy, rtl and more. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### eventText string Text for the event word. **Default value**: `'event'` ### eventsText string Text for the events word (plural). **Default value**: `'events'` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### moreEventsPluralText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day, and there are more than one extra labels. The `{count}` inside the string will be replaced with the number of extra labels. When not specified, the [moreEventsText](#localization-moreEventsText) option will be used for both plural and singular form. **Default value**: `undefined` ### moreEventsText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day. The `{count}` inside the string will be replaced with the number of extra labels. Use the [moreEventsPluralText](#localization-moreEventsPluralText) as well, if the plural form is different. **Default value**: `'{count} more'` ### newEventText string Title for the newly created event with the [dragToCreate](#opt-dragToCreate) and the [clickToCreate](#opt-clickToCreate) action. **Default value**: `'New event'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### Templates The display of the Event Calendar can be customized with different templating functions. ### dayContentTemplate Customize the day cells content of the event calendar. The Eventcalendar will take care of the styling and you can focus on what you show beside the day number. If you are looking to fully customize the day (e.g. add custom hover effects) you will need to use the [dayTemplate](#template-dayTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. **Default value**: `undefined` ### dayTemplate Customize the day cells of the calendar view and the date header in case of scheduler and timeline views. If you are looking to customize only the day cells content and don't want to bother with the styling of the event, in case of calendar and scheduler views you can use the [dayContentTemplate](#template-dayContentTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. - `isActive`: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year **Default value**: `undefined` ### eventContentTemplate Template to customize the event content that appears on the agenda and the popover. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [eventTemplate](#template-eventTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### eventTemplate Template to customize the events that appear on the agenda and the popover. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [eventContentTemplate](#template-eventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. **Default value**: `undefined` ### headerTemplate Template to customize the header of the event calendar. You can use custom markup or components as well as the built in header components of the calendar. **Default value**: `undefined` ### labelContentTemplate Template to customize the label contents, that appears on the calendar. The Eventcalendar will take care of styling and you can focus on what you show inside of the label. If you are looking to fully customize the label (ex. add custom hover effects) you will need to use the [labelTemplate](#template-labelTemplate) option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. **Default value**: `undefined` ### labelTemplate Customize the labels that appear on the calendar view. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the label, you can use the [labelContentTemplate](#template-labelContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `original`: _MbscCalendarEvent_ - The original event object. Any custom property on the event can be accessed through this property. - `start`: _string_ - The formatted start time, if the event is not all day. **Default value**: `undefined` ### Types ### MbscCalendarColor Interface Properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscCalendarEvent Interface Properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. ### MbscCalendarInvalid Interface Properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### MbscCalendarLabel Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label ### MbscCalendarMarked Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscDateType string | Date | object ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscEventcalendarOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## CRUD ## Updating event properties The Eventcalendar is bound to an array of event objects as described in the [data binding](data-binding) section. To update a single event with new event data, it's not enough to update the particular event object. A new event array reference is also needed otherwise the change won't be picked up by the eventcalendar. ```ts title="Updating an event title" @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { type: "month" }, agenda: { type: "month" }, }; myEvents: MbscCalendarEvent[] = [ { id: 'id1' start: '2023-09-24', end: '2023-09-30', title: 'Short trip!'}, // highlight-next-line { id: 'id2' start: '2023-10-12', end: '2023-10-12', title: 'Birthday'}, { id: 'id3' start: '2023-12-24', end: '2023-12-26', title: 'X-mas'}, ]; editEvent(eventID: string) { // highlight-start const myNewArray = [...this.myEvents]; const index = myNewArray.findIndex((ev) => ev.id === eventID); myNewArray[index].title = 'My Birthday'; this.myEvents = myNewArray; // highlight-end } } ``` ```html Edit second event ``` The same concept can be used to add or delete a calendar event. Or to update any properties of an event with incoming data, regardless where the data comes from (outside of the eventcalendar), be it an edit form or an external API. ## Working with servers The Eventcalendar exposes a variety of [events](api#events) that are triggered on certain actions made on calendar events. These events can be used to send your data to your API or save it to a persistent storage. ### Event create To enable the creation of events on the Eventcalendar you can use the [`dragToCreate`](api#opt-dragToCreate) and the [`clickToCreate`](api#opt-clickToCreate) options (desktop browsers only). When an event is about to be created using click or drag on the Eventcalendar UI, the [`onEventCreate`](api#event-onEventCreate) event is fired. If not canceled by returning `false` a temporary event is created on the Eventcalendar followed by the [`onEventCreated`](api#event-onEventCreated). Any of these two events are passed the event properties that can be used to save the event to a persistent storage or to send it through an API. ```ts title="Save a new event through an API" @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { type: "month" }, agenda: { type: "month" }, }; myEvents: MbscCalendarEvent[] = []; saveEvent(args: MbscEventCreateEvent) { // highlight-start const eventToSave = args.event; // you can use whatever library you want instead of axios axios.post('/your-api', eventToSave); // highlight-end } } ``` ```html ``` ### Event update Similar to [event creation](#event-create) above, to enable event editing you can use the [`dragToResize`](api#opt-dragToResize) and [`dragToMove`](api#opt-dragToMove) options. When an event is about to be updated by dragging on the Eventcalendar UI, the [`onEventUpdate`](api#event-onEventUpdate) event is fired. If not canceled by returning `false` the calendar event is updated on the calendar. This update is followed by the [`onEventUpdated`](api#event-onEventUpdated). Any of these two events are passed the calendar event previous and new properties that can be used to save the event to a persistent storage or to send it through an API. ```ts title="Send an updated event through an API" @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: "week" }, }; myEvents: MbscCalendarEvent[] = [ { id: 'id1' start: '2023-09-24', end: '2023-09-30', title: 'Short trip!'}, ]; updateEvent(args: MbscEventUpdatedEvent) { // highlight-start const updatedEvent = args.event; // you can use whatever library you want instead of axios axios.post('/your-api', updatedEvent); // highlight-end } } ``` ```html ``` :::info When updating a recurring event from the UI (by dragging for example), the update won't affect all the occurences of the event. A single instance is updated from a set of occurences by adding an [exception to the rule](../core-concepts/recurrence#rule-exceptions) and creating another event with the changed properties. Adding this exception to the rule is an update to the event, so the [`onEventUpdate`](./api#event-onEventUpdate) and [`onEventUpdated`](./api#event-onEventUpdated) will be fired as expected. There will also be an [`onEventCreate`](./api#event-onEventCreate) and [`onEventCreated](./api#event-onEventCreated) event fired for the changed occurence, that is not be part of the recurring set anymore. ::: In case you would like to edit a recurring event, you can use the `updateRecurringEvent` helper function: ### updateRecurringEvent (originalRecurringEvent: [MbscCalendarEvent](#type-MbscCalendarEvent), oldEventOccurrence: [MbscCalendarEvent](#type-MbscCalendarEvent), newEvent: [MbscCalendarEvent](#type-MbscCalendarEvent), updatedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent), updateMode: "all" | "current" | "following", timezone: string, timezonePlugin: [MbscTimezonePlugin](#type-MbscTimezonePlugin)) => {newEvent: [MbscCalendarEvent](#type-MbscCalendarEvent) | null, updatedEvent: [MbscCalendarEvent](#type-MbscCalendarEvent)} Updates a recurring event, returns the updated and the new event. Parameters: - originalRecurringEvent - The original event to update. - oldEventOccurrence - The original event occurrence in case of & (what is dragged). - newEvent - The created even in case of & (where is dragged). - updatedEvent - The updated event from popup. - updateMode - The update type. ### Event delete When an event is selected on the Eventcalendar, hitting the `Delete` or `Backspace` button will delete the event. Just before the event is deleted, the [`onEventDelete`](./api#event-onEventDelete) event is fired. Returning `false` from the `onEventDelete` will prevent the delete from happening. If not prevented, there will be an [`onEventDeleted`](./api#event-onEventDeleted) event fired and the event will be removed from the Eventcalendar. Either one of these events can be used to send the deletion through an API. ```ts title="Notify a server of an event deletion" @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: "week" }, }; myEvents: MbscCalendarEvent[] = [ { id: 'id1' start: '2023-09-24', end: '2023-09-30', title: 'Short trip!'}, ]; deleteEvent(args: MbscEventDeletedEvent) { // highlight-start const theEvent = args.event; // you can use whatever library you want instead of axios axios.post('/your-api', theEvent); // highlight-end } } ``` ```html ``` :::caution When deleting a recurring event, there will not be an [`onEventDelete`](./api#event-onEventDelete) nor an [`onEventDeleted`](./api#event-onEventDeleted) event fired because the event is not deleted actually. A single instance is deleted from a set of occurences by adding an [exception to the rule](../core-concepts/recurrence#rule-exceptions). Adding this exception to the rule is an update to the event, so the [`onEventUpdate`](./api#event-onEventUpdate) and [`onEventUpdated`](./api#event-onEventUpdated) are fired instead of the delete. ::: --- ## Data binding { value: 'Local Data', level: 2, id: 'local-data'}, { value: 'Remote Data', level: 2, id: 'remote-data'}, { value: 'On demand loading', level: 2, id: 'on-demand-loading'} ]; The Eventcalendar accepts an array of event objects through the [`data`](api#opt-data) option of the component. The event array can be either a local static array, or populated on demand with remote requests. ## Event data structure The events of the Eventcalendar are specified as an array of event objects. The event object supports the following properties: - `id` _String, Number_ - A unique id for the event. If not specifed, the event will get a generated id. - `start` _Date, String, Object_ - Specifies the start of the event. - `end` _Date, String, Object_ - Specifies the end of the event. - `title` _String_ - The title of the event. - `color` _String_ - The color of the event. - `allDay` _Boolean_ - Specifies if the event is all day or not. - `editable` _Boolean_ - specify if an event is editable or not. Setting it to false disables drag & drop, resize and delete, and the event will have the `.mbsc-readonly-event` css class. With this class, the fixed events will be easily customizable, for example: add opacity or disable the cursor on the fixed events. - `dragBetweenResources` _Boolean_ - specifies whether the event is movable across resources. It applies for [scheduler](scheduler) and [timeline](timeline) views. Has precedence over the `eventDragBetweenResources` property of the [resource](resources) and the [`dragBetweenResources`](api#opt-dragBetweenResources) option. - `dragInTime` _Boolean_ - specifies whether the event is movable in time. Has precedence over the `eventDragInTime` property of the [resource](resources) and the [`dragInTime`](api#opt-dragInTime) option. - `resize` _Boolean_ - specifies whether the event is resizable. Has precedence over the `eventResize` property of the [resource](resources) and the [`dragToResize`](api#opt-dragToResize) option. - `resource` _String, Number, Array_ - specify resource ids for the events. The event will display only in the specified [resource](resources) group. If there is no resource id defined the event will be displayed at every resource group. - `slot` _String, Number_ - specify slot ids for the events. The event will display only in the specified [`slot`](api#opt-slots) group. If there is no slot id defined the event will be displayed at every slot group. - `recurring` _String, Object_ - Recurrence rule for the event. - `recurringException` _String, Object, Array_ - Represents the exceptions of a recurring event. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule` _String, Object_ - Represents the exception rule of a recurring event. Useful when recurring dates need to be skipped from the rule. - `timezone` _String_ - The timezone of the event. When specified, it takes precedence over [`dataTimezone`](api#opt-dataTimezone). A timezone plugin must be also passed to the component. - `tooltip` _String_ - Specifies the tooltip text of the event. - `cssClass` _String_ - Can be used to pass custom CSS classes on an event to event basis. Useful when customization is needed on the event level. For example: setting the width for specific events. - `bufferBefore` _Number_ - Defines a buffer time in minutes that will be displayed before the start of the event. This buffer area can help you visualise delays or added minutes for tasks. For example travel time for meetings/appointments, briefing before flight, check in time on duty card. - `bufferAfter` _Number_ - Defines a buffer time in minutes that will be displayed after the end of the event. This buffer area can help you visualise delays or added minutes for tasks. For example travel time after meetings/appointments, debriefing after flight, check out time on duty card. ```javascript title="Simple event object" const myMeeting = { start: "2023-07-14T08:00", end: "2023-07-14T09:00", title: "Meeting with Jenny", }; ``` :::info The dates in the above structure can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: ```javascript title="Using date object in event objects" const myBirthday = { // highlight-next-line start: new Date(1988, 5, 28), // 1988 June 28th allDay: true, recurring: { repeat: "yearly", }, title: "My Birthday", }; ``` :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: The event objects may have additional custom properties as well. The custom properties are not used by the eventcalendar, but they are kept and will be available anywhere the event objects are used. E.g. the [`onEventClick`](api#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ```javascript title="Event object with custom properties" const weeklyMeeting = { start: '2023-07-26T15:45', end: '2023-07-26T16:00', title: 'Daily summary', // highlight-start address: 'Main Street 64' videoUrl: 'https://myaddress.com/location', recipients: ['Jack', 'Sam', 'Teal`c'] // highlight-end } ``` ## Recurring events The `recurring`, `recurringException` and `recurringExceptionRule` properties of the event object are used to define events that happen again over time. Check out the [recurrence section](../core-concepts/recurrence) for a more comprehensive description on recurring rules. Local data To bind local data to the event calendar, you can simply assign a JavaScript array of objects to the [`data`](api#opt-data) option of the component. ```html ``` ```ts @Component({...}) export class MyComponent { myData: MbscCalendarEvent[] = [{ id: "event_id1", start: "2023-07-09", end: "2023-07-13", title: "My First Event", }, { id: "event_id2", start: "2023-08-01", end: "2023-08-03", title: "My Second Event", }]; } ``` Remote data You can load the data through an external request and assign it to the data-bound variable to update the eventcalendar with the newly received data. ```html ``` ```ts @Component({...}) export class MyComponent implements AfterViewInit { myView: MbscEventcalendarView = { calendar: { type: "month" }, agenda: { type: "month" }, }; myData: MbscCalendarEvent[] = []; ngAfterViewInit() { getJson( "https://trial.mobiscroll.com/events/?vers=5", (events) => { this.myData = events; }, "jsonp" ) } } ``` On demand loading Use the [`onPageLoading`](api#event-onPageLoading) event to load the data relevant to the currently active view. The event fires every time the date range of the view changes, for example when someone navigates the event calendar. Getting the events in real time as the user interacts with the UI improves load performance and always serves the most recent data. :::tip You can pass the view variables - like month and year - in the URL and handle the filtering inside the API implementation. ::: ```html ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: 'day' } }; myData: MbscCalendarEvent[] = []; myHandlePageLoad(args: MbscPageLoadingEvent) { const year = args.month.getFullYear(); const month = args.month.getMonth(); const day = args.month.getDate(); getJson( 'https://trial.mobiscroll.com/weeklyevents/?year=' + year + '&month=' + month + '&day=' + day, (events) => { this.myData = events; }, "jsonp" ); } } ``` In case of the timeline view, data can also be [loaded dynamically during scrolling](timeline#load-data-on-scroll). Scrolling vertically or horizontally triggers the [onVirtualLoading](#event-onVirtualLoading) lifecycle event, which can be used to [load data incrementally during scrolling](https://demo.mobiscroll.com/timeline/load-resources-on-scroll). --- ## Drag & drop { value: 'Draggable', level: 3, id: 'draggable'}, { value: 'Draggable options', level: 3, id: 'draggable-options'}, { value: 'Third party dragging support', level: 3, id: 'third-party-dragging-support'}, { value: 'The Eventcalendar as source', level: 2, id: 'the-eventcalendar-as-source'}, { value: 'Dropcontainer', level: 3, id: 'dropcontainer'}, { value: 'Dropcontainer events', level: 3, id: 'dropcontainer-events'}, { value: 'Drop to third party drag&drop list', level: 3, id: 'third-party-dropping-support'}, ]; Calendar events can be created, moved and resized on the Eventcalendar. Furthermore it is possible to drag and drop events from an external source or to drag and drop to an external target from the Eventcalendar. The following sections describe how these solutions can be implemented and used. ## Internal drag/resize/create The events on the Eventcalendar can be moved and resized with mouse/touch interactions. The [`dragToMove`](./api#opt-dragToMove) and [`dragToResize`](./api#opt-dragToResize) options enable the events drag and drop and resize functionality. With the [`dragTimeStep`](./api#opt-dragTimeStep) option the minimum amount of drag/resize step can be specified in minutes. With the [`dragToCreate`](./api#opt-dragToCreate) option enabled, events can be created by dragging on the empty areas of the Eventcalendar. On a desktop environment a new event can also be created with the [`clickToCreate`](./api#opt-clickToCreate) option. To customize the newly created event use the [`extendDefaultEvent`](./api#opt-extendDefaultEvent) option. ![Eventcalendar move/resize/create](/img/drag-resize-create.gif) ## Targeting the Eventcalendar There is a possibility to drag & drop any external element into your calendar. In order to achieve this, first you need to grant permission to your calendar to accept this behavior. You can do that by setting the [`externalDrop`](./api#opt-externalDrop) option to `true`. As a second step, you'll have to create your external draggable element and pass a skeleton event definition through the `dragData` option which will be added to the Eventcalendar on drop. If omitted, a default event will be created. Draggable You can initialize the draggable containers by using the `mbsc-draggable` directive on the element. ```html
My Draggable event
``` ```ts @Component({...}) export class MyComponent { myEvent: MbscCalendarEvent = { title: "My new 3h long event", start: new Date(2023, 10, 10, 12), end: new Date(2023, 10, 10, 15), color: "green", }; } ``` Draggable options ### context string | HTMLElement Specify where the dragged element will be appended in the DOM. ### dragData string | [MbscCalendarEvent](#type-MbscCalendarEvent) | [MbscResource](#type-MbscResource) The data of the dragged element. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. The [`MbscResource`](#type-MbscResource) type has the following properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. ### element HTMLElement The HTML element of the dragged item. ### type "event" | "resource" The type of the draggable element. Third party dragging libraries Mobiscroll comes with built-in support for two widely used reorderable drag-and-drop list libraries: [SortableJS](https://sortablejs.github.io/Sortable/) and [Dragula](https://bevacqua.github.io/dragula/). With the `sortableJsDraggable` and `dragulaDraggable` plugins, you can seamlessly drag items into the Eventcalendar with just a few lines of code. SortableJS: Integration: call the `sortableJsDraggable` plugin’s `init()` method and pass the SortableJS instance along with the `options` object. The options object can include the following properties: - `cloneSelector` - *string* - the selector of the SortableJS clone element, typically `'.sortable-drag'` - `dragData` - *(el: HTMLElement) => MbscCalendarEvent | MbscResource* - function to build the resource or event object. Defaults to `data-drag-data` attribute on the element. - `type` - *'event' | 'resource'* - Creates an event or resource on the Eventcalendar. Defaults to `'event'`. - `externalDrop` - *boolean* - Enables drop from Eventcalendar to SortableJS list. - `onExternalDrop` - *(args: {container: HTMLElement, position: number, dragData: MbscCalendarEvent | MbscResource, afterElement?: HTMLElement}) => void* - function triggered on drop from Eventcalendar to SortableJS list. ```html
Sortable appointments
Winfred Lesley - Teeth whitening
1.5 hours
Rosalin Delice - Crown and bridge
2 hours
``` ```ts @Component({...}) export class MyComponent implements AfterViewInit { @ViewChild('sortableList', { static: true }) public sortableList!: ElementRef; public ngAfterViewInit() { const sortableInst = new Sortable(this.sortableList.nativeElement, { animation: 150, forceFallback: true, }); sortableJsDraggable.init(sortableInst, { cloneSelector: '.sortable-drag', }); } } ``` :::info The SortableJS integration works only if fallback mode is used. The `cloneSelector` must be set in the `options` object. ::: Dragula: Integration: call the `dragulaDraggable` plugin’s `init()` method and pass the Dragula instance, optionally providing an `options` object to customize the behavior. The options object can include the following properties: - `dragData` - *(el: HTMLElement) => MbscCalendarEvent | MbscResource* - function to build the resource or event object. Defaults to `data-drag-data` attribute on the element. - `type` - *'event' | 'resource'* - Creates an event or resource on the Eventcalendar. Defaults to `'event'`. - `externalDrop` - *boolean* - Enables drop from Eventcalendar to Dragula list. - `onExternalDrop` - *(args: {container: HTMLElement, position: number, dragData: MbscCalendarEvent | MbscResource, afterElement?: HTMLElement}) => void* - function triggered on drop from Eventcalendar to Dragula list. ```html
Dragula appointments
Winfred Lesley - Teeth whitening
1.5 hours
Rosalin Delice - Crown and bridge
2 hours
``` ```ts @Component({...}) export class MyComponent implements AfterViewInit { @ViewChild('dragulaList', { static: true }) public dragulaList!: ElementRef; public ngAfterViewInit() { const drake = dragula([dragulaList], { copy: true, }); dragulaDraggable.init(drake); } } ``` :::info When using the Dragula integration on touch devices, draggable items require the following CSS rule to ensure proper behavior: `.task { touch-action: none; }` This is a known limitation in Dragula’s touch support that has not been addressed yet. ::: The Eventcalendar as source The [`externalDrag`](./api#opt-externalDrag) option enables events to be dragged out from the calendar/schedule/timeline views and dropped on another instance of the Eventcalendar or any [Dropcontainer](#dropcontainer). When an event leaves the Eventcalendar the [`onEventDragLeave`](./api#event-onEventDragLeave) life-cycle event will be fired and a clone of the calendar event will be displayed for a better illustration of the movement. If the [`dragToMove`](./api#opt-dragToMove) option is not enabled the dragged event will instantly leave the calendar container and the [`onEventDragLeave`](./api#event-onEventDragLeave) event will fire and the event clone will be displayed. When an event enters the Eventcalendar the [`onEventDragEnter`](./api#event-onEventDragEnter) life-cycle event will be fired. Dropcontainer The Dropcontainer defines a container where events can be dragged from or dropped to. The [`onItemDragLeave`](#event-onItemDragLeave) and [`onItemDragEnter`](#event-onItemDragEnter) life-cycle events can be used to track when an event exits or enters the Dropcontainer. When an item is dropped inside the container the [`onItemDrop`](#event-onItemDrop) event is triggered. This can be useful for unscheduling work or appointments that were already scheduled. ```html
My Unscheduled events:
  • {{event.title}}
 ``` ```ts @Component({...}) export class MyComponent { myUnscheduledEvents: MbscCalendarEvent[] = [{ id: 1, title: "My new 3h long event", start: new Date(2023, 10, 10, 12), end: new Date(2023, 10, 10, 15), color: "green", }]; unscheduleEvent(dropEvent: MbscItemDragEvent) { this.myUnscheduledEvents = [...this.myUnscheduledEvents, dropEvent.data] } scheduleEvent(args: MbscEventCreateEvent) { this.myUnscheduledEvents = this.myUnscheduledEvents.filter(item => item.id !== args.event.id); } } ``` Dropcontainer events ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onItemDragEnter (args: MbscItemDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `data`: *MbscCalendarEvent | MbscResource * - The dragged data. - `dataType`: *'event' | 'resource'* - The type of the dragged item. ### onItemDragLeave (args: MbscItemDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `data`: *MbscCalendarEvent | MbscResource * - The dragged data. - `dataType`: *'event' | 'resource'* - The type of the dragged item. ### onItemDrop (args: MbscItemDragEvent) => void Triggered when an event is dropped inside the drop container. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `data`: *MbscCalendarEvent | MbscResource * - The dragged data. - `dataType`: *'event' | 'resource'* - The type of the dragged item. Drop to third party drag&drop list Mobiscroll comes with built-in support for dropping events and resources from the Eventcalendar to two of the most popular reordable drag and drop lists: [SortableJS](https://sortablejs.github.io/Sortable/) and [Dragula](https://bevacqua.github.io/dragula/). Unscheduling events or drag out resources can be enabled with the `sortableJsDraggable` and `dragulaDraggable` plugins. Integration: enable dropping to third-party lists by setting `externalDrop` to `true` in the `sortableJsDraggable` or/and `dragulaDraggable` plugin’s `options` configuration and use the `onExternalDrop` callback to update the list. This function returns the following arguments: - `afterElement` - *HTMLElement* - the list element before which the clone is dropped. - `container` - *HTMLElement* - the list container. - `dragData` - *MbscCalendarEvent | MbscResource* - the dragged data. - `position` - *number* - the index where the clone is dropped. ```ts // options object of the sortableJsDraggable or dragulaDraggable // enable drop from Eventcalendar to Dragula or SortableJS list externalDrop: true, // update the list items after drop event onExternalDrop: (args: MbscExternalDropEvent) => { const listItems = [...this.myListItems]; listItems.splice(args.position, 0, args.dragData); this.myListItems = listItems; }, ``` --- ## Navigating to a date and time You can navigate to another view programatically any time, by changing the [`selectedDate`](./api#opt-selectedDate) option. This will navigate the calendar to the view containing the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. When multiple days, weeks, months or years are displayed, the position of the specified date on the view (first, second, third, etc. day/week/month/year) is determined by the [`refDate`](./api#opt-refDate) option. ```html ``` ```ts @Component({...}) export class AppComponent { myDate = new Date(2020, 2, 18); setDate() { this.myDate = new Date(2020, 3, 19); } } ``` --- ## Eventcalendar The Eventcalendar component supports four highly configurable views: a [Calendar view](/angular/eventcalendar/calendar), a [Scheduler with time grid](/angular/eventcalendar/scheduler), a [Timeline](/angular/eventcalendar/timeline) and an [Agenda view](/angular/eventcalendar/agenda). ## Usage The following example will create an Eventcalendar with the default options. ```html ``` For many more examples - simple and complex use-cases - check out the [Eventcalendar demos](https://demo.mobiscroll.com/eventcalendar). --- ## Print { value: 'Printing', level: 2, id: 'printing'}]; The Print Module is an optional module, that includes styles and functions for printing. It can be installed and used with the Mobiscroll Eventcalendar. ## Installing the Print Module When your Mobiscroll package is created with the [Download Builder](https://download.mobiscroll.com) and you have access to the Print Module, you can choose to include it in the built package. In this case you will need make sure you checked the print module before downloading the package from the download page. After installing your downloaded package, the Print Module will be available for import. In case it was downloaded with the download builder, the Print Module needs to be imported from the generated package. When you're using the full Mobiscroll package from NPM, then you have the possibility to install the Print Module as an additional package (also from NPM). In this case, after successfully using the Mobiscroll CLI to configure the project, you will have to install the `@mobiscroll/print` package from npm. Use the following command: ```bash npm install @mobiscroll/print ``` ## Importing the Print Module The Print Module consists of print specific styles, that need to be loaded into the document. Also, there's a JavaScript part, that needs to be imported and passed to the component via the [`modules`](./api#opt-modules) option. #### Stylesheets :::info In the case of the package built by the download builder, there's no additional stylesheet. It is already bundled into the same file all the other component files are. ::: For the NPM package, styles can be found at the `dist/css/` folder inside the package. ```javascript // importing the css // importing the SASS - if you are using SASS ``` #### JavaScript The print module can be imported from the installed package and passed to the component using the [modules](./api#opt-modules) option. Here's an example: ```ts @Component({...}) export class MyComponent { myModules = [print]; } ``` ```html ``` Printing Printing the Eventcalendar contents can be done using the print method of the Eventcalendar [instance](../core-concepts/instance). Calling this method will create a new window containing only the Eventcalendar and will invoke the print function of the browser. After the printing is done, the window should close automatically. :::info When you want to include more than just the Eventcalendar in your print, you can invoke the print screen of your browser. You don't have to worry about the printing styles for the eventcalendar, they will be applied in this case as well. ::: The new window created by the print method will include all the styles and links to stylesheets from the original page. These styles will be copied over automatically, but in case you are using relative urls, the base url of the new window might not match yours. In this case, the print method can be passed a config object, with your custom `baseUrl`, to make the relative paths work. By default, the `baseUrl` will be the original pages origin. :::caution Popup blockers might block the created window, so you need to disable the blocker for this method to work. ::: ```ts @Component({...}) export class MyComponent { myModules = [print]; } ``` ```html Print it! ``` :::info If you want to learn more about calling instance methods check out the [instance](../core-concepts/instance) section! ::: --- ## Resources Resources can be many things, ranging from **people** through **conference rooms** to **company assets**, that need schedulig. The Eventcalendar can handle multiple resources inside a single instance. The resource object supports the following properties: - `background` _String_ - Specifies the background color of the resource row or column. - `children` _Array of object_ - Array of resource objects which will render as a child of the specified resource. - `collapsed` _Boolean_ - Defines the displayed state of the child resoruce group. - `id` _Number, String_ - This is an id that can be referenced in the events/invalids/colors data. - `name` _String_ - The name of the resource that will be displayed at the top of the resource column. - `color` _String_ - The color controls the default event color of the resource. Event colors can be specified further on the event object itself. If the color is omitted the events of the resource will inherit the default calendar color. - `fixed` _Boolean_ - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. - `eventCreation` _Boolean_ - Disables event creation on specific resources by setting it to false. It's true by default. - `eventDragBetweenResources` _Boolean_ - Specifies whether the events in the specified resource are movable across resources. It applies for scheduler and timeline views and has precedence over [`dragBetweenResources`](api#opt-dragBetweenResources) option. - `eventDragBetweenSlots` _Boolean_ - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventDragInTime` _Boolean_ - Specifies whether the events in the specified resource are movable in time. Has precedence over the [`dragInTime`](api#opt-dragInTime) option. - `eventOverlap` _Boolean_ - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize` _Boolean_ - Specifies whether the events in the specified resource are resizable. Has precedence over [`dragToResize`](api#opt-dragToResize) option. - `reorder` _Boolean_ - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. Has precedence over the `resourceReorder` property. Besides the base properties you can add any custom property, like title, job, etc. ```javascript title="Defining resources" const myResources = [ { id: "my_id_1", name: "Jane", job: "Developer" }, { id: "my_id_2", name: "Bob", job: "Administrator" }, { id: "my_id_3", name: "Andy", job: "Designer" }, ]; ``` :::tip For more information on resource grouping and hierarchy check out the [timeline's](timeline#resource-grouping-and-hierarchy) or the [scheduler's](scheduler#resource-grouping) sections for resources. ::: [Events](api#opt-data), [colors](api#opt-colors), [invalids](api#opt-invalid) can be tied to a single or multiple resources. This can be done with the `resource` property of the objects, where the id of the resource should be passed. It can be a single value and the element would be linked to a single resource or in case of an array the element will show up at the specified resources. If no resource property is specified to the color/event/invalid object then the element will show up in every resource group. ```javascript title="Invalid rule for specific resources" const myResources = [ { id: 1, name: 'General Courier'}, // highlight-start { id: 2, name: 'Express Courier'}, { id: 3, name: 'Super Express Courier'}, // highlight-end ]; const myInvalid = [ { // highlight-next-line resource: [2, 3] // is unavailable at weekends: recurring: { repeat: 'weekly', weekDays: 'SU,SA', interval: 1 } } ]; ``` :::tip Check out the [recurrence section](../core-concepts/recurrence) for more details on recurring rules ::: --- ## Scheduler Use the [Scheduler view](https://demo.mobiscroll.com/scheduler) which features a time grid - vertically scrollable [daily, weekly and monthly views](https://demo.mobiscroll.com/scheduler/show-hide-hours-days) with built in [resource support](https://demo.mobiscroll.com/scheduler/resource-view), [templating](#templating) and more. ## Overview The Scheduler displays a time grid with its related events. It can be configured as a [daily, weekly or monthly schedule](https://demo.mobiscroll.com/scheduler/show-hide-hours-days). [Work hours and work days](https://demo.mobiscroll.com/scheduler/work-week-hours) along with [disabled time-spans, breaks](https://demo.mobiscroll.com/scheduler/time-off-blocked-ranges) can be added. Use it for [advanced scheduling tasks](https://demo.mobiscroll.com/scheduler/doctors-appointment) with built-in drag & drop. The capabilities like [recurring events](/angular/core-concepts/recurrence), [all-day, multi-day events](#opt-data), [responsiveness](#responsiveness) are supported by the Scheduler. ![Scheduler overview](/img/scheduler-overview.png) ## Showing the Scheduler ### View combination The four views - [scheduler](./scheduler), [calendar](./calendar), [timeline](./timeline), [agenda](./agenda) - can be used alone or combined with each-other to create the perfect user experience on mobile, desktop and on everything in-between. For example, the daily Scheduler can also be combined with the Calendar week view. The view option will look like the following: ```html title="Daily Scheduler combined with Weekly Calendar" ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { calendar: { type: 'week' }, schedule: { type: 'day' } }; } ``` ### Configuring the view The Scheduler view can be configured through the `view` option. Below are listed the `schedule` object properties which can help you fine-tune this view. ```html title="Example" ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: 'week', startDay: 1, endDay: 5, startTime: '09:00', endTime: '17:00', timeCellStep: 60, timeLabelStep: 60, currentTimeIndicator: true } }; } ``` ### allDay boolean Show or hide the all day events. **Default value**: `true` ### currentTimeIndicator boolean Show or hide the current time indicator. It defaults to `true` when the resolution is less than a day otherwise defaults to `false`. ### days boolean Show or hide week days above the schedule grid. **Default value**: `true` ### endDay number Specifies the last visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. **Default value**: `6` ### endTime string Set the end time of scheduler column. Hours and minutes can be specified in the same string, example: `'18:30'`. **Default value**: `'24:00'` ### hideEmptyColumns boolean Hide the empty columns. **Default value**: `false.` ### hideInvalidColumns boolean Hide the fully invalid columns. **Default value**: `false.` ### maxEventStack number | "all" | "auto" Limit the number of displayed events. When the number of overlapping events reaches the specified value, a "more" button will be displayed which opens a popover showing the rest of the events. - If it is a `number`, it specifies how many events will be displayed before the "more" button appears. - If set to `'all'`, all events will be displayed. - If set to `'auto'`, the component will decide how many events can be placed inside the column, based on the `minEventWidth` view option and the actual column width. **Default value**: `'all'` ### minEventWidth number Specifies the minimum event width. Will be used when `maxEventStack: 'auto'` is used. ### size number Specifies the number of displayed months, weeks or days. **Default value**: `1` ### startDay number Specifies the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. Should not be mistaken for the [firstDay](#localization-firstDay) option, which sets the first day of the week, and, if not set, is defined by the [localization](#localization-locale). **Default value**: `0` ### startTime string Set the start time of scheduler column. Hours and minutes can be specified in the same string, example: `'09:30'`. **Default value**: `'00:00'` ### timeCellStep number Specifies the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440 **Default value**: `60` ### timeLabelStep number Specifies the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. **Default value**: `60` ### timezones Array Display times in multiple timezones on the time scale and time indicator. The timezones array can contain timezone strings or objects with timezone and label properties. Timezone strings must use the name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172). If no label is provided, the time column label will be UTC +/- the timezone offset. ```js timezones: ['Europe/Berlin','Europe/Bucharest'] ``` ```js timezones: [ { timezone: 'America/Chicago', label: 'CHI'}, { timezone: 'America/New_York', label: 'NY'} ] ``` ### type "day" | "month" | "week" Sets the scheduler type. **Default value**: `'week'` ### Row height There might be cases when you would like to change the height of the schedule cell. You can use the following CSS classes for this purpose: ```css .mbsc-schedule-time-wrapper, .mbsc-schedule-item { height: 20px; } ``` ### Column width CSS classes offer the flexibility to adjust column widths, allowing you to fully customize the layout of both resource columns and day columns. You can choose to customize them together or separately, giving you the freedom to create a design that suits your specific needs. ```css title="Setting general column width" .mbsc-schedule-col-width { width: 100px; } ``` #### Customizing weekday column widths Each weekday column has a predefined CSS class that allows setting different widths for them: - `.mbsc-schedule-column-mon` (Monday) - `.mbsc-schedule-column-tue` (Tuesday) - `.mbsc-schedule-column-wed` (Wednesday) - `.mbsc-schedule-column-thu` (Thursday) - `.mbsc-schedule-column-fri` (Friday) - `.mbsc-schedule-column-sat` (Saturday) - `.mbsc-schedule-column-sun` (Sunday) ```css title="Adjusting width for Monday" .mbsc-schedule-column-mon { width: 150px; } ``` #### Customizing resource column widths Resource column widths can be adjusted by assigning a custom CSS class to resources using the cssClass property. Check out how to change resource column widths in [this example](https://demo.mobiscroll.com/scheduler/content-dependent-resource-width). ```ts title="Assigning a class to a resource" resources: [ { id: 1, name: 'Resource 1', cssClass: 'resource-column-small' }, { id: 2, name: 'Resource 2', cssClass: 'resource-column-large' } ] ``` ```css title="Define styles for the resource classes" .resource-column-small { width: 80px; } .resource-column-large { width: 160px; } ``` :::info If you override both resource and day column widths, make sure column groups (day or resource, depending on the [`groupBy`](#opt-groupBy) option) are wide enough to contain their child elements, or specify a `min-width` for the group column instead of a fixed width. ::: ### Hide empty columns Columns without any events can be hidden by setting `hideEmptyColumns` to `true` under the [view](#configuring-the-view) configuration. ### Hide invalid columns Fully invalid columns can be hidden by setting `hideInvalidColumns` to `true` under the [view](#configuring-the-view) configuration. :::info A column is considered fully invalid if it contains [invalid](#opt-invalid) periods defined with `allDay`, date values, or a single time range that covers a full day or multiple days. ::: ## Resources ### Resource grouping The Scheduler view can display multiple [resources](resources) inside a single instance. By default the displayed resources will be grouped by the given resources and the grouping can be changed with the [`groupBy`](#opt-groupBy) option, which also supports grouping by date. ```html title="Grouping resources by date" ``` ```ts @Component({...}) export class MyComponent { myResources: MbscResource[] = [{ id: 1, name: 'Ryan', color: '#f7c4b4' }, { id: 2, name: 'Kate', color: '#c6f1c9' }, { id: 3, name: 'John', color: '#e8d0ef' }]; } ``` The color property controls the default event color of the resource. If an event doesn't have a specified color it will inherit from the resource. The [agenda](agenda) and [calendar view](calendar) events and labels will also inherit the resource color. [Events](#opt-data), [colors](#opt-colors), [invalids](#opt-invalids) can be tied to a single or multiple resources. This can be done with the `resource` property of the objects, where the id of the resource should be passed. It can be a single value where the element would be linked to a single resource or in case of an array the element will show up at all of the specified resources. If no resource property is specified to the color/event/invalid object then the element will show up in every resource group. ```html title="Invalid rule tied to a single resource" ``` ```ts @Component({...}) export class MyComponent { myInvalid: MbscDateType[] = [{ // highlight-next-line resource: 1, // this invalid will be displayed only in resource group where id is 1 start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break' }] } ``` ```html title="Event tied to multiple resources" ``` ```ts @Component({...}) export class MyComponent { myData: MbscCalendarEvent[] = [{ // highlight-next-line resource: [2, 3] // this event will be displayed in resource groups where id is 2 and 3 start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, }]; } ``` ```html title="Color rule for all the resources (resource not specified)" ``` ```ts @Component({...}) export class MyComponent { myColors: MbscCalendarColor[] = [{ // highlight-next-line // this color will display at every resource group start: new Date(2021, 5, 12, 16), end: new Date(2021, 5, 12, 17), color: "green", }]; } ``` ### Resource order The initial order in which the resources appear on the scheduler follows the order of the array passed to the component. If the initial order needs to be changed, sort the resource array before passing it to the event calendar. For dynamic sorting during runtime, sort the resource array and pass the updated array to the calendar. ## Responsiveness The Scheduler is [fully responsive](https://demo.mobiscroll.com/scheduler/responsive-day-week-schedule#). It adapts to the available space and fills the screen to look good everywhere. While you don't have to worry about the width the height can be manually adjusted with the [height](#opt-height) option. This specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. Use the [responsive](#opt-responsive) option to configure how the calendar behaves on different sized screens. The responsive option is equipped with five breakpoints: - `xsmall` (up to 575px), - `small` (up to 767px), - `medium` (up to 991px), - `large` (up to 1199px), - `xlarge` (from 1200px). Also, custom breakpoints can be added if necessary: - `my-custom-breakpoint: { breakpoint: 600 }` (from 600px up to the next breakpoint). :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries. ::: ```html title="Responsive configuration with the view option" ``` ```ts @Component({...}) export class MyComponent { responsiveSettings: MbscEventcalendarView = { xsmall: { view: { schedule: { type: 'day' }} }, custom: { // Custom breakpoint, you can use multiple if needed, but each must have a unique name. breakpoint: 600, view: { schedule: { type: 'week' }} } }; } ``` ![Scheduler responsive behavior](/img/scheduler-responsive.gif) ## Templating The display of Scheduler can be customized with different [templating functions](#templates). ### The cell Use the [cellTemplate](#template-cellTemplate) option to fully customize the Scheduler cells. Customize how the cell look and what they show. The template gets an object with properties like date, events, colors, invalids, and resource, which can be used to display custom content. :::info Since cells are rendered frequently while scrolling, keep the customization lightweight for best performance. ::: Check out how you can style the cell in [this example](https://demo.mobiscroll.com/scheduler/cell-content-template#) or just play with the slider below to see the differences. ### The event, their content and buffer areas The events can be customized in two ways: - You can use the [scheduleEventTemplate](#template-scheduleEventTemplate) option to customize the events that appear on the Scheduler. It should return the markup of the event. The Eventcalendar will take care of the positioning, but anything else you want to show is up to you - like a title, description, color the background or show any content. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [scheduleEventContentTemplate](#template-scheduleEventContentTemplate) option. Mobiscroll will position the event to the right place and will render essential information like the color of the event, the time and if it's an all day event or not. The title, description and any other fields you want to show (like participants or an avatar) will be coming from your custom function. The buffers can be customized through the [bufferBeforeTemplate](#template-bufferBeforeTemplate) and [bufferAfterTemplate](#template-bufferAfterTemplate) options. These can help you visualise delays or added minutes for tasks. For example travel time for meetings/appointments, check in/check out for flights. Check out how you can style event, their content and buffer areas in [this example](https://demo.mobiscroll.com/angular/scheduler/customizing-events#) or just play with the slider below to see the differences. ### The date header There are two approaches you can take: - Customize the date headers of the Scheduler with the [dayTemplate](#template-dayTemplate) option by adding relevant content, labels or completely change how they look. It takes a function that should return the desired markup. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. The render function will receive an object as parameter. This data can be used to show day specific things on the Scheduler. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [dayContentTemplate](#template-dayContentTemplate) option. You will get the styling taken care of by the Eventcalendar, and you can focus on what you show besides the day number. The template will receive an object as data. This data can be used to show day specific things on the Scheduler. Check out how you can style the date header in [this example](https://demo.mobiscroll.com/angular/scheduler/date-header-template#) or just play with the slider below to see the differences. ### The resource header Use the [resourceTemplate](#template-resourceTemplate) option to customize the resource template of the Scheduler. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](#opt-resources) array. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. Check out how you can style the resources in [this example](https://demo.mobiscroll.com/angular/scheduler/custom-resource-header-template#) or just play with the slider below to see the differences. ### The scheduler header Customize how the header of the Scheduler looks and how the components are arranged with the [headerTemplate](#template-headerTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar. While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's [building blocks](/angular/eventcalendar/templating#header-templating). These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. Check out how you can style the Scheduler header in [this example](https://demo.mobiscroll.com/angular/scheduler/customizing-header#) or just play with the slider below to see the differences. ## Event order The rendered event order is determined by the following two concepts: 1. Event data order 2. Event layout The combination of these concepts results in the final rendered event order. ### Event data order The sequence in which events are processed before being passed to the layout algorithm. The default ordering rules are as follows: 1. All-day events are placed at the top. 2. Non-all-day events follow, sorted by their start times. 3. Events with the same start time are further ordered alphabetically by their titles. This default order can be modified using the `order` property in the event [event data](#opt-data). The order property takes precedence over the default rules. If two events have the same order value, the default rules apply. For more complex ordering requirements, the [eventOrder](#opt-eventOrder) option can be used. This option accepts a function that compares two events and returns an order (-1 or 1). ### Event layout The event layout process determines the visual positioning and dimensions of events. This is a built-in functionality and cannot be altered externally. The layout algorithm processes the sorted event list and calculates each event's position and size. The algorithm follows these steps: 1. The first event is placed in the first position of the event track. 2. If two or more events overlap in their start/end times, the later event is placed in the next event track, positioned below or next to the previous event. 3. If a subsequent event does not overlap with any already added events, it is placed back in the first event track. 4. This process continues until all events are positioned within their respective columns or rows. ## API Here is a comprehensive list of all the specific options, events and methods of the Scheduler view. ### Options Explore the following API options that help you easily configure the Scheduler. ### clickToCreate boolean | "double" | "single" Enable new event creation on click. If `true` or `'double'`, a new event will be created only with a double click and with the `'single'` value the event will be created instantly with a single click. This option will only work on desktop environment where mouse events are fired. It will also allow deleting of the focused events using the Delete or Backspace key. In touch environment a long tap should be used to create a new event and it is controlled by the [dragToCreate](#opt-dragToCreate) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### colors Array<[MbscCalendarColor](#type-MbscCalendarColor)> Specifies the color for certain dates or date ranges on the calendar. The [`MbscCalendarColor`](#type-MbscCalendarColor) type has the following properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The colored range will be considered all-day if: - the `allDay` property is explicitly set. - the `start` / `end` properties are not specified, only the `date`. ::: :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The colors can be combined with the [labels](#opt-labels) or [marked](#opt-marked) options. ::: ```js [ { date: new Date(2020, 2, 23), background: 'pink' }, { date: new Date(2020, 2, 24), background: 'green' }, { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } }, { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } } ] ``` **Default value**: `undefined` ### context string | HTMLElement The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> The events for the Eventcalendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The event objects may have additional custom properties as well. The custom properties are not used by the event calendar, but they are kept and will be available anywhere the event objects are used. E.g. the [onEventClick](#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ::: :::info Use the [getEvents](#method-getEvents) method to get the events between two dates. ::: ```js data: [ { start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, color: 'red' }, { title: 'Work project', recurring: { repeat: 'daily', until: '2021-04-01' }, recurringException: ['2021-03-15', '2021-03-25'], recurringExceptionRule: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelectedDate [MbscDateType](#type-MbscDateType) Specifies the initial selected date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### dragBetweenResources boolean If `false`, the events will not be moveable across resources, only in time. To control movement in time, use the [dragInTime](#opt-dragInTime) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragInTime boolean If `false`, the events will not be moveable in time. In case of the scheduler and timeline views events events can still be moved between resources. To control movement between resources, use the [dragBetweenResources](#opt-dragBetweenResources) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragTimeStep number Specifies the steps in minutes for the scheduler and timeline events during drag. **Default value**: `15` ### dragToCreate boolean If `true`, dragging on an empty cell will create a new event. It will also allow deleting of the focused events using the Delete or Backspace key. The title of the new event can be specified with the [newEventText](#opt-newEventText) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### dragToMove boolean If `true`, the events will be moveable. **Default value**: `undefined` ### dragToResize boolean If `true`, the events will be resizable. **Default value**: `undefined` ### eventDelete boolean Enables or disables event deletion. When `true`, the focused event will be deleted on pressing the Delete or Backspace keys on the keyboard. By default the event deletion depends on the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. If either of those are `true`, and no `eventDelete` option is set, then event deletion is also enabled, otherwise not. **Default value**: `undefined` ### eventOrder (event1: [MbscCalendarEvent](#type-MbscCalendarEvent), event2: [MbscCalendarEvent](#type-MbscCalendarEvent)) => number Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1. If not specified, the default order is: - all day events - rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title **Default value**: `undefined` ### eventOverlap boolean If `false`, the events cannot overlap. **Default value**: `true` ### exclusiveEndDates boolean If `true`, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. `end: '2021-07-03T00:00'` means that the event ends on 2nd of July and will not be displayed on 3rd of July. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: ### extendDefaultEvent (args: MbscNewEventData) => void | [MbscCalendarEvent](#type-MbscCalendarEvent) Use this option to set properties to the new event created with click or drag. The event creation is handled by the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. It takes a function that should return the properties for the new event. The argument object passed to this function has the following properties: - `start`: *Date* - The date when the newly created event will start. - `resource`: *string | number* - The id of the resource where the event creation started. ```js extendDefaultEvent: (args) => { return { color: args.resource === 'admin' ? 'green' : 'red', title: 'My event', }; } ``` **Default value**: `undefined` ### externalDrag boolean If `true`, external drag & drop is allowed and events can be dragged outside of the component view. **Default value**: `undefined` ### externalDrop boolean If `true`, external events can be dragged into the view. **Default value**: `undefined` ### groupBy "date" | "resource" Groups the [events](#opt-data) by date or by [resource](#opt-resource). **Default value**: `'resource'` ### height string | number Sets the height of the component. The height of the calendar view impacts the number of labels that fit into a table cell. A "show more" label will be displayed for events that don't fit. **Default value**: `undefined` ### immutableData boolean If `true`, the Eventcalendar will work in immutable mode. In this mode the component won't update the data directly, only fire the necessary lifecycle events, where the original data can be updated manually. **Default value**: `undefined` ### invalid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the invalid values. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the invalid range is all day or not. - `start`: *Date | string | object* - Start of the invalid range. - `end`: *Date, string | object* - End of the invalid range. - `recurring`: *string | object* - Recurrence rule for recurring invalid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - Specifies the [resource](#opt-resources) ids for the invalid range. The invalid range will be displayed only in the specified resource. If there is no resource defined, the invalid range will be displayed in every resource. - `slot`: *string | number* - Specifies the [slot](#opt-slots) id for the invalid range. The invalid range will be displayed only in the specified slot. If there is no slot defined, the invalid range will be displayed in every slot. - `title`: *string* - Text which will be displayed for the invalid range. Only applicable for the timeline and scheduler views. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### invalidateEvent "strict" | "start-end" Specifies how to validate events against [invalid](#opt-invalid) ranges on create/move/resize: - `'strict'` - The event cannot intersect with an invalid range at all. - `'start-end' - The event start and end cannot be inside an invalid range. **Default value**: `'strict'` ### max [MbscDateType](#type-MbscDateType) Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the [invalid](#opt-invalid) option with daily recurrence starting from the specific date. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the [invalid](#opt-invalid) option with daily recurrence until the specific date. **Default value**: `undefined` ### modules Array Additional modules can be added to the eventcalendar. The option receives an array of module objects. For example, the print module can be added through this option. ```js // import the print module // later on, add it to the modules array: modules: [print] ``` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed. If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01. It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is `01/16/2024`, the pages are calculated from this date, so the initial page will contain `[01/16/2024, 01/16/2024, 01/17/2024]`, the next page `[01/18/2024, 01/19/2024, 01/20/2024]` and so on. In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day. Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the [selectedDate](#opt-selectedDate) option. **Default value**: `undefined` ### resources Array<[MbscResource](#type-MbscResource)> The scheduler and timeline views can handle multiple resources. Resource grouping can be modified with the help of the [groupBy](#opt-groupBy) option. If set to `null` or `undefined`, all events will be displayed, regardless of their `resource` property. The timeline view will not display the resource column, if the resources option is not set. If set to an empty array, only those events will be displayed which are not tied to any resource. The timeline view will display an empty resource column when an empty array is passed. The timeline view can render multiple levels of hierarchy groups. Levels can be added with the help of the `children` property. The [`MbscResource`](#type-MbscResource) type has the following properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. ```js resources: [ { id: 1, name: 'Flatiron Room', color: '#f7c4b4' }, { id: 2, name: 'The Capital City', color: '#c6f1c9' }, { id: 3, name: 'Heroes Square', color: '#e8d0ef' } ] ``` **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### selectMultipleEvents boolean When `true`, enables multiple event selection on the calendar. **Default value**: `false` ### selectedDate [MbscDateType](#type-MbscDateType) Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the [refDate](#opt-refDate) option. You also need to pass a handler for the [onSelectedDateChange](#event-onSelectedDateChange) event to update the selected date when the date is changed from the calendar. **Default value**: `undefined` ### selectedEvents Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Specifies the selected events on the calendar. The [onSelectedEventsChange](#event-onSelectedEventsChange) event will be fired when the selected events change from the calendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. **Default value**: `undefined` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showControls boolean Show or hide the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker. **Default value**: `true` ### showEventBuffer boolean If `true`, it will display the event buffers defined in the [event data](#opt-data). **Default value**: `true` ### showEventTooltip boolean If `false`, it will hide the native tooltip that shows up when hovering over an event. **Default value**: `true` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### width string | number Sets the width of the component. **Default value**: `undefined` ### Events The Scheduler ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onCellClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event object has the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellDoubleClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is double-clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellHoverIn (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered day. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellHoverOut (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered cell. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellRightClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is right-clicked on the calendar, scheduler, or timeline grid . Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onEventClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventCreate (args: MbscEventCreateEvent, inst: EventcalendarBase) => void Triggered when an event is about to create and it is not yet rendered on its final position. Event creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The newly created event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being created. - inst - The component instance. ### onEventCreateFailed (args: MbscEventCreateFailedEvent, inst: EventcalendarBase) => void Triggered when an event creation failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - inst - The component instance. ### onEventCreated (args: MbscEventCreatedEvent, inst: EventcalendarBase) => void Triggered when an event is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - `target`: *HTMLElement* - The DOM element of the created event. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - inst - The component instance. ### onEventDelete (args: MbscEventDeleteEvent, inst: EventcalendarBase) => void Triggered when an event is about to be deleted and it is not yet removed from the view. Event deletion can be performed with delete and backspace button on an active event. Deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from of the keydown action. - `event`: *MbscCalendarEvent* - The event being deleted. - `events`: *Array* - The events being deleted in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event is being deleted. - inst - The component instance. ### onEventDeleted (args: MbscEventDeletedEvent, inst: EventcalendarBase) => void Triggered when an event is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The deleted event. - `events`: *Array* - The deleted events in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event was deleted. - inst - The component instance. ### onEventDoubleClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is double-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicker, if [slots](#opt-slots) are set. - `slotObj`: *MbscResource* - The resource where the event was clicker, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventDragEnd (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has ended. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event was dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event was dragged. - inst - The component instance. ### onEventDragEnter (args: MbscEventDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragLeave (args: MbscEventDragEvent) => void Triggered when an event is dragged out form the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragStart (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has started. Parameters: - args - The event argument with the following properties: - `action`: *'create' | 'resize' | 'move'* - The user action which triggered the event. - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event is dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. - inst - The component instance. ### onEventHoverIn (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event is hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event is hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event is hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverOut (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event was hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventRightClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is right-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventUpdate (args: MbscEventUpdateEvent, inst: EventcalendarBase) => void Triggered when an event is about to update. Update can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `oldResource`: number | string - The id of the resource from which the event was dragged. - `oldResourceObj`: *MbscResource* - The resource from which the event was dragged. - `oldSlot`: number | string - The id of the slot from which the event was dragged. - `oldSlotObj`: *MbscSlot* - The slot from which the event was dragged. - `resource`: number | string - The id of the resource where the event was dropped. - `resourceObj`: *MbscResource* - The resource where the event was dropped. - `slot`: number | string - The id of the slot where the event was dropped. - `slotObj`: *MbscSlot* - The slot where the event was dropped. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being updated. - inst - The component instance. ### onEventUpdateFailed (args: MbscEventUpdateFailedEvent, inst: EventcalendarBase) => void Triggered when an event update failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - inst - The component instance. ### onEventUpdated (args: MbscEventUpdatedEvent, inst: EventcalendarBase) => void Triggered when an event is updated and is rendered in its new position. This is where you update the event in your database or persistent storage. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `resourceObj`: *MbscResource* - The resource where the event is updated, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is updated, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - `target`: *HTMLElement* - The DOM element of the updated event. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onPageChange (args: MbscPageChangeEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscPageLoadedEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscPageLoadingEvent, inst: EventcalendarBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onResourceClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceDoubleClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is double-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceHoverIn (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceHoverOut (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceRightClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is right-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onSelectedDateChange (args: MbscSelectedDateChangeEvent, inst: EventcalendarBase) => void Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows. You can use this event in conjunction with the [selectedDate](#opt-selectedDate) option to customize where the Eventcalendar should navigate. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The newly selected date. - inst - The component instance. ### onSelectedEventsChange (args: MbscSelectedEventsChangeEvent, inst: EventcalendarBase) => void Triggered when an event is selected or deselected on the UI, when [multiple event selection](#opt-selectMultipleEvents) is enabled. You can also select events programmatically using the [selectedEvents](#opt-selectedEvents) option. Parameters: - args - The event argument with the following properties: - `events`: *Array* - The selected events. - inst - The component instance. ### Localization The Scheduler is fully localized. This covers date and time format, button copy, rtl and more. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateFormatLong string Long date format, used by the agenda view and timeline day headers. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'D DDD MMM YYYY'` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### newEventText string Title for the newly created event with the [dragToCreate](#opt-dragToCreate) and the [clickToCreate](#opt-clickToCreate) action. **Default value**: `'New event'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### Templates The display of the Scheduler can be customized with different templating functions. ### bufferAfterTemplate Template reference to fully customize the buffer area that is displayed at the end of the scheduler and timeline events. The buffer can be defined with the help of the `bufferAfter` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### bufferBeforeTemplate Template reference to fully customize the buffer area that is displayed at the start of the scheduler and timeline events. The buffer can be defined with the help of the `bufferBefore` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### cellTemplate Customize the cells of the Eventcalendar in scheduler and timeline views. The template will receive an object as context, which can be used to display custom content in the cells. Keep the cell template simple, as it will be called and rendered **very frequently** during scroll and view changes. The object passed to the template contains the following properties: - `colors`: _Array_ - The list of colors for the current cell. - `date`: _Date_ – The current cell's date. - `events`: _Array_ List of events for the current cell. - `invalids`: _Array_ - The list of invalids for the current cell. - `resource`: _MbscResource_ - The resource object of the current cell. - `slot`: _MbscSlot_ - The slot object of the rendered cell. **Default value**: `undefined` ### dayContentTemplate Customize the day cells content of the event calendar. The Eventcalendar will take care of the styling and you can focus on what you show beside the day number. If you are looking to fully customize the day (e.g. add custom hover effects) you will need to use the [dayTemplate](#template-dayTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. **Default value**: `undefined` ### dayTemplate Customize the day cells of the calendar view and the date header in case of scheduler and timeline views. If you are looking to customize only the day cells content and don't want to bother with the styling of the event, in case of calendar and scheduler views you can use the [dayContentTemplate](#template-dayContentTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. - `isActive`: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year **Default value**: `undefined` ### headerTemplate Template to customize the header of the event calendar. You can use custom markup or components as well as the built in header components of the calendar. **Default value**: `undefined` ### resourceTemplate Template to customize the resource template of the scheduler and timeline views. The following properties are available: - `resource`: _MbscResource_ - The rendered resource. - `day`: _Date_ - The date on which the resource is rendered. Available when grouping by date in the scheduler view, or when vertical day resolution is used in the timeline view. ```html
{{resource.name}}

{{resource.description}}

 ``` **Default value**: `undefined` ### scheduleEventContentTemplate Template to customize the event content that appears on the scheduler and timeline. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [scheduleEventTemplate](#template-scheduleEventTemplate) option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### scheduleEventTemplate Template to customize the events that appear on the scheduler and timeline. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [scheduleEventContentTemplate](#template-scheduleEventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### Types ### MbscCalendarColor Interface Properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscCalendarEvent Interface Properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. ### MbscCalendarInvalid Interface Properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### MbscDateType string | Date | object ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResource Interface Properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. The `MbscResource` supports custom properties in the form: ``` [x:string]: any ``` ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscEventcalendarOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## Setting the initial view By default the initial view of the calendar displays the current date. Depending on the view type, this might be the current day, week, month or year. For views, where time is also displayed, the view will be scrolled to the current time as well. To change the initial view to another date, the [`selectedDate`](./api#opt-selectedDate) option can be used. Use two-way binding on the property (using the "banana in the box" syntax), so that the bound value will be updated on calendar navigation, and changing the value programmatically will navigate the calendar to the given date and time. ```html ``` ```ts @Component({...}) export class AppComponent { myDate = new Date(2020, 2, 18); } ``` For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. When multiple days, weeks, months or years are displayed, the position of the specified date on the view (first, second, third, etc. day/week/month/year) is determined by the [`refDate`](./api#opt-refDate) option. --- ## Templating ## Overview You can customize many parts of the Eventcalendar by writing custom templates. In Angular these templates are defined using the `` component and then passed to the eventcalendar as references. You will find a comprehensive list of all the templates available for the Eventcalendar in the [API templates](api#templates) section. ## Event templating When you want to customize how the events look, depending on what your goal is, you have two options: 1. [Customize the event content](#event-content-templating) - Mobiscroll takes care of rendering the events in the correct order and also prints basic fields, like `start`/`end`, whether it is an `allDay` event or not and also takes care of coloring the event appropriately. Everything else comes from the custom template. 2. [Customize the full event](#full-event-templating) - Mobiscroll takes care of rendering the events in the correct order, but everything else comes from the template you write. To define a template, create an `` tag with a variable reference and pass it to the apropriate eventcalendar option: ```html title="Using the v-slot directive" ``` ### Event content templating In most cases you only want to customize the content section of the event. In this case your template will be used as the content of the event. Mobiscroll will position the event to the right place and will render essential information like the color of the event, the time and if it's an all day event or not. The title, description and any other fields you want to show (like participants, an avatar...) will be coming from your custom template. - For the agenda and popover - use the [`eventContentTemplate`](api#template-eventContentTemplate) for the custom template - For event labels in the calendar and all-day events in the scheduler - use the [`labelContentTemplate`](api#template-labelContentTemplate) for the custom template - For the scheduler and timeline - use the [`scheduleEventContentTemplate`](api#template-scheduleEventContentTemplate) for the custom template ```html ``` Play with the slider below to see the differences. ### Full event templating In case of full event templating, whenever there is an event (in the agenda, scheduler, timeline, labels or popover) your custom template will be used instead of the default template. Mobiscroll will position your component to the right place, but anything else you want to show is up to you... like a title, description, color the background or show any content. - For the agenda and popover - use the [`eventTemplate`](api#template-eventTemplate) for the custom template - For event labels in the calendar and all-day events in the scheduler - use the [`labelTemplate`](api#template-labelTemplate) for the custom template - For the scheduler and timeline - use the [`scheduleEventTemplate`](api#template-scheduleEventTemplate) for the custom template Play with the slider below to see the differences. ## Resource templating To customize the display of the resources, the [`resourceTemplate`](api#template-resourceTemplate) can be used. ```html
{resource.name} - {resource.location}
 ``` :::info In case of the timeline view there are other parts of the Eventcalendar that can be customized through templates. Check out the [timeline templating](timeline#templating) section for more details. ::: Play with the slider below to see the differences. ## Header templating The header of the calendar can be fully customized to one's needs with the use of the [`headerTemplate`](api#template-headerTemplate) option. ```html

Any Title you want here or

 ``` While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's building blocks. These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. For example you can leave out parts from the default header, change the order of the default buttons appearance or add custom components between them. Here's the list of the built in components of the default header: - `` - Previous button component, that navigates to the previous month. - `` - Next button component, that navigates to the next month. - `` - Today button component, that navigates to the current date. - `` - The title navigation button component, that opens the year/month navigation. The above components can be used inside of the custom header. The following example will render the prev and next buttons and then a custom title that is set from a custom variable (myTitle variable). ```html title="Custom header with default buttons"
{{myTitle}}
 ``` Play with the slider below to see the differences. --- ## Timeline Use the [Timeline view](https://demo.mobiscroll.com/timeline) which features a horizontally scrollable view with multiple resource support for [day, week, work-week, month and year view](https://demo.mobiscroll.com/timeline/multiple-days-weeks-months-quarters-years-variable-resolution) with built in [templating](#templating), [drag & drop](https://demo.mobiscroll.com/timeline/move-resize-drag-drop-to-create-events) and more. ## Overview This Timeline view displays a timeline with its related events. You can render the [times/days horizontally and the resources vertically](https://demo.mobiscroll.com/timeline/timeline-time-grid). The Timeline can easily accommodate a [large number of resources](https://demo.mobiscroll.com/timeline/loading-big-data-sets) thanks to the vertical scroll that is easy to understand for users. This plays well on larger screens and in landscape containers. [Work hours and work days](https://demo.mobiscroll.com/timeline/switching-day-week-work-week-timeline) along with [disabled time-spans, breaks](https://demo.mobiscroll.com/timeline/colors-invalids-css-class) can be added. Use it to for [advanced tasks](https://demo.mobiscroll.com/timeline/restaurant-shift-management) with built-in drag & drop. By default the Timeline rows will have variable height and will expand to accommodate the displayed events. But, this can be changed by the `rowHeight` property of the [Timeline view](#opt-view) option. [If it is set to equal](https://demo.mobiscroll.com/timeline/timeline-resource-height), the rows will have equal heights, and overlapping events will be distributed evenly to fit in the row. Also, the `eventList` [property](#opt-view) transforms the event display into a [daily listing mode](https://demo.mobiscroll.com/timeline/event-listing). This view represents a daily summary rather than an hour-by-hour layout. The capabilities like [recurring events](/angular/core-concepts/recurrence), [all-day, multi-day events](#opt-data), [responsiveness](#responsiveness) are supported by the Timeline. ![Timeline overview](/img/timeline-overview.png) ## Showing the Timeline ### Configuring the view The Timeline view can be configured through the `view` option. Below are listed the `timeline` object properties which can help you fine-tune this view. ```html title="Example" ``` ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { timeline: { maxEventStack: 2, eventList: true, resolutionHorizontal: 'day', type: 'week', resourceReorder: true } }; } ``` ### columnWidth MbscTimelineColumnWidth Sets the width of grid columns in the timeline to one of the predefined column widths. Possible values and their corresponding widths: - `xxsmall`: 1.5em - `xsmall`: 3em - `small`: 4.5em - `medium`: 6em - `large`: 7.5em - `xlarge`: 9em - `xxlarge`: 10.5em - `xxxlarge`: 12em; When not defined, the column width will be set automatically based on the view type and size. :::info You can [customize the predefined column widths using CSS](./timeline#column-width) to fit your layout needs. ::: **Default value**: `undefined` ### currentTimeIndicator boolean Show or hide the current time indicator. Defaults to `true`, when the horizontal resolution is less than a day. ### endDay number Specifies the last visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. **Default value**: `6` ### endTime string Specifies the end time of schedule column. Hours and minutes can be specified in the same string, example: '18:30'. **Default value**: `'24:00'` ### eventHeight "variable" | "equal" Specifies wether the height of the events is equal or variable. :::info [Learn more about variable event heights](https://mobiscroll.com/docs/eventcalendar/timeline#variable-event-height). ::: **Default value**: `'equal'` ### eventList boolean If `true`, transforms the layout into a summary view. The events are listed in the appropriate cell one after the other. **Default value**: `false` ### hideEmptyRows boolean Hide the empty rows. :::info Parent resources will always be displayed, even when empty. ::: **Default value**: `false.` ### hideInvalidRows boolean Hide the fully invalid rows. :::info Parent resources will always be displayed, even when fully invalid, unless `resolutionVertical: 'day'` is used. ::: **Default value**: `false.` ### maxEventStack number | "all" Limit the number of displayed events. When the number of overlapping events reaches the specified value, a "more" button will be displayed which opens a popover showing the rest of the events. - If it is a `number`, it specifies how many events will be displayed before the "more" button appears. - If set to `'all'`, all events will be displayed. **Default value**: `'all'` ### ~~resolution~~ (deprecated) "day" | "hour" | "month" | "year" | "week" | "quarter" DEPRECATED: Use the `resolutionHorizontal` and `resolutionVertical` properties instead. Specifies the resolution of the timeline column. Possible values: 'hour', 'day', 'week', 'month', 'quarter', 'year'. ### resolutionHorizontal "day" | "hour" | "month" | "year" | "week" | "quarter" Sets the horizontal resolution of the timeline. In case of hourly resolution, the columns can be split to minutes (1, 5, 15, 20, 30) or merge to multiple hours (2, 3, 4, 6, 8, 12) using the `timeCellStep` and `timeLabelStep` properties. **Default value**: `'hour'` ### resolutionVertical "day" Sets the vertical time unit of the timeline to days. When set to 'day', the days will be rendered on the vertical axis, while the hours of the day will be displayed on the horizontal axis. **Default value**: `undefined` ### resourceReorder boolean Specifies whether the resource can be dragged and reordered. A drag handle icon will appear in front of the resource name, serving as the point of interaction to drag and reposition the resource. **Default value**: `false` ### rowHeight "variable" | "equal" Controls the height of the timeline rows. By default rows will have variable height and will expand to accommodate the displayed events. If it is set to `'equal'`, the rows will have equal heights. **Default value**: `'variable'` ### size number Specifies the number of displayed years, months, weeks or days. **Default value**: `1` ### startDay number Specifies the first visible weekday of the view. Sunday is 0, Monday is 1, etc. Days outside of the `startDay` and `endDay` range will not be visible. Should not be mistaken for the [firstDay](#localization-firstDay) option, which sets the first day of the week, and, if not set, is defined by the [localization](#localization-locale). **Default value**: `0` ### startTime string Specifies the start time of schedule column. Hours and minutes can be specified in the string, example: '09:30'. **Default value**: `'00:00'` ### timeCellStep number Specifies the step of the grid cells in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440 **Default value**: `60` ### timeLabelStep number Specifies the step of the time labels in minutes. Supported values: 1, 5, 10, 15, 20, 30, 60, 120, 180, 240, 360, 480, 720, 1440. **Default value**: `60` ### type "day" | "month" | "year" | "week" Specifies the timeline type. **Default value**: `'week'` ### virtualScroll boolean Enable or disable virtual scroll. **Default value**: `true` ### weekNumbers boolean Show or hide week numbers. **Default value**: `false` ### zoomLevels { [key:string]: MbscTimelineZoomLevel } Defines configuration options for multiple zoom levels for the timeline view. Each zoom level can specify its own properties for displaying a custom layout. Use the [zoomLevel](#opt-zoomLevel) option to select the current zoom level. Available properties: - `size` - `resolutionHorizontal` - `resolutionVertical` - `columnWidth` - `currentTimeIndicator` - `endDay` - `endTime` - `eventList` - `startDay` - `startTime` - `timeCellStep` - `timeLabelStep` - `weekNumbers` - `type` **Default value**: `undefined` ### Event slots Besides the [`resources`](#opt-resources) which are grouping data for the whole date range, [`slots`](#opt-slots) introduce a horizontal daily grouping in case of the Timeline view. Slots can be used alongside resources. The [slotTemplate](#template-slotTemplate) can be used to customize the slot template of the Timeline view. When [slots are used](https://demo.mobiscroll.com/timeline/employee-shifts) the Timeline view will display in daily listing mode and only the [`dragToMove`](#opt-dragToMove) event iteraction will be available. The [`dragToCreate`](#opt-dragToCreate) and [`dragToResize`](#opt-dragToResize) interactions will be truned off. ```html title="Slots used for work shift management" ``` ```ts @Component({...}) export class MyComponent { myShifts: MbscSlot[] = [ { id: 1, name: "Morning shift", }, { id: 2, name: "Afternoon shift", }, ]; } ``` ![Timeline slots](/img/timeline-slots.png) ### Column width The [`columnWidth`](timeline#view-timeline-columnWidth) option in the timeline view allows you to control the width of the timeline columns. It supports the following predefined sizes: xxsmall, xsmall, small, medium, large, xlarge, xxlarge, and xxxlarge. Here are the default sizes and their corresponding widths: ```css .mbsc-timeline-column-xxs { width: 1.5em; // 24px } .mbsc-timeline-column-xs { width: 3em; // 48px } .mbsc-timeline-column-s { width: 4.5em; // 72px } .mbsc-timeline-column-m { width: 6em; // 96px } .mbsc-timeline-column-l { width: 7.5em; // 120px } .mbsc-timeline-column-xl { width: 9em; // 144px } .mbsc-timeline-column-xxl { width: 10.5em; // 168px } .mbsc-timeline-column-xxxl { width: 12em; // 192px } ``` To specify the columnWidth in your view configuration, include it as part of the timeline view options: ```ts view: { timeline: { columnWidth: 'large' } } ``` The predefined sizes correspond to specific default widths, but you can override them using CSS: ```css .mbsc-timeline-column-l { width: 50px; } ``` :::caution You need to apply these rules after the mobiscroll default rules, otherwise the default rules will take precedence over them. ::: ## Resources ### Resource grouping and hierarchy The Timeline view supports resource hierarchy. [Hierarchy groups](https://demo.mobiscroll.com/timeline/resource-grouping-hierarchy) can be defined with the `children` property of the `resource` [object](#opt-resources). Child objects are also resources and have the same properties, thus they can also have children. ```html title="Multi-level hierarchy groups" ``` ```ts @Component({...}) export class MyComponent { myResources: MbscResource[] = [{ name: 'Site 1', children: [{ name: 'Building 1' children: [{ name: 'Room 1' }, { name: 'Room 2' }] }, { name: 'Building 2' }] }, { name: 'Site 2', children: [{ name: 'Building A' }] }]; } ``` By default every resource group will be displayed and this can be modified with the `collapsed` attribute of the parent objects. ```html title="Collapsed groups" ``` ```ts @Component({...}) export class MyComponent { myResources: MbscResource[] = [{ name: 'Main Building', id: 'main', description: 'Used the most for scheduling' // highlight-next-line collapsed: true, children: [{ name: 'Big conf. room' id: 'bfg', }, { name: 'Smaller conf. room' id: 'sfg', }] }, { name: 'Secondary Building', id: 'sec', description: 'For smaller, less important meetings' // highlight-next-line collapsed: false, children: [...] }, { name: 'Long forgotten Cave', id: 'cave', description: 'Where developers used to work' // highlight-next-line collapsed: false, }]; } ``` Both parent and child rows can contain events and events can be moved between any rows. ```html title="Resources & events" ``` ```ts @Component({...}) export class MyComponent { myResources: MbscResource[] = [{ name: 'Main Building', id: 'main', children: [{ name: 'Big conf. room' id: 'bfg', }] }, { name: 'Secondary Building', id: 'sec', }]; myEvents: MbscCalendarEvent[] = [ { title: 'Open day celebration', resource: 'main', date: '2023-08-24'}, { title: 'Monthly staff meeting', resource: 'bfg', start: '2023-08-01T11:00', end: '2023-08-01T11:00' }, { title: 'Weekly chit-chat', resource: 'sec', start: '2023-08-02T09:00', end: '2023-08-02T09:40' }, // ... ]; } ``` Child or parent rows can be disabled by creating an [invalid rule](#opt-invalid) which repeats daily and it is tied to the specific resources. Example: ```html title="Disable parent and/or child resources" ``` ```jsx @Component({...}) export class MyComponent { myInvalid: MbscDateType[] = [ { recurring: { repeat: "daily" }, resource: [ /* resource id(s) */ ], }, ]; } ``` ### Resource order The initial order in which the resources appear on the timeline follows the order of the array passed to the component. If the initial order needs to be changed, sort the resource array before passing it to the event calendar. For dynamic sorting during runtime, sort the resource array and pass the updated array to the calendar. Resources can be [reordered directly through the UI](https://demo.mobiscroll.com/timeline/resource-drag-drop-reorder) by enabling the `resourceReorder` option in the [view](#configuring-the-view) configuration. When enabled, a drag handle icon will appear before each resource, serving as the point of interaction to drag and reposition the resource. After a resource is dragged and dropped to a new position, the [onResourceOrderUpdate](#event-onResourceOrderUpdate) lifecycle event is triggered. To make specific resources non-draggable, set the `reorder` property of the corresponding resource object to `false`; ### Resource external drag and drop You can drag and drop resources into or out of the timeline view, allowing for easy organization and adjustments. #### Targeting the timeline To allow external resources to be dragged into your timeline, first set the the [`externalResourceDrop`](./api#opt-externalResourceDrop) option to `true`. As a second step, you'll need to create your external [draggable](./drag-and-drop#draggable) element and pass a skeleton resource definition through the `dragData` option. Make sure to also set `type="resource"` on the draggable element so the timeline correctly identifies it as a resource. #### The timeline as a source Resources can be dragged out of the timeline and dropped onto another instance of the Timeline or any [Dropcontainer](./drag-and-drop#dropcontainer). To enable this behavior, you'll need to set the [`externalResourceDrag`](./api#opt-externalResourceDrag) option to `true`. When a resource is dragged out of the timeline, the [`onResourceDragLeave`](./api#event-onResourceDragLeave) lifecycle event is triggered. A visual clone of the resource is shown to indicate the movement. If the resource is dropped into an external drop container or another timeline, it gets removed from the original timeline. This action also triggers the [`onResourceDelete`](./api#event-onResourceDelete) and [`onResourceDeleted`](./api#event-onResourceDeleted) lifecycle events. When a resource is dragged into the timeline, the [`onResourceDragEnter`](./api#event-onResourceDragEnter) lifecycle event is triggered. If the resource is dropped, the [`onResourceCreate`](./api#event-onResourceCreate) and [`onResourceCreated`](./api#event-onResourceCreated) events will be fired, finalizing the addition. ### Resource column width The width of the resources column on the Timeline view is fixed. It can be overwritten from CSS using the following rule: ```css title="Resource column width" .mbsc-timeline-resource-col { width: 200px; } ``` The width of the resource column adjusts as resources are expanded or collapsed. The default increment step can be modified with a CSS rule: ```css title="Resource expand step" .mbsc-timeline-resource-depth-step { width: 20px; } ``` If the step adjustment is not needed, it can disabled by setting the value to `width: 0;`. ### Resource row height There are three CSS classes which can be used for [changing the height of resource rows](https://demo.mobiscroll.com/timeline/setting-row-height): 1. For setting the resource row heights in general, you can use the `.mbsc-timeline-row` class. ```css .mbsc-timeline-row { height: 80px; } ``` 2. For setting the height of the parent resources, you can use the `.mbsc-timeline-parent` class. ```css .mbsc-timeline-parent { height: 30px; } ``` :::info There's minimum height of the rows which can only be decreased if the event creation is disabled on the relevant resource. You can prevent event creation by using the `eventCreation` property of the the [`resources`](#opt-resources) option. ::: 3. For customizing the remaining empty space below the events, you can use the `.mbsc-timeline-row-gutter` class. ```css .mbsc-timeline-row-gutter { height: 6px; } ``` ### Hide empty resources Rows without any events can be hidden by setting `hideEmptyRows` to `true` under the [view](#configuring-the-view) configuration. :::info Parent resources will always be displayed, even when empty. If [resolutionVertical](#view-timeline-resolutionVertical) is set to `'day'` and all resources for a given day are empty, the entire day will be hidden. ::: ### Hide invalid resources Fully invalid rows can be hidden by setting `hideInvalidRows` to `true` under the [view](#configuring-the-view) configuration. :::info A resource row is considered fully invalid if it contains [invalid](#opt-invalid) periods defined with `allDay`, date values, or a single time range that covers a full day or multiple days. Parent resources will always be displayed, even when fully invalid. If [resolutionVertical](#view-timeline-resolutionVertical) is set to `'day'` and all resources for a given day are fully invalid, the entire day will be hidden. ::: ## Virtual scroll Virtual scroll is a performance optimization that ensures smooth scrolling and fast rendering when displaying large numbers of events or resources in the timeline. The timeline view is virtualized, meaning its markup is dynamically generated and managed as needed. As you scroll vertically or horizontally, the component updates what's visible in real time, only rendering the elements that appear in the viewport. This approach dramatically improves performance for large datasets: events and resources are not all loaded into memory at once, keeping the interface fast and responsive. When virtual scroll is enabled, the timeline calculates which items should be displayed based on the current scroll position. Only the visible portion of the view is rendered, while non-visible parts are skipped until they come into view. Scrolling triggers the [onVirtualLoading](#event-onVirtualLoading) lifecycle event, which can be used to load data incrementally during scrolling, instead of fetching everything upfront. You can see an example of this pattern in the [Load resources on scroll demo](https://demo.mobiscroll.com/timeline/load-resources-on-scroll). The calendar needs to be to placed inside a container which has a height. This can be either a fixed height, a height in percentage, or a flex height. When the calendar is placed directly in a container with a fixed height, it will work out of the box. If the height of the container is specified in percentage, e.g. you'd like to fill the full page height, you need to make sure that all parent elements also have height: 100% specified, up until the body and html elements, or until the closest parent which has a fixed height. If the container is inside a parent with flex layout, it will also work out of the box. In some cases, you may want to disable virtual scroll, for example: - When working with a small dataset that doesn't benefit from virtualization. - When you need to access or manipulate all DOM elements at once. To disable it, set [virtualScroll](#view-timeline-virtualScroll) to `false`. ## Event connections The Timeline view can [display connections between events](https://demo.mobiscroll.com/timeline/connecting-linking-events-arrows). Events will be linked with lines and additionally arrows can be displayed to illustrate the direction of the connection. Events can have multiple connections simultaneously. Connections can be specified with the [`connections`](#opt-connections) option. ![Timeline event connections](/img/event-connections.png) ## Event order The rendered event order is determined by the following two concepts: 1. Event data order 2. Event layout The combination of these concepts results in the final rendered event order. ### Event data order The sequence in which events are processed before being passed to the layout algorithm. The default ordering rules are as follows: 1. All-day events are placed at the top. 2. Non-all-day events follow, sorted by their start times. 3. Events with the same start time are further ordered alphabetically by their titles. This default order can be modified using the `order` property in the event [event data](#opt-data). The order property takes precedence over the default rules. If two events have the same order value, the default rules apply. For more complex ordering requirements, the [eventOrder](#opt-eventOrder) option can be used. This option accepts a function that compares two events and returns an order (-1 or 1). ### Event layout The event layout process determines the visual positioning and dimensions of events. This is a built-in functionality and cannot be altered externally. The layout algorithm processes the sorted event list and calculates each event's position and size. The algorithm follows these steps: 1. The first event is placed in the first position of the event track. 2. If two or more events overlap in their start/end times, the later event is placed in the next event track, positioned below to the previous event. 3. If a subsequent event does not overlap with any already added events, it is placed back in the first event track. 4. This process continues until all events are positioned within their respective rows. ## Responsiveness The Timeline is fully responsive. It adapts to the available space and fills the screen to look good everywhere. While you don't have to worry about the width the height can be manually adjusted with the [height](#opt-height) option. This specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. Use the [responsive](#opt-responsive) option to configure how the calendar behaves on different sized screens. The responsive option is equipped with five breakpoints: - `xsmall` (up to 575px), - `small` (up to 767px), - `medium` (up to 991px), - `large` (up to 1199px), - `xlarge` (from 1200px). Also, custom breakpoints can be added if necessary: - `my-custom-breakpoint: { breakpoint: 600 }` (from 600px up to the next breakpoint). :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries. ::: ```html title='Responsive configuration with the view option' ``` ```ts @Component({...}) export class MyComponent { myResponsive: MbscEventcalendarView = { xsmall: { view: { timeline: { type: 'day', size: 2 }} }, medium: { view: { timeline: { type: 'week' } } }, custom: { // Custom breakpoint, you can use multiple if needed, but each must have a unique name. breakpoint: 1000, view: { timeline: { type: 'month' }} } }; } ``` ![Timeline responsive behavior](/img/timeline-responsive.gif) ## Zoom Levels The timeline view allows you to define and use multiple zoom levels, making it easy to switch between different time scales. You can select a specific zoom level to focus on the desired level of detail. ### Configuring Zoom Levels Zoom levels are set up in the [zoomLevels](#view-timeline-zoomLevels) property of the timeline view. Each zoom level can have its own options for customizing the timeline's layout and behavior. You can specify a zoom level using number or string-based keys, and the corresponding view options will be applied. ### Available options - [type](#view-timeline-type) - [size](#view-timeline-size) - [resolutionHorizontal](#view-timeline-resolutionHorizontal) - [resolutionVertical](#view-timeline-resolutionVertical) - [columnWidth](#view-timeline-columnWidth) - [currentTimeIndicator](#view-timeline-currentTimeIndicator) - [startDay](#view-timeline-startDay) - [endDay](#view-timeline-endDay) - [startTime](#view-timeline-startTime) - [endTime](#view-timeline-endTime) - [timeCellStep](#view-timeline-timeCellStep) - [timeLabelStep](#view-timeline-timeLabelStep) - [weekNumbers](#view-timeline-weekNumbers) ### Example Configuration ```ts view: { timeline: { zoomLevels: { -4: { type: 'year', size: 6, resolutionHorizontal: 'year' }, -3: { type: 'month', size: 6, resolutionHorizontal: 'month' }, -2: { type: 'week', size: 5, resolutionHorizontal: 'week' }, -1: { type: 'week', size: 5, resolutionHorizontal: 'day' }, 0: { type: 'week', size: 5, resolutionHorizontal: 'day', columnWidth: 'large' }, 1: { type: 'week', size: 5, resolutionHorizontal: 'day', columnWidth: 'xlarge' }, 2: { type: 'day', size: 3, resolutionHorizontal: 'hour', timeCellStep: 360, timeLabelStep: 360 }, 3: { type: 'day', size: 3, resolutionHorizontal: 'hour', timeCellStep: 180, timeLabelStep: 360 }, 4: { type: 'day', size: 3, resolutionHorizontal: 'hour', timeCellStep: 30, timeLabelStep: 60 }, } } }, zoomLevel: 0 ``` ### Setting the Active Zoom Level The [zoomLevel](#opt-zoomLevel) option determines which zoom level is currently active. When set, the timeline automatically applies the corresponding settings from zoomLevels. :::info To ensure the calendar view is correctly aligned when zooming, the getViewDate() method is used to retrieve the current middle date of the visible calendar view. Based on the zoom level, the [refDate](#opt-refDate) is set to a corresponding date, ensuring that the view date can always be scrolled to the center. ::: Learn how to implement and adjust zoom levels by checking [this example](https://demo.mobiscroll.com/timeline/calendar-zoom#). ## Templating The display of Timeline can be customized with different [templating functions](#templates). ### The cell Use the [cellTemplate](#template-cellTemplate) option to fully customize the Timeline cells. Customize how the cell look and what they show. The template gets an object with properties like date, events, colors, invalids, resource, and slot which can be used to display custom content. :::info Since cells are rendered frequently while scrolling, keep the customization lightweight for best performance. ::: Check out how you can style the cell in [this example](https://demo.mobiscroll.com/scheduler/dynamic-cell-content-template#) or just play with the slider below to see the differences. ### The resource, their header and footer There are three approaches you can take: - Use the [resourceTemplate](#template-resourceTemplate) option to customize the resource template of the Timeline. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](#opt-resources) array. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. - Customize the empty cell content above the resource column with the [resourceHeaderTemplate](#template-resourceHeaderTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. - Or if you want to customize the empty cell content below the resource column you can achieve this with the [resourceFooterTemplate](#template-resourceFooterTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the Timeline view, if the [dayFooterTemplate](#template-dayFooterTemplate) option is present. Check out how you can style these resource parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#) or just play with the slider below to see the differences. ### The sidebar, their header and footer Besides the resource template, an additional sidebar can be rendered on the opposite end of the row and there are three approaches you can take: - Use the [sidebarTemplate](#template-sidebarTemplate) option to render a custom sidebar on the right side of the Timeline. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. The template will receive the resource object as data. This data can be used to show resource specific things on the sidebar. - Customize the empty cell content above the sidebar column with the [sidebarHeaderTemplate](#template-sidebarHeaderTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the Timeline view, if the [sidebarTemplate](#template-sidebarTemplate) option is present. - Or if you want to customize the empty cell content below the sidebar column you can achieve this with the [sidebarFooterTemplate](#template-sidebarFooterTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. This element only renders for the Timeline view, if the [sidebarTemplate](#template-sidebarTemplate) option is present. Check out how you can style the sidebar parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#) or just play with the slider below to see the differences. ### The date header and footer The headers hold key information like the date, day of the week and in some cases it also holds the full date. Whenever you need to show extra information, or if you would like to change the styling or date format, time format you can use the various header templates, depending on the view configuration. You can also show a footer element, for displaying more information. Depending on the resolution, the first Timeline row under the navigation header can show a line for each of the following: #### Hourly header/footer template With an hourly (or sub-hourly) resolution the [hourTemplate](#template-hourTemplate) and [hourFooterTemplate](#template-hourFooterTemplate) options can be used for customizing the header and footer. #### Daily header/footer template With a daily resolution, the [dayTemplate](#template-dayTemplate) and [dayFooterTemplate](#template-dayFooterTemplate) options can come in handy for customizing the header and footer. #### Weekly header/footer template When the resolution is weekly, the [weekTemplate](#template-weekTemplate) and [weekFooterTemplate](#template-weekFooterTemplate) options can be used. #### Monthly header/footer template When displaying multiple months, the [monthTemplate](#template-monthTemplate) and [monthFooterTemplate](#template-monthFooterTemplate) options can be used for customizing the header and footer per month. #### Quarter header/footer template When displaying multiple quarters, the [quarterTemplate](#template-quarterTemplate) and [quarterFooterTemplate](#template-quarterFooterTemplate) options can be used for customizing the header and footer per quarter. #### Yearly header/footer template With a yearly resolution, the [yearTemplate](#template-yearTemplate) and [yearFooterTemplate](#template-yearFooterTemplate) options can be used for customizing the header and footer. Check out how you can style the date header and footer in [this example](https://demo.mobiscroll.com/timeline/hour-day-week-month-quarter-year-header-footer-template#) or just play with the sliders above to see the differences. ### The event and buffer areas You can use the [scheduleEventTemplate](#template-scheduleEventTemplate) option. to customize the events that appear on the scheduler. It should return the markup of the event. The Eventcalendar will take care of the positioning, but anything else you want to show is up to you - like a title, description, color the background or show any content. The buffers can be customized through the [bufferBeforeTemplate](#template-bufferBeforeTemplate) and [bufferAfterTemplate](#template-bufferAfterTemplate) options. These can help you visualise delays or added minutes for tasks. For example travel time for meetings/appointments, check in/check out for flights. Check out how you can style the events and the buffer areas in [this example](https://demo.mobiscroll.com/angular/timeline/timeline-custom-event-rendering#) or just play with the slider below to see the differences. ### The event content If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [scheduleEventContentTemplate](#template-scheduleEventContentTemplate) option. Mobiscroll will position the event to the right place and will render essential information like the color of the event, the time and if it's an all day event or not. The title, description and any other fields you want to show (like participants or an avatar) will be coming from your custom function. Check out how you can style the event content in [this example](https://demo.mobiscroll.com/angular/timeline/meal-planner#) or just play with the slider below to see the differences. ### The event slots Use the [slotTemplate](#template-slotTemplate) option to customize the slot template of the Timeline view. Customize how the time slots look and what they show. Utilize properties passed in the [slots](#opt-slots) array. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well. Check out how you can style the slots in [this example](https://demo.mobiscroll.com/angular/timeline/shift-template#) or just play with the slider below to see the differences. ### The timeline header Customize how the header of the Timeline looks and how the components are arranged with the [headerTemplate](#template-headerTemplate) option. It takes a function that should return the desired markup. In the returned markup, you can use custom html as well as the built in header components of the calendar. While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's [building blocks](/angular/eventcalendar/templating#header-templating). These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. Check out how you can style the Timeline header in [this example](https://demo.mobiscroll.com/timeline/switching-day-week-work-week-timeline) or just play with the slider below to see the differences. ### Variable event height When using [event templating](./templating#event-templating), you might end up with various event heights, depending on the displayed content, e.g. larger description, list of tasks, etc. By default this might not show up correctly, resulting in events overlapping each other. You can enable support for variable event heights by setting the `eventHeight: 'variable'` property for the timeline inside the [`view`](./api#opt-view) option. This will enable a new rendering mode. In case of large views, where virtual scrolling is used, the height of the rows might change dynamically as new events are loaded into the view during scroll. ![Timeline variable event heights](/img/timeline-variable-event-height.png) ## API Here is a comprehensive list of all the specific options, events and methods of the Timeline view. ### Options Explore the following API options that help you easily configure the Timeline. ### clickToCreate boolean | "double" | "single" Enable new event creation on click. If `true` or `'double'`, a new event will be created only with a double click and with the `'single'` value the event will be created instantly with a single click. This option will only work on desktop environment where mouse events are fired. It will also allow deleting of the focused events using the Delete or Backspace key. In touch environment a long tap should be used to create a new event and it is controlled by the [dragToCreate](#opt-dragToCreate) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### colors Array<[MbscCalendarColor](#type-MbscCalendarColor)> Specifies the color for certain dates or date ranges on the calendar. The [`MbscCalendarColor`](#type-MbscCalendarColor) type has the following properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The colored range will be considered all-day if: - the `allDay` property is explicitly set. - the `start` / `end` properties are not specified, only the `date`. ::: :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The colors can be combined with the [labels](#opt-labels) or [marked](#opt-marked) options. ::: ```js [ { date: new Date(2020, 2, 23), background: 'pink' }, { date: new Date(2020, 2, 24), background: 'green' }, { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } }, { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } } ] ``` **Default value**: `undefined` ### connections Array<[MbscEventConnection](#type-MbscEventConnection)> Specifies connections between events. On the UI events will be linked with lines and additionally arrows can be displayed to illustrate the direction of the connection. Events can have multiple connections simultaneously. An array of connection objects can be passed. The [`MbscEventConnection`](#type-MbscEventConnection) type has the following properties: - `arrow`: *boolean | "from" | "to" | "bidirectional"* - Specifies where to display arrows If `true`, the arrow will display only at the end side of the connection. - `color`: *string* - Specifies the color of the connection. - `cssClass`: *string* - Custom CSS class for the connection line for further customization. - `from`: *string | number* - The id of the event where the connection will begin - `to`: *string | number* - The id of the event where the connection will end. - `type`: *"fs" | "sf" | "ss" | "ff"* - The type of the connection. Possible values: `'fs'` - finish-to-start, `'sf'` - start-to-finish, `'ss'` - start-to-start, `'ff'` - finish-to-finish. **Default value**: `undefined` ### context string | HTMLElement The DOM element in which the popups (event popover, year and month picker) are rendered. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> The events for the Eventcalendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The event objects may have additional custom properties as well. The custom properties are not used by the event calendar, but they are kept and will be available anywhere the event objects are used. E.g. the [onEventClick](#event-onEventClick) event will receive the event object as argument, containing the custom properties as well. ::: :::info Use the [getEvents](#method-getEvents) method to get the events between two dates. ::: ```js data: [ { start: new Date(2021, 5, 23), end: new Date(2021, 5, 30), title: 'Conference', allDay: true, color: 'red' }, { title: 'Work project', recurring: { repeat: 'daily', until: '2021-04-01' }, recurringException: ['2021-03-15', '2021-03-25'], recurringExceptionRule: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelectedDate [MbscDateType](#type-MbscDateType) Specifies the initial selected date on the calendar. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### dragBetweenResources boolean If `false`, the events will not be moveable across resources, only in time. To control movement in time, use the [dragInTime](#opt-dragInTime) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragBetweenSlots boolean If `false`, the events will not be moveable across slots, only in time and resource. To control movement in time, use the [dragInTime](#opt-dragInTime) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragInTime boolean If `false`, the events will not be moveable in time. In case of the scheduler and timeline views events events can still be moved between resources. To control movement between resources, use the [dragBetweenResources](#opt-dragBetweenResources) option. Consider that [dragToMove](#opt-dragToMove) has to be enabled. **Default value**: `true` ### dragTimeStep number Specifies the steps in minutes for the scheduler and timeline events during drag. **Default value**: `15` ### dragToCreate boolean If `true`, dragging on an empty cell will create a new event. It will also allow deleting of the focused events using the Delete or Backspace key. The title of the new event can be specified with the [newEventText](#opt-newEventText) option. Using the [extendDefaultEvent](#opt-extendDefaultEvent) option extra properties can be set for the created event. The event deletion functionality can be overwritten using the [eventDelete](#opt-eventDelete) option. **Default value**: `undefined` ### dragToMove boolean If `true`, the events will be moveable. **Default value**: `undefined` ### dragToResize boolean If `true`, the events will be resizable. **Default value**: `undefined` ### eventDelete boolean Enables or disables event deletion. When `true`, the focused event will be deleted on pressing the Delete or Backspace keys on the keyboard. By default the event deletion depends on the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. If either of those are `true`, and no `eventDelete` option is set, then event deletion is also enabled, otherwise not. **Default value**: `undefined` ### eventOrder (event1: [MbscCalendarEvent](#type-MbscCalendarEvent), event2: [MbscCalendarEvent](#type-MbscCalendarEvent)) => number Determines the ordering of the events within the same day. Can be a function that accepts two event objects as arguments and should return -1 or 1. If not specified, the default order is: - all day events - rest of events, sorted by start time; events with identical start times, will be ordered alphabetically based on their title **Default value**: `undefined` ### eventOverlap boolean If `false`, the events cannot overlap. **Default value**: `true` ### exclusiveEndDates boolean If `true`, the Eventcalendar will work in exclusive end dates mode, meaning that the last moment of the range (event, invalid, colors, etc.) is not part of the range. E.g. `end: '2021-07-03T00:00'` means that the event ends on 2nd of July and will not be displayed on 3rd of July. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: ### extendDefaultEvent (args: MbscNewEventData) => void | [MbscCalendarEvent](#type-MbscCalendarEvent) Use this option to set properties to the new event created with click or drag. The event creation is handled by the [clickToCreate](#opt-clickToCreate) and [dragToCreate](#opt-dragToCreate) options. It takes a function that should return the properties for the new event. The argument object passed to this function has the following properties: - `start`: *Date* - The date when the newly created event will start. - `resource`: *string | number* - The id of the resource where the event creation started. ```js extendDefaultEvent: (args) => { return { color: args.resource === 'admin' ? 'green' : 'red', title: 'My event', }; } ``` **Default value**: `undefined` ### externalDrag boolean If `true`, external drag & drop is allowed and events can be dragged outside of the component view. **Default value**: `undefined` ### externalDrop boolean If `true`, external events can be dragged into the view. **Default value**: `undefined` ### externalResourceDrag boolean If `true`, external drag & drop is allowed and resource can be dragged outside of the component view. **Default value**: `undefined` ### externalResourceDrop boolean If `true`, external resources can be dragged into the view. **Default value**: `undefined` ### height string | number Sets the height of the component. The height of the calendar view impacts the number of labels that fit into a table cell. A "show more" label will be displayed for events that don't fit. **Default value**: `undefined` ### immutableData boolean If `true`, the Eventcalendar will work in immutable mode. In this mode the component won't update the data directly, only fire the necessary lifecycle events, where the original data can be updated manually. **Default value**: `undefined` ### invalid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the invalid values. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the invalid range is all day or not. - `start`: *Date | string | object* - Start of the invalid range. - `end`: *Date, string | object* - End of the invalid range. - `recurring`: *string | object* - Recurrence rule for recurring invalid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - Specifies the [resource](#opt-resources) ids for the invalid range. The invalid range will be displayed only in the specified resource. If there is no resource defined, the invalid range will be displayed in every resource. - `slot`: *string | number* - Specifies the [slot](#opt-slots) id for the invalid range. The invalid range will be displayed only in the specified slot. If there is no slot defined, the invalid range will be displayed in every slot. - `title`: *string* - Text which will be displayed for the invalid range. Only applicable for the timeline and scheduler views. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### invalidateEvent "strict" | "start-end" Specifies how to validate events against [invalid](#opt-invalid) ranges on create/move/resize: - `'strict'` - The event cannot intersect with an invalid range at all. - `'start-end' - The event start and end cannot be inside an invalid range. **Default value**: `'strict'` ### max [MbscDateType](#type-MbscDateType) Maximum date and time. The calendar cannot be navigated beyond the specified maximum date. If navigation is needed, but event creation should not be allowed after a specific date, use the [invalid](#opt-invalid) option with daily recurrence starting from the specific date. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum date and time. The calendar cannot be navigated beyond the specified minimum date. If navigation is needed, but event creation should not be allowed before a specific date, use the [invalid](#opt-invalid) option with daily recurrence until the specific date. **Default value**: `undefined` ### modules Array Additional modules can be added to the eventcalendar. The option receives an array of module objects. For example, the print module can be added through this option. ```js // import the print module // later on, add it to the modules array: modules: [print] ``` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date for the view calculation, when multiple days, weeks, months or years are displayed. If not specified, for the scheduler and timeline views will be today's date, for the calendar and agenda views will be 1970/01/01. It denotes the reference point when calculating the pages going in the future and in the past. For example if the view type is day, the view size is 3, and the current date is `01/16/2024`, the pages are calculated from this date, so the initial page will contain `[01/16/2024, 01/16/2024, 01/17/2024]`, the next page `[01/18/2024, 01/19/2024, 01/20/2024]` and so on. In case of day view, the reference point will be exactly the specified date. For week, month and year views the reference point will be the start of the week, month or year of the specified day. Changing the reference date will not navigate the calendar to the specified date, it only recalculates the pages from the new reference date. To navigate the view to a specified date and time, use the [selectedDate](#opt-selectedDate) option. **Default value**: `undefined` ### resources Array<[MbscResource](#type-MbscResource)> The scheduler and timeline views can handle multiple resources. Resource grouping can be modified with the help of the [groupBy](#opt-groupBy) option. If set to `null` or `undefined`, all events will be displayed, regardless of their `resource` property. The timeline view will not display the resource column, if the resources option is not set. If set to an empty array, only those events will be displayed which are not tied to any resource. The timeline view will display an empty resource column when an empty array is passed. The timeline view can render multiple levels of hierarchy groups. Levels can be added with the help of the `children` property. The [`MbscResource`](#type-MbscResource) type has the following properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. ```js resources: [ { id: 1, name: 'Flatiron Room', color: '#f7c4b4' }, { id: 2, name: 'The Capital City', color: '#c6f1c9' }, { id: 3, name: 'Heroes Square', color: '#e8d0ef' } ] ``` **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### selectMultipleEvents boolean When `true`, enables multiple event selection on the calendar. **Default value**: `false` ### selectedDate [MbscDateType](#type-MbscDateType) Specifies the selected date on the calendar. This can be changed programmatically and when changed the calendar will automatically navigate to the specified date. For views, where time is also displayed, the view will be scrolled to the specified time. If the time part is not explicitly specified, it defaults to the start of the day. This does not change the reference date that defines the reference point of the navigation pages. To change the reference point for the navigation (e.g. start the paging from the newly selected date) use the [refDate](#opt-refDate) option. You also need to pass a handler for the [onSelectedDateChange](#event-onSelectedDateChange) event to update the selected date when the date is changed from the calendar. **Default value**: `undefined` ### selectedEvents Array<[MbscCalendarEvent](#type-MbscCalendarEvent)> Specifies the selected events on the calendar. The [onSelectedEventsChange](#event-onSelectedEventsChange) event will be fired when the selected events change from the calendar. The [`MbscCalendarEvent`](#type-MbscCalendarEvent) type has the following properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. **Default value**: `undefined` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showControls boolean Show or hide the calendar header controls: the previous and next buttons, and the current view button together with the year and month picker. **Default value**: `true` ### showEventBuffer boolean If `true`, it will display the event buffers defined in the [event data](#opt-data). **Default value**: `true` ### showEventTooltip boolean If `false`, it will hide the native tooltip that shows up when hovering over an event. **Default value**: `true` ### slots Array<[MbscSlot](#type-MbscSlot)> The slots, besides the [resources](#opt-resources) introduce a horizontal level of data grouping to the timeline view. If set to `null` or `undefined`, all events will be displayed, regardless of their slot property. If set to an empty array, only those events will be displayed which are not tied to any slot. The [`MbscSlot`](#type-MbscSlot) type has the following properties: - `eventDragBetweenSlots`: *boolean* - Specifies whether the event is movable across slots. - `id`: *string | number* - The id of the slot. It that can be referenced in the events/invalids/colors data. - `name`: *string* - The name of the slot that will be displayed at the top of the slot column. ```js slots: [ { id: 1, name: 'Morning shift', }, { id: 2, name: 'Afternoon shift', } ] ``` **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### width string | number Sets the width of the component. **Default value**: `undefined` ### zoomLevel string | number Specifies the current zoom level of the timeline view. The zoom levels can be listed using the `zoomLevels` property of the timeline inside the view option. **Default value**: `undefined` ### Events The Timeline ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onCellClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event object has the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellDoubleClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is double-clicked on the calendar day, scheduler cell, or timeline cell. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellHoverIn (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered day. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellHoverOut (args: MbscCellHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a day on the calendar view (does not apply for agenda view). Parameters: - args - The event argument with the following properties: - `colors`: *Array* - The colors for the hovered cell. - `date`: *Date* - The date of the hovered cell. - `events`: *Array* - The events for the hovered cell. - `invalids`: *Array* - The invalid dates for the hovered cell. - `labels`: *Array* - If the cell has labels, contains the label objects for the hovered cell. - `marked`: *Array* - If the cell is marked, contains the marked objects for the hovered cell. - `selected`: *boolean* - Specifies if the cell is currently selected or not (in case of calendar view). - `target`: *HTMLElement* - The DOM element of the cell. - `resource`: *MbscResource* - The resource object for the hovered cell. - inst - The component instance. ### onCellRightClick (args: MbscCellClickEvent, inst: EventcalendarBase) => void Triggered when a cell is right-clicked on the calendar, scheduler, or timeline grid . Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `events`: *Array* - The events for the clicked date. - `resource`: *string | number* - The id of the resource where the cell was clicked, if [resources](#opt-resources) are set. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onEventClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventCreate (args: MbscEventCreateEvent, inst: EventcalendarBase) => void Triggered when an event is about to create and it is not yet rendered on its final position. Event creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The newly created event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being created. - inst - The component instance. ### onEventCreateFailed (args: MbscEventCreateFailedEvent, inst: EventcalendarBase) => void Triggered when an event creation failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `originEvent`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the event was created by dragging a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - inst - The component instance. ### onEventCreated (args: MbscEventCreatedEvent, inst: EventcalendarBase) => void Triggered when an event is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `action`: *'click' | 'drag' | 'externalDrop'* - The action which created the event. - `event`: *MbscCalendarEvent* - The newly created event. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was created. - `target`: *HTMLElement* - The DOM element of the created event. - `resourceObj`: *MbscResource* - The resource where the event is being created, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is being created, if [slots](#opt-slots) are set. - inst - The component instance. ### onEventDelete (args: MbscEventDeleteEvent, inst: EventcalendarBase) => void Triggered when an event is about to be deleted and it is not yet removed from the view. Event deletion can be performed with delete and backspace button on an active event. Deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from of the keydown action. - `event`: *MbscCalendarEvent* - The event being deleted. - `events`: *Array* - The events being deleted in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event is being deleted. - inst - The component instance. ### onEventDeleted (args: MbscEventDeletedEvent, inst: EventcalendarBase) => void Triggered when an event is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The deleted event. - `events`: *Array* - The deleted events in case of multiple event selection. - `source`: *'agenda' | 'calendar' | 'timeline' | 'schedule'* - The view where the event was deleted. - inst - The component instance. ### onEventDoubleClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is double-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicker, if [slots](#opt-slots) are set. - `slotObj`: *MbscResource* - The resource where the event was clicker, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventDragEnd (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has ended. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event was dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event was dragged. - inst - The component instance. ### onEventDragEnter (args: MbscEventDragEvent) => void Triggered when an event is dragged into the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragLeave (args: MbscEventDragEvent) => void Triggered when an event is dragged out form the calendar/timeline/schedule view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. ### onEventDragStart (args: MbscEventDragEvent, inst: EventcalendarBase) => void Triggered when an event drag has started. Parameters: - args - The event argument with the following properties: - `action`: *'create' | 'resize' | 'move'* - The user action which triggered the event. - `domEvent`: *Event* - The DOM event of the drag. - `event`: *MbscCalendarEvent* - The dragged calendar event. - `resource`: *string | number* - The id of the resource where the event is dragged, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is dragged, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is dragged, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is dragged, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'schedule' | 'timeline'* - The view where the event is dragged. - inst - The component instance. ### onEventHoverIn (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event is hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event is hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event is hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event is hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event is hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event is hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventHoverOut (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves an event on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was hovered. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the hover. - `event`: *MbscCalendarEvent* - The hovered calendar event. - `resource`: *string | number* - The id of the resource where the event was hovered, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was hovered, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was hovered, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was hovered, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was hovered. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventRightClick (args: MbscEventClickEvent, inst: EventcalendarBase) => void Triggered when an event is right-clicked. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date on which the event was clicked. In case of the timeline view, this will be the first day of the event on the current view. - `domEvent`: *Event* - The DOM event of the click. - `event`: *MbscCalendarEvent* - The clicked calendar event. - `resource`: *string | number* - The id of the resource where the event was clicked, if [resources](#opt-resources) are set. - `resourceObj`: *MbscResource* - The resource where the event was clicked, if [resources](#opt-resources) are set. - `slot`: *string | number* - The id of the slot where the event was clicked, if [slots](#opt-slots) are set. - `slotObj`: *MbscSlot* - The slot where the event was clicked, if [slots](#opt-slots) are set. - `source`: *'agenda' | 'calendar' | 'schedule' | 'timeline' | 'popover'* - The view where the event was clicked. - `target`: *HTMLElement* - The DOM element of the event. - inst - The component instance. ### onEventUpdate (args: MbscEventUpdateEvent, inst: EventcalendarBase) => void Triggered when an event is about to update. Update can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `oldResource`: number | string - The id of the resource from which the event was dragged. - `oldResourceObj`: *MbscResource* - The resource from which the event was dragged. - `oldSlot`: number | string - The id of the slot from which the event was dragged. - `oldSlotObj`: *MbscSlot* - The slot from which the event was dragged. - `resource`: number | string - The id of the resource where the event was dropped. - `resourceObj`: *MbscResource* - The resource where the event was dropped. - `slot`: number | string - The id of the slot where the event was dropped. - `slotObj`: *MbscSlot* - The slot where the event was dropped. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event is being updated. - inst - The component instance. ### onEventUpdateFailed (args: MbscEventUpdateFailedEvent, inst: EventcalendarBase) => void Triggered when an event update failed due to overlapping an invalid range or another event. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `invalid`: *object* - The invalid object which the event overlapped. - `overlap`: *MbscCalendarEvent* - The overlapped event. - `newEvent`: *MbscCalendarEvent* - The newly created event. Will be set only if the dragged event was a recurring event occurrence. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEventOccurrence`: *MbscCalendarEvent* - The occurrence of the event which was dragged. Will be set only if the dragged event was a recurring event occurrence. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - inst - The component instance. ### onEventUpdated (args: MbscEventUpdatedEvent, inst: EventcalendarBase) => void Triggered when an event is updated and is rendered in its new position. This is where you update the event in your database or persistent storage. Parameters: - args - The event argument with the following properties: - `event`: *MbscCalendarEvent* - The updated event. - `events`: *Array* - The updated events. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `oldEvent`: *MbscCalendarEvent* - The original event before the update. - `oldEvents`: *Array* - The original events before the update. It is set on recurring event delete, when [multiple event selection](#opt-selectMultipleEvents) is enabled. - `resourceObj`: *MbscResource* - The resource where the event is updated, if [resources](#opt-resources) are set. - `slotObj`: *MbscSlot* - The slot where the event is updated, if [slots](#opt-slots) are set. - `source`: *'calendar' | 'timeline' | 'schedule'* - The view where the event was updated. - `target`: *HTMLElement* - The DOM element of the updated event. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onPageChange (args: MbscPageChangeEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscPageLoadedEvent, inst: EventcalendarBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscPageLoadingEvent, inst: EventcalendarBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onResourceClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceCollapse (args: MbscResourceCollapseEvent, inst: EventcalendarBase) => void Triggered when a parent resource is collapsed on the timeline. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the click. - `resource`: *string | number* - The id of the collapsed [resource](#opt-resources). - `resourceObj`: *MbscResource* - The collapsed [resource](#opt-resources). - inst - The component instance. ### onResourceCreate (args: MbscResourceCreateEvent, inst: EventcalendarBase) => void Triggered when an resource is about to create and it is not yet rendered on its final position. Resource creation can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The newly created resource. - inst - The component instance. ### onResourceCreated (args: MbscResourceCreatedEvent, inst: EventcalendarBase) => void Triggered when a resource is created and it is rendered in its position. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The newly created resource. - inst - The component instance. ### onResourceDelete (args: MbscResourceDeleteEvent, inst: EventcalendarBase) => void Triggered when an resource is about to be deleted and it is not yet removed from the view. Resource deletion can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The former position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The resource being deleted. - inst - The component instance. ### onResourceDeleted (args: MbscResourceDeletedEvent, inst: EventcalendarBase) => void Triggered when a resource is deleted and it is removed from the view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event from the end of the gesture (mouseup or touchend). - `index`: *number* - The former position of the resource within its siblings. - `parent`: *MbscResource* - The parent resource. - `resource`: *MbscResource* - The deleted resource. - inst - The component instance. ### onResourceDoubleClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is double-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onResourceDragEnter (args: MbscResourceDragEvent, inst: EventcalendarBase) => void Triggered when a resource is dragged into the timeline view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `resource`: *MbscResource* - The dragged resource. - inst - The component instance. ### onResourceDragLeave (args: MbscResourceDragEvent, inst: EventcalendarBase) => void Triggered when a resource is dragged out from the timeline view. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the drag. - `resource`: *MbscResource* - The dragged resource. - inst - The component instance. ### onResourceExpand (args: MbscResourceExpandEvent, inst: EventcalendarBase) => void Triggered when a parent resource is expanded on the timeline. Parameters: - args - The event argument with the following properties: - `domEvent`: *Event* - The DOM event of the click. - `resource`: *string | number* - The id of the expanded [resource](#opt-resources). - `resourceObj`: *MbscResource* - The expanded [resource](#opt-resources). - inst - The component instance. ### onResourceHoverIn (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer hovers a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceHoverOut (args: MbscResourceHoverEvent, inst: EventcalendarBase) => void Triggered when the mouse pointer leaves a resource cell on the timeline or scheduler view. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered resource cell in case of group by date. - `resource`: *MbscResource* - The hovered resource. - `source`: *'schedule' | 'timeline'* - The view where the resource cell was hovered. - `target`: *HTMLElement* - The DOM element of the resource cell. - inst - The component instance. ### onResourceOrderUpdate (args: MbscResourceOrderEvent, inst: EventcalendarBase) => void Triggered after a resource is dragged and dropped into a new location. Resource reorder can be prevented by returning `false` from the handler function. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. Parameters: - args - The event argument with the following properties: - `index`: *Resource* - The new position of the resource within its siblings. - `oldIndex`: *Resource* - The old position of the resource within its siblings. - `oldParent`: *Resource* - The old parent resource. - `parent`: *Resource* - The parent resource. - `resource`: *Resource* - The updated resource. - `resources`: Array<*Resource*> - The entire resources array with the new order. - inst - The component instance. ### onResourceRightClick (args: MbscResourceClickEvent, inst: EventcalendarBase) => void Triggered when a resource cell is right-clicked on the scheduler or timeline. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the resource was clicked, when resources are grouped by day. - `domEvent`: *Event* - The DOM event of the click. - `resource`: *MbscResource* - The resource associated with the clicked cell. - `source`: *'schedule' | 'timeline'* - The view where the cell was clicked. - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onSelectedDateChange (args: MbscSelectedDateChangeEvent, inst: EventcalendarBase) => void Triggered when the selected date is changed, e.g. by clicking on a day on a calendar view, or by using the navigation arrows. You can use this event in conjunction with the [selectedDate](#opt-selectedDate) option to customize where the Eventcalendar should navigate. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The newly selected date. - inst - The component instance. ### onSelectedEventsChange (args: MbscSelectedEventsChangeEvent, inst: EventcalendarBase) => void Triggered when an event is selected or deselected on the UI, when [multiple event selection](#opt-selectMultipleEvents) is enabled. You can also select events programmatically using the [selectedEvents](#opt-selectedEvents) option. Parameters: - args - The event argument with the following properties: - `events`: *Array* - The selected events. - inst - The component instance. ### onVirtualLoading (args: MbscVirtualLoadEvent, inst: EventcalendarBase) => void Triggered when a new virtual page is loaded. You can use this to load events and resources on demand while scrolling the timeline grid. Parameters: - args - The event argument with the following properties: - `viewStart`: *Date* - The date where the virtual view starts. - `viewEnd`: *Date* - The date where the virtual view end. - `resourceStart`: *number|string* - The id of the resource where the virtual view starts. - `resourceEnd`: *number|string* - The id of the resource where the virtual view ends. - `oldResourceStart`: *number|string* - The id of the resource where the previous virtual view started. - `oldResourceEnd`: *number|string* - The id of the resource where the previous virtual view ended. - `oldViewStart`: *Date* - The date where the previous virtual view started. - `oldViewEnd`: *Date*- The date where the previous virtual view ended. - inst - The component instance. ### Localization The Timeline is fully localized. This covers date and time format, button copy, rtl and more. ### allDayText string Text for all day events. **Default value**: `'All-day'` ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateFormatLong string Long date format, used by the agenda view and timeline day headers. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'D DDD MMM YYYY'` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### newEventText string Title for the newly created event with the [dragToCreate](#opt-dragToCreate) and the [clickToCreate](#opt-clickToCreate) action. **Default value**: `'New event'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### quarterText string Text for quarter numbers in the timeline header. The {count} inside the string will be replaced with the number of the current quarter. **Default value**: `'Q {count}'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### weekText string Text for week numbers in the timeline header. The {count} inside the string will be replaced with the number of the current week. **Default value**: `'Week {count}'` ### Templates The display of the Timeline can be customized with different templating functions. ### bufferAfterTemplate Template reference to fully customize the buffer area that is displayed at the end of the scheduler and timeline events. The buffer can be defined with the help of the `bufferAfter` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### bufferBeforeTemplate Template reference to fully customize the buffer area that is displayed at the start of the scheduler and timeline events. The buffer can be defined with the help of the `bufferBefore` property of the [event data](#opt-data). The template will receive an event object as data. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### cellTemplate Customize the cells of the Eventcalendar in scheduler and timeline views. The template will receive an object as context, which can be used to display custom content in the cells. Keep the cell template simple, as it will be called and rendered **very frequently** during scroll and view changes. The object passed to the template contains the following properties: - `colors`: _Array_ - The list of colors for the current cell. - `date`: _Date_ – The current cell's date. - `events`: _Array_ List of events for the current cell. - `invalids`: _Array_ - The list of invalids for the current cell. - `resource`: _MbscResource_ - The resource object of the current cell. - `slot`: _MbscSlot_ - The slot object of the rendered cell. **Default value**: `undefined` ### dayContentTemplate Customize the day cells content of the event calendar. The Eventcalendar will take care of the styling and you can focus on what you show beside the day number. If you are looking to fully customize the day (e.g. add custom hover effects) you will need to use the [dayTemplate](#template-dayTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. **Default value**: `undefined` ### dayFooterTemplate Template to customize the footer of each day for the timeline. The following day specific details are available: - `date`: _Date_ - The date of the day. - `events`: _Array_ - The list of events for the day. **Default value**: `undefined` ### dayTemplate Customize the day cells of the calendar view and the date header in case of scheduler and timeline views. If you are looking to customize only the day cells content and don't want to bother with the styling of the event, in case of calendar and scheduler views you can use the [dayContentTemplate](#template-dayContentTemplate) option. The template will receive an object as data. This data can be used to show day specific things on the Eventcalendar. The object passed to the template has the following properties: - `date`: Date object - The specific date as a Date object. - `selected`: Boolean - True if the date is selected. (In case of calendar view) - `events`: Array - The list of events of the day. - `resource`: String, Number - The id of the resource in case of scheduler(week and month views) when the events are grouped by resources. - `isActive`: Boolean - On the timeline view, this parameter will be true when rendering the current day/week/month/year **Default value**: `undefined` ### headerTemplate Template to customize the header of the event calendar. You can use custom markup or components as well as the built in header components of the calendar. **Default value**: `undefined` ### hourFooterTemplate Template to customize the footer of the hour columns on the timeline view. The following properties are available: - `date`: _Date_ - The date and time of the rendered hour. - `events`: _Array_ - The list of events for the hour. - `isActive`: _boolean_ - True for the current hour. **Default value**: `undefined` ### hourTemplate Template to customize the header of the hour columns on the timeline view. The following properties are available: - `date`: _Date_ - The date and time of the rendered hour. - `events`: _Array_ - The list of events for the hour. - `isActive`: _boolean_ - True for the current hour. **Default value**: `undefined` ### monthFooterTemplate Template to customize the footer of the month column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered month. - `events`: _Array_ - The list of events for the month. - `isActive`: _boolean_ - True for the current month. **Default value**: `undefined` ### monthTemplate Template to customize the header of the month column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered month. - `events`: _Array_ - The list of events for the month. - `isActive`: _boolean_ - True for the current month. **Default value**: `undefined` ### quarterFooterTemplate Template to customize the footer of the quarter column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered quarter. - `events`: _Array_ - The list of events for the quarter. - `isActive`: _boolean_ - True for the current quarter. **Default value**: `undefined` ### quarterTemplate Template to customize the header of the quarter columns on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered quarter. - `events`: _Array_ - The list of events for the quarter. - `isActive`: _boolean_ - True for the current quarter. **Default value**: `undefined` ### resourceEmptyTemplate Template to customize the content of the resource column in case of an empty resource array. ```html ``` **Default value**: `undefined` ### resourceFooterTemplate Template to customize the cell content below the resource column on the timeline view. **Default value**: `undefined` ### resourceHeaderTemplate Template to customize the cell content above the resource column on the timeline view. **Default value**: `undefined` ### resourceTemplate Template to customize the resource template of the scheduler and timeline views. The following properties are available: - `resource`: _MbscResource_ - The rendered resource. - `day`: _Date_ - The date on which the resource is rendered. Available when grouping by date in the scheduler view, or when vertical day resolution is used in the timeline view. ```html
{{resource.name}}

{{resource.description}}

 ``` **Default value**: `undefined` ### scheduleEventContentTemplate Template to customize the event content that appears on the scheduler and timeline. The Eventcalendar will take care of styling and you can focus on what you show inside of the event. If you are looking to fully customize the event (e.g. add custom hover effects) you will need to use the [scheduleEventTemplate](#template-scheduleEventTemplate) option. In that case you will only get the positioning done by the Eventcalendar and everything else is up to you. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### scheduleEventTemplate Template to customize the events that appear on the scheduler and timeline. The Eventcalendar will take care of the positioning, but everything else (like background color, hover effect, etc.) is left to you. If you are looking to customize only the content (e.g. add custom elements) and don't want to bother with the styling of the event, you can use the [scheduleEventContentTemplate](#template-scheduleEventContentTemplate) option. Some of the event specific details are computed, but there is also a reference to the **original** event they come from. The following event specific properties are available: - `allDay`: _string_ - The localized all-day text in case of all day events. - `end`: _string_ - The formatted end time, if the event is not all day. - `id`: _string_ - The id of the event. - `isMultiDay`: _boolean_ - True if the event spans across multiple days. - `lastDay`: _boolean_ - True if it's rendered on the last day of a multiple event. - `original`: _MbscCalendarEvent_ - The original event object. - `start`: _string_ - The formatted start time, if the event is not all day. - `title`: _string_ - The title of the event. - `currentResource`: _string | number_ - The resource of the row or column where the event is being rendered. **Default value**: `undefined` ### sidebarFooterTemplate Template to customize the empty cell content below the sidebar column. This template is only rendered for the timeline view, if the [sidebarTemplate](#template-sidebarTemplate) is present. **Default value**: `undefined` ### sidebarHeaderTemplate Template to customize the empty cell content above the sidebar column. This template is only rendered for the timeline view, if the [sidebarTemplate](#template-sidebarTemplate) is present. **Default value**: `undefined` ### sidebarTemplate Template to customize and add a sidebar on the right side of the timeline. The template will receive the resource object as data. This data can be used to show resource specific things on the sidebar. **Default value**: `undefined` ### slotTemplate Template to customize the slot template of the timeline view. It will receive an object as parameter that has the following properties: - `date`: _Date_ - The specific date where the slot is rendered. - `slot`: _MbscSlot_ - Data of the rendered slot. ```
{{slotdata.slot.name}}

{{slotdata.slot.description}}

 ``` **Default value**: `undefined` ### weekFooterTemplate Template to customize the footer of the week column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered week. - `events`: _Array_ - The list of events for the week. - `isActive`: _boolean_ - True for the current week. - `endDate`: _Date_ - The end date of the week. - `startDate`: _Date_ - The start date of the week. - `weekNr`: _number_ - The week number. Enumeration starts with the first week of the year. **Default value**: `undefined` ### weekTemplate Template to customize the header of the week column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered week. - `events`: _Array_ - The list of events for the week. - `isActive`: _boolean_ - True for the current week. - `endDate`: _Date_ - The end date of the week. - `startDate`: _Date_ - The start date of the week. - `weekNr`: _number_ - The week number. Enumeration starts with the first week of the year. **Default value**: `undefined` ### yearFooterTemplate Template to customize the footer of the year column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered year. - `events`: _Array_ - The list of events for the year. - `isActive`: _boolean_ - True for the current year. **Default value**: `undefined` ### yearTemplate Template to customize the header of the year column on the timeline view. The following properties are available: - `date`: _Date_ - First day of the rendered year. - `events`: _Array_ - The list of events for the year. - `isActive`: _boolean_ - True for the current year. **Default value**: `undefined` ### Types ### MbscCalendarColor Interface Properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscCalendarEvent Interface Properties: - `allDay`: *boolean* - Specifies if the event is all day or not. - `bufferAfter`: *number* - Defines a buffer time in minutes that will be displayed after the end of the event. - `bufferBefore`: *number* - Defines a buffer time in minutes that will be displayed before the start of the event. - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the event - `cssClass`: *string* - Specifies a custom CSS class that is applied to the event. Useful when customization is needed on the event level. For example: setting the width for specific events. - `date`: *string | object | Date* - Specifies a single date for the event - `dragBetweenResources`: *boolean* - Specifies whether the event is movable across resources. - `dragBetweenSlots`: *boolean* - Specifies whether the event is movable across across slots. - `dragInTime`: *boolean* - Specifies whether the event is movable in time. - `editable`: *boolean* - Specifies if an event is editable or not. If false, drag & drop and resize is not allowed. - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the event - `id`: *string | number* - A unique id for the event. If not specified, the event will get a generated id. - `order`: *number* - Specifies the order of the event in the array. Has precedence over the default ordering rules. - `overlap`: *boolean* - Specifies whether the event can be overlapped. Has precedence over the `eventOverlap` property of the resource and the [eventOverlap](#opt-eventOverlap) option. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring events. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resize`: *boolean* - Specifies whether the event is resizable. Has precedence over the `eventResize` property of the resource and the [dragToResize](#opt-dragToResize) option. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the event. The event will be displayed only on the specified resource. If there is no resource defined, it will be displayed on every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the event. The event will be displayed only on the specified slot. If there is no slot defined, it will be displayed on every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the event - `textColor`: *string* - A color applied on the text. - `timezone`: *string* - Timezone of the event - `title`: *string* - The title of the event. - `tooltip`: *string* - The tooltip text of the event. ### MbscCalendarInvalid Interface Properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### MbscDateType string | Date | object ### MbscEventConnection Interface Properties: - `arrow`: *boolean | "from" | "to" | "bidirectional"* - Specifies where to display arrows If `true`, the arrow will display only at the end side of the connection. - `color`: *string* - Specifies the color of the connection. - `cssClass`: *string* - Custom CSS class for the connection line for further customization. - `from`: *string | number* - The id of the event where the connection will begin - `to`: *string | number* - The id of the event where the connection will end. - `type`: *"fs" | "sf" | "ss" | "ff"* - The type of the connection. Possible values: `'fs'` - finish-to-start, `'sf'` - start-to-finish, `'ss'` - start-to-start, `'ff'` - finish-to-finish. ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResource Interface Properties: - `background`: *string* - Specifies the background color of the resource row or column. - `children`: *Array<[MbscResource](#type-MbscResource)>* - Child resources. - `collapsed`: *boolean* - Specifies the displayed state of the child resource group. - `color`: *string* - Specifies the default event color of the resource. If an event has an explicit color set, the resource color will be overridden. If the color is not set, the events of the resource will inherit the default calendar color. - `cssClass`: *string* - Specifies a css class for the resource row or column. - `eventCreation`: *boolean* - Disables event creation on specific resources by setting it to false. Defaults to true. - `eventDragBetweenResources`: *boolean* - Specifies whether the events in this resource are movable across resources. It applies for scheduler and timeline views. Has precedence over the [dragBetweenResources](#opt-dragBetweenResources) option. - `eventDragBetweenSlots`: *boolean* - Specifies whether the events in this slot are movable across slots. Has precedence over the [dragBetweenSlots](#opt-dragBetweenSlots) option. - `eventDragInTime`: *boolean* - Specifies whether the events in this resource are movable in time. Has precedence over the [dragInTime](#opt-dragInTime) option. - `eventOverlap`: *boolean* - Specifies whether the events in this resource can be overlapped. Has precedence over the [eventOverlap](#opt-eventOverlap) option. - `eventResize`: *boolean* - Specifies whether the events in this resource are resizable. Has precedence over the [dragToResize](#opt-dragToResize) option. - `fixed`: *boolean* - Specifies whether the resource is fixed to the top. It applies for timeline view if `resolutionVertical` in [view](#opt-view) option is not given, or it's value is set to `none`. Consider that the fixed resources always have to be the first elements of the array in a sequence (no non-fixed resources inserted in between) so that the dra & rop and event creation functionalities to work properly. - `id`: *string | number* - The id of the resource. - `name`: *string* - Specifies the name of the resource. - `reorder`: *boolean* - Specifies whether the resource can be dragged and reordered. It applies for timeline view if `resourceReorder` in [view](#opt-view) option is enabled. The `MbscResource` supports custom properties in the form: ``` [x:string]: any ``` ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscEventcalendarOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscSlot Interface Properties: - `eventDragBetweenSlots`: *boolean* - Specifies whether the event is movable across slots. - `id`: *string | number* - The id of the slot. It that can be referenced in the events/invalids/colors data. - `name`: *string* - The name of the slot that will be displayed at the top of the slot column. The `MbscSlot` supports custom properties in the form: ``` [x:string]: any ``` ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## Timezones ## Overview By default the Eventcalendar uses the local timezone of the browser to show event data. If you want to show the data or interpret it in a different timezone, you will need an external library to handle the timezone conversions. There are three libraries that Mobiscroll supports: **moment-timezone**, **luxon** and **Day.js**. When using a timezone plugin with the Eventcalendar, the [`exclusiveEndDates`](api#opt-exclusiveEndDates) option defaults to `true`. Learn more about [exclusive end dates](#exclusive-end-dates)! ## Library Install To setup the library, first you have to install it on your page. In this guide we'll assume you are using npm to install packages, but you can consult the installation guide on the libraries official pages ([moment-timezone install page](https://momentjs.com/timezone/), [luxon install page](https://moment.github.io/luxon/)) for more options on how to install them. ### The Moment-Timezone library **1.** To install the moment-timezone library with npm you will need to run the following commands: ```bash npm install moment-timezone ``` **2.** After the library is installed, you will have to import it with the `momentTimezone` object from mobiscroll: **Moment library import** ```javascript import moment from 'moment-timezone'; ``` **3.** Then set the mobiscroll's reference to the imported library: **Moment library setup** ```javascript import moment from 'moment-timezone'; // highlight-next-line momentTimezone.moment = moment; ``` **4.** After that, you can pass the `momentTimezone` object to the Eventcalendar's [`timezonePlugin`](./api#opt-timezonePlugin) option. ```html ``` ```ts momentTimezone.moment = moment; @Component({...}) export class MyComponent { myMomentTimezone = momentTimezone; } ``` ### The Luxon library **1.** To install the luxon library with npm you will need to run the following commands: ```bash npm install luxon ``` In case you are using typescript you can also consider installing the types, because they come separately: ```bash npm install --save-dev @types/luxon ``` **2.** After the library is installed, you will have to import it with the `luxonTimezone` object from mobiscroll: **Luxon library import** ```javascript import * as luxon from 'luxon'; ``` **3.** Then set the mobiscroll's reference to the imported library: **Luxon library setup** ```javascript import * as luxon from 'luxon'; // highlight-next-line luxonTimezone.luxon = luxon; ``` **4.** After that, you can pass the `luxonTimezone` object to the Eventcalendar's `timezonePlugin` option. ```html ``` ```ts luxonTimezone.luxon = luxon; @Component({...}) export class MyComponent { myLuxonTimezone = luxonTimezone; } ``` ### The Day.js library **1.** To install the Day.js library with npm you will need to run the following commands: ```bash npm install dayjs ``` **2.** After installing the library, the `utc` and `timezone` plugins need to be included. You'll also need to import the `dayjsTimezone` plugin from mobiscroll: **Day.js library import** ```javascript import dayjs from 'dayjs'; dayjs.extend(utc); dayjs.extend(timezone); ``` **3.** Then set the mobiscroll's reference to the imported library: ```javascript title="Day.js library setup" dayjsTimezone.dayjs = dayjs; ``` **4.** After that, you can pass the `dayjsTimezone` object to the Eventcalendar's `timezonePlugin` option. ```html ``` ```ts dayjs.extend(utc); dayjs.extend(timezone); dayjsTimezone.dayjs = dayjs; @Component({...}) export class MyComponent { // highlight-next-line myDayjsTimezone: MbscTimezonePlugin = dayjsTimezone; } ``` ## Using timezones When working with timezones, you usually have your data stored in one timezone, and display it in a different timezone. A common scenario is storing the data in UTC, and displaying it in the user's local timezone. You can set this using the [`dataTimezone`](api#opt-dataTimezone) and [`displayTimezone`](api#opt-displayTimezone) options. You can also store the timezone inside the event data, using the `timezone` property. If an event has the timezone specified, this will take precedence over the timezone set by `dataTimezone`. This is particularly useful for recurring events. Storing recurring events in UTC is not useful in most of the cases, since the occurrences will be generated in UTC time, which does not have daylight saving times. When converted to a displayTimezone which uses DST, the event times will be shifted with an hour when DST changes. Storing the timezone on the event makes it unambiguous, and will be correctly converted to `displayTimezone`. ```ts title="Example" // highlight-next-line // setup the reference to moment // highlight-next-line momentTimezone.moment = moment; @Component({...}) export class MyComponent { myMomentTimezone = momentTimezone; } ``` ```html // highlight-end ``` ## Exclusive end dates Exclusive end dates means that the last moment of a given range is not actually part of the range. Many of existing calendaring solutions (e.g. Google Calendar) and standards (e.g. [iCalendar](https://icalendar.org/)) are working with exclusive end dates, so this makes interoperabiliy with our Eventcalendar UI simpler. With the introduction of timezone support, this also became a necessity, e.g. if you have an event with start: `'2021-07-09T20:00Z'` and end: `'2021-07-09T21:00Z'`, defined in UTC, when displayed in Europe/Bucharest timezone, the end becomes '2021-07-10T00:00+03:00'. With inclusive end dates the event will show up on 10th of July as well, which is unexpected. The exclusive end dates mode can be enabled using the [`exclusiveEndDates`](api#opt-exclusiveEndDates) option. When timezones are used ([`displayTimezone`](api#opt-displayTimezone) and/or [`dataTimezone`](api#opt-dataTimezone) is set), exclusive end dates are automatically enabled. :::caution Enabling exclusive end dates can cause breaking changes, especially with all-day events with no time specified. With inclusive end dates an event with start: `'2021-07-09'` and end: `'2021-07-10'` will show as a two day event on the calendar view, expanded over 9th and 10th of July. With exclusive end dates the event will be a single day event, showing up only on 9th of July. ::: --- ## Accessibility(Datepicker) ## Keyboard Support The Datepicker can render different kinds of [controls](./controls) on the screen depending on the use-case. Each of these controls can be operated by keyboard. When focusing the input component one can open the picker using the `Space` or `Enter` keys. The `Esc` key acts as the cancel button and closes the picker. The `Tab` and `Shift + Tab` keys can be used to navigate between the major parts of the Datepicker: * the month and year navigation button * the previous, next and today buttons * the currently rendered control * the set and cancel buttons if they are rendered Buttons can be activated using the `Space` key. ### Calendar When focusing the calendar control or the month and year navigation, the focus can be moved using the `Left`, `Right`, `Up` and `Down` arrow keys. The focused day (or month or year depending on the selection) can be marked as selected with the `Space` key or the `Enter` key. The later also confirms the selection and closes the Datepicker. ### Date & Time Scroller When using the date and time scrollers, the `Tab` and `Shift + Tab` keys can be used to move the focus between the rendered wheels. The `Up` and `Down` arrow keys are used to rotate the wheel and change the selected value. The selection can be confirmed with the `Enter` key, which also closes the picker. ### Timegrid The selectable times can be navigated using the `Tab` and `Shift + Tab` keys. The focused item can be marked as selected with the `Space` key or the `Enter` key. The later also confirms the selection and closes the Datepicker. ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Supported aria-label on icon buttons, aria-hidden on decoration elements 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Supported label, description and icons can be specified for the picker input 1.3.6 Identify Purpose AAA Supported - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported - 1.4.11 Non-text Contrast AA Supported - 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Not Applicable - ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported - 2.1.2 No Keyboard Trap A Supported in case of modal picker there is a keyboard trap but can be closed by `ESCAPE` or `ENTER` 2.1.3 Keyboard (No Exception) AAA Supported - 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Not applicable - 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported - 2.2.4 Interruptions AAA Not Applicable - 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Not supported Calendar view page change animation 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Supported label and description can be specified for the picker input 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Supported can be defined through `label` and `aria-label` options 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Not fully supported in case of the range clear button 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Not Applicable - 2.5.8 Target Size (Minimum) AA Not fully supported in case of the range clear button ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility Remarks 3.1 Readable 3.1.1 Language of Page A Not Applicable - 3.1.2 Language of Parts AA Not Applicable - 3.1.3 Unusual Words AAA Not Applicable - 3.1.4 Abbreviations AAA Supported - 3.1.5 Reading Level AAA Not Applicable - 3.1.6 Pronunciation AAA Not Applicable - 3.2 Predictable 3.2.1 On Focus A Supported - 3.2.2 On Input A Not Applicable - 3.2.3 Consistent Navigation AA Not Applicable - 3.2.4 Consistent Identification AA Not Applicable - 3.2.5 Change on Request AAA Not Applicable - 3.2.6 Consistent Help A Not Applicable - 3.3 Input Assistance 3.3.1 Error Identification A Supported using the `error` and `error-message` options 3.3.2 Labels or Instructions A Supported can be defined through `label` and `aria-label` options 3.3.3 Error Suggestion AA Supported using the `error` and `error-message` options 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable - 3.3.5 Help AAA Not Applicable - 3.3.6 Error Prevention (All) AAA Not Applicable - 3.3.7 Redundant Entry A Not Applicable - 3.3.8 Accessible Authentication (Minimum) AA Not Applicable - 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable - ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Not Applicable --- ## Datepicker API Here is a comprehensive list of all the options, events and methods of the Datepicker component. ## Options Explore the following API options that help you easily configure our components. ### anchor HTMLElement Specifies the anchor element for positioning, if [display](#opt-display) is set to `'anchored'`. **Default value**: `undefined` ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed, if [display](#opt-display) is not set to `'inline'`. Possible values: - `'pop'` - `'slide-down'` - `'slide-up'` If `false`, the animation is turned off. **Default value**: `undefined` ### ariaLabel string Specifies the accessible name of the picker input. **Default value**: `undefined` ### buttons Array Buttons to display on the component. Each item of the array will be a button. A button can be specified as a string, or as a button object. If a string, it must be one of the predefined buttons: - `'ok'` - Approve action. Will display the caption specified by the [okText](#localization-okText) option. - `'cancel'` - Dismisses the popup. Will display the caption specified by the [cancelText](#localization-cancelText) option. - `'close'` - Closes the popup. Will display the caption specified by the [closeText](#localization-closeText) option. - `'set'` - Approve action. Will display the caption specified by the [setText](#localization-setText) option. The [`MbscPopupButton`](#type-MbscPopupButton) type has the following properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ```js title="Example for using predefined and custom buttons" [ 'set', { text: 'Custom', icon: 'checkmark', cssClass: 'my-btn', handler: function (event) { alert('Custom button clicked!'); } }, 'cancel' ] ``` ```js title="Example for using a predefined button handler" [ 'set', { text: 'Hide', handler: 'cancel', icon: 'close', cssClass: 'my-btn' } ] ``` **Default value**: `['set', 'cancel']` ### calendarScroll "horizontal" | "vertical" Controls the direction of the calendar navigation. You can navigate by scrolling, swiping or by clicking the arrow buttons in the header. Possible values: - `'horizontal'` - Enables navigating the view horizontally. - `'vertical'` - Enables navigating the view vertically. When navigation is `'vertical'`, the outer days (days from previous and next months) are hidden. You can explicitly override it with the [showOuterDays](#opt-showOuterDays) option. **Default value**: `'horizontal'` ### calendarSize number Number of months or weeks to display. The view starts from a reference date defined by [refDate](#opt-refDate) option. **Default value**: `1` ### calendarType "month" | "year" | "week" Specifies the type of the calendar. In case of `'month'` set the number of displayed months using the [pages](#opt-pages) option (swipeable month view) or the [calendarSize](#opt-calendarSize) option (grid month view). In case of `'week'` set the number of displayed weeks using the [calendarSize](#opt-calendarSize) option. **Default value**: `'month'` ### circular boolean | Array If `true`, the scroll wheels are circular. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: `[true, false, false]` sets the first wheel circular. If not specified, if a wheel has more values than the number of the displayed rows, the scroll wheel becomes circular. **Default value**: `undefined` ### closeOnEsc boolean If `true`, the popup is closed when the ESC key is pressed. **Default value**: `true` ### closeOnOverlayClick boolean If `true`, the popup is closed on overlay click or tap. **Default value**: `true` ### colors Array<[MbscCalendarColor](#type-MbscCalendarColor)> Specifies the color for certain dates or date ranges on the calendar. The [`MbscCalendarColor`](#type-MbscCalendarColor) type has the following properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The colored range will be considered all-day if: - the `allDay` property is explicitly set. - the `start` / `end` properties are not specified, only the `date`. ::: :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The colors can be combined with the [labels](#opt-labels) or [marked](#opt-marked) options. ::: ```js [ { date: new Date(2020, 2, 23), background: 'pink' }, { date: new Date(2020, 2, 24), background: 'green' }, { background: '#ff0000', recurring: { repeat: 'weekly', weekDays: 'SU' } }, { background: 'yellow', recurring: { repeat: 'weekly', weekDays: 'SA' } } ] ``` **Default value**: `undefined` ### context string | HTMLElement The DOM element in which the component is appended and positioned (when not inline). Can be a selector string or a DOM element. **Default value**: `'body'` ### controls Array<[MbscDatepickerControl](#type-MbscDatepickerControl)> List of controls to display on the picker. Possible values: - `['calendar']` - `['calendar', 'time']` - `['date']` - `['datetime']` - `['date', 'time']` - `['time']` - `['timegrid']` **Default value**: `['calendar']` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### dataTimezone string The timezone in which the data is interpreted. If the data contains timezone information (when the ISO string has a timezone offset, e.g. `"2021-03-28T01:00:00Z"` or `"2021-03-28T03:00:00+03:00"`) then the data's timezone is used instead. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. If not specified, it defaults to the [displayTimezone](#opt-displayTimezone). **Default value**: `undefined` ### defaultSelection any Default selection which appears on the picker. The provided value will not be set as picker value, it's only a pre-selection. If not provided, the default selection will be the current date and/or time. If `null` is passed, in case of the calendar control there will be no selected value, in case of scroller controls the current date and time will still be displayed on the selected line, as an empty value cannot be displayed on the scroller. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the input. **Default value**: `false` ### display [MbscPopupDisplay](#type-MbscPopupDisplay) Controls the positioning of the component. Possible values are: - `'center'` - The component appears as a popup at the center of the viewport. - `'inline'` - The component is rendered inline. - `'anchored'` - The component appears positioned to the element defined by the [anchor](#opt-anchor) option. - `'top'` - The component appears docked to the top of the viewport. - `'bottom'` - The component appears docked to the bottom of the viewport. The default display mode depends on the [theme](#opt-theme), it defaults to `'bottom'` for the iOS theme and to `'center'` for all other themes. **Default value**: `undefined` ### displayTimezone string The timezone in which the data is displayed. :::info When using timezones, the [exclusiveEndDates](#opt-exclusiveEndDates) option is also turned on by default. ::: :::info When using anything other than the default (`'local'`), a [timezone plugin](#opt-timezonePlugin) must be also passed to the component. ::: Possible values: - `'local'` - The system's local timezone. - `'utc'` - UTC (Universal Coordinated Time) timezone. - Timezone name - The timezone name from the [IANA time zone database](https://gist.github.com/aviflax/a4093965be1cd008f172), e.g. `"America/New_York"`. **Default value**: `'local'` ### endIcon string Specifies the icon which will be displayed at the end of the input. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### endInput any Sets the input for the end date. When using the Datepicker to [select a range](#opt-select), it can be used with one, two or no inputs. When the `endInput` is specified, it will put the range end part of the selection to that input. Similarly the input for the range start can be specified using the [startInput](#opt-startInput) option. **Default value**: `undefined` ### error boolean If `true`, the input will be displayed with error styles. **Default value**: `false` ### errorMessage string Error message for the input. If the [error](#opt-error) option is set to `true`, the message will be displayed. **Default value**: `undefined` ### exclusiveEndDates boolean If `true`, the picker will work in exclusive end dates mode, meaning that the last moment of the range (selected value, colors, invalids, marked days etc.) is not part of the range. For example, when selecting a date range without the time part, selecting `'2021-07-20'` for the range end, the underlying value will return `'2021-07-21'` instead, because the range ends on the 21st, not including the 21st. :::info When using timezones, the `exclusiveEndDates` option will default to `true`. ::: **Default value**: `false` ### firstSelectDay number Sets the first day of the selection, when `'preset-range'` [selection](#opt-select) is used. It takes a number representing the day of the week, * Sunday is 0, Monday is 1, etc. If not specified, it defaults to the first day of the week defined by the [localization](#localization-locale). The length of the selection can be controlled with the [selectSize](#opt-selectSize) option. **Default value**: `undefined` ### focusOnClose boolean If `true`, after closing the popup the focus will be moved to the last focused element before the popup was opened. **Default value**: `true` ### focusOnOpen boolean If `true`, the popup will receive the focus when opened. **Default value**: `true` ### focusTrap boolean If `true` and [display](#opt-display) is not set to `'inline'`, focus won't be allowed to leave the popup. **Default value**: `true` ### headerText string Specifies a custom string which appears in the picker header. If it contains the `'{value}'` string, it will be replaced with the selected value of the picker. **Default value**: `undefined` ### inRangeInvalid boolean In case of [range selection](#opt-select), specifies if invalid dates are allowed between the start and end dates. When set to `false`, the end selection will be limited to the next invalid date from the selected start date. For example, when designing a booking system, a possible solution for already booked dates is to set those dates to invalid. When considering check-in and check-out selections with the datepicker, in some cases it is desireable to be able to check out on dates that already have a check-in. In this case, those dates would be disabled. Using the [rangeEndInvalid](#opt-rangeEndInvalid) option it can be allowed that the first invalid day after the start date can be selected as end date. **Default value**: `false` ### inputComponent any The input component to render if the picker is modal If not specified, it will render a [Mobiscroll Input](../forms/input) component. Props can be specified using the [inputProps](#opt-inputProps) option. **Default value**: `undefined` ### inputProps any Props for the rendered input, specified by the [inputComponent](#opt-inputComponent) option. **Default value**: `undefined` ### inputStyle "outline" | "box" | "underline" Specifies the style of the input. Possible values: - `'underline'` - `'box'` - `'outline'` The default value depends on the [theme](#opt-theme): - iOS: `'underline'` - Material: `'box'` - Windows: `'outline'` **Default value**: `undefined` ### inputTyping boolean Allow the typing into the input field in desktop mode. **Default value**: `true` ### invalid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the invalid values. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the invalid range is all day or not. - `start`: *Date | string | object* - Start of the invalid range. - `end`: *Date, string | object* - End of the invalid range. - `recurring`: *string | object* - Recurrence rule for recurring invalid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - Specifies the [resource](#opt-resources) ids for the invalid range. The invalid range will be displayed only in the specified resource. If there is no resource defined, the invalid range will be displayed in every resource. - `slot`: *string | number* - Specifies the [slot](#opt-slots) id for the invalid range. The invalid range will be displayed only in the specified slot. If there is no slot defined, the invalid range will be displayed in every slot. - `title`: *string* - Text which will be displayed for the invalid range. Only applicable for the timeline and scheduler views. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `false` ### itemHeight number Height in pixels of one item on the wheel. The default value depends on the [theme](#opt-theme): - iOS: 34 - Material: 40 - Windows: 44 ### label string Specifies the label of the input. **Default value**: `undefined` ### labelStyle "inline" | "floating" | "stacked" Specifies the position of the input label. Possible values: - `'stacked'` - `'inline'` - `'floating'` The default value depends on the [theme](#opt-theme): - iOS: `'inline'` - Material: `'floating'` - Windows: `'stacked'` **Default value**: `undefined` ### labels Array<[MbscCalendarLabel](#type-MbscCalendarLabel)> Specifies labels for calendar days. The [`MbscCalendarLabel`](#type-MbscCalendarLabel) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The labels can be combined with the [colors](#opt-colors) option. ::: ```js [ { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), text: 'Conference', color: 'red' }, { text: 'Christmas', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: undefined ### marked Array<[MbscCalendarMarked](#type-MbscCalendarMarked)> Mark certain dates on the calendar. An array containing dates, or objects with the following properties: The [`MbscCalendarMarked`](#type-MbscCalendarMarked) type has the following properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: :::info The marked days can be combined with the [colors](#opt-colors) option. ::: ```js [ new Date(2020, 2, 15), new Date(2020, 2, 22), { start: new Date(2020, 2, 23), end: new Date(2020, 2, 24), color: 'red' }, { color: 'green', recurring: { repeat: 'yearly', month: 12, day: 24 } } ] ``` **Default value**: `undefined` ### max [MbscDateType](#type-MbscDateType) Maximum value that can be selected. **Default value**: `undefined` ### maxHeight string | number Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px. **Default value**: `undefined` ### maxRange number Sets the maximum range that can be selected. When selecting a date range without the time part, it sets the maximum number of days the selected range can contain. When there is a time part in the selection, it sets the maximum range in milliseconds. **Default value**: `undefined` ### maxTime [MbscDateType](#type-MbscDateType) It sets the maximum time that is selectable on the time or the timegrid [control](#opt-controls). When there is a date part of the selection, the maximum is applied to each day. For example `maxTime: '18:00'` will limit the time part of the selection to at most 18 o'clock each day, in contrast to the [max](#opt-max) option, which will limit the date part of the selection as well. For example: `max: '2021-08-22T18:00` will limit the selection to August 22nd 18 o'clock, but will allow selection of times past 18 o'clock on dates before August 22nd. :::info This option can't be used with the `'datetime'` [control](#opt-controls). ::: **Default value**: `undefined` ### maxWheelWidth number | Array Maximum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ### maxWidth string | number Sets the maximum width of the component. **Default value**: `undefined` ### min [MbscDateType](#type-MbscDateType) Minimum value that can be selected. **Default value**: `undefined` ### minRange number Sets the minimum range that can be selected. When selecting a date range without the time part, it sets the minimum number of days the selected range can contain. When there is a time part in the selection, it sets the minimum range in milliseconds. **Default value**: `undefined` ### minTime [MbscDateType](#type-MbscDateType) It sets the minimum time that is selectable on the time or the timegrid [control](#opt-controls). When there is a date part of the selection, the minimum is applied to each day. For example `minTime: '08:00'` will limit the time part of the selection to at least 8 o'clock each day. in contrast to the [min](#opt-min) option, which will limit the date part of the selection as well. For example: `min: '2021-08-22T08:00` will limit the selection to August 22nd 8 o'clock, but will allow selection of times earlier than 8 o'clock on dates after August 22nd. :::info This option can't be used with the `'datetime'` [control](#opt-controls). ::: **Default value**: `undefined` ### minWheelWidth number | Array Minimum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ### moment any Reference to the Moment.js library. Needed when using Moment objects as [return values](#opt-returnFormat). **Default value**: `undefined` ### pages number | "auto" Number of calendar pages (month or week) to display. If `'auto'`, the displayed number of pages will be decided based on the viewport size. **Default value**: `1` ### rangeEndInvalid boolean When `true`, it enables the end date to be selected on the first invalid date that comes after the selected start date. For example, When designing a booking system, a possible solution for already booked dates is to set those dates to invalid. When considering check-in and check-out selections with the datepicker, in some cases it is desireable to be able to check out on dates that already have a check-in. In this case, those dates would be disabled. With this option it can be enabled, so the selection's end can be on the same day the first invalid is. :::info When the [inRangeInvalid](#opt-inRangeInvalid) option is set to `true` (default), this option is ignored, so make sure to turn that off too if you want to use this one. ::: **Default value**: `false` ### rangeHighlight boolean When selecting a range on the calendar control, it is optional to highlight the dates between the start and end date. By default, the dates are highlighted between the start and end values. When the highlight is turned off, only the start and end dates are shown as selected on the calendar. On desktop devices where a cursor is available, hovering the calendar days also help to visualize the selecting range. The hover styling is also turned off, when the range is not highlighted. **Default value**: `true` ### refDate [MbscDateType](#type-MbscDateType) Specifies the reference date of the component, which represents when to start to calculate the view you want to display. For example, if you want to display 2 months from the current month, you must specify the first day of the current month as the reference date. Then you can use the [calendarSize](#opt-calendarSize) option to show 2 months. **Default value**: `'1970/01/01'` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### returnFormat "locale" | "jsdate" | "iso8601" | "moment" Specifies the format in which the selected dates are returned. - `'jsdate'` - JavaScript date object. - `'iso8601'` - ISO 8601 date string. - `'locale'` - Formatted date string based on the locale option, or the [dateFormat](#localization-dateFormat) and [timeFormat](#localization-timeFormat) options, if they are specified. - `'moment'` - Moment object. Ensure that [moment.js](https://momentjs.com/) is loaded and passed through the [moment](#opt-moment) option. :::info When using a [timezone plugin](#opt-timezonePlugin), the returned values are always in 'iso8601' format and this option is not taken into account. ::: **Default value**: `'jsdate'` ### rows number Number of visible rows on the wheel. The default value depends on the [theme](#opt-theme): - iOS: 5 - Material: 3 - Windows: 6 ### select "date" | "range" | "preset-range" In terms of value selection, the Datepicker can be used to select a single date/time or multiple dates/times, as well as a date range or a time range. It is also possible to select a week or a part of the week as a range. The select option defines if the picker is used for selecting independent dates or a range. Possible values are: - `'date'` - Used for single or multiple date/time selection. - `'range'` - Used for date range or time range selection. - `'preset-range'` - Used for a week range selection. **Default value**: `'date'` ### selectCounter boolean If `true` and [multiple selection](#opt-selectMultiple) is enabled, the number of selected items will be displayed in the header. **Default value**: `false` ### selectMax number The maximum number of selected items in case of [multiple selection](#opt-selectMultiple). **Default value**: `undefined` ### selectMultiple boolean If `true`, multiple selection will be enabled. **Default value**: `false` ### selectSize number Sets the length of the selection in days when [preset-range selection](#opt-select) is used. The start of the selection can be set using the [firstSelectDay](#opt-firstSelectDay) option and will have the specified length. It defaults to a full week (7 days). **Default value**: `7` ### separator string Separator between date and time in the formatted date string. **Default value**: `' '` ### showArrow boolean Show or hide the popup arrow, when [display](#opt-display) is `'anchored'`. **Default value**: `true` ### showInput boolean If `true`, it will render an input field for the component. **Default value**: `true` ### showOnClick boolean Opens the component on element click/tap. **Default value**: `true` ### showOnFocus boolean Opens the component on element focus. **Default value**: `false on desktop, true on mobile` ### showOuterDays boolean Show or hide days from previous and next months. :::info Hiding outer days only works in case of month view, and not supported for week view. ::: :::info Outer days are automatically hidden if [calendarScroll](#opt-calendarScroll) is set to `'vertical'`. ::: **Default value**: `true` ### showOverlay boolean Show or hide the popup overlay. **Default value**: `true` ### showRangeLabels boolean Show or hide the range labels. When [selecting a range](#opt-select), a start and end label is displayed on the picker. These labels indicate which part of the range are we selecting (start or end). The labels can also be used to switch the active selection from start to end or vice versa. The [start label text](#localization-rangeStartLabel) and [end label text](#localization-rangeEndLabel) as well as the [start value placeholder](#localization-rangeStartHelp) and the [end value placeholder](#localization-rangeEndHelp) can be customized. **Default value**: `true` ### showWeekNumbers boolean Show week numbers on the calendar view. Enumeration starts with the first week of the year. **Default value**: `false` ### startIcon string Specifies the icon which will be displayed at the start of the input. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### startInput any Sets the input for the start date. When using the Datepicker to [select a range](#opt-select), it can be used with one, two or no inputs. When the `startInput` is specified, it will put the range start part of the selection to that input. Similarly the input for the range end can be specified using the [endInput](#opt-endInput) option. **Default value**: `undefined` ### stepHour number Step for the hours scroll wheel. Also, sets the hours step for the timegrid. **Default value**: `1` ### stepMinute number Step for the minutes scroll wheel. Also, sets the minutes step for the timegrid. **Default value**: `1` ### stepSecond number Step for the seconds scroll wheel. Also, sets the seconds step for the timegrid. **Default value**: `1` ### tagInput boolean If `true` and used with [multiple selection](#opt-selectMultiple), it will display the selected values inside the input as tags (chips). **Default value**: `false` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### timezonePlugin [MbscTimezonePlugin](#type-MbscTimezonePlugin) Specifies the timezone plugin, which can handle the timezone conversions. By default the component uses the local timezone of the browser to interpret dates. If you want to interpret dates a different timezone, you will need an external library to handle the timezone conversions. There are two supported libraries: [moment-timezone](https://momentjs.com/timezone/) and [luxon](https://moment.github.io/luxon/#/). You can specify either the [dataTimezone](#opt-dataTimezone) or the [displayTimezone](#opt-displayTimezone) or both. Depending on which external library you use you can pass either the `momentTimezone`, `dayjsTimezone` or `luxonTimezone` objects. These objects can be imported from the mobiscroll bundle. **Default value**: `undefined` The [`MbscTimezonePlugin`](#type-MbscTimezonePlugin) type has the following properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* - ### valid Array<[MbscDateType](#type-MbscDateType)> | Array<[MbscCalendarInvalid](#type-MbscCalendarInvalid)> An array containing the valid values. Use it when it's more convenient to specify valid values instead of the invalid ones. If specified, everything else is considered to be invalid, and the [invalid](#opt-invalid) option will be ignored. Can contain dates, or objects with the following properties: - `allDay`: *boolean* - Specifies whether the valid range is all day or not. - `start`: *Date | string | object* - Start of the valid range. - `end`: *Date, string | object* - End of the valid range. - `recurring`: *string | object* - Recurrence rule for recurring valid ranges. - `recurringException`: *string | object | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | object* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. :::info The dates can be specified as JavaScript Date objects, ISO 8601 strings, or moment objects. ::: :::info For Javascript Date objects the month numbers are zero based. Like: 0 - January, 1 - February ... 11 - December. ::: ```js [ // Passing exact dates and times new Date(2021, 1, 7), // Date object '2021-10-15T12:00', // ISO 8601 string moment('2020-12-25'), // moment object // Passing invalid ranges { // ISO 8601 strings start: '2021-10-15T12:00', end: '2021-10-18T13:00', title: 'Company 10th anniversary', }, { // Date objects allDay: true, start: new Date(2021, 2, 7), end: new Date(2021, 2, 9), title: 'Conference for the whole team', }, { // Time range with recurrence start: '13:00', end: '12:00', recurring: { repeat: 'weekly', weekDays: 'MO,TU,WE,TH,FR' }, title: 'Lunch break', }, { // Disable weekends recurring: { repeat: 'weekly', weekDays: 'SA,SU' } } ] ``` **Default value**: `undefined` The [`MbscCalendarInvalid`](#type-MbscCalendarInvalid) type has the following properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### wheelWidth number | Array Width of the scroller wheels, in pixels. Wheel content will be truncated, if it exceeds the width. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ## Events The Datepicker ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onActiveDateChange (args: MbscDatepickerActiveDateChangeEvent, inst: DatepickerBase) => void Triggered when the active date changes from start to end or vice versa, in case of range selection mode. Parameters: - args - The event argument with the following properties: - `active`: *string* - The activated part of the range, `'start'` or `'end'`. - inst - The component instance. ### onCancel (args: MbscDatepickerCancelEvent, inst: DatepickerBase) => void Triggered when the picker is canceled. Parameters: - args - The event argument with the following properties: - `value`: *MbscDateType | MbscDateType[]* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onCellClick (args: MbscDatepickerCellClickEvent, inst: DatepickerBase) => void Triggered when a cell is clicked on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the clicked cell. - `domEvent`: *Event* - The DOM event of the click. - `selected`: *boolean* - Specifies if the day is currently selected or not (before it was clicked). - `target`: *HTMLElement* - The DOM element of the clicked cell. - inst - The component instance. ### onCellHoverIn (args: MbscDatepickerCellHoverEvent, inst: DatepickerBase) => void Triggered when the mouse pointer hovers a day on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered day. - `labels`: *Array* - If the day has labels, contains the label objects for the hovered day. - `marked`: *Array* - If the day is marked, contains the marked objects for the hovered day. - `selected`: *boolean* - Specifies if the day is currently selected or not. - `target`: *HTMLElement* - The DOM element of the cell. - inst - The component instance. ### onCellHoverOut (args: MbscDatepickerCellHoverEvent, inst: DatepickerBase) => void Triggered when the mouse pointer leaves a day on the calendar view (does not apply for agenda, schedule and timeline views). Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the hovered day. - `labels`: *Array* - If the day has labels, contains the label objects for the hovered day. - `marked`: *Array* - If the day is marked, contains the marked objects for the hovered day. - `selected`: *boolean* - Specifies if the day is currently selected or not. - `target`: *HTMLElement* - The DOM element of the cell. - inst - The component instance. ### onChange (args: MbscDatepickerChangeEvent, inst: DatepickerBase) => void Triggered when the value is changed. Parameters: - args - The event argument with the following properties: - `value`: *MbscDateType | MbscDateType[]* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onClose (args: MbscDatepickerCloseEvent, inst: DatepickerBase) => void Triggered when the picker is closed. Parameters: - args - The event argument with the following properties: - `value`: *MbscDateType | MbscDateType[]* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onLabelClick (args: MbscDatepickerLabelClickEvent, inst: DatepickerBase) => void Triggered when a label is clicked on the calendar. Parameters: - args - The event argument with the following properties: - `date`: *Date* - The date of the day on which the label was clicked. - `domEvent`: *Event* - The DOM event of the click. - `label`: *MbscCalendarLabel* - The original object of the label which was clicked, `undefined` in case of the "more" label. - `labels`: *Array* - An array containing each label object for the given day. - `target`: *HTMLElement* - The DOM element of the label. - inst - The component instance. ### onOpen (args: MbscDatepickerOpenEvent, inst: DatepickerBase) => void Triggered when the picker is opened. Parameters: - args - The event argument with the following properties: - `target`: *HTMLElement* - The DOM element of the popup. - `value`: *MbscDateType | MbscDateType[]* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onPageChange (args: MbscDatepickerPageChangeEvent, inst: DatepickerBase) => void Triggered when the calendar page is changed (with buttons or swipe). Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoaded (args: MbscDatepickerPageLoadedEvent, inst: DatepickerBase) => void Triggered when the calendar page is changed (with buttons or swipe) and the view finished rendering. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onPageLoading (args: MbscDatepickerPageLoadingEvent, inst: DatepickerBase) => void Triggered before the markup of a calendar page is starting to render. Parameters: - args - The event argument with the following properties: - `firstDay`: *Date* - The first day of the displayed page. - `lastDay`: *Date* - The last day of the displayed page, as an exclusive end date, pointing to 00:00 of the next day. - `month`: *Date* - The first day of the visible month in case of month view. - inst - The component instance. ### onTempChange (args: MbscDatepickerTempChangeEvent, inst: DatepickerBase) => void Triggered when the temporary value is changed. Parameters: - args - The event argument with the following properties: - `value`: *MbscDateType | MbscDateType[]* - The selected value. - inst - The component instance. ## Localization The Datepicker is fully localized. This covers date and time format, button copy, rtl and more. ### amText string Text for AM. **Default value**: `'am'` ### calendarSystem MbscCalendarSystem Specifies the calendar system to be used. Supported calendars: - Gregorian - Gregorian calendar. This is the default calendar system. - Jalali - Persian calendar. The Farsi language needs to be included to the package. - Hijri - Hijri calendar. The Arabic language needs to be included to the package **Default value**: `undefined` ### cancelText string Text for the "Cancel" button. **Default value**: `'Cancel'` ### closeText string Text for the "Close" button. **Default value**: `'Close'` ### dateFormat string The format for parsed and displayed dates: - `M` - month of year (no leading zero) - `MM` - month of year (two digit) - `MMM` - month name short - `MMMM` - month name long - `D` - day of month (no leading zero) - `DD` - day of month (two digit) - `DDD` - day of week (short) - `DDDD` - day of week (long) - `YY` - year (two digit) - `YYYY` - year (four digit) - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'MM/DD/YYYY'` ### dateFormatFull string Human readable date format, used by screen readers to read out full dates. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. **Default value**: `'DDDD, MMMM D, YYYY'` ### dateText string Specifies the accessibility label for the date wheel. **Default value**: `'Date'` ### dateWheels string Display order and formatting for month/day/year wheels. Characters have the same meaning as in the [dateFormat](#localization-dateFormat) option. The options also controls if a specific wheel should appear or not, e.g. use `'MMMMYYYY'` to display month and year wheels only, `'MMDDD DDYYYY'` to display both day of week and date on the day wheel. If not specified, the order of the wheels will be taken from the [dateFormat](#localization-dateFormat) option, and the formatting will be defined by the [theme](#opt-theme). To display the whole date on one wheel, the format of the date should be specified between `|` characters: ```js dateWheels: '|DDD MMM D|' // Will produce 'Sun Sep 9' ``` **Default value**: `undefined` ### dayNames Array The list of long day names, starting from Sunday. **Default value**: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']` ### dayNamesMin Array The list of minimal day names, starting from Sunday. **Default value**: `['S', 'M', 'T', 'W', 'T', 'F', 'S']` ### dayNamesShort Array The list of abbreviated day names, starting from Sunday. **Default value**: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']` ### daySuffix string Additional string to display after the day on the wheel. **Default value**: `undefined` ### dayText string Specifies the accessibility label for the day wheel. **Default value**: `'Day'` ### firstDay number Set the first day of the week: Sunday is 0, Monday is 1, etc. **Default value**: `0` ### hourText string Specifies the accessibility label for the hour wheel. **Default value**: `'Hour'` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### minuteText string Specifies the accessibility label for the minute wheel. **Default value**: `'Minute'` ### monthNames Array The list of full month names. **Default value**: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']` ### monthNamesShort Array The list of abbreviated month names. **Default value**: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']` ### monthSuffix string Additional string to display after the month on the wheel. **Default value**: `undefined` ### monthText string Specifies the accessibility label for the month wheel. **Default value**: `'Month'` ### moreEventsPluralText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day, and there are more than one extra labels. The `{count}` inside the string will be replaced with the number of extra labels. When not specified, the [moreEventsText](#localization-moreEventsText) option will be used for both plural and singular form. **Default value**: `undefined` ### moreEventsText string Text for the "more" label on the calendar, when there's not enough space to display all the labels for the day. The `{count}` inside the string will be replaced with the number of extra labels. Use the [moreEventsPluralText](#localization-moreEventsPluralText) as well, if the plural form is different. **Default value**: `'{count} more'` ### nextPageText string Text for the next button in the calendar header, used as accessibility label. **Default value**: `'Next page'` ### okText string Text for the "Ok" button. **Default value**: `'Ok'` ### pmText string Text for PM. **Default value**: `'pm'` ### prevPageText string Text for the previous button in the calendar header, used as accessibility label. **Default value**: `'Previous page'` ### quarterText string Text for quarter numbers in the timeline header. The {count} inside the string will be replaced with the number of the current quarter. **Default value**: `'Q {count}'` ### rangeEndHelp string When selecting a range, it specifies the placeholder text for the end value under the [end label](#opt-showRangeLabels). **Default value**: `'Please select'` ### rangeEndLabel string When selecting a range, it specifies the text of the [end label](#opt-showRangeLabels). **Default value**: `'End'` ### rangeStartHelp string When selecting a range, it specifies the placeholder text for the start value under the [start label](#opt-showRangeLabels). **Default value**: `'Please select'` ### rangeStartLabel string When selecting a range, it specifies the text of the [start label](#opt-showRangeLabels). **Default value**: `'Start'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### secondText string Specifies the accessibility label for the second wheel. **Default value**: `'Second'` ### selectedPluralText string Specifies the plural form of the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items. **Default value**: `'{count} selected'` ### selectedText string Specifies the amount of selected items according to the rules of particular language. The '{count}' substring will be replaced with the number of selected items. **Default value**: `'{count} selected'` ### setText string Text for the "Set" button. **Default value**: `'Set'` ### timeFormat string The format for parsed and displayed times: - `h` - 12 hour format (no leading zero) - `hh` - 12 hour format (leading zero) - `H` - 24 hour format (no leading zero) - `HH` - 24 hour format (leading zero) - `m` - minutes (no leading zero) - `mm` - minutes (leading zero) - `s` - seconds (no leading zero) - `ss` - seconds (leading zero) - `a` - lowercase am/pm - `A` - uppercase AM/PM - `'...'` - literal text - `''` - single quote - anything else - literal text **Default value**: `'hh:mm A'` ### timeText string Specifies the accessibility label for the time wheel. **Default value**: `'Time'` ### timeWheels string Display order and formatting of the time wheels. Characters have the same meaning as in the [timeFormat](#localization-timeFormat) option. If not specified, the order of the wheels will be taken from the [timeFormat](#localization-timeFormat) option, and the formatting will be defined by the theme. To display the whole time on one wheel, the format of the time should be specified between `|` characters: ```js timeWheels: '|h:mm A|' // Will produce '9:12 AM' ``` **Default value**: `undefined` ### todayText string Text for the "Today" button. **Default value**: `'Today'` ### yearSuffix string Additional string to display after the year on the wheel. **Default value**: `undefined` ### yearText string Specifies the accessibility label for the year wheel. **Default value**: `'Year'` ## Methods These methods are actions that can be performed on a component instance. ### isVisible () => boolean Returns a boolean indicating whether the component is visible or not. ### navigate (date: [MbscDateType](#type-MbscDateType)) => void Display a specific month on the calendar without setting the date. Parameters: - date - Date to navigate to. Can be a Date object, ISO8601 date string, or moment object. ### position () => void Recalculates the position of the component (if not inline). ### setActiveDate (active: "end" | "start") => void Sets which date or time is currently selected. Parameters: - active - Specifies the active selection: start or end. ## Templates The display of the Datepicker component can be customized with different templating functions. ### calendarHeaderTemplate Template reference for custom calendar header rendering. ### dayContentTemplate Template reference for customizing the day cells of the Datepicker. If you are looking to fully customize the day cell (ex. add custom hover effects) you will need to use the [dayTemplate](#template-dayTemplate) option. The following day specific details are available: - `date`: _Date_ - The specific date as a Date object. - `selected`: _boolean_ - True if the date is selected. - `events`: _Array_ - The list of events of the day. ### dayTemplate Template reference for customizing the day cells of the Datepicker. If you are looking to customize only the day cell content, you can use the [dayContentTemplate](#template-dayContentTemplate) option. The following day specific details are available: - `date`: _Date_ - The specific date as a Date object. - `selected`: _boolean_ - True if the date is selected. (In case of calendar view) - `events`: _Array_ - The list of events of the day. ## Types ### MbscCalendarColor Interface Properties: - `allDay`: *boolean* - Specifies whether the date you want to color is all day or not. - `background`: *string* - Background color of the cell. It can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `cssClass`: *string* - Specifies a custom CSS class for the color. Useful when customization is needed for the background of cells and time ranges. Only applicable for the timeline and scheduler views. - `date`: *string | object | Date* - Specifies a single date for the color - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the color - `highlight`: *string* - Highlight color of the day, can be any valid CSS color (`'red'`, `'#ff0000'`, `'rgb(255, 0, 0)'`, etc.). - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `resource`: *string | number | Array* - In case of the timeline and scheduler view of the Eventcalendar, specifies the [resource](#opt-resources) ids for the color. The color will be displayed only on the specified resource. If there is no resource defined, it will be applied to every resource. - `slot`: *string | number* - In case of the timeline view of the Eventcalendar, specifies the [slot](#opt-slot) id for the color. The color will be displayed only on the specified slot. If there is no slot defined, it will be applied to every slot. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the color - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscCalendarInvalid Interface Properties: - `allDay`: *boolean* - If true the specified invalid will cover the whole day. - `end`: *[MbscDateType](#type-MbscDateType)* - Specifies the end of the invalid range. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Recurrence rule for recurring invalid ranges. - `recurringException`: *[MbscDateType](#type-MbscDateType) | Array<[MbscDateType](#type-MbscDateType)>* - Specifies recurring exceptions. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence exception rule. Useful when recurring dates need to be skipped from the rule. - `start`: *[MbscDateType](#type-MbscDateType)* - Specifies the start of the invalid range. ### MbscCalendarLabel Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Background color of the label. - `cssClass`: *string* - Specifies a custom CSS class that is applied to the label. - `date`: *string | object | Date* - Specifies a single date for the label - `end`: *string | object | Date* - Specifies the end date/time of a date/time range for the label - `order`: *number* - Specifies the order of the label in the array. Has precedence over the default ordering rules. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range for the label - `textColor`: *string* - A color applied on the text. - `title`: *string* - The title of the label. - `tooltip`: *string* - Tooltip for the label ### MbscCalendarMarked Interface Properties: - `cellCssClass`: *string* - CSS class for the day cell. Only applicable for the calendar view. - `color`: *string* - Color of the mark. - `date`: *string | object | Date* - Specifies a single date when this is applicable - `end`: *string | object | Date* - Specifies the end date/time of a date/time range when this is applicable - `markCssClass`: *string* - CSS class for the mark. - `recurring`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Specifies a recurrence rule for handling recurring days. - `recurringException`: *string | object | Date | Array* - Exception dates of the recurring rule. Useful when specific dates need to be skipped from the rule. - `recurringExceptionRule`: *string | [MbscRecurrenceRule](#type-MbscRecurrenceRule)* - Exception rule of the recurring rule. Useful when recurring dates need to be skipped from the rule. - `start`: *string | object | Date* - Specifies the start date/time of a date/time range when this is applicable - `textColor`: *string* - A color applied on the text. - `title`: *string* - A title that will be displayed on the item. ### MbscDateType string | Date | object ### MbscDatepickerControl "calendar" | "date" | "time" | "datetime" | "timegrid" ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscPopupButton Interface Properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ### MbscPopupDisplay "center" | "bottom" | "top" | "anchored" | "inline" | "bubble" ### MbscPopupPredefinedButton "set" | "cancel" | "ok" | "close" ### MbscRecurrenceRule Interface Properties: - `count`: *number* - `day`: *number | Array* - `from`: *[MbscDateType](#type-MbscDateType)* - `interval`: *number* - `month`: *number | Array* - `pos`: *number* - `repeat`: *"daily" | "weekly" | "monthly" | "yearly"* - `until`: *[MbscDateType](#type-MbscDateType)* - `weekDays`: *string* - `weekStart`: *string* ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscDatepickerOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscTimezonePlugin Interface Properties: - `createDate`: *(s: any, year: string | number | Date | MbscTimezonedDate, month: number, date: number, h: number, min: number, sec: number, ms: number) => MbscTimezonedDate* - `parse`: *(date: string | number, s: any) => MbscTimezonedDate* --- ## Controls The Datepicker component can render different kinds of controls on the screen. These controls are referred to as the **Calendar view**, the **Date scroller**, the **Time scroller**, the **Date & time scroller** and the **Timegrid**. Each of these controls are suitable in different scenarios, depending on the use-case. For example, the Date scroller can be used for selecting a single date, as well as the Calendar view. But only the Calendar view can be used for [selecting multiple dates](./value-selection#multiple). The [`controls`](./api#opt-controls) option specifies which control is rendered on the UI and it can use the following values: * The **Calendar view** can be used for single or multiple date selection as well as date range selection. It is represented by the `'calendar'` string. It is the **default** of the controls option. ```ts // highlight-next-line @Component({...}) export class AppComponent { // highlight-next-line myControl: MbscDatepickerControl[] = ['calendar'], } ``` ```html ``` * The **Date scroller** can be used for single date selection or date range selection. It is represented by the `'date'` string. ```ts // highlight-next-line @Component({...}) export class AppComponent { // highlight-next-line myControl: MbscDatepickerControl[] = ['date'], } ``` ```html ``` * The **Time scroller** can be used for single time selection or time range selection. It can also be combined with other controls. It is represented by the `'time'` string. ```ts // highlight-next-line @Component({...}) export class AppComponent { // highlight-next-line myControl: MbscDatepickerControl[] = ['time'], } ``` ```html ``` * The **Date & Time scroller** can be used for single date & time selection as well as date & time range selection. It is represented by the `'datetime'` string. ```ts // highlight-next-line @Component({...}) export class AppComponent { // highlight-next-line myControl: MbscDatepickerControl[] = ['datetime'], } ``` ```html ``` * The **Timegrid** can be used for single time selection or time range selection. It can also be combined with the `'calendar'` or the `'date'` control. It is represented by the `'timegrid'` string. ```ts // highlight-next-line @Component({...}) export class AppComponent { // highlight-next-line myControl: MbscDatepickerControl[] = ['timegrid'], } ``` ```html ``` ## Control combinations Some controls can't be used in all situations. To have a better user experience, controls can be combined. The [`controls`](./api#opt-controls) option takes an array of strings, with the above predefined values. The Time scroller and the Timegrid controls can be combined with either the Calendar view or the Date scroller for extending the selection precision. ```js title="Combining controls" @Component({...}) export class AppComponent { myControlCombo1: MbscDatepickerControl[] = ['calendar', 'timegrid']; myControlCombo2: MbscDatepickerControl[] = ['calendar', 'time']; myControlCombo3: MbscDatepickerControl[] = ['date', 'time']; myControlCombo4: MbscDatepickerControl[] = ['date', 'timegrid']; } ``` --- ## Customizing the input ## Overview The datepicker, as explained below, can be used with one, two or no inputs. ## Using without inputs The first choice of input customization is to have no inputs at all. In this case rendering the component in [inline display](/angular/datepicker/display-modes) mode will leave out the use of inputs. ```html title="Inline picker" ``` ## Using with one input The datepicker component will render a Mobiscroll Input by default. This input will hold the formatted value after selection. Having a custom input can be achived using the datepicker directive on the component you want. ```ts title="Using the datepicker on an IonInput" @Component({...}) export class AppComponent { // highlight-next-line myDatepickerOptions = { select: 'date', controls: ['calendar'] }; } ``` ```html ``` ## Using with two inputs When selecting a range, you have basically two values to display: the start of the range and the end of the range. These can be shown in different inputs using the [`startInput`](/angular/datepicker/api#opt-startInput) and the [`endInput`](/angular/datepicker/api#opt-endInput) options. ```html title="Two inputs for range selection" ``` When the [`startInput`](/angular/datepicker/api#opt-startInput) and the [`endInput`](/angular/datepicker/api#opt-endInput) options are provided, the datepicker will not render any other inputs. It will open when these inputs are focused/clicked instead. --- ## Display modes The component supports five display modes that specify where on the screen is it going to render itself: 1. `'center'` - will render the Datepicker on the center of the screen 2. `'top'` - will render the Datepicker on the top of the screen sliding down 3. `'bottom'` - will render the Datepicker on the bottom of the screen sliding up 4. `'anchored'` - will render the Datepicker above or below the element it is anchored to. The [`anchor`](./api#opt-anchor) option will specify the element to which the Datepicker is positioned. By default it is the input element rendered by the datepicker. 5. `'inline'` - will render the Datepicker into the page embedded. Additionally to the display option, the picker also takes into consideration the environment, whether it is used on mobile or a desktop device. This is represented by the [`touchUi`](./api#opt-touchUi) option and by default it is set to automatically detect the environment. :::info The default buttons that appear on the picker depend on the display mode and touchUi option. It also determins if the picker operates in [live selection](./live-selection) or not. ::: ```html title="Setting a display option" ``` --- ## Exclusive end dates ## The problem To understand why we need exclusive end dates support, we need to look at what dates and date ranges represent. Javascript date objects (and ISO8601 date strings - no matter the format) technically represent a point in time. A date range on the other hand is a duration between two points in time (the start of the range and the end of the range). The problem comes when we want to translate between the daily language to the technical world. For example, when we say "I'm on holiday from the 21st until the 27th of July" we refer to this range as ``` 2022-07-21 - 2022-07-27 ``` Technically this range ends at the first moment on the 27th of July, because `2022-07-27` is the same as `2022-07-27T00:00:00.000`. But we think of it as the whole day, meaning I'm still on holiday on the 27th (and expect my colleages not to bother me with work). The correct and precise timestamps for the above range, which I actually mean is the following: ``` 2022-07-21T00:00:00.000 - 2022-07-27T23:59:59.999 ``` To work with this end date is a bit awkward and because of that also error prone. It's not easily readable and also causes calculation headaches. For example if we try to calculate how long is this vacation (duration = end - start) we get 7 days minus 1 millisecond. ## The solution The solution to this problem is the [`exclusiveEndDates`](./api#opt-exclusiveEndDates) option. When this options is `true` and we select dates only, without time part, we always exclude the end date from the range. To keep going with the above example, the selected range will be: ``` 2022-07-21 - 2022-07-28 ``` In terms of UX, the user should not have to think about all that, so the Datepicker will show the correct range for them. On the calendar for example, the highlighted range will still be 21st-27th, but the returned dates will be 21st and 28th. :::caution Enabling exclusive end dates can cause breaking changes. The [`invalid`](./api#opt-invalid), [`labels`](./api#opt-labels), [`marked`](./api#opt-marked) and [`colors`](./api#opt-colors) options all can be specified with date ranges, and these ranges will be interpreted according to the `exclusiveEndDate` option. With inclusive end dates an invalid with start: '2021-07-09' and end: '2021-07-10' will disable two days on the calendar, the 9th and 10th of July. With exclusive end dates only a single day will be disabled, the 9th of July. ::: --- ## Live selection The component can operate in two modes that depends on whether the picker renders a Set button or not. When there is no Set button rendered, the picker operates in a "live" selection mode. What is selected on the UI, gets written into the input element and the model immediately. When there is a Set button rendered, the selection on the UI becomes temporary as long as the Set button is not clicked. The default of the rendered buttons depend on the [`display`](./api#opt-display) and the [`touchUi`](./api#opt-touchUi) options, but can be overwritten with the [`buttons`](./api#opt-buttons) option. For the `center`, `top` and `bottom` display modes and also for the `anchored` when the `touchUi` option is `true` (mobile), there is a Set button rendered by default. For the `inline` display mode and also for the `anchored` when the `touchUi` options is `false` (desktop), there will not be a Set button rendered. When needed, the temporary value mentioned above can be queried using the [`getTempVal`](./api#method-getTempVal) and set using the [`setTempVal`](./api#method-setTempVal) methods of the component [instance](../core-concepts/instance). Furthermore the [`onTempChange`](./api#event-onTempChange) event is raised whenever the temporary value changes. --- ## Date & Time picker The Datepicker component is the ultimate tool for selecting a [single date](https://demo.mobiscroll.com/calendar) and/[or time](https://demo.mobiscroll.com/datetime), [multiple dates](https://demo.mobiscroll.com/calendar/multiple-select#) or a [date range](https://demo.mobiscroll.com/range). ## Usage The following example will create a Datepicker with default options. ```html ``` For many more examples - simple and complex use-cases - check out the [date & time picker demos](https://demo.mobiscroll.com/calendar). --- ## Return value The default type of return values is the JavaScript Date object, but Mobiscroll supports more types than that. The Datepicker will choose the type depending on the [`returnFormat`](./api#opt-returnFormat) option. :::caution When using a timezone plugin, the Datepicker will return the selected values in **ISO8601** strings, regardless of the returnFormat option. ::: Here's a list on supported formats and some hints on where are they really usefull: - `'jsdate'` - JavaScript date object - For example if you need to manipulate programmatically the selected value further, the Date object is a good starting point, since it has most of the functions for date & time manipulation - `'iso8601'` - ISO 8601 date string - For example if you need to send the selected value to a server, or need to serialize it, the ISO8601 string is the way to go. - `'locale'` - Formatted date string based on the [`locale`](./api#localization-locale) option, or the [`dateFormat`](./api#localization-dateFormat) and [`timeFormat`](./api#localization-timeFormat) options, if they are specified. It gives the most flexible formatting options. - `'moment'` - moment object - The [Moment.js](https://momentjs.com/) library helps in manipulating the date & time values. It has many functions the built in JavaScript Date object doesn't. It is very convenient when working a lot with dates. When working with 'moment', you need to ensure that your project [includes the Moment.js library](https://momentjs.com/docs/#/use-it/) and also you will need to pass the moment libary reference to the Datepicker. Example on how to pass Moment.js to the Datepicker: **app.component.html** ```html ``` **app.component.ts** ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { // highlight-next-line theMomentLib = moment; } ``` --- ## Templating(Datepicker) The display of the Datepicker component can be customized with different [templating functions](api#templates). ## Calendar header template The header of the calendar can be fully customized to one's needs with the use of the [`calendarHeaderTemplate`](api#template-calendarHeaderTemplate) option. ```html

Any Title you want here or

 ``` While fully customizing the header is very usefull, sometimes it's desireable to customize only parts of it. In this case you can take advantage of the default header's building blocks. These components let you put toghether the header you want, while you don't have to worry about the functionality behind them. For example you can leave out parts from the default header, change the order of the default buttons appearance or add custom components between them. Here's the list of the built in components of the default header: - `` - Previous button component, that navigates to the previous month. - `` - Next button component, that navigates to the next month. - `` - Today button component, that navigates to the current date. - `` - The title navigation button component, that opens the year/month navigation. The above components can be used inside of the custom header. The following example will render the prev and next buttons and then a custom title that is set from a custom variable (myTitle variable). ```html title="Custom header with default buttons"
{{myTitle}}
 ``` ```ts @Component(...) export class YourComponent { myTitle = 'My Custom Title'; } ``` ![Calendar header template](/img/calendar-header-template.png) ## Calendar cell template There are two options that enable the customization of calendar cells: the [`dayContentTemplate`](./api#template-dayContentTemplate) and the [`dayTemplate`](./api#template-dayTemplate) option. The difference between the two is that the Datepicker will style the cells by default (background, hover, etc.) in the case of the `dayContentTemplate` option and will render the dates as usual. The custom content will be rendered after the dates in each cell. In the case of the `dayTemplate` option however, both the styling and the content (the dates too) will come from the custom template. ```html title="Example of custom cells" **{{day.date.getDate()}}** ``` ![Calendar cell template](/img/calendar-cell-template.png) --- ## Timezones(Datepicker) By default the Datepicker uses the local timezone of the browser for value selection. If you want to select a date-time in a different timezone, you will need an external library to handle the timezone conversions. There are three libraries that Mobiscroll supports: [moment-timezone](https://momentjs.com/timezone/), [luxon](https://moment.github.io/luxon/) and [Day.js](https://day.js.org/). :::info When using a timezone plugin with the Datepicker, the returned values are always ISO 8601 date strings, no matter what [`returnFormat`](./api#opt-returnFormat) option is used. ::: :::info When using a timezone plugin with the Datepicker, the [`exclusiveEndDates`](./api#opt-exclusiveEndDates) options defaults to `true`. Learn more about [exclusive end dates](./exclusive-end-dates)! ::: ## Library Install To setup the library, first you have to install it on your page. In this guide we'll assume you are using npm to install packages, but you can consult the installation guide on the libraries official pages ([moment-timezone install page](https://momentjs.com/timezone/), [luxon install page](https://moment.github.io/luxon/)) for more options on how to install them. ### The Moment-Timezone library **1.** To install the moment-timezone library with npm you will need to run the following commands: ```bash npm install moment-timezone ``` **2.** After the library is installed, you will have to import it with the `momentTimezone` object from mobiscroll: **Moment library import** ```javascript import moment from 'moment-timezone'; ``` **3.** Then set the mobiscroll's reference to the imported library: **Moment library setup** ```javascript import moment from 'moment-timezone'; // highlight-next-line momentTimezone.moment = moment; ``` **4.** After that, you can pass the `momentTimezone` object to the Datepicker's [`timezonePlugin`](./api#opt-timezonePlugin) option. ```html ``` ```ts momentTimezone.moment = moment; @Component({...}) export class AppComponent { // highlight-next-line myPlugin: MbscTimezonePlugin = momentTimezone; myDataTz = 'utc'; myDisplayTz = 'Europe/Berlin'; } ``` ### The Luxon library **1.** To install the luxon library with npm you will need to run the following commands: ```bash npm install luxon ``` In case you are using typescript you can also consider installing the types, because they come separately: ```bash npm install --save-dev @types/luxon ``` **2.** After the library is installed, you will have to import it with the `luxonTimezone` object from mobiscroll: **Luxon library import** ```javascript import * as luxon from 'luxon'; ``` **3.** Then set the mobiscroll's reference to the imported library: **Luxon library setup** ```javascript import * as luxon from 'luxon'; // highlight-next-line luxonTimezone.luxon = luxon; ``` **4.** After that, you can pass the `luxonTimezone` object to the Datepicker's `timezonePlugin` option. ```html ``` ```ts luxonTimezone.luxon = luxon; @Component({...}) export class AppComponent { // highlight-next-line myPlugin: MbscTimezonePlugin = luxonTimezone; myDataTz = 'utc'; myDisplayTz = 'Europe/Berlin'; } ``` ### The Day.js library **1.** To install the Day.js library with npm you will need to run the following commands: ```bash npm install dayjs ``` **2.** After installing the library, the `utc` and `timezone` plugins need to be included. You'll also need to import the `dayjsTimezone` plugin from mobiscroll: **Day.js library import** ```javascript import dayjs from 'dayjs'; dayjs.extend(utc); dayjs.extend(timezone); ``` **3.** Then set the mobiscroll's reference to the imported library: ```javascript title="Day.js library setup" dayjsTimezone.dayjs = dayjs; ``` **4.** After that, you can pass the `dayjsTimezone` object to the Datepicker's `timezonePlugin` option. ```html ``` ```ts dayjs.extend(utc); dayjs.extend(timezone); dayjsTimezone.dayjs = dayjs; @Component({...}) export class AppComponent { // highlight-next-line myDayjsTimezone: MbscTimezonePlugin = dayjsTimezone; myDataTz = 'utc'; myDisplayTz = 'Europe/Berlin'; } ``` --- ## Value Selection The Datepicker can be used for 4 major date and time selection tasks: 1. [Single value selection](#single) - a single date, a single time or a single date-time - use the [date & time](https://demo.mobiscroll.com/angular/datetime) or [calendar](https://demo.mobiscroll.com/angular/calendar) 2. [Multiple value selection](#multiple) - one or more dates - use the [calendar](https://demo.mobiscroll.com/angular/calendar) 3. [Range selection](#range) - a pair of start/end date, a pair of start/end time or a pair of start/end date-times - use the [range picker](https://demo.mobiscroll.com/angular/range) 4. [Preset range selection](#preset-range) - for selecting a week or a predefined part of the week as a start/end date pair The [`select`](./api#opt-select) and [`selectMultiple`](./api#opt-selectMultiple) options control how the selection works. Also with the [`firstSelectDay`](./api#opt-firstSelectDay) and [`selectSize`](./api#opt-selectSize) options the selection can be tailored further, when using the `preset-range` selection. ## Single Value Selection This is the default behavior, and it can also be initialized with the `select="date"` option. Depending on the [controls](./controls) option, the Datepicker will select either a single date or a single time or both (a single datetime). ```html ``` The `myValue` in the above example will hold the selected value. :::info The type of the selected value depends on the [`returnFormat`](./api#opt-returnFormat) option. Learn more about the [returned value](./return-value)! ::: ## Multiple Value Selection The [`selectMultiple`](./api#opt-selectMultiple) option will enable the selection of multiple dates. It can be used with the calendar control only. The selected value in this case will be an array of dates instead of just a single date. ```html ``` ## Range Selection The Datepicker can be used to select a date or a time range. The range selection feature can be activated with the `select="range"` option. The selected value in this case will be an array of dates with two values: the start and the end. ```javascript title="Range value examples" const dateRangeExample1 = ['2023-10-19', '2023-10-24']; const dateRangeExample2 = [new Date(2023, 9, 19), new Date(2023, 9, 24)]; const timeRangeExample1 = ['10:00', '13:30']; const timeRangeExample2 = [new Date(2023, 9, 19, 10, 0), new Date(2023, 9, 19, 13, 30)]; ``` Depending on the [controls](./controls) passed to the datepicker, it will select a date range, a time range or a datetime range. Both the start and end value of the returned array will respect the [`returnFormat`](./api#opt-returnFormat) option. Learn more on how to work with ISO strings or date objects in the [Return value](./return-value) section. **app.component.html** ```html ``` **app.component.ts** ```ts // highlight-next-line @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], standalone: true, imports: [CommonModule, MbscModule] }) export class AppComponent { // highlight-next-line myTimeControl: Array = ['time']; } ``` The returned value after the selection in the above example will be an array with two ISO8601 strings: ```javascript title="Example value" ['14:50', '20:45'] ``` ## Preset-Range Selection The Datepicker can be used to select a week or predefined part of the week. The preset-range selection feature can be activated with the `select="preset-range"` option. The selected value in this case will be an array of dates with two values just like with range selection: the start and the end of the range. The difference in this case is that you don't have to select the start and end values separately. You can click any day on the week and the start and end values will be calculated accordingly. When the preset-range selection mode is on, the start date will be fixed to a specific day of the week (for example: Monday). This can be achieved with the [`firstSelectDay`](./api#opt-firstSelectDay) option, which defaults to the [`firstDay`](./api#localization-firstDay) of the week. The length of the selection will be a set number of days (for example: 5 days) and can be controlled with the [`selectSize`](./api#opt-selectSize) option. By default it is set to 7 (will select the whole week), but can be reduced to even a single day. ```html title="Example for selecting a work week (Monday to Friday)" ``` --- ## Accessibility(Select) ## Keyboard Support When focusing the input component rendered, one can open the Select using the Space or Enter keys. The `Tab` and `Shift + Tab` keys can be used for navigating between the rendered wheels if there are multiple wheels available (for example having a group wheel). Also if there is a filter input or there are buttons rendered, the same keys will cycle through them too. The `Up` and `Down` arrow keys can be used to focus wheelitems in desktop mode with the `Space` key to select the item. In mobile mode the arrow keys rotate the wheel so that automatically changes the selection. The `Enter` key can be used to confirm the selection and close the picker, while the `Esc` key will act as a cancel action (also closing the Select component). ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Supported aria-label on icon buttons, aria-hidden on decoration elements 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Supported label, description and icons can be specified for the picker input 1.3.6 Identify Purpose AAA Supported - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported - 1.4.11 Non-text Contrast AA Supported - 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Not Applicable - ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported - 2.1.2 No Keyboard Trap A Supported in case of modal picker there is a keyboard trap but can be closed by `ESCAPE` or `ENTER` 2.1.3 Keyboard (No Exception) AAA Supported - 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Not applicable - 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported - 2.2.4 Interruptions AAA Not Applicable - 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Not supported scroll wheel animation 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Supported label and description can be specified for the picker input 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Supported can be defined through `label` and `aria-label` options 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Not fully supported in case of the multiple select input clear buttons 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Not Applicable - 2.5.8 Target Size (Minimum) AA Not fully supported in case of the multiple select input clear buttons ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility Remarks 3.1 Readable 3.1.1 Language of Page A Not Applicable - 3.1.2 Language of Parts AA Not Applicable - 3.1.3 Unusual Words AAA Not Applicable - 3.1.4 Abbreviations AAA Not Applicable - 3.1.5 Reading Level AAA Not Applicable - 3.1.6 Pronunciation AAA Not Applicable - 3.2 Predictable 3.2.1 On Focus A Supported - 3.2.2 On Input A Not Applicable - 3.2.3 Consistent Navigation AA Not Applicable - 3.2.4 Consistent Identification AA Not Applicable - 3.2.5 Change on Request AAA Not Applicable - 3.2.6 Consistent Help A Not Applicable - 3.3 Input Assistance 3.3.1 Error Identification A Supported using the `error` and `error-message` options 3.3.2 Labels or Instructions A Supported can be defined through `label` and `aria-label` options 3.3.3 Error Suggestion AA Supported using the `error` and `error-message` options 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable - 3.3.5 Help AAA Not Applicable - 3.3.6 Error Prevention (All) AAA Not Applicable - 3.3.7 Redundant Entry A Not Applicable - 3.3.8 Accessible Authentication (Minimum) AA Not Applicable - 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable - ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Not Applicable --- ## Select API Here is a comprehensive list of all the options, events and methods of the Select component. ## Options Explore the following API options that help you easily configure the Select component. ### anchor HTMLElement Specifies the anchor element for positioning, if [display](#opt-display) is set to `'anchored'`. **Default value**: `undefined` ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed, if [display](#opt-display) is not set to `'inline'`. Possible values: - `'pop'` - `'slide-down'` - `'slide-up'` If `false`, the animation is turned off. **Default value**: `undefined` ### ariaLabel string Specifies the accessible name of the picker input. **Default value**: `undefined` ### buttons Array Buttons to display on the component. Each item of the array will be a button. A button can be specified as a string, or as a button object. If a string, it must be one of the predefined buttons: - `'ok'` - Approve action. Will display the caption specified by the [okText](#localization-okText) option. - `'cancel'` - Dismisses the popup. Will display the caption specified by the [cancelText](#localization-cancelText) option. - `'close'` - Closes the popup. Will display the caption specified by the [closeText](#localization-closeText) option. - `'set'` - Approve action. Will display the caption specified by the [setText](#localization-setText) option. The [`MbscPopupButton`](#type-MbscPopupButton) type has the following properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ```js title="Example for using predefined and custom buttons" [ 'set', { text: 'Custom', icon: 'checkmark', cssClass: 'my-btn', handler: function (event) { alert('Custom button clicked!'); } }, 'cancel' ] ``` ```js title="Example for using a predefined button handler" [ 'set', { text: 'Hide', handler: 'cancel', icon: 'close', cssClass: 'my-btn' } ] ``` **Default value**: `['set', 'cancel']` ### circular boolean | Array If `true`, the scroll wheels are circular. If an array, it can be specified as a per wheel configuration, e.g. for 3 wheels: `[true, false, false]` sets the first wheel circular. If not specified, if a wheel has more values than the number of the displayed rows, the scroll wheel becomes circular. **Default value**: `undefined` ### closeOnEsc boolean If `true`, the popup is closed when the ESC key is pressed. **Default value**: `true` ### closeOnOverlayClick boolean If `true`, the popup is closed on overlay click or tap. **Default value**: `true` ### context string | HTMLElement The DOM element in which the component is appended and positioned (when not inline). Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### data Array Specifies the selectable options for the component. When it's an array of strings, the selectable options will be the items of the array. The strings will appear on the picker, and the selected values will be the strings themselves. The [`MbscSelectData`](#type-MbscSelectData) type has the following properties: - `disabled`: *boolean* - The disabled state of the option. Disabled options cannot be selected. - `group`: *string* - The group name, in case of grouped options. - `text`: *string* - The label of the option - `value`: *any* - The value of the option **Default value**: `undefined` ### defaultSelection any Default selection which appears on the picker. The provided value will not be set as picker value, it's only a pre-selection. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the input. **Default value**: `false` ### display [MbscPopupDisplay](#type-MbscPopupDisplay) Controls the positioning of the component. Possible values are: - `'center'` - The component appears as a popup at the center of the viewport. - `'inline'` - The component is rendered inline. - `'anchored'` - The component appears positioned to the element defined by the [anchor](#opt-anchor) option. - `'top'` - The component appears docked to the top of the viewport. - `'bottom'` - The component appears docked to the bottom of the viewport. The default display mode depends on the [theme](#opt-theme), it defaults to `'bottom'` for the iOS theme and to `'center'` for all other themes. **Default value**: `undefined` ### dropdown boolean If `false`, the down arrow icon is hidden. **Default value**: `true` ### endIcon string Specifies the icon which will be displayed at the end of the input. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### error boolean If `true`, the input will be displayed with error styles. **Default value**: `false` ### errorMessage string Error message for the input. If the [error](#opt-error) option is set to `true`, the message will be displayed. **Default value**: `undefined` ### filter boolean If `true`, it turns filtering on. A filter input will be rendered above the selectable options. Typing in the input will filter the selectable options and will also trigger the [onFilter](#event-onFilter) event. The default behavior is based on the presence of the search term in the option text. The [onFilter](#event-onFilter) event can be used to prevent the default filtering and customize the experience. **Default value**: `false` ### focusOnClose boolean If `true`, after closing the popup the focus will be moved to the last focused element before the popup was opened. **Default value**: `true` ### focusTrap boolean If `true` and [display](#opt-display) is not set to `'inline'`, focus won't be allowed to leave the popup. **Default value**: `true` ### headerText string Specifies a custom string which appears in the picker header. If it contains the `'{value}'` string, it will be replaced with the selected value of the picker. **Default value**: `undefined` ### inputComponent any The input component to render if the picker is modal If not specified, it will render a [Mobiscroll Input](../forms/input) component. Props can be specified using the [inputProps](#opt-inputProps) option. **Default value**: `undefined` ### inputProps any Props for the rendered input, specified by the [inputComponent](#opt-inputComponent) option. **Default value**: `undefined` ### inputStyle "outline" | "box" | "underline" Specifies the style of the input. Possible values: - `'underline'` - `'box'` - `'outline'` The default value depends on the [theme](#opt-theme): - iOS: `'underline'` - Material: `'box'` - Windows: `'outline'` **Default value**: `undefined` ### invalid Array An array of values that are invalid. Invalid options cannot be selected, and show up as disabled on the Select. **Default value**: `undefined` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `false` ### itemHeight number Height in pixels of one item on the wheel. The default value depends on the [theme](#opt-theme): - iOS: 34 - Material: 40 - Windows: 44 ### label string Specifies the label of the input. **Default value**: `undefined` ### labelStyle "inline" | "floating" | "stacked" Specifies the position of the input label. Possible values: - `'stacked'` - `'inline'` - `'floating'` The default value depends on the [theme](#opt-theme): - iOS: `'inline'` - Material: `'floating'` - Windows: `'stacked'` **Default value**: `undefined` ### maxHeight string | number Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px. **Default value**: `undefined` ### maxWheelWidth number | Array Maximum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ### maxWidth string | number Sets the maximum width of the component. **Default value**: `undefined` ### minWheelWidth number | Array Minimum width of the scroller wheels in pixels. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### rows number Number of visible rows on the wheel. The default value depends on the [theme](#opt-theme): - iOS: 5 - Material: 3 - Windows: 6 ### selectMultiple boolean If `true`, multiple selection will be enabled. **Default value**: `false` ### showArrow boolean Show or hide the popup arrow, when [display](#opt-display) is `'anchored'`. **Default value**: `true` ### showGroupWheel boolean If `true` and the Select has groups, two columns will be rendered on the picker, the first containing the group labels, and the second one the options. Groups can be specified either by `optgroup` elements, when the data comes from the html markup, or by using the `group` property of the option objects, when the [data](#opt-data) option is used. **Default value**: `false` ### showInput boolean If `true`, it will render an input field for the component. **Default value**: `true` ### showOnClick boolean Opens the component on element click/tap. **Default value**: `true` ### showOnFocus boolean Opens the component on element focus. **Default value**: `false on desktop, true on mobile` ### showOverlay boolean Show or hide the popup overlay. **Default value**: `true` ### startIcon string Specifies the icon which will be displayed at the start of the input. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### tagInput boolean If `true` and used with [multiple selection](#opt-selectMultiple), it will display the selected values inside the input as tags (chips). **Default value**: `false` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### touchUi boolean | "auto" Use `true` to render a touch optimized user interface, or `false` for a user interface optimized for pointer devices (mouse, touchpad). Can be used with the [responsive](#opt-responsive) option to change the user interface based on viewport width. If set to `'auto'`, the touch UI will be automatically enabled based on the platform. **Default value**: `'auto'` ### wheelWidth number | Array Width of the scroller wheels, in pixels. Wheel content will be truncated, if it exceeds the width. If a number, it is applied to all wheels, if an array, it is applied to each wheel separately. **Default value**: `undefined` ## Events The Select component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onCancel (args: MbscSelectCancelEvent, inst: SelectBase) => void Triggered when the picker is canceled. Parameters: - args - The event argument with the following properties: - `value`: *any* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onChange (args: MbscSelectChangeEvent, inst: SelectBase) => void Triggered when the value is changed. Parameters: - args - The event argument with the following properties: - `value`: *any* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onClose (args: MbscSelectCloseEvent, inst: SelectBase) => void Triggered when the picker is closed. Parameters: - args - The event argument with the following properties: - `value`: *any* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onFilter (args: MbscSelectFilterEvent, inst: SelectBase) => boolean | void Triggered when the value of the filter input changes. Filtering can be turned on with the [filter](#opt-filter) option. To fully customize the filtering, the default behavior can be prevented by returning `false` from the handler function. Parameters: - args - The event argument with the following properties: - `filterText`: *string* - The value of the filter input. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onOpen (args: MbscSelectOpenEvent, inst: SelectBase) => void Triggered when the picker is opened. Parameters: - args - The event argument with the following properties: - `target`: *HTMLElement* - The DOM element of the popup. - `value`: *any* - The selected value. - `valueText`: *string* - The selected value as text. - inst - The component instance. ### onTempChange (args: MbscSelectTempChangeEvent, inst: SelectBase) => void Triggered when the temporary value is changed. Parameters: - args - The event argument with the following properties: - `value`: *any* - The selected value. - inst - The component instance. ## Localization The Select component is fully localized. This covers date and time format, button copy, rtl and more. ### cancelText string Text for the "Cancel" button. **Default value**: `'Cancel'` ### closeText string Text for the "Close" button. **Default value**: `'Close'` ### filterEmptyText string Text for the empty state of the Select. The Select will show this message, when [filtering](#opt-filter) is turned on and there are no results for the searched text. **Default value**: `'No results'` ### filterPlaceholderText string Placeholder text for the filter input, when [filtering](#opt-filter) is turned on. **Default value**: `'Search'` ### groupText string Specifies the accessibility label for the group wheel, when present. **Default value**: `'Group'` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### okText string Text for the "Ok" button. **Default value**: `'Ok'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### setText string Text for the "Set" button. **Default value**: `'Set'` ## Methods These methods are actions that can be performed on a component instance. ### getTempVal () => any Returns the temporary value selected on the picker. ### isVisible () => boolean Returns a boolean indicating whether the component is visible or not. ### position () => void Recalculates the position of the component (if not inline). ### setTempVal (value: any) => void Sets the temporary value to be selected on the picker. The value will be committed when the user hits the set button. Parameters: - value - The value to set. ## Templates The display of the Select component can be customized with different templating functions. ### itemTemplate Template to customize each selectable item on the wheel. When the group wheel is also shown using the [`showGroupWheel`](#opt-showGroupWheel) option, the `data` property and the `isGroup` property of the item will be `undefined` in the case of the group wheel items. So, you can distinguish from the group wheel and the option wheel by checking if both the `data` and the `isGroup` are undefined. Available parameters: - `display`: _string_ - The text of the item. - `value`: _any_ - The value of the item. - `isGroup`: _boolean_ - For group headers this property will be true - `data`: _MbscSelectData_ - The original option item that is passed in the [`data`](#opt-data) array **Default value**: `undefined` ## Types ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscPopupButton Interface Properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ### MbscPopupDisplay "center" | "bottom" | "top" | "anchored" | "inline" | "bubble" ### MbscPopupPredefinedButton "set" | "cancel" | "ok" | "close" ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscSelectOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px ### MbscSelectData Interface Properties: - `disabled`: *boolean* - The disabled state of the option. Disabled options cannot be selected. - `group`: *string* - The group name, in case of grouped options. - `text`: *string* - The label of the option - `value`: *any* - The value of the option The `MbscSelectData` supports custom properties in the form: ``` [key:string]: any ``` The data object is available in the [templates](./templating), so it is a convenient way for customizing the items on the select. Example: ```js { value: 'US', text: 'United States of America', flagUrl: '//urlto/usa-flag', // custom property }, { value: 'DE', text: 'Germany', flagUrl: '//urlto/german-flag', } ``` --- ## Customizing the input(Select) When initializing the Select component on a native select element, by default that element will be hidden and an input element is rendered that will hold the selection text. Also this input element gets the focus and click handlers that will open the picker. ```jsx ``` You can use any custom input with the select component using the `inputElement` [option](/5.35.0/angular/select/api#opt-inputElement). Passing another element to it, the default input won't be rendered. The passed element will get the event handlers to open the picker, and also the selected value's text will be written to it as well. This option will only work with the directive version of the component. ```jsx ``` --- ## Data binding(Select) ## Data option The Mobiscroll Select component has a [`data`](./api#opt-data) option, that is used to define the selection options. The `data` option receives an array of strings or an array of objects containing a `text`, a `value` and optionally a `group` property. The text must be a string, which will show up on the wheels. The value can be any kind of object (string, number, object, etc.), that will be the selected value when selecting it on the select. The group property must be a string, that is used to group together a number of options. The options that have the same string specified by the group property will be grouped together. When groups are specified in the data, a header will be shown at the top of each group with the text specified in the group property. Additionally, when using the [`showGroupWheel`](./api#opt-showGroupWheel) option, an additional wheel will be shown, with the groups to help navigation. More on that in the [Grouping section](#grouping) below. When an array of string is passed to the data option, it is treated as both the `text` and the `value` would be the particular array item. ```javascript const strArray = ['USA', 'Canada', 'Mexico']; // is the same as: const objArray = [{ text: 'USA', value: 'USA'}, { text: 'Canada', value: 'Canada'}, { text: 'Mexico', value: 'Mexico' }]; ``` In the above example the two arrays will show the same 3 countries to select from, and the selected value will also be the country's name as string. #### Example with numbers as values ```html title="Department selection example" ``` ```ts @Component({...}) export class MyComponent { myData: MbscSelectData = [ { text: 'Marketing', value: 1 }, { text: 'Sales', value: 2 }, { text: 'Support', value: 3 }, { text: 'Development', value: 4 }, ]; selectedValue: number = 2; } ``` #### Example with complex objects as values ```html title="Department selection example" ``` ```ts @Component({...}) export class MyComponent { myData: MbscSelectData = [ { text: 'Alice', value: { id: 123, fullName: 'Alice Cooper' }}, { text: 'Brandon', value: { id: 456, fullName: 'Brandon Lee' }}, { text: 'Louisa', value: { id: 789, fullName: 'Louisa Crawford'}}, ]; mySelectedUser: MyUser | null = null; } ``` ### Dynamic or async data The select component supports dynamic data binding. For cases when the data is not immediately available or when the data changes with time (new options are added, or others removed) this feature is the most usefull. ## Group options Through the [`data`](./api#opt-data) option, with each item can be passed an optional `group` property. This `group` property is a string, that defines the group of the item. When the group is passed to any of the items, the whole data is treated as grouped and a header will be rendered above each group on the Select wheels. The header will contain the group name as specified in the group property. ```javascript title="Assigning groups to items" const myCountries = [{ text: 'United Kingdom', value: 'GB', }, { text: 'France', value: 'FR', // highlight-next-line group: 'Europe' }, { text: 'Hungary', value: 'HU', // highlight-next-line group: 'Europe' }, { text: 'United States of America', value: 'US', // highlight-next-line group: 'America' }]; ``` Furthermore an additional "group wheel" can be also rendered with the [`showGroupWheel`](./api#opt-showGroupWheel) option set to `true`. The group wheel items will be the group property values or the optgroup label attributes, and will help in navigating the option wheel. ```html ``` ```ts @Component({...}) export class MyComponent { myCountries: MbscSelectData = [{ text: 'France', value: 'FR', group: 'Europe' }, { text: 'Hungary', value: 'HU', group: 'Europe' } // ... ]; selected: string = 'HU'; } ``` ## Data through templates Just like the native `` or ``, the [`data`](./api#opt-data) option must be provided. ```html title="Using with an input" ``` When using the select directive with ` ``` ### Working with Ionic Ionic is a good example for custom components usage. For instance, the select directive can be used on an `` component, thus one can have the selection handled by the select and at the same time maintain the style of an ionic form. ```html My Label ``` --- ## Display modes(Select) The component supports five display modes that specify where on the screen is it going to render itself: 1. `'center'` - will render the Datepicker on the center of the screen 2. `'top'` - will render the Datepicker on the top of the screen sliding down 3. `'bottom'` - will render the Datepicker on the bottom of the screen sliding up 4. `'anchored'` - will render the Datepicker above or below the element it is anchored to. The [`anchor`](./api#opt-anchor) option will specify the element to which the Datepicker is positioned. By default it is the input element rendered by the datepicker. 5. `'inline'` - will render the Datepicker into the page embedded. Additionally to the display option, the picker also takes into consideration the environment, whether it is used on mobile or a desktop device. This is represented by the [`touchUi`](./api#opt-touchUi) option and by default it is set to automatically detect the environment. :::info The default buttons that appear on the picker depend on the display mode and touchUi option. It also determins if the picker operates in [live selection](./live-selection) or not. ::: ```html title="Setting a display option" ``` --- ## Filtering Filtering can be turned on with the [`filter`](./api#opt-filter) option. It is very usefull when using large datasets and you want to find a particular item. When filtering is on, a filter input is rendered above the selectable options. The placeholder of the input can be customized and localized with the [`filterPlaceholderText`](./api#localization-filterPlaceholderText) option. Typing a text in the input filters the options you can choose from. Also, with each change on the filter input text, the [`onFilter`](./api#event-onFilter) event is triggered. When no items match the filter the Mobiscroll Select will show a "No results" message, that can be customized and localized with the [`filterEmptyText`](./api#localization-filterEmptyText) option. ## Local Filtering By defaut filtering is done client side on the dataset passed to the Select with the [data](./api#opt-data) option. The filter text is searched in the option items `text` property and if there is a match the item stays in the list - otherwise it's hidden. ```html ``` ```ts @Component({...}) export class MyComponent { countries: MbscSelectData[] = [ { text: 'US - United States', value: 3 }, { text: 'DE - Germany', value: 19 }, { text: 'HU - Hungary', value: 93 }, // ... long list of 195 countries { text: 'ZW - Zimbabwe', values: 73 }, ]; } ``` ## Remote Filtering Server side filtering can be implemented with the help of the [`onFilter`](./api#event-onFilter) event and using the [`data`](./api#opt-data) option dynamically. Returning `false` from the [`onFilter`](./api#event-onFilter) event handler will prevent the filtering of the option items locally. Then, a request can be made to the server with the `filterText` and the returned data can be set to the Select dynamically. ```html ``` ```ts @Component({...}) export class MyComponent { myData: MbscSelectData[] = []; mySelectOptions: MbscSelectOptions = { filter: true, onFilter: (args: MbscSelectFilterEvent) => { const text = args.filterText; // create a request here and set the results to the data myCreateARequestMethod(text) .then((filteredArray) => { // highlight-start // this is probably an async operation this.myData = filteredArray; // highlight-end }); // highlight-start // this is synchronous return false; // highlight-end } } } ``` :::caution When implementing remote filtering, you have to use the `[options]` attribute instead of subscribing to the `(onFilter)` event emitter. The `(onFilter)` event emitter is asynchronous and returning `false` there is too late to cancel the built in filtering of the select. Event handlers in the `[options]` object are synchronous and makes this implementation possible. ::: :::info In the above example, we did not specify any library to handle the remote calls on purpose. If you need a library to handle http requests, check out [Axios](https://github.com/axios/axios). It's a very popular library. ::: --- ## Invalid items Invalid items are items that cannot be selected. They appear disabled on the wheels and when clicked, a selection will not happen. Invalid items can be set using the `invalid` [option](/angular/select/api#opt-invalid) or the `data` [option](/angular/select/api#opt-data). The `invalid` [option](/angular/select/api#opt-invalid) takes an array of values and disables those values. When using the `data` [option](/angular/select/api#opt-data), each item can take a disables property, that `disables` that item. ```html title="Invalid example" ``` ```ts @Component(...) export class MyComponent { public extras = [ { value: 'sug', text: 'Sugar'}, { value: 'hon', disabled: true, text: 'Honey'}, { value: 'cre', text: 'Cream' } ]; public myInvalid = ['sug']; public selectedExtra: string; } ``` --- ## Live selection(Select) The component can operate in two modes that depends on whether the picker renders a Set button or not. When there is no Set button rendered, the picker operates in a "live" selection mode. What is selected on the UI, gets written into the input element and the model immediately. When there is a Set button rendered, the selection on the UI becomes temporary as long as the Set button is not clicked. The default of the rendered buttons depend on the [`display`](./api#opt-display) and the [`touchUi`](./api#opt-touchUi) options, but can be overwritten with the [`buttons`](./api#opt-buttons) option. For the `center`, `top` and `bottom` display modes and also for the `anchored` when the `touchUi` option is `true` (mobile), there is a Set button rendered by default. For the `inline` display mode and also for the `anchored` when the `touchUi` options is `false` (desktop), there will not be a Set button rendered. When needed, the temporary value mentioned above can be queried using the [`getTempVal`](./api#method-getTempVal) and set using the [`setTempVal`](./api#method-setTempVal) methods of the component [instance](../core-concepts/instance). Furthermore the [`onTempChange`](./api#event-onTempChange) event is raised whenever the temporary value changes. --- ## Select The Select component lets you pick a [single value](https://demo.mobiscroll.com/select/single-select#) or [multiple values](https://demo.mobiscroll.com/select/multiple-select#) from a list of options. ## Usage The following example will create a Select component with four options to choose from, each of them being a city. ```html ``` ```ts @Component({...}) export class MyComponent { myData: MbscSelectData[] = [ { text: 'Atlanta', value: 1 }, { text: 'Berlin', value: 2 }, { text: 'Chicago', value: 3 }, { text: 'London', value: 4 }, ]; } ``` For many more examples - simple and complex use-cases - check out the [select demos](https://demo.mobiscroll.com/select). --- ## Templating(Select) The selectable options (items) on the Select UI can be customized using the [`itemTemplate`](./api#template-itemTemplate) and the [`itemHeight`](./api#opt-itemHeight) options. The item data is accessible through the `data` property of the template parameter. ```html
{{item.data.text}}
{{item.data.value}}
{{item.data.yourCustomProperty}}
 ``` #### Example for adding images to items ```html
{{item.data.text}}
``` ```ts @Component({...}) export class MyComponent { countries: MbscSelectData[] = [{ value: 'US', text: 'United States of America', flagUrl: '//urlto/usa-flag', }, { value: 'DE', text: 'Germany', flagUrl: '//urlto/german-flag', }, { value: 'FR', text: 'France', flagUrl: '//urlto/french-flag', }]; } ``` :::info Every item on the Select must have the same height. For styles that go beyond the default height, the [`itemHeight`](./api#opt-itemHeight) option can be used to adjust the styling. ::: --- ## Value Selection(Select) The Select component can be used to select one or multiple values from a list. The values can be of any type, for example `number`, `string` or `object` as described in the [data binding](./data-binding) section. ## Single value selection By default the Select operates in single value selection mode, but can be used to select multiple values from a list as well. ```html ``` ```ts @Component({...}) export class MyComponent { drinks: MbscSelectData[] = [ { text: 'Mohito', value: 'mohito'}, { text: 'Long Island', value: 'longisland'}, { text: 'Margarita', value: 'margarita'} ]; selected: string | null = null; } ``` ## Multiple value selection Multiselection can be enabled using the [`selectMultiple`](./api#opt-selectMultiple) option. ```html ``` ```ts @Component({...}) export class MyComponent { bonuses: MbscSelectData[] = ['Free ticket', 'Free Drink', 'Free Hug']; selected: string[] = []; } ``` --- ## Accessibility(Forms) ## Keyboard Support The `Tab` and `Shift + Tab` keys can be used to navigate between the Form elements. Buttons can be activated using the `Space` key. The `Up`, `Down`, `Left`, `Right` arrows to change the selected segmented item. ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Supported name, label, and aria-label can be specified 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Supported input type, autocomplete, icon, and description can be specified 1.3.6 Identify Purpose AAA Supported - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported - 1.4.11 Non-text Contrast AA Supported - 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Not Applicable - ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported - 2.1.2 No Keyboard Trap A Supported - 2.1.3 Keyboard (No Exception) AAA Supported - 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Not applicable - 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported - 2.2.4 Interruptions AAA Not Applicable - 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Not fully supported animations for the Switch and Segmented button can't be turned off 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Supported - 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not fully supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Supported - 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Supported - 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Supported - 2.5.8 Target Size (Minimum) AA Supported - ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility Remarks 3.1 Readable 3.1.1 Language of Page A Not Applicable - 3.1.2 Language of Parts AA Not Applicable - 3.1.3 Unusual Words AAA Not Applicable - 3.1.4 Abbreviations AAA Not Applicable - 3.1.5 Reading Level AAA Not Applicable - 3.1.6 Pronunciation AAA Not Applicable - 3.2 Predictable 3.2.1 On Focus A Supported - 3.2.2 On Input A Not Applicable - 3.2.3 Consistent Navigation AA Not Applicable - 3.2.4 Consistent Identification AA Not Applicable - 3.2.5 Change on Request AAA Not Applicable - 3.2.6 Consistent Help A Not Applicable - 3.3 Input Assistance 3.3.1 Error Identification A Supported using the `error` and `error-message` options 3.3.2 Labels or Instructions A Supported can be defined through `label`, `aria-label`, and `description` options 3.3.3 Error Suggestion AA Supported using the `error` and `error-message` options 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable - 3.3.5 Help AAA Not Applicable - 3.3.6 Error Prevention (All) AAA Not Applicable - 3.3.7 Redundant Entry A Not Applicable - 3.3.8 Accessible Authentication (Minimum) AA Not Applicable - 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable - ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Not Applicable --- ## Button The Button component is an interactive element activated by the user. Once activated, it performs an action, such as submitting a form or opening a dialog. ## Usage Buttons can display text, icons, or both. They can be colored and styled with various options. #### Button styles ```html title="Button variations" Standard button Flat button Outline button With start icon With end icon Primary button Secondary button Success button Danger button Warning button Info button Light button Dark button ``` #### Button sizes and groups ```html Full width Button
Button 1 Button 2 Button 3
Button 1 Button 2 Button 3
Button 1 Button 2 Button 3
``` ## Handling clicks Clicks can be handled using the standard `click` event. ```html Click me! ``` ## Options Explore the following API options that help you easily configure the Button component. ### ariaLabel string Specifies the accessible name of the button. Recommended for icon-only buttons. **Default value**: `undefined` ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the button. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the button. **Default value**: `false` ### endIcon any Specifies the icon which will be displayed at the end of the button. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### icon any Specifies the icon for an icon-only button. **Default value**: `undefined` ### startIcon any Specifies the icon which will be displayed at the start of the button. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### tabIndex number Specifies the `tabindex` attribute of the button. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### variant "outline" | "standard" | "flat" Specifies the style of the button. **Default value**: `'standard'` ## Localization The Button component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` ## Events The Button component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. --- ## Checkbox The Checkbox component allow the selection of multiple options from a set. They appear as checked when activated. ## Usage Use the [`label`](#opt-label) option to provide a label to the Checkbox. The Checkbox can be positioned before or after the label using the [`position`](#opt-position) option. ```html ``` ## Value binding The Checkbox can be bound to a boolean value using either the `[(ngModel)]` or the `formControlName` directives. In this case the Checkbox will update it's state according to the bound the value. ```html ``` ```ts @Component({...}) export class MyComponent { bedroomLight = false; } ``` ## Options Explore the following API options that help you easily configure the Checkbox compoennt. ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the checkbox. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### description string Specifies the description text of the checkbox. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the checkbox. **Default value**: `false` ### label string Specifies the label of the checkbox. **Default value**: `undefined` ### position "end" | "start" Sets the position of the checkbox depending on the [rtl](#localization-rtl) option. When in left-to-right mode, `'start'` will render the checkbox to the left, and `'end'` will render it to the right. In right-to-left mode, `'start'` will render the checkbox to the right, and `'end'` will render it to the left. **Default value**: `'end'` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Checkbox component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Checkbox component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Dropdown The Dropdown component can be used for collecting user provided information from a set of options. ## Usage Use the [`label`](#opt-label) option to provide a label to the dropdown. ```html ``` ```html title="Dynamic options" ``` ## Value binding The dropdown can be bound to a string value using either the `[(ngModel)]` or the `formControlName` directives. In this case the dropdown will update it's state according to the bound value. ```html ``` ## Options Explore the following API options that help you easily configure the Dropdown component. ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the input. **Default value**: `false` ### endIcon string Specifies the icon which will be displayed at the end of the input. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### error boolean If `true`, the input will be displayed with error styles. **Default value**: `false` ### errorMessage string Error message for the input. If the [error](#opt-error) option is set to `true`, the message will be displayed. **Default value**: `undefined` ### inputStyle "outline" | "box" | "underline" Specifies the style of the input. Possible values: - `'underline'` - `'box'` - `'outline'` The default value depends on the [theme](#opt-theme): - iOS: `'underline'` - Material: `'box'` - Windows: `'outline'` **Default value**: `undefined` ### label string Specifies the label of the input. **Default value**: `undefined` ### labelStyle "inline" | "floating" | "stacked" Specifies the position of the input label. Possible values: - `'stacked'` - `'inline'` - `'floating'` The default value depends on the [theme](#opt-theme): - iOS: `'inline'` - Material: `'floating'` - Windows: `'stacked'` **Default value**: `undefined` ### startIcon string Specifies the icon which will be displayed at the start of the input. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Dropdown component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Dropdown component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Input The Input component can be used for collecting information from the user. ## Usage Use the [`label`](#opt-label) option to provide a label to the input field. ```html ``` ## Input style With the [`inputStyle`](#opt-inputStyle) attribute you can customize the look of input. There are three styles to choose from: ```html ``` ## Label style With the [`labelStyle`](#opt-labelStyle) attribute you can define the position of the label. ```html ``` ## Value binding The input can be bound to a string value using either the `[(ngModel)]` or the `formControlName` directives. In this case the input will update it's state according to the bound value. ```html ``` ## Options Explore the following API options that help you easily configure the Input component. ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the input. **Default value**: `false` ### endIcon string Specifies the icon which will be displayed at the end of the input. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### error boolean If `true`, the input will be displayed with error styles. **Default value**: `false` ### errorMessage string Error message for the input. If the [error](#opt-error) option is set to `true`, the message will be displayed. **Default value**: `undefined` ### inputStyle "outline" | "box" | "underline" Specifies the style of the input. Possible values: - `'underline'` - `'box'` - `'outline'` The default value depends on the [theme](#opt-theme): - iOS: `'underline'` - Material: `'box'` - Windows: `'outline'` **Default value**: `undefined` ### label string Specifies the label of the input. **Default value**: `undefined` ### labelStyle "inline" | "floating" | "stacked" Specifies the position of the input label. Possible values: - `'stacked'` - `'inline'` - `'floating'` The default value depends on the [theme](#opt-theme): - iOS: `'inline'` - Material: `'floating'` - Windows: `'stacked'` **Default value**: `undefined` ### passwordToggle boolean Specifies the password toggle visibility on a password field. **Default value**: `false` ### placeholder string Specifies the placeholder text for the input. **Default value**: `undefined` ### startIcon string Specifies the icon which will be displayed at the start of the input. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Input component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Input component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Radio button Radio button component is used when the user needs to select one option from a set. This UI component is best used when there is enough space, since all the options are visible at once. If you need to save space, a better UI choice would be the [Dropdown](./dropdown) component, which only displays the selected option and the others are only visible on selection. ## Usage Radio button component can be used individually or can be grouped logically inside a Radio Group component. The Radio Group component, also helps to specify the group name only once, otherwise it needs to be added to every Radio button. ```html ``` ```html ``` ## Value binding Radio button component can be bound to a string value using either the `[(ngModel)]` or the `formControlName` directives. These directives can be used individually on every Radio button component or can be applied to the radio group. ```html
``` ```ts @Component({...}) export class MyComponent { myAge = 'adult'; myEye = 'green'; } ``` ## Options Explore the following API options that help you easily configure the Radio button component. ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the radio button. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### description string Specifies the description text of the radio button. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the radio button. **Default value**: `false` ### id string Specifies the id of the radio button. **Default value**: `undefined` ### label string Specifies the label of the radio button. **Default value**: `undefined` ### name string Specifies the name of the radio button. **Default value**: `undefined` ### position "end" | "start" Sets the position of the radio button depending on the [rtl](#localization-rtl) option. When in left-to-right mode, `'start'` will render the radio button to the left, and `'end'` will render it to the right. In right-to-left mode, `'start'` will render the radio button to the right, and `'end'` will render it to the left. **Default value**: `'end'` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Radio button component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Radio button component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Segmented The Segmented component is a horizontal control made of multiple segments, each segment functioning as a button. ## Usage In single selection mode the functionality is similar to the [radio buttons](./radio), where selecting one will deselect all others. ```html Option 1 Option 2 Option 3 ``` ## Value binding Segmetned components can be bound to a string value using either the `[(ngModel)]` or the `formControlName` directives. These directives can be used individually on every segmented component or can be applied to the segmented group. #### Single selection Use the value and onChange props to set a value to the whole segmented group. ```html Day Week Month Year ``` #### Multiple selection In multiple selection mode segments can be selected and de-selected independently from each other. ```html {{item.text}} ``` ```ts @Component({...}) export class MyComponent { myGroupItems: Array<{ checked: boolean, text: string, value: string }> = [ { checked: false, text: 'S', value: 'sunday' }, { checked: true, text: 'M', value: 'monday' }, { checked: false, text: 'T', value: 'tuesday' }, { checked: false, text: 'W', value: 'wednesday' }, { checked: true, text: 'T', value: 'thursday' }, { checked: false, text: 'F', value: 'friday' }, { checked: false, text: 'S',value: 'saturday' } ]; } ``` ## Options Explore the following API options that help you easily configure the Segmented component. ### ariaLabel string Specifies the accessible name of the segmented button. Recommended for icon-only buttons. **Default value**: `undefined` ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the segmented button. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### description string Specifies the description text of the segmented button. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the segmented button. **Default value**: `false` ### endIcon any Specifies the icon which will be displayed at the end of the segmented button. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### icon any Specifies the icon for an icon-only segmented button. **Default value**: `undefined` ### id string Specifies the id of the segmented button. **Default value**: `undefined` ### label string Specifies the label of the segmented button. **Default value**: `undefined` ### name string Specifies the name of the segmented button. **Default value**: `undefined` ### startIcon any Specifies the icon which will be displayed at the start of the segmented button. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Segmented component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Segmented component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Stepper The Stepper component lets the user adjust a value by increasing and decreasing it in small steps. Steppers are used in situations where a user needs to adjust a value by a small amount. ## Usage Use the [`label`](#opt-label) option to provide a label to the stepper. ```html ``` ## Value binding The stepper can be bound to a number value using either the `[(ngModel)]` or the `formControlName` directives. In this case the stepper will update it's state according to the bound the value. ```html ``` ```ts @Component({...}) export class MyComponent { myAge = 24; } ``` ## Options Explore the following API options that help you easily configure the Stepper component. ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the stepper. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### description string Specifies the description text of the stepper. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the stepper. **Default value**: `false` ### inputPosition "center" | "end" | "start" Specifies the input field position compared to the +/- stepper buttons. **Default value**: `'center'` ### label string Specifies the label of the stepper. **Default value**: `undefined` ### max number Specifies the minimum value that can be selected. **Default value**: `0` ### min number Specifies the maximum value that can be selected. **Default value**: `100` ### step number Specifies the step between values. **Default value**: `1` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Stepper component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Stepper component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Switch The Switch component is a two value control. It is like a physical toggle switch, it has an on and an off state that is represented as a boolean value. ## Usage Use the [`label`](#opt-label) option to provide a label to the switch. The switch can be positioned before or after the label using the [`position`](#opt-position) option. ```html ``` For being more informative a [`description`](#opt-description) and a [`color`](#opt-color) can also be passed to the switch. ```html ``` ## Value binding The switch can be bound to a boolean value using either the `[(ngModel)]` or the `formControlName` directives. In this case the switch will update it's state according to the bound the value. ```html ``` ```ts @Component({...}) export class MyComponent { bedroomLight = false; } ``` ## Options Explore the following API options that help you easily configure the Switch component. ### color "success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined color of the switch. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### description string Specifies the description text of the switch. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the switch. **Default value**: `false` ### label string Specifies the label of the switch. **Default value**: `undefined` ### position "end" | "start" Sets the position of the switch depending on the [rtl](#localization-rtl) option. When in left-to-right mode, `'start'` will render the switch to the left, and `'end'` will render it to the right. In right-to-left mode, `'start'` will render the switch to the right, and `'end'` will render it to the left. **Default value**: `'end'` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Switch component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Switch component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Textarea The Textarea component can be used for collecting information from the user in the form of multi-line text. ## Usage Use the [`label`](#opt-label) option to provide a label to the textarea. ```html ``` ## Input style With the [`inputStyle`](#opt-inputStyle) attribute you can customize the look of textarea. There are three styles to choose from: ```html ``` ## Label style With the [`labelStyle`](#opt-labelStyle) attribute you can define the position of the label. ```html ``` ## Value binding The textarea can be bound to a string value using either the `[(ngModel)]` or the `formControlName` directives. In this case the textarea will update it's state according to the bound value. ```html ``` ## Options Explore the following API options that help you easily configure the Textarea component. ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### disabled boolean Specifies the disabled state of the input. **Default value**: `false` ### endIcon string Specifies the icon which will be displayed at the end of the input. Use the [startIcon](#opt-startIcon) option for specifying an icon at the start. **Default value**: `undefined` ### error boolean If `true`, the input will be displayed with error styles. **Default value**: `false` ### errorMessage string Error message for the input. If the [error](#opt-error) option is set to `true`, the message will be displayed. **Default value**: `undefined` ### inputStyle "outline" | "box" | "underline" Specifies the style of the input. Possible values: - `'underline'` - `'box'` - `'outline'` The default value depends on the [theme](#opt-theme): - iOS: `'underline'` - Material: `'box'` - Windows: `'outline'` **Default value**: `undefined` ### label string Specifies the label of the input. **Default value**: `undefined` ### labelStyle "inline" | "floating" | "stacked" Specifies the position of the input label. Possible values: - `'stacked'` - `'inline'` - `'floating'` The default value depends on the [theme](#opt-theme): - iOS: `'inline'` - Material: `'floating'` - Windows: `'stacked'` **Default value**: `undefined` ### placeholder string Specifies the placeholder text for the input. **Default value**: `undefined` ### rows number Maximum number of rows to display before the textarea becomes scrollable. **Default value**: `6` ### startIcon string Specifies the icon which will be displayed at the start of the input. Use the [endIcon](#opt-endIcon) option for specifying an icon at the end. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Textarea component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ## Localization The Textarea component is fully localized. This covers date and time format, button copy, rtl and more. ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### rtl boolean Enables right-to-left display. **Default value**: `false` --- ## Accessibility(Popup) ## Keyboard Support The Popup listens for the `Space` or the `Enter` keys to open the Popup. The `Tab` and `Shift + Tab` keys can be used to navigate between Popup controls. The `Esc` key can be used to cancel, while the `Enter` key is for the set action. The [`focusTrap`](./api#opt-focusTrap) option by default won't let the focus to leave the Popup. Buttons can be activated using the `Space` key. ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: :::info In case of Popup, the evaluation criteria do not apply to the content, as it is provided and entered by the user. ::: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Not Applicable - 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Not Applicable - 1.3.6 Identify Purpose AAA Not Applicable - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported - 1.4.11 Non-text Contrast AA Supported - 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Not Applicable - ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported - 2.1.2 No Keyboard Trap A Supported in case of modal picker there is a keyboard trap but can be closed by `ESCAPE` or `ENTER` 2.1.3 Keyboard (No Exception) AAA Supported - 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Not applicable - 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported - 2.2.4 Interruptions AAA Not Applicable - 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Supported open and close animations can be turned off 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Not Applicable - 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Not Applicable - 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Not fully supported - 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Not Applicable - 2.5.8 Target Size (Minimum) AA Supported - ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility Remarks 3.1 Readable 3.1.1 Language of Page A Not Applicable - 3.1.2 Language of Parts AA Not Applicable - 3.1.3 Unusual Words AAA Not Applicable - 3.1.4 Abbreviations AAA Not Applicable - 3.1.5 Reading Level AAA Not Applicable - 3.1.6 Pronunciation AAA Not Applicable - 3.2 Predictable 3.2.1 On Focus A Supported - 3.2.2 On Input A Not Applicable - 3.2.3 Consistent Navigation AA Not Applicable - 3.2.4 Consistent Identification AA Not Applicable - 3.2.5 Change on Request AAA Not Applicable - 3.2.6 Consistent Help A Not Applicable - 3.3 Input Assistance 3.3.1 Error Identification A Not Applicable - 3.3.2 Labels or Instructions A Not Applicable - 3.3.3 Error Suggestion AA Not Applicable - 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable - 3.3.5 Help AAA Not Applicable - 3.3.6 Error Prevention (All) AAA Not Applicable - 3.3.7 Redundant Entry A Not Applicable - 3.3.8 Accessible Authentication (Minimum) AA Not Applicable - 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable - ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Not Applicable --- ## Popup API Here is a comprehensive list of all the options, events and method the Popup component has. ## Options Explore the following API options that help you easily configure the Popup component. ### anchor HTMLElement Specifies the anchor element for positioning, if [display](#opt-display) is set to `'anchored'`. **Default value**: `undefined` ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed, if [display](#opt-display) is not set to `'inline'`. Possible values: - `'pop'` - `'slide-down'` - `'slide-up'` If `false`, the animation is turned off. **Default value**: `undefined` ### ariaLabel string Specifies the accessible name of the popup. **Default value**: `undefined` ### buttons Array Buttons to display on the component. Each item of the array will be a button. A button can be specified as a string, or as a button object. If a string, it must be one of the predefined buttons: - `'ok'` - Approve action. Will display the caption specified by the [okText](#localization-okText) option. - `'cancel'` - Dismisses the popup. Will display the caption specified by the [cancelText](#localization-cancelText) option. - `'close'` - Closes the popup. Will display the caption specified by the [closeText](#localization-closeText) option. - `'set'` - Approve action. Will display the caption specified by the [setText](#localization-setText) option. The [`MbscPopupButton`](#type-MbscPopupButton) type has the following properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ```js title="Example for using predefined and custom buttons" [ 'set', { text: 'Custom', icon: 'checkmark', cssClass: 'my-btn', handler: function (event) { alert('Custom button clicked!'); } }, 'cancel' ] ``` ```js title="Example for using a predefined button handler" [ 'set', { text: 'Hide', handler: 'cancel', icon: 'close', cssClass: 'my-btn' } ] ``` **Default value**: `undefined` ### closeOnEsc boolean If `true`, the popup is closed when the ESC key is pressed. **Default value**: `true` ### closeOnOverlayClick boolean If `true`, the popup is closed on overlay click or tap. **Default value**: `true` ### contentPadding boolean When set to false, it will remove the default padding from the content area. **Default value**: `true` ### context string | HTMLElement Specify the DOM element in which the component is rendered and positioned, if [display](#opt-display) is not `'inline'`. Can be a selector string or a DOM element. **Default value**: `'body'` ### cssClass string Specifies a custom CSS class for the component. :::info The `mbsc-no-padding` class removes the built in padding of the popup content. ::: ### display [MbscPopupDisplay](#type-MbscPopupDisplay) Controls the positioning of the component. Possible values are: - `'center'` - The component appears as a popup at the center of the viewport. - `'inline'` - The component is rendered inline. - `'anchored'` - The component appears positioned to the element defined by the [anchor](#opt-anchor) option. - `'top'` - The component appears docked to the top of the viewport. - `'bottom'` - The component appears docked to the bottom of the viewport. The default display mode depends on the [theme](#opt-theme), it defaults to `'bottom'` for the iOS theme and to `'center'` for all other themes. **Default value**: `undefined` ### focusOnClose boolean If `true`, after closing the popup the focus will be moved to the last focused element before the popup was opened. **Default value**: `true` ### focusOnOpen boolean If `true`, the popup will receive the focus when opened. **Default value**: `true` ### focusTrap boolean If `true` and [display](#opt-display) is not set to `'inline'`, focus won't be allowed to leave the popup. **Default value**: `true` ### fullScreen boolean If `true`, the popup will appear in full screen, but, by default, its width and height won't exceed 600px. You can change that using the [maxWidth](#opt-maxWidth) and [maxHeight](#opt-maxHeight) options. **Default value**: `false` ### headerText string Text to display in the header. **Default value**: `undefined` ### height string | number Sets the height of the component. **Default value**: `undefined` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `false` ### maxHeight string | number Sets the maximum height of the component. If not specified, on larger screens (>=768px width) it defaults to 600px. **Default value**: `undefined` ### maxWidth string | number Sets the maximum width of the component. **Default value**: `undefined` ### responsive [MbscResponsiveOptions](#type-MbscResponsiveOptions) Specifies different options for different container widths, in a form of an object, where the keys are the name of the breakpoints, and the values are objects containing the options for the given breakpoint. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px Custom breakpoints can be defined by passing an object containing the `breakpoint` property specifying the min-width in pixels. Example: ``` responsive: { small: { display: 'bottom' }, custom: { // Custom breakpoint, you can use multiple, but each must have a unique name breakpoint: 600, display: 'center' }, large: { display: 'anchored' } } ``` **Default value**: `undefined` ### scrollLock boolean Disables page scrolling, if the content of the popup is not scrollable. **Default value**: `true` ### showArrow boolean Show or hide the popup arrow, when [display](#opt-display) is `'anchored'`. **Default value**: `true` ### showOverlay boolean Show or hide the popup overlay. **Default value**: `true` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### touchUi boolean | "auto" Use `true` to render a touch optimized user interface, or `false` for a user interface optimized for pointer devices (mouse, touchpad). Can be used with the [responsive](#opt-responsive) option to change the user interface based on viewport width. If set to `'auto'`, the touch UI will be automatically enabled based on the platform. **Default value**: `'auto'` ### width string | number Sets the width of the component. **Default value**: `undefined` ## Events The Popup component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (args: MbscPopupCloseEvent, inst: PopupBase) => void Triggered when the component is closed. Parameters: - args - The event argument with the following properties: - `source`: *string* - Determines what triggered the close event. Can be one of `'set'`, `'cancel'`, `'ok'`, `'close'`, `'overlay'`, `'esc'`, `'scroll'`. - inst - The component instance. ### onDestroy (args: any, inst: any) => void Triggered when the component is destroyed. Parameters: - args - The event argument object. - inst - The component instance. ### onInit (args: any, inst: any) => void Triggered when the component is initialized. Parameters: - args - The event argument object. - inst - The component instance. ### onOpen (args: MbscPopupOpenEvent, inst: PopupBase) => void Triggered when the component is opened. Parameters: - args - The event argument with the following properties: - `target`: *HTMLElement* - The DOM element of the popup. - inst - The component instance. ### onPosition (args: MbscPopupPositionEvent, inst: PopupBase) => void Triggered when the component is positioned (on initial show and resize / orientation change). Useful if dimensions needs to be modified before the positioning happens, e.g. set a custom width or height. Custom positioning can also be implemented in this handler. In that case, returning `false` from the handler function will prevent the built in positioning. Parameters: - args - The event argument with the following properties: - `target`: *HTMLElement* - The DOM element of the popup. - `windowWidth`: *number* - The window width. - `windowHeight`: *number* - The window height. - inst - The component instance. ## Localization The Popup component is fully localized. This covers date and time format, button copy, rtl and more. ### cancelText string Text for the "Cancel" button. **Default value**: `'Cancel'` ### closeText string Text for the "Close" button. **Default value**: `'Close'` ### locale [MbscLocale](#type-MbscLocale) Sets the language of the component. The locale object contains all the translations for a given language. The built in language modules are listed below. If a language is not listed, it can be provided as a [custom language module](https://mobiscroll.com/docs/core-concepts/localization#language-modules). Supported values: - Arabic: `localeAr`, `'ar'` - Bulgarian: `localeBg`, `'bg'` - Catalan: `localeCa`, `'ca'` - Czech: `localeCs`, `'cs'` - Chinese: `localeZh`, `'zh'` - Croatian: `localeHr`, `'hr'` - Danish: `localeDa`, `'da'` - Dutch: `localeNl`, `'nl'` - English: `localeEn` or `undefined`, `'en'` - English (UK): `localeEnGB`, `'en-GB'` - Farsi: `localeFa`, `'fa'` - German: `localeDe`, `'de'` - Greek: `localeEl`, `'el'` - Spanish: `localeEs`, `'es'` - Finnish: `localeFi`, `'fi'` - French: `localeFr`, `'fr'` - Hebrew: `localeHe`, `'he'` - Hindi: `localeHi`, `'hi'` - Hungarian: `localeHu`, `'hu'` - Italian: `localeIt`, `'it'` - Japanese: `localeJa`, `'ja'` - Korean: `localeKo`, `'ko'` - Lithuanian: `localeLt`, `'lt'` - Norwegian: `localeNo`, `'no'` - Polish: `localePl`, `'pl'` - Portuguese (Brazilian): `localePtBR`, `'pt-BR'` - Portuguese (European): `localePtPT`, `'pt-PT'` - Romanian: `localeRo`, `'ro'` - Russian: `localeRu`, `'ru'` - Russian (UA): `localeRuUA`, `'ru-UA'` - Slovak: `localeSk`, `'sk'` - Serbian: `localeSr`, `'sr'` - Swedish: `localeSv`, `'sv'` - Thai: `localeTh`, `'th'` - Turkish: `localeTr`, `'tr'` - Ukrainian: `localeUa`, `'ua'` **Default value**: `undefined` ### okText string Text for the "Ok" button. **Default value**: `'Ok'` ### rtl boolean Enables right-to-left display. **Default value**: `false` ### setText string Text for the "Set" button. **Default value**: `'Set'` ## Methods These methods are actions that can be performed on a component instance. ### isVisible () => boolean Returns if the component is opened or not. ### position () => void Recalculates the position of the component. ## Types ### MbscLocale Interface Properties: - `allDayText`: *string* - `amText`: *string* - `calendarSystem`: *MbscCalendarSystem* - `cancelText`: *string* - `clearText`: *string* - `closeText`: *string* - `dateFormat`: *string* - `dateFormatFull`: *string* - `dateFormatLong`: *string* - `dateText`: *string* - `dateWheelFormat`: *string* - `dayNames`: *Array* - `dayNamesMin`: *Array* - `dayNamesShort`: *Array* - `daySuffix`: *string* - `dayText`: *string* - `eventText`: *string* - `eventsText`: *string* - `filterEmptyText`: *string* - `filterPlaceholderText`: *string* - `firstDay`: *number* - `fromText`: *string* - `hourText`: *string* - `minuteText`: *string* - `monthNames`: *Array* - `monthNamesShort`: *Array* - `monthSuffix`: *string* - `monthText`: *string* - `moreEventsPluralText`: *string* - `moreEventsText`: *string* - `nextMonthText`: *string* - `nextYearText`: *string* - `noEventsText`: *string* - `nowText`: *string* - `pmText`: *string* - `prevMonthText`: *string* - `prevYearText`: *string* - `rangeEndHelp`: *string* - `rangeEndLabel`: *string* - `rangeStartHelp`: *string* - `rangeStartLabel`: *string* - `rtl`: *boolean* - `secondText`: *string* - `selectedPluralText`: *string* - `selectedText`: *string* - `setText`: *string* - `timeFormat`: *string* - `timeText`: *string* - `timeWheels`: *string* - `toText`: *string* - `todayText`: *string* - `weekText`: *string* - `yearSuffix`: *string* - `yearText`: *string* ### MbscPopupButton Interface Properties: - `color`: *"success" | "light" | "dark" | "primary" | "secondary" | "danger" | "warning" | "info"* - Specifies the predefined color of the button - `cssClass`: *string* - A custom CSS class that will be applied to the element - `disabled`: *boolean* - Disabled state of the button - `handler`: *[MbscPopupPredefinedButton](#type-MbscPopupPredefinedButton) | (event: any) => void* - Specifies what happens when the button is pressed. It can be a predefined button handler like `'set'`, `'cancel'` or a custom function. - `icon`: *string* - When specified, it renders an icon on the button. It requires the name of the icon that should be displayed. - `keyCode`: *number | "enter" | "esc" | "space" | Array* - The key code associated with the button to activate it from keyboard. Can be a single value or multiple value passed as an array. Predefined string values are: `'enter'`, `'esc'`, `'space'`. - `text`: *string* - Sets the label of the button - `variant`: *"outline" | "standard" | "flat"* - The style of the button ### MbscPopupDisplay "center" | "bottom" | "top" | "anchored" | "inline" | "bubble" ### MbscPopupPredefinedButton "set" | "cancel" | "ok" | "close" ### MbscResponsiveOptions Interface The `MbscResponsiveOptions` supports custom properties in the form: ``` [key:string]: MbscPopupOptions & {breakpoint?: number} ``` The keys are the names of the breakpoints, and the values are objects containing the options for the given breakpoint. The `breakpoint` property, when present, specifies the min-width in pixels. The options will take into effect from that width. :::info The available width is queried from the container element of the component and not the browsers viewport like in css media queries ::: There are five predefined breakpoints: - `xsmall` - min-width: 0px - `small` - min-width: 576px - `medium` - min-width: 768px - `large` - min-width: 992px - `xlarge` - min-width: 1200px --- ## Display modes(Popup) The Popup component supports five display modes that specify where on the screen is it going to render itself: 1. `'center'` - will render the popup on the center of the screen 2. `'top'` - will render the popup on the top of the screen sliding down 3. `'bottom'` - will render the popup on the bottom of the screen sliding up 4. `'anchored'` - will render the popup above or below the element it is anchored to. The [`anchor`](./api#opt-anchor) option will specify the element to which the popup is positioned. By default it is the input element rendered by the popup. 5. `'inline'` - will render the popup into the page embedded. ```html title="Setting a display option"

Some content inside the popup!

 ``` --- ## Popup The Popup component provides a frame for all your popover needs, able to render custom content, forms or combined views. Use it for contextual pop-ups, data-entry or to inform users in a consistent way with all other Mobiscroll components. ## Usage The following example will create a popup with static content. When clicked or tapped the overlay, the Popup will close: ```html

Hi

Are you feeling good today?

 ``` ```ts @Component({...}) export class MyComponent { isPopupOpen = true; closePopup() { this.isPopupOpen = false; } } ``` --- ## Accessibility(Notifications) ## Keyboard Support The `Tab` and `Shift + Tab` keys can be used to navigate between modal controls. In case of the Alert/ Confirm/ Prompt, the `Esc` key can be used to cancel, while the `Enter` key is for the set action. The Alert/ Confirm/ Prompt by default won't let the focus to leave the modal. Buttons can be activated using the `Space` key. ## WCAG 2.2 The [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) provide guidelines developed by the World [Wide Web Consortium (W3C)](https://www.w3.org/) to ensure web content is accessible to people with disabilities. WCAG 2.2 establishes a framework of accessibility principles and their associated success criteria. The level of accessibility conformance achieved by a web application is determined by the extent to which it meets these success criteria, categorized into three levels: A, AA, and AAA. While Mobiscroll components are not fully compliant with WCAG 2.2 at this time, we are committed to enhancing their accessibility. We are actively working on improving compliance and continuously making progress. The guidelines and success criteria are organized around the following four principles: ### [1. Perceivable](https://www.w3.org/TR/WCAG22/#perceivable) Information and user interface components must be presentable to users in ways they can perceive. Guidelines Level Compatibility Remarks 1.1 Text Alternatives 1.1.1 Non-text Content A Supported in case of the Prompt the label can be specified 1.2 Time-based Media 1.2.1 Audio-only and Video-only (Prerecorded) A Not Applicable - 1.2.2 Captions (Prerecorded) A Not Applicable - 1.2.3 Audio Description or Media Alternative (Prerecorded) A Not Applicable - 1.2.4 Captions (Live) AA Not Applicable - 1.2.5 Audio Description (Prerecorded) AA Not Applicable - 1.2.6 Sign Language (Prerecorded) AAA Not Applicable - 1.2.7 Extended Audio Description (Prerecorded) AAA Not Applicable - 1.2.8 Media Alternative (Prerecorded) AAA Not Applicable - 1.2.9 Audio-only (Live) AAA Not Applicable - 1.3 Adaptable 1.3.1 Info and Relationships A Supported - 1.3.2 Meaningful Sequence A Supported - 1.3.3 Sensory Characteristics A Supported - 1.3.4 Orientation AA Supported responsiveness works with all orientations 1.3.5 Identify Input Purpose AA Supported in case of the Prompt the description can be specified 1.3.6 Identify Purpose AAA Supported - 1.4 Distinguishable 1.4.1 Use of Color A Supported - 1.4.2 Audio Control A Not Applicable - 1.4.3 Contrast (Minimum) AA Not fully supported by building a height contrast theme 1.4.4 Resize Text AA Supported - 1.4.5 Images of Text AA Not Applicable - 1.4.6 Contrast (Enhanced) AAA Not fully supported by building a height contrast theme 1.4.7 Low or No Background Audio AAA Not Applicable - 1.4.8 Visual Presentation AAA Supported by building a custom theme or custom CSS 1.4.9 Images of Text (No Exception) AAA Not Applicable - 1.4.10 Reflow AA Supported - 1.4.11 Non-text Contrast AA Supported - 1.4.12 Text Spacing AA Supported can be modified with custom CSS 1.4.13 Content on Hover or Focus AA Not Applicable - ### [2. Operable](https://www.w3.org/TR/WCAG22/#operable) User interface components and navigation must be operable. Guidelines Level Compatibility Remarks 2.1 Keyboard Accessible 2.1.1 Keyboard A Supported - 2.1.2 No Keyboard Trap A Supported in case of the Alert/ Confirm/ Prompt there is a keyboard trap but can be closed by `ESCAPE` or `ENTER` 2.1.3 Keyboard (No Exception) AAA Supported - 2.1.4 Character Key Shortcuts A Not Applicable - 2.2 Enough Time 2.2.1 Timing Adjustable A Supported in case of the Toast and Snackbar the timing is adjustable 2.2.2 Pause, Stop, Hide A Not Applicable - 2.2.3 No Timing AAA Supported in case of the Toast and Snackbar the timing can be disabled 2.2.4 Interruptions AAA Supported in case of the Alerts the developer is responsible for only showing emergency alerts for people with attention deficits and postponing other alerts 2.2.5 Re-authenticating AAA Not Applicable - 2.2.6 Timeouts AAA Not Applicable - 2.3 Seizures and Physical Reactions 2.3.1 Three Flashes or Below Threshold A Supported - 2.3.2 Three Flashes AAA Supported - 2.3.3 Animation from Interactions AAA Supported open and close animations can be turned off 2.4 Navigable 2.4.1 Bypass Blocks A Not Applicable - 2.4.2 Page Titled A Not Applicable - 2.4.3 Focus Order A Supported - 2.4.4 Link Purpose (In Context) A Not Applicable - 2.4.5 Multiple Ways AA Not Applicable - 2.4.6 Headings and Labels AA Supported - 2.4.7 Focus Visible AA Supported - 2.4.8 Location AAA Not Applicable - 2.4.9 Link Purpose (Link Only) AAA Not Applicable - 2.4.10 Section Headings AAA Not Applicable - 2.4.11 Focus Not Obscured (Minimum) AA Supported - 2.4.12 Focus Not Obscured (Enhanced) AAA Supported - 2.4.13 Focus Appearance AAA Not fully supported - 2.5 Input Modalities 2.5.1 Pointer Gestures A Supported - 2.5.2 Pointer Cancellation A Supported - 2.5.3 Label in Name A Not applicable - 2.5.4 Motion Actuation A Not Applicable - 2.5.5 Target Size (Enhanced) AAA Supported - 2.5.6 Concurrent Input Mechanisms AAA Supported - 2.5.7 Dragging Movements AA Not applicable - 2.5.8 Target Size (Minimum) AA Supported - ### [3. Understandable](https://www.w3.org/TR/WCAG22/#understandable) Information and the operation of user interface must be understandable. Guidelines Level Compatibility Remarks 3.1 Readable 3.1.1 Language of Page A Not Applicable - 3.1.2 Language of Parts AA Not Applicable - 3.1.3 Unusual Words AAA Not Applicable - 3.1.4 Abbreviations AAA Not Applicable - 3.1.5 Reading Level AAA Not Applicable - 3.1.6 Pronunciation AAA Not Applicable - 3.2 Predictable 3.2.1 On Focus A Supported - 3.2.2 On Input A Not Applicable - 3.2.3 Consistent Navigation AA Not Applicable - 3.2.4 Consistent Identification AA Not Applicable - 3.2.5 Change on Request AAA Not Applicable - 3.2.6 Consistent Help A Not Applicable - 3.3 Input Assistance 3.3.1 Error Identification A Not applicable - 3.3.2 Labels or Instructions A Supported in case of the Prompt can be defined through `label` and `message` options 3.3.3 Error Suggestion AA Not applicable - 3.3.4 Error Prevention (Legal, Financial, Data) AA Not Applicable - 3.3.5 Help AAA Not Applicable - 3.3.6 Error Prevention (All) AAA Not Applicable - 3.3.7 Redundant Entry A Not Applicable - 3.3.8 Accessible Authentication (Minimum) AA Not Applicable - 3.3.9 Accessible Authentication (Enhanced) AAA Not Applicable - ### [4. Robust](https://www.w3.org/TR/WCAG22/#robust) Content must be robust enough that it can be interpreted reliably by a wide variety of user agents, including assistive technologies. Guidelines Level Compatibility 4.1 Compatible 4.1.1 Parsing (Obsolete and removed) - - 4.1.2 Name, Role, Value A Supported 4.1.3 Status Messages AA Supported only applicable in case of the Toast and Snackbar --- ## Alert An Alert dialog notifies or warns the user about something. It displays a single button which closes the Alert component. ## Usage The following example displays an Alert message: ```ts @Component({...}) export class MyComponent { constructor(public notify: Notifications) {} showAlert() { this.notify.alert({ title: "Cellular Data is Turned Off for 'Safari'", message: "You can turn on cellular data for this app in Settings.", }); } } ``` ## Options Explore the following API options that help you easily configure the Alert component. ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### display "center" | "top" | "bottom" Controls the positioning of the component. **Default value**: `undefined` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `undefined` ### message string Message to present. ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### title string Title for the dialog. **Default value**: `undefined` ## Localization The Alert component is fully localized. This covers date and time format, button copy, rtl and more. ### okText string Text for the button which closes the dialog. **Default value**: `'OK'` ## Events The Alert component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (result: undefined) => void Triggered when the component is closed. --- ## Confirm A confirm dialog is used when it is required to confirm an action. It has two buttons, one of which confirms the action, and the other one rejects it. ## Usage The following example displays a confirm dialog: ```ts @Component({...}) export class MyComponent { constructor(public notify: Notifications) {} showConfirm() { this.notify.confirm({ title: "Use location service?", message: "Help apps determine location. This means sending anonymous location data, even when no apps are running.", okText: "Agree", cancelText: "Disagree", onClose: (result) => { console.log('Result: ', result); } }); } } ``` ## Options Explore the following API options that help you easily configure the Confirm component. ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### display "center" | "top" | "bottom" Controls the positioning of the component. **Default value**: `undefined` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `undefined` ### message string Message to present. ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### title string Title for the dialog. **Default value**: `undefined` ## Localization The Confirm component is fully localized. This covers date and time format, button copy, rtl and more. ### cancelText string Text for the button which cancels the dialog. **Default value**: `'Cancel'` ### okText string Text for the button which closes the dialog. **Default value**: `'OK'` ## Events The Confirm component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (result: boolean) => void Triggered when the component is closed. --- ## Prompt A prompt dialog is used when it's required to get some data from the user, e.g. a password confirmation. It has two buttons, one of which submits the entered data, the other one cancels the dialog. ## Usage The following example displays a prompt dialog: ```ts @Component({...}) export class MyComponent { constructor(public notify: Notifications) {} showPrompt() { this.notify.prompt({ title: "Sign in to iTunes Store", message: "Enter the Apple ID password for 'hello@mobiscroll.com'.", placeholder: "Enter password", inputType: "password", onClose: function(result) { console.log('Result: ', result); } }); } } ``` ## Options Explore the following API options that help you easily configure the Prompt component. ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### display "center" | "top" | "bottom" Controls the positioning of the component. **Default value**: `undefined` ### inputType string Initial value of the displayed input. **Default value**: `undefined` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `undefined` ### label string Label for the displayed input. **Default value**: `undefined` ### message string Message to present. ### placeholder string Placeholder text for the displayed input. **Default value**: `undefined` ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ### title string Title for the dialog. **Default value**: `undefined` ### value string Initial value of the displayed input. **Default value**: `undefined` ## Localization The Prompt component is fully localized. This covers date and time format, button copy, rtl and more. ### cancelText string Text for the button which cancels the dialog. **Default value**: `'Cancel'` ### okText string Text for the button which closes the dialog. **Default value**: `'OK'` ## Events The Prompt component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (result: string) => void Triggered when the component is closed. --- ## Snackbar The Snackbar component provide brief feedback after an action through a message at the bottom of the screen. A Snackbar may contain an action, such as "Undo" or "Retry". Snackbars don't lock the app's main interface and are automatically dismissed after a while. ## Usage The following example displays a Snackbar message with a "Retry" button: ```ts @Component({...}) export class MyComponent { constructor(public notify: Notifications) {} showSnack() { this.notify.snackbar({ message: "Connection timed out. Showing limited messages.", button: { text: 'Retry', action: () => { console.log('Retrying...'); } } }); } } ``` ## Options Explore the following API options that help you easily configure the Snackbar component. ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed. **Default value**: `undefined` ### button {action?: () => void, icon?: string, text?: string} Displays an action button on the snackbar. Properties: - `text`: *string* - Text of the button. - `icon`: *string* - Icon of the button. - `action`: *() => void* - A function which executes when the button is clicked. ### color "success" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined background color of the message, each serving its own semantic purpose. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### display "center" | "top" | "bottom" Controls the positioning of the component. **Default value**: `undefined` ### duration number | boolean Specifies the display time of the message in milliseconds. If `false`, the message will be persistent. **Default value**: `3000` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `undefined` ### message string Message to present. ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Snackbar component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (result: undefined) => void Triggered when the component is closed. --- ## Toast The Toast component is a simple text only notification informing the user. They should be primarly used to display messages not necessarily related to a user action, such as background synchronization or similar. The Toast component don't lock the app's main interface and are automatically dismissed after a while. ## Usage The following example displays a toast message: ```ts @Component({...}) export class MyComponent { constructor(public notify: Notifications) {} showToast() { this.notify.toast({ message: "Message sent" }); } } ``` ## Options Explore the following API options that help you easily configure the Toast component. ### animation boolean | "pop" | "slide-down" | "slide-up" Animation to use when the component is opened or closed. **Default value**: `undefined` ### color "success" | "primary" | "secondary" | "danger" | "warning" | "info" Specifies the predefined background color of the message, each serving its own semantic purpose. **Default value**: `undefined` ### cssClass string Specifies a custom CSS class for the component. **Default value**: `undefined` ### display "center" | "top" | "bottom" Controls the positioning of the component. **Default value**: `undefined` ### duration number | boolean Specifies the display time of the message in milliseconds. If `false`, the message will be persistent. **Default value**: `3000` ### isOpen boolean Specifies if the component is opened or not. Use it together with the [onClose](#event-onClose) event, by setting it to `false` when the component closes. **Default value**: `undefined` ### message string Message to present. ### theme string Specifies the visual appearance of the component. If it is `'auto'` or `undefined`, the theme will automatically be chosen based on the platform. If custom themes are also present, they will take precedence over the built in themes, e.g. if there's an iOS based custom theme, it will be chosen on the iOS platform instead of the default iOS theme. Supplied themes: - `'ios'` - iOS theme - `'material'` - Material theme - `'windows'` - Windows theme It's possible to [modify theme colors](../theming/sass-variables) or [create custom themes](../theming/sass-themes). :::info Make sure that the theme you set is included in the downloaded package. ::: **Default value**: `undefined` ### themeVariant "auto" | "light" | "dark" Controls which variant of the [theme](#opt-theme) will be used (light or dark). Possible values: - `'light'` - Use the light variant of the theme. - `'dark'` - Use the dark variant of the theme. - `'auto'` or `undefined` - Detect the preferred system theme on devices where this is supported. To use the option with custom themes, make sure to create two custom themes, where the dark version has the same name as the light one, suffixed with `'-dark'`, e.g.: `'my-theme'` and `'my-theme-dark'`. **Default value**: `undefined` ## Events The Toast component ships with different event hooks for deep customization. Events are triggered through the lifecycle of the component where you can tie in custom functionality and code. ### onClose (result: undefined) => void Triggered when the component is closed. --- ## Grid Layout ## Overview The Mobiscroll Grid Layout is a powerful flexbox system for building custom layouts of all shapes and sizes. ## Basic usage The grid is combined from the following units: grid, rows and columns. It has a twelve column layout with different breakpoints depending on the size of the screen or the predefined CSS class. ```jsx title="Three columns with the same size"
One of three columns
One of three columns
One of three columns
``` For many more examples - simple and complex use-cases - check out the [grid-layout demos](https://demo.mobiscroll.com/grid-layout). ## Grid size By default the grid has full width and with the `.mbsc-grid-fixed` class the layout will have a max width based on the screen size. ```jsx title="Fix width grid"
This grid has a fixed width
``` Extra small (<576px) Small (>=576px) Medium (>=768px) Large (>=992px) Extra large (>=1200px) Max container width auto 540px 720px 960px 1140px Class prefix .col- .col-sm- .col-md- .col-lg- .col-xl- Number of columns 12 Gutter width 2em (1em on each side of the column) Column ordering Yes ## Column sizing Column classes specify the number of columns out of the possible 12 per row. See the grids below illustrating the column classes. ### Equal-width With `.mbsc-col` class, each column will be the same width inside of a row for every device and viewport. Equal-width columns mbsc-col (1 of 3) mbsc-col (1 of 3) mbsc-col (1 of 3) mbsc-col (1 of 5) mbsc-col (1 of 5) mbsc-col (1 of 5) mbsc-col (1 of 5) mbsc-col (1 of 5) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) mbsc-col (1 of 10) ### Specified column sizes Specifying a numbered class will adjust columns to take up `x` columns out of the available columns. Using the `.mbsc-col-{size}` class will set the column width for all devices and screens. Specified column widths for all screen sizes mbsc-col-1 mbsc-col-11 mbsc-col-2 mbsc-col-10 mbsc-col-3 mbsc-col-9 mbsc-col-4 mbsc-col-8 mbsc-col-5 mbsc-col-7 mbsc-col-6 mbsc-col-6 mbsc-col-12 ### Responsive classes Using the `.mbsc-col-{breakpoint}-{size}` classes, the column widths will adapt to the screen size based on the predefined classes and become horizontal at the specified breakpoint. :::info Try this example with different screen sizes. ::: Specified column widths for all screen sizes mbsc-col-sm-4 mbsc-col-sm-8 mbsc-col-md-3 mbsc-col-md-7 mbsc-col-md-2 mbsc-col-lg-3 mbsc-col-lg-4 mbsc-col-lg-5 mbsc-col-xl-6 mbsc-col-xl-6 Specified column widths for all screen sizes Column 1 Column 2 Column 3 ### Setting one column width Using our predefined classes, it's possible to set the width of one column and have the remaining columns automatically resize around it. Setting one column width mbsc-col-2 mbsc-col mbsc-col mbsc-col mbsc-col mbsc-col-7 mbsc-col mbsc-col mbsc-col-10 ### Variable-width With the `.mbsc-col-{breakpoint}-auto` attributes, the columns are sized based on the natural width of its content. The adjacent columns will resize to fill the row. Variable width content mbsc-col mbsc-col-sm-auto example mbsc-col mbsc-col mbsc-col-sm-auto another example ## Alignment ### Vertical alignment All columns can be vertically aligned inside of a row by adding different attributes to the row. Classes: `.mbsc-align-items-start`, `.mbsc-align-items-center`, `.mbsc-align-items-end`. ```jsx title="Columns vertically aligned to the end"
First column
Second column
``` ### Horizontal alignment All columns can be horizontally aligned inside of a row by adding different attributes to the row. Classes: `.mbsc-justify-content-start`, `.mbsc-justify-content-center`, `.mbsc-justify-content-end`, `.mbsc-justify-content-around`, `.mbsc-justify-content-between`. ```jsx title="Columns horizontally aligned to center"
First column
Second column
``` ## Offseting columns Offset classes are used to increase the left margin of a column by `x` columns. Classes: `mbsc-offset-{size}`, `.mbsc-offset-{breakpoint}-{size}`. ```jsx title="Offsetting columns"
Col 4
This column's margin left is increased by 3 columns
``` ## Push and pull It's possible to change the order of the grid columns with the push and pull attributes: `.mbsc-push-{breakpoint}-{size}`, `.mbsc-pull-{breakpoint}-{size}`. These attributes adjust the left and right of the columns by `x` columns making it easy to reorder them. ```jsx title="Using push and pull"
This column is the first on large screen
This column is the first on small (<576px) screen
``` ## No padding The columns initially have right and left padding which can be removed with the `mbsc-no-padding` class. ```jsx title="Columns without padding"
This column has no padding
``` --- ## Theming Mobiscroll components are shipped with a ready-to-use, carefully crafted design, with the ability to adapt to the platform where they are being used. The available themes are: - `ios` and `ios-dark` - theme matching the iOS platform look & feel - `material` and `material-dark` - theme matching the Material Design specification - `windows` and `windows-dark` - theme matching the Universal Windows platform look & feel The Mobiscroll package is shipped with a pre-built css file, once it's added to your project, the bundled themes can be used right away. The packages also contain scss files, for theme customizations and tree shaking solutions. ### Customizing the look and feel While the provided pre-built themes are enough in many use cases, most of the times on top of adapting to a specific platform, you'd also like to match a brand or color scheme. Mobiscroll provides various ways to achieve this: - [Override the Sass color variables](./sass-variables) - the straightforward way to change the colors in one place throughout the application. - [Create custom themes using Sass](./sass-themes) - use this, if you need multiple themes with different color variatons, in case you have pages with different colors, or you'd like to users to customize the colors of your app. - [Create custom themes using the theme builder](#theme-builder) - the custom themes can be also built using our theme builder, on a graphical user interface, without any coding, or the need for Sass support in your project. To work with the first two methods, you need to have Sass support configured for your project. ### Theme Builder If Sass support is not available in your project, or you prefer a visual theme editor, you can use our theme builder to create custom themes. The theme builder is very easy to use, no coding is needed, you just choose the colors, and save the custom theme. Using our [download builder](https://download.mobiscroll.com) you can select one or more custom themes to include in the package. You can find more information on the theme builder features and usage [here](http://help.mobiscroll.com/mobiscroll-products-and-tools/theme-builder). --- ## Custom themes If you'd like to use multiple color variations for the Mobiscroll components, the solution is to create one or more custom themes. A custom theme is a variation of one of the [built-in themes](./built-in-themes), referred as the base theme. ## Create a custom theme To create a custom theme using Sass, you can use the provided [`mbsc-custom-theme`](#method-mbsc-custom-theme) function, which can be called after the mobiscroll scss file has been imported: ```scss // Import the library @use "@mobiscroll/angular/dist/css/mobiscroll.scss"; // Specify the custom colors $colors-my-happy-brand: ( button: #6D8764, accent: #6D8764, background: #F7F7F7, text: #000000 ); // Create a custom theme called 'my-happy-brand' @include mobiscroll.mbsc-custom-theme('my-happy-brand', 'ios', $colors-my-happy-brand); ``` When using the deprecated [Ruby Sass](https://sass-lang.com/ruby-sass/) or [LibSass](https://sass-lang.com/libsass/) implementations, use the following syntax: ```scss // Import the library @import "@mobiscroll/angular/dist/css/mobiscroll.scss" // Specify the custom colors: $colors-my-happy-brand: ( button: #6D8764, accent: #6D8764, background: #F7F7F7, text: #000000 ); // Create a custom theme called 'my-happy-brand' @include mbsc-custom-theme('my-happy-brand', 'ios', $colors-my-happy-brand); ``` Before you can use the custom theme, you will also need to register it in your javascript code. This can be done after the mobiscroll resources has been loaded, but before using any of the components. Use the [`createCustomTheme`](#method-createCustomTheme) function. Make sure to use the same name which was specified to the Sass function, and specify the same base theme as second parameter. **app.component.ts** ```js // register the custom theme createCustomTheme('my-happy-brand', 'ios'); ``` **app.component.html** ```html ``` ## Light and Dark variants To use custom themes together with the `themeVariant` option (which controls whether the light or dark variant of a theme will be used), make sure to create two custom themes. The dark version must have the same name as the light one, suffixed with `'-dark'`, for example: `'my-theme'` and `'my-theme-dark'`. ## Methods ### createCustomTheme (theme: string, baseTheme: string) => void Registers a custom theme for use. * `theme` - _String_ - The name of the custom theme. Make sure to use the same name you used with the SCSS function when creating the theme. * `baseTheme` - _String_ - One of the [supported base themes](./built-in-themes). ### mbsc-custom-theme ($theme-name, $base-theme-name, $colors) => void An SCSS function which creates the styling for a custom theme, with the specified colors * `$theme-name` - _String_ - Name of the custom theme * `$base-theme-name` - _String_ - Name of the [base theme](./built-in-themes) name * `$colors` - _Map_ - A key-value map containing the input colors. Possible keys: - `accent` - `background` - `text` - `button` - for the `ios` base theme only --- ## Sass variables A convenient way to customize the colors of the components is to override the Sass color variables. Let's say your branding uses a nice red accent color, and you'd like that color to appear on the Mobiscroll components as well, while still using platform specific themes (e.g. `ios` on iOS devices, `material` on Android devices). You can override the accent color for every theme: ```scss @use '@mobiscroll/angular/dist/css/mobiscroll.scss' with ( $mbsc-ios-accent: #e61d2a, $mbsc-material-accent: #e61d2a, $mbsc-windows-accent: #e61d2a ); ``` When using the deprecated [Ruby Sass](https://sass-lang.com/ruby-sass/) or [LibSass](https://sass-lang.com/libsass/) implementations, use the following syntax: ```scss // Override the variables BEFORE the scss file import, otherwise they won't take effect $mbsc-ios-accent: #e61d2a; $mbsc-material-accent: #e61d2a; $mbsc-windows-accent: #e61d2a; @import '@mobiscroll/angular/dist/css/mobiscroll.scss'; ``` Here's the complete list of the Sass color variables available grouped by themes: ## iOS color variables ```scss title="Available color variables and defaults for iOS" $mbsc-ios-accent: #007bff; // Accent color $mbsc-ios-background: #f7f7f7; // Background color $mbsc-ios-text: #000000; // Text color $mbsc-ios-dark-accent: #ff8400; // Dark Accent color $mbsc-ios-dark-background: #000000; // Dark Background color $mbsc-ios-dark-text: #ffffff; // Dark Text color $mbsc-ios-primary: #3f97f6; // Primary color $mbsc-ios-secondary: #90979e; // Secondary color $mbsc-ios-success: #43be5f; // Success color $mbsc-ios-danger: #f5504e; // Danger color $mbsc-ios-warning: #f8b042; // Warning color $mbsc-ios-info: #5bb7c5; // Info color $mbsc-ios-light: #ffffff; // Light color $mbsc-ios-dark: #47494a; // Dark color ``` ## Material color variables ```scss title="Available color variables and defaults for Material" $mbsc-material-accent: #009688; // Accent color $mbsc-material-background: #eeeeee; // Background color $mbsc-material-text: #5b5b5b; // Text color $mbsc-material-dark-accent: #81ccc4; // Accent color for dark version $mbsc-material-dark-background: #303030;// Background color for dark version $mbsc-material-dark-text: #c2c2c2; // Text color for dark version $mbsc-material-primary: #3f97f6; // Primary color $mbsc-material-secondary: #90979E; // Secondary color $mbsc-material-success: #43BE5F; // Success color $mbsc-material-danger: #f5504e; // Danger color $mbsc-material-warning: #f8b042; // Warning color $mbsc-material-info: #5BB7C5; // Info color $mbsc-material-light: #ffffff; // Light color $mbsc-material-dark: #47494A; // Dark color ``` ## Windows color variables ```scss title="Available color variables and defaults for Windows" $mbsc-windows-accent: #0078d7; // Accent color $mbsc-windows-background: #f2f2f2; // Background color $mbsc-windows-text: #262626; // Text color $mbsc-windows-dark-accent: #0078d7; // Accent color for dark version $mbsc-windows-dark-background: #1a1a1a; // Background color for dark version $mbsc-windows-dark-text: #ffffff; // Text color for dark version $mbsc-windows-primary: #3f97f6; // Primary color $mbsc-windows-secondary: #90979E; // Secondary color $mbsc-windows-success: #43BE5F; // Success color $mbsc-windows-danger: #f5504e; // Danger color $mbsc-windows-warning: #f8b042; // Warning color $mbsc-windows-info: #5BB7C5; // Info color $mbsc-windows-light: #ffffff; // Light color $mbsc-windows-dark: #47494A; // Dark color ``` --- ## Tree shaking for styles ## Overview Tree shaking is a term commonly used in web development and particularly in JavaScript for unused code removal. Since websites are served (mostly) over the network, loading times depend on content size, so minification and unused content elimination plays a major role in making webapps fluid. For the JavaScript part, popular frameworks already have the treeshaking built in, so the components that are not used will be left out from the built project. ## Eliminating unused styles In case of the styles, leaving out the unused rules is not as straight forward. The overarching idea is that CSS selectors match elements in the DOM, and those elements in the DOM come from all sorts of places: your static templates, dynamic templates based on server-side state, and of course, JavaScript, which can manipulate the DOM in any way at all, including pull things from APIs and third parties. ## Sass variables to the rescue The Mobiscroll Library comes with a modular [SASS](https://sass-lang.com/) bundle, that can be configured which component styles and which themes to leave in and out for the compiled css file. Every component and theme has a SASS variable that can be turned on or off. If the variable is falsy the styles that it needs will not be added to the bundle. ```jsx title="Example on configuring the styles" // include the ios theme $mbsc-ios-theme: true; // include the components: $mbsc-datepicker: true; $mbsc-eventcalendar: true; @import "@mobiscroll/angular/dist/css/mobiscroll.modular.scss" ``` In the above example the styles needed for the eventcalendar and datepicker will be included and only for the ios theme. All other components (like select or grid-layout) and all other themes will be left out from the bundle. :::info It's important that you override the variables BEFORE the scss file import, otherwise it won't make any difference. ::: Here's the complete list of the components and themes that can be used: * `$mbsc-datepicker` * `$mbsc-eventcalendar` * `$mbsc-grid-layout` * `$mbsc-popup` * `$mbsc-select` * `$mbsc-ios-theme` * `$mbsc-material-theme` * `$mbsc-windows-theme` :::info Some components use others internally, so it might happen that even though you don't want to include some styles, they will still end up in your bundle. For example if you don't want to include the form components (input, button, segmented, etc...), but you are using the select component, the styles for the mobiscroll buttons, will still be in, because of the dependency. ::: --- ## AI Integration # AI Integration Mobiscroll provides a set of machine-readable documentation files and AI behavior rules that enable coding assistants to generate accurate, framework-specific code. These files prevent common AI issues like hallucinated APIs, mixed framework imports, and outdated patterns. ## Why AI integration? AI coding assistants work best when they have access to structured, authoritative documentation. Without it, they often: - **Hallucinate APIs** — invent option names, events, or types that don't exist - **Mix frameworks** — use React hooks in Angular code, or jQuery patterns in Vue - **Reference outdated versions** — generate v5 code when the current version is v6 - **Ignore framework conventions** — skip `MbscModule` imports in Angular, or use wrong CSS loading patterns The Mobiscroll AI integration solves these problems by providing documentation optimized for AI consumption, combined with behavior rules that enforce framework isolation and correct API usage. ## Architecture overview The integration consists of three layers: ### Data layer — llms files Machine-readable documentation files containing the complete Mobiscroll API reference and guides, one per framework. These are the source of truth that AI tools read to answer questions. | File | Description | |:---|:---| | `llms-angular-full.txt` | Complete Angular documentation | | `llms-angular.txt` | Angular table of contents (links to individual pages) | | `5.35.0/llms-icons.txt` | Icon names for Mobiscroll v5 — all frameworks | :::info You don't need to download or host these files — the rules files and the Claude Code plugin reference them directly and fetch their content automatically. ::: ### Rules layer — rules files Rules files provide Mobiscroll context to **Cursor** and **GitHub Copilot** only. Claude Code uses the Mobiscroll plugin instead — no manual file setup needed. Two approaches are available: - **Option A** — file-based context loading. A rules file (`.mdc` for Cursor, `.instructions.md` for Copilot) contains API documentation and behavior rules. No MCP server required. - **Option B** — live schema fetching via MCP server. Extended rule files instruct the AI to call the Mobiscroll MCP server for live component schema lookups on each generation. Suited for interactive coding agents that need per-query precision. Choose based on your preference and setup. #### Files **Option A — file-based rules:** | File | Format | For | |:---|:---|:---| | | Cursor rule file | Cursor | | | Copilot instruction file | GitHub Copilot | **Option B — extended rules with MCP:** | File | Format | For | |:---|:---|:---| | mobiscroll-ui.mdc | Cursor extended rule (orchestrator) | Cursor | | mobiscroll-ui-angular.mdc | Cursor extended rule (Angular) | Cursor | | mobiscroll-ui-theming.mdc | Cursor extended rule (theming) | Cursor | | mobiscroll-ui.instructions.md | Copilot extended instruction (orchestrator) | GitHub Copilot | | mobiscroll-ui-angular.instructions.md | Copilot extended instruction (Angular) | GitHub Copilot | | mobiscroll-ui-theming.instructions.md | Copilot extended instruction (theming) | GitHub Copilot | #### Which tool uses which files? | Tool | Approach | Files used | |:---|:---|:---| | **Cursor** | Option A | `mobiscroll-angular.mdc` | | **Cursor** | Option B | `mobiscroll-ui.mdc`, `mobiscroll-ui-angular.mdc`, `mobiscroll-ui-theming.mdc` | | **GitHub Copilot** | Option A | `mobiscroll-angular.instructions.md` | | **GitHub Copilot** | Option B | `mobiscroll-ui.instructions.md`, `mobiscroll-ui-angular.instructions.md`, `mobiscroll-ui-theming.instructions.md` | ## Cursor setup ### Step 1: Register documentation sources Open **Cursor Settings → Indexing & Docs** and add the documentation source for your framework: | Framework | Name | URL | |:---|:---|:---| | Angular | Mobiscroll Angular | | Only register the source matching your use case. Do not register multiple sources — this prevents cross-domain contamination. ### Step 2: Add behavior rules Choose one approach — Option A works immediately with no additional setup; Option B adds live MCP schema lookups for higher accuracy but requires the MCP server to be configured. #### Option A — .mdc rules file Download the mobiscroll-angular.mdc file and place it in `.cursor/rules/`: ``` your-project/ ├── .cursor/ │ └── rules/ │ └── mobiscroll-angular.mdc ├── src/ └── package.json ``` The `.mdc` file provides text-based API rules — no additional setup required. #### Option B — Extended rule files + MCP (3 files) Download the three extended rule files and place them in `.cursor/rules/`: - mobiscroll-ui.mdc (orchestrator) - mobiscroll-ui-angular.mdc (Angular conventions) - mobiscroll-ui-theming.mdc (theming) ``` your-project/ ├── .cursor/ │ └── rules/ │ ├── mobiscroll-ui.mdc │ ├── mobiscroll-ui-angular.mdc │ └── mobiscroll-ui-theming.mdc ├── src/ └── package.json ``` Unlike Option A, these rule files instruct Cursor's AI to call the Mobiscroll MCP server for live component schema lookups on each generation — so it always uses the current API instead of guessing from memory. #### Rule activation The extended `.mdc` files use `alwaysApply: false` with a `description` in their frontmatter. Cursor reads the description and activates the rule only when the context is relevant — the rule is not included in every message. You can also trigger it manually with `@rule-name` (e.g. `@mobiscroll-ui`). The `.mdc` format works in all Cursor modes including Agent mode. ### Step 3: Configure MCP server (Optional) Configure the Mobiscroll MCP server so the extended rules can call it for live schema lookups. Create or edit `.cursor/mcp.json` in your project root: :::warning No `type` field Cursor infers the transport type from the URL. Do **not** add `"type": "http"` to Cursor's config — it causes an error. ::: ``` your-project/ ├── .cursor/ │ ├── mcp.json │ └── rules/ │ ├── mobiscroll-ui.mdc │ ├── mobiscroll-ui-angular.mdc │ └── mobiscroll-ui-theming.mdc ├── src/ └── package.json ``` | Scope | Config file | Shared with team | |:---|:---|:---| | project | `.cursor/mcp.json` in project root | Yes, if committed | | global | `~/.cursor/mcp.json` | No, all your projects | **Verify the connection:** Open the **Output** panel in Cursor and select **MCP Logs** from the dropdown. A successful connection logs tool discovery messages for the `mobiscroll` server. ### How it works When asking Cursor about Mobiscroll, include `@docs` to ensure it reads the registered documentation: ``` @docs How do I set up a weekly scheduler with Mobiscroll? ``` ``` @docs What options does the Eventcalendar timeline view accept? ``` ## GitHub Copilot setup ### Step 1: Add behavior rules Choose one approach — Option A works immediately with no additional setup; Option B adds live MCP schema lookups for higher accuracy but requires the MCP server to be configured. #### Option A — .instructions.md rules file Download the mobiscroll-angular.instructions.md file and place it in `.github/instructions/`: ``` your-project/ ├── .github/ | └── instructions/ | └── mobiscroll-angular.instructions.md ├── src/ └── package.json ``` The `.instructions.md` file provides text-based API rules — no additional setup required. #### Option B — Extended instruction files + MCP (3 files) Download the three extended instruction files and place them in `.github/instructions/`: - mobiscroll-ui.instructions.md (orchestrator) - mobiscroll-ui-angular.instructions.md (Angular conventions) - mobiscroll-ui-theming.instructions.md (theming) ``` your-project/ ├── .github/ | └── instructions/ | ├── mobiscroll-ui.instructions.md | ├── mobiscroll-ui-angular.instructions.md | └── mobiscroll-ui-theming.instructions.md ├── src/ └── package.json ``` ### Step 2: Configure MCP server (Optional) Configure the Mobiscroll MCP server so the extended instruction files can call it for live schema lookups. Create or edit `.vscode/mcp.json` in your project root: :::warning `"servers"` not `"mcpServers"` VS Code uses `"servers"` as the root key — not `"mcpServers"` like Claude Code and Cursor. Using the wrong key silently breaks the config with no error message. ::: ``` your-project/ ├── .vscode/ │ └── mcp.json ├── .github/ │ └── instructions/ │ ├── mobiscroll-ui.instructions.md │ ├── mobiscroll-ui-angular.instructions.md │ └── mobiscroll-ui-theming.instructions.md ├── src/ └── package.json ``` | Scope | Config file | Shared with team | |:---|:---|:---| | workspace | `.vscode/mcp.json` in project root | Yes, if committed | | user profile | Opened via **MCP: Open User Configuration** | No, all your workspaces | **Verify the connection:** Open the **Command Palette** and run **MCP: List Servers**. The `mobiscroll` server should appear with a connected status. A trust dialog appears on first use — approve it to allow the server to start. Alternatively, open the **Command Palette** and run **MCP: Add Server** for a guided setup. ### How it works The instruction files with `applyTo: "**"` apply automatically to all Copilot Chat queries — no manual reference needed. Both options contain: - **Documentation URLs** — point the AI to the correct framework docs - **Component mapping** — map user intents (e.g., "scheduler") to the correct Mobiscroll APIs - **Rules** — enforce correct package imports, CSS loading, and API usage - **Constraints** — prevent cross-framework mixing and API hallucination Ask Mobiscroll questions directly: ``` How do I set up a weekly scheduler with Mobiscroll? ``` ``` What options does the Eventcalendar timeline view accept? ``` ## Claude Code setup Install the Mobiscroll plugin for Claude Code. The plugin bundles framework coding skills and the MCP server in a single install — no per-project configuration files needed. ### Step 1: Register the marketplace Run this once in Claude Code to register the Mobiscroll plugin marketplace: ``` /plugin marketplace add acidb/mobiscroll-marketplace ``` ### Step 2: Install the plugin ``` /plugin install mobiscroll@mobiscroll ``` ### Step 3: Configure MCP server (Optional) The plugin bundles the MCP server — no separate configuration is needed for most setups. To configure it manually or share it with your team: :::warning VS Code extension If you are using the Claude Visual Studio Code extension, the server will not appear unless it is added with project scope. See the next command below. ::: To share the server with your team automatically, use project scope: This creates or updates `.mcp.json` in your project root. You can also create that file manually: | Scope | CLI flag | Config location | Shared with team | |:---|:---|:---|:---| | local (default) | `--scope local` | `~/.claude.json` | No | | project | `--scope project` | `.mcp.json` in project root | Yes, via version control | | user | `--scope user` | `~/.claude.json` | No, all your projects | :::info Use `--scope project` for team repos so everyone gets the MCP server automatically when they clone the project. ::: **Verify the connection:** Run `/mcp` inside Claude Code. The panel lists each connected server and its tool count. A healthy connection shows `mobiscroll` with at least one tool. ### How it works Once installed, the plugin provides: - **Skills** — `mobiscroll-ui` is the orchestrator skill that detects your framework (React, Angular, Vue, JavaScript, or jQuery) and loads the matching framework sub-skill. Theming questions are handled by `mobiscroll-ui-theming`. All skills are installed together. - **MCP server** — The bundled Mobiscroll MCP server provides live component schema lookup, code validation, and example search on demand — so Claude always uses the current API, never hallucinated or outdated options. When you ask Claude Code to write Mobiscroll code, it: 1. Detects your framework and Mobiscroll version via `resolveEnvironment` 2. Loads the matching framework skill with idiomatic conventions 3. Looks up the component schema before writing any props or events 4. Validates generated code before returning it to you ## Framework isolation :::warning Critical Each rules file and documentation source targets exactly **one** framework or domain. Never combine files from different frameworks, or mix UI framework files with Connect files. ::: **Why this matters:** - Most API options are shared across frameworks, but component usage and templating differs for each — mixing them produces broken code **Mobiscroll Connect is a separate domain:** - Connect is a backend integration layer — OAuth 2.0, REST API, webhooks, calendar sync - It has no UI components, no JSX, no frontend framework bindings - Connect uses `mobiscroll-connect.mdc` and `llms-connect-full.txt` — never the UI framework files - Mixing Connect docs with UI docs causes the AI to conflate REST endpoints with component APIs **Rules:** 1. Use only rules files that match **one** framework or domain — never mix files from different frameworks 2. Register only **one** documentation source in Cursor 3. If your project uses multiple frameworks (e.g., micro-frontends), set up separate directories with separate `.mdc` files 4. If your project uses both a UI framework and Mobiscroll Connect, use separate AI context directories for each 5. If an AI assistant generates code with wrong framework imports, check that the correct rules file is in place ## Example queries These examples show the kind of questions the AI integration is designed to handle correctly. ``` How do I import MbscModule into my standalone component? Set up a monthly calendar view with mbsc-eventcalendar. Where do I add the Mobiscroll CSS in angular.json? ``` ## Troubleshooting ### AI generates code with the wrong framework **Symptom:** You are using Angular but the AI generates React code with `import { Eventcalendar } from '@mobiscroll/react'`. **Fix:** Verify that you have the correct rules file in place. For Angular in Cursor, use `mobiscroll-angular.mdc`; for Copilot, use `mobiscroll-angular.instructions.md`. In Cursor, check that the registered @docs source points to `5.35.0/llms-angular-full.txt`. ### AI invents non-existent APIs **Symptom:** The AI suggests options, events, or types that don't exist in the Mobiscroll documentation. **Fix:** The `.mdc` rules instruct the AI to only use APIs found in the docs. If this still happens, explicitly reference `@docs` in Cursor queries, or verify that the Mobiscroll plugin is installed in Claude Code (`/plugin list`). You can also ask the AI to verify an option exists in the Mobiscroll docs. ### AI mixes Mobiscroll Connect with UI components **Symptom:** The AI generates REST API calls when you asked about a frontend calendar component, or generates JSX/component code when you asked about the Connect API. **Fix:** Mobiscroll Connect is a backend integration layer (OAuth, REST, webhooks) and has no UI components. Eventcalendar is a frontend UI component with no REST API. They use entirely separate `.mdc` files and documentation sources. Verify that the correct `.mdc` file is active for your project. If you use both in the same codebase, keep separate AI context directories for each. ### MCP server does not appear after setup **Symptom:** The MCP server panel shows no `mobiscroll` entry, or tools are not available. **Fix:** Check that the config file is in the correct location and uses the correct root key — `mcpServers` for Claude Code and Cursor, `servers` for VS Code. Validate that the file is well-formed JSON. For Claude Code, run `/mcp` to inspect connected servers. ## File reference All AI integration files are available at the following URLs: ### Documentation files | File | URL | |:---|:---| | Angular | | ### Rules files | File | Cursor (`.mdc`) | Copilot (`.instructions.md`) | |:---|:---|:---| | Angular rules | | | ### Extended rule files | File | Cursor (`.mdc`) | Copilot (`.instructions.md`) | |:---|:---|:---| | Orchestrator | mobiscroll-ui.mdc | | | Angular conventions | mobiscroll-ui-angular.mdc | | | Theming | mobiscroll-ui-theming.mdc | | ## File contents The complete contents of each file are shown below. You can copy directly from these blocks or use the download links above. ### Extended rule files
View mobiscroll-ui.mdc (orchestrator)
View mobiscroll-ui-angular.mdc (Angular conventions)
View mobiscroll-ui-theming.mdc (theming)
### Rules files (.mdc)
View mobiscroll-angular.mdc
--- ## Migrating from Bryntum to Mobiscroll ## Overview This article provides a comprehensive guide for migrating your scheduling solution from Bryntum to Mobiscroll. It highlights the key differences between the two libraries and outlines step-by-step instructions, covering installation, configuration, resources, events, and features, ensuring a smooth and informed transition. ## Installation Migrating from Bryntum to Mobiscroll starts with a different approach to installation, especially regarding package access and tooling. ### Mobiscroll installation steps: Install the [Mobiscroll CLI](/angular/getting-started/installation#install-the-cli) (only needed once): ```bash npm install -g @mobiscroll/cli ``` [Configure Mobiscroll](/angular/getting-started/installation#installing-from-npm) in your project (navigate to your project root folder and run): ```bash mobiscroll config angular ``` Alternatively, Mobiscroll also supports [manual installation](/angular/getting-started/installation#installing-manually) if you’re not using NPM. However, using NPM is generally the recommended approach for simplicity and maintainability. ## Initialization ### Bryntum: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { } ``` ### Mobiscroll: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { } ``` ## View configuration Key Differences: - With Mobiscroll, you get precise control over time ranges on [Scheduler](https://demo.mobiscroll.com/scheduler/show-hide-hours-days) and [Timeline](https://demo.mobiscroll.com/timeline/daily-weekly-monthly-yearly-timeline) views, plus feature-rich [Event Calendar](https://demo.mobiscroll.com/eventcalendar) and [Agenda](https://demo.mobiscroll.com/agenda) views for seamless scheduling. - Bryntum provides built-in view presets. ### Bryntum Scheduler Pro: For the Bryntum Scheduler, the time axis is configured using three settings: `startDate`, `endDate`, and `viewPreset`. The `startDate` and `endDate` define the overall date range visible on the axis, while the `viewPreset` controls its visual layout and determines which specific dates are displayed. **app.component.html** ```html ``` **app.component.ts** ```ts const schedulerProProps: BryntumSchedulerProps = { startDate: new Date(2017, 0, 1, 6), endDate: new Date(2017, 0, 1, 20), viewPreset: 'hourAndDay', }; @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) xport class AppComponent { schedulerProProps = schedulerProProps; } ``` ### Mobiscroll Timeline view: In the Mobiscroll Timeline view, the `timeline` object within the [`view`](/angular/eventcalendar/timeline#configuring-the-view) option allows you to customize the visible days and the timeline’s scale. You can specify which days to display (e.g., weekdays), set the time scale (e.g., 30-minute intervals), and define the frequency of the labels shown (e.g., every 15 minutes). **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { myView: MbscEventcalendarView = { timeline: { type: 'day', size: 1, startTime: '06:00', endTime: '20:00', } }; mySelectedDate: MbscDate = '2017-01-01'; // if you want to set the initial view to a specific date } ``` Check out how you can configure the Timeline view in [this live example](https://demo.mobiscroll.com/timeline/daily-weekly-monthly-yearly-timeline#). ### Bryntum Calendar view config: In the Bryntum Calendar, the `date` option sets the initial date that the Calendar, its sidebar date picker, and the active view should center around upon initialization. The `mode` option determines which of the built-in views (such as day, week, or month) is active by default. **app.component.html** ```html ``` **app.component.ts** ```ts BryntumCalendarModule, BryntumCalendarProps, } from '@bryntum/calendar-angular'; const calendarProps: BryntumCalendarProps = { date: new Date(2022, 0, 1), }; @Component({ selector: 'app-root', imports: [BryntumCalendarModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { calendarProps = calendarProps; } ``` ### Mobiscroll Scheduler: You can customize the visible days and hours, as well as the time grid scale, using the `schedule` object under the [`view`](/angular/eventcalendar/scheduler#configuring-the-view) option. This allows you to define which days are shown (e.g., weekdays), set the visible time range (e.g., 8 AM to 6 PM), adjust the time scale (e.g., 30-minute intervals), and control the frequency of the labels (e.g., every 15 minutes). **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { myView: MbscEventcalendarView = { scheduler: { type: 'week' } }; mySelectedDate: MbscDate = '2022-01-01'; // if you want to set the initial view to a specific date } ``` Check out how you can configure the Scheduler view in [this live example](https://demo.mobiscroll.com/scheduler/show-hide-hours-days#). ## Resource configuration Migrating resource data from Bryntum to Mobiscroll should be relatively straightforward. ### Bryntum Scheduler Pro – resource definition: ```ts myResources = [ { id: 'r1', name: 'Mike' }, { id: 'r2', name: 'Linda' }, // ... ]; ``` ### Mobiscroll Timeline view/ Scheduler – resource definition: ```ts myResources: MbscResource[] = [ { id: 'r1', name: 'Mike' }, { id: 'r2', name: 'Linda' }, // ... ]; ``` As shown above, both Bryntum and Mobiscroll use similar structures for defining resources, typically including `id` and `name` [properties](/angular/eventcalendar/timeline#opt-resources). Like Bryntum, Mobiscroll also supports a wide range of additional properties, as demonstrated in [this example](https://demo.mobiscroll.com/timeline/resource-data-structure#). For more advanced use cases, refer to the [Mobiscroll documentation](/angular/eventcalendar/resources) for additional options, including [custom rendering and templating of resources](/angular/eventcalendar/timeline#the-resource-their-header-and-footer). You can also explore our demo page for [detailed resource configuration](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer) examples. ## Event migration As shown above, there are clear differences in how events are structured between Bryntum and Mobiscroll. Bryntum defines an event inside the `events` option using a `startDate`, along with a `duration` and `durationUnit` to determine the end time. In contrast, Mobiscroll uses the [`data`](/angular/eventcalendar/timeline#opt-data) option and explicit `start` and `end` [properties](https://demo.mobiscroll.com/timeline/event-data-structure#) for defining the event period. ### Event structure comparison #### Bryntum: ```ts myEvents = [ { id: 1, resourceId: 'r1', startDate: new Date(2017, 0, 1, 10), duration: 2, durationUnit: 'h', name: 'Click me' } ]; ``` #### Mobiscroll: ```ts myEvents: MbscCalendarEvent[] = [ { id: 1, resource: 'r1', start: '2017-01-01T10:00', end: '2017-01-01T12:00', title: 'Click me' } ]; ``` ### Converting Bryntum events to Mobiscroll format Here’s a simple example of how to convert Bryntum-style events into the format used by Mobiscroll: ```ts this.mobiscrollEvents = this.bryntumEvents.map(event => { const start = new Date(event.startDate); const end = new Date(start.getTime() + event.duration * 60 * 60 * 1000); return { id: event.id, title: event.name, start, end, resource: event.resourceId }; }); ``` Every project may have its own unique data format and requirements, so this script serves only as a basic starting point. You’ll likely need to adapt your transformation logic to fit your application’s specific needs. ### Loading and saving data When selecting a scheduling or calendar UI component, one of the most important factors to evaluate is how the component loads and saves data. The chosen approach can significantly influence performance, scalability, and integration complexity. We will examine how each framework handles: - Loading data from local or remote sources. - Saving or synchronizing changes to a backend system. ### Loading data Bryntum: - Bryntum components use stores, structured data collections that manage entities such as resources, events, and project details. - Data is typically loaded from remote REST endpoints (e.g., /load, /read-resources) that return JSON. These endpoints can support filtering and chunking to optimize handling of large datasets. - Lazy loading (or paginated loading) is supported, allowing data to be fetched on demand as the user scrolls or navigates, minimizing initial load times and memory usage. - The backend layer is fully decoupled, enabling the use of any technology stack (Node.js, PHP, Java, etc.) to deliver JSON payloads to the Bryntum frontend. Mobiscroll: - Mobiscroll components accept static arrays, which can be [inline](/angular/eventcalendar/data-binding#local-data) (preloaded in memory) or [dynamically fetched](/angular/eventcalendar/data-binding#remote-data) from remote APIs. - The [`onPageLoading`](/angular/eventcalendar/api#event-onPageLoading) event plays a central role in incremental data loading, enabling applications to [request only the events needed](https://demo.mobiscroll.com/timeline/load-events-on-demand) for the current view (e.g., the current month or week) as the user navigates. - Mobiscroll also offers [integration with external calendar services](/angular/eventcalendar/calendar-integrations/) ([Google Calendar](https://demo.mobiscroll.com/eventcalendar/sync-events-google-calendar#), [Outlook](https://demo.mobiscroll.com/eventcalendar/sync-events-outlook-calendar#)) via plugins, handling data retrieval and format conversion internally. Let’s see an example for each case: ### Local data #### Bryntum: You can use the `events` option for passing the data inline. ```html ``` #### Mobiscroll: Pass the event array to the [`data`](/angular/eventcalendar/api#opt-data) option. ```html ``` ### Remote data #### Bryntum You can use a project definition that solves the loading of the events from the backend. **app.component.html** ```html ``` **app.component.ts** ```ts const schedulerProProps: BryntumSchedulerProps = { columns: [{ type: 'resourceInfo', width: 150 }], startDate: new Date(2017, 0, 1, 6), endDate: new Date(2017, 0, 1, 20), viewPreset: 'hourAndDay', }; @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { schedulerProProps = schedulerProProps; } ``` #### Mobiscroll You can load the data through an external request and assign it to the data-bound variable to update the eventcalendar with the newly received data. In case of Mobiscroll, you can also use the [`onPageLoading`](/angular/eventcalendar/api#event-onPageLoading) pevent to load the data (on demand) relevant to the currently active view. The event fires every time the date range of the view changes, for example, when someone navigates the event calendar. Getting the events in real time as the user interacts with the UI improves load performance and always serves the most recent data. **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: 'day' } }; myData: MbscCalendarEvent[] = []; handlePageLoading(args: MbscPageLoadingEvent) { const year = args.month.getFullYear(); const month = args.month.getMonth(); const day = args.month.getDate(); getJson( 'https://example.remotedata.com/weeklyevents/?year=' + year + '&month=' + month + '&day=' + day, (events) => { this.myData = events; }, "jsonp" ); } } ``` In case of the timeline view, data can also be [loaded dynamically during scrolling](/angular/eventcalendar/timeline#load-data-on-scroll). Scrolling vertically or horizontally triggers the [`onVirtualLoading`](/angular/eventcalendar/api#event-onVirtualLoading) lifecycle event, which can be used to [load data incrementally during scrolling](https://demo.mobiscroll.com/timeline/load-resources-on-scroll). ### Saving data #### Bryntum - Developers can manually connect stores to custom endpoints. - By enabling `autoSync: true` in the project configuration, local changes automatically trigger API requests to persist modifications without additional boilerplate. Example: **app.component.html** ```html ``` **app.component.ts** ```ts const schedulerProProps: BryntumSchedulerProps = { columns: [{ type: 'resourceInfo', width: 150 }], startDate: new Date(2017, 0, 1, 6), endDate: new Date(2017, 0, 1, 20), viewPreset: 'hourAndDay', }; @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { schedulerProProps = schedulerProProps; } ``` #### Mobiscroll - Persistence is managed by listening to Mobiscroll’s [CRUD lifecycle events](/angular/eventcalendar/crud). - The Event Calendar exposes a [variety of events](/angular/eventcalendar/api#events) that are triggered on certain actions made on calendar events. These events can be used to send your data to your API or save it to persistent storage. Example for saving, updating, and deleting an event through an API: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: "week" }, }; myEvents: MbscCalendarEvent[] = [ { id: 'id1' start: '2023-09-24', end: '2023-09-30', title: 'Short trip!'}, ]; saveEvent(args: MbscEventCreatedEvent) { fetch('add.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); }, updateEvent(args: MbscEventUpdatedEvent) { fetch('update.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); }, deleteEvent(args: MbscEventDeletedEvent) { fetch('delete.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); } }); ``` Mobiscroll offers a flexible, event-driven approach suitable for both lightweight client-side setups and API-driven applications. Developers are responsible for implementing their own persistence logic, allowing for high adaptability but requiring more manual integration effort. Both libraries are capable of handling modern scheduling needs, but the choice depends largely on application scale, data complexity, and desired control over the persistence layer. ## Lifecycle events Both libraries, Bryntum and Mobiscroll, provide a comprehensive set of lifecycle event hooks, enabling deep customization and integration with your application logic. These events are emitted at various stages of a component’s lifecycle, offering developers full control to inject custom behavior and extend default functionality. Whether you’re looking to manipulate data before rendering, respond to user interactions, or perform cleanup tasks, Mobiscroll’s event system offers the flexibility to tailor components to your specific needs. When migrating between Bryntum and Mobiscroll, it’s important to note that most lifecycle events follow similar patterns across both libraries. This alignment minimizes friction during the transition process and helps preserve custom behaviors with minimal adjustments. One such example is how each library handles a double-click on a cell. Below is a comparison of the respective event handlers and their parameters. ### Bryntum In Bryntum, the `onCellDblClick` event is triggered when a user double-clicks a grid cell. This event provides access to several key objects that describe the interaction and context: - `event`: Object - The Bryntum event object - `grid`: Grid - The grid instance - `record`: Model - The record representing the row - `column`: Column - The column to which the cell belongs - `cellElement`: HTMLElement - The cell HTML element - `target`: HTMLElement - The target element - `event`: MouseEvent - The native DOM event Example: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... handleCellDblClick(event: { date: Date; resourceRecord: any }) { console.log('Cell double-clicked:', event.date, event.resourceRecord); // Example: open editor for a new event // this.schedulerpro.editEventDialog.show({ startDate: event.date, event.resourceRecord }); } } ``` ### Mobiscroll Mobiscroll components (e.g., Event Calendar, Scheduler, Timeline) expose a similar [`onCellDoubleClick`](/angular/eventcalendar/api#event-onCellDoubleClick) event, which is fired when a cell is double-clicked. It includes contextual information that allows for granular control over the interaction: - `args` - The event argument with the following properties: - `date`: Date - The date of the clicked cell. - `domEvent`: Event - The DOM event of the click. - `events`: Array - The events for the clicked date. - `resource`: string | number - The id of the resource where the cell was clicked, if resources are set. - `selected`: boolean - Specifies if the day is currently selected or not (before it was clicked). - `source`: 'calendar' | 'schedule' | 'timeline' - The view where the cell was clicked. - `target`: HTMLElement - The DOM element of the clicked cell. - `inst` - The component instance. Example: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... handleCellDblClick(args: MbscEventClickEvent) { console.log('Cell double-clicked:', args.date, args.resource); // Example: open editor for a new event // this.showCreateEventDialog(args.date, args.resource); } } ``` Although the naming conventions and parameter structures differ slightly between Bryntum and Mobiscroll, the overall event purpose and customization potential remain aligned. Developers familiar with Bryntum’s event model will find it straightforward to adapt similar functionality in Mobiscroll, ensuring a smooth migration path with minimal overhead. To explore the full list of available Mobiscroll lifecycle events and understand how they can be leveraged, please refer to the [documentation](/angular/eventcalendar/api#events). Additionally, you can see these events in action through live, interactive examples for the following Mobiscroll components: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/event-hooks) - [Scheduler](https://demo.mobiscroll.com/scheduler/event-hooks) - [Timeline](https://demo.mobiscroll.com/timeline/event-hooks) - [Agenda](https://demo.mobiscroll.com/agenda/event-hooks) These examples provide hands-on insights into how lifecycle events work in practice. ## Feature migration As a final step, let’s explore how core features from Bryntum can be replicated using Mobiscroll. While some capabilities are available out of the box in Bryntum, Mobiscroll often requires more explicit setup but offers much more flexibility. ### Drag & Drop functionality - Bryntum enables drag-and-drop operations by default with no extra configuration needed. - In Mobiscroll, the D&D features must be enabled explicitly via [configuration options](/angular/eventcalendar/drag-and-drop). #### Enabling Drag & Drop in Mobiscroll: ```html ``` This configuration allows users to create, move, resize, and delete events in Mobiscroll. ### Switching Views (Calendar/Scheduler/Agenda) - Bryntum enables switching views by default with no extra configuration needed. - Mobiscroll doesn’t include a built-in view-switching UI by default. However, it offers greater flexibility by allowing you to implement a custom header where you can design the view-switching experience to fit your needs. For example, you can use a [dropdown menu](https://demo.mobiscroll.com/select) or [segmented controls](https://demo.mobiscroll.com/forms/segmented) to let users switch between views like Calendar, Scheduler, Agenda, or any other layout that fits your use case. #### Bryntum: **app.component.html** ```html ``` **app.component.ts** ```ts BryntumCalendarModule, BryntumCalendarProps, } from '@bryntum/calendar-angular'; const calendarProps: BryntumCalendarProps = { date: new Date(2022, 0, 1), }; @Component({ selector: 'app-root', imports: [BryntumCalendarModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { calendarProps = calendarProps; } ``` #### Mobiscroll: In Mobiscroll, switching between views like Day, Week, or Month requires setting up a custom header along with event listeners to handle the view changes. You can see an example of this implementation [here](https://demo.mobiscroll.com/scheduler/switching-calendar-scheduler-agenda). **app.component.html** ```html
Month Week Day Agenda
``` **app.component.ts** ```ts setOptions({ theme: 'ios', themeVariant: 'light' }); @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [CommonModule, FormsModule, MbscModule], }) export class AppComponent implements OnInit { constructor(private http: HttpClient) {} myEvents: MbscCalendarEvent[] = []; view = 'month'; calView: MbscEventcalendarView = { calendar: { labels: true }, }; ngOnInit(): void { this.http.jsonp('https://trial.mobiscroll.com/events/?vers=5', 'callback').subscribe((resp) => { this.myEvents = resp; }); } changeView(): void { setTimeout(() => { switch (this.view) { case 'year': this.calView = { calendar: { type: 'year' }, }; break; case 'month': this.calView = { calendar: { labels: true }, }; break; case 'week': this.calView = { schedule: { type: 'week' }, }; break; case 'day': this.calView = { schedule: { type: 'day' }, }; break; case 'agenda': this.calView = { calendar: { type: 'week' }, agenda: { type: 'week' }, }; break; } }); } } ``` ### Timezones Handling time zones accurately is crucial in calendar and scheduling applications, especially when working across regions or coordinating international events. Both Bryntum and Mobiscroll offer support for working with time zones, though they approach it differently in terms of configuration and underlying technology. So, let’s see a simple example of how this scenario is handled in the case of Bryntum and Mobiscroll. #### Bryntum Bryntum provides built-in time zone support across all of its scheduling products. This allows you to configure components to operate in a specific time zone, independent of the browser or system time. To enable time zone conversion in Bryntum, simply set the [`timeZone`](https://bryntum.com/products/schedulerpro/docs/api/Scheduler/model/ProjectModel#config-timeZone) configuration on the project object. You can use either: - an IANA time zone identifier (e.g., 'Europe/Stockholm'), or - a UTC offset in minutes (e.g., -120) Timezone can be set on the project or on the scheduler component directly: ```html ``` ```html ``` #### Mobiscroll By default, Mobiscroll will not do any timezone conversion, will display the dates without modification, handling them as timezone-less. If your use case requires interpreting or displaying data in a different time zone, you can achieve this by using one of the supported third-party libraries for time zone conversion: - [Moment-Timezone](/angular/eventcalendar/timezones#the-moment-timezone-library) - [Luxon](/angular/eventcalendar/timezones#the-luxon-library) - [Day.js](/angular/eventcalendar/timezones#the-dayjs-library) Mobiscroll exposes two configuration options to handle time zones: - `dataTimezone` [option](/angular/eventcalendar/api#opt-dataTimezone) – the time zone in which your event data is stored (e.g., 'utc') - `displayTimezone` [option](/angular/eventcalendar/api#opt-displayTimezone) – the time zone in which you want the data to be presented (e.g., 'Europe/Stockholm') So, let’s say you want to use the Day.js timezone library. After [installing](/angular/eventcalendar/timezones#the-dayjs-library) it into your project, you can pass the `dayjsTimezone` object to the Timeline’s [`timezonePlugin`](/angular/eventcalendar/api#opt-timezonePlugin) option: **app.component.html** ```html ``` **app.component.ts** ```ts dayjs.extend(utc); dayjs.extend(timezone); dayjsTimezone.dayjs = dayjs; @Component({...}) export class MyComponent { myDayjsTimezone: MbscTimezonePlugin = dayjsTimezone; } ``` Also, feel free to explore live examples to see how time zones work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/setting-the-timezone#) - [Scheduler](https://demo.mobiscroll.com/scheduler/setting-the-timezone#) - [Timeline](https://demo.mobiscroll.com/timeline/setting-the-timezone#) - [Agenda](https://demo.mobiscroll.com/agenda/setting-the-timezone#) Or you can also check advanced demos such as: - [switching timezones (on the fly) from the header](https://demo.mobiscroll.com/eventcalendar/multiple-timezone-support) - [display time for multiple timezones](https://demo.mobiscroll.com/scheduler/show-multiple-timezones) - [create a meeting planner across multiple timezones](https://demo.mobiscroll.com/timeline/timezone-meeting-planner) You can also store the timezone inside the event data, using the [`timezone`](/angular/eventcalendar/api#opt-data) property. As a conclusion, both libraries, Bryntum and Mobiscroll, provide timezone support. Mobiscroll supports multiple timezone libraries ([Moment-Timezone](/angular/eventcalendar/timezones#the-moment-timezone-library), [Luxon](/angular/eventcalendar/timezones#the-luxon-library), and [Day.js](/angular/eventcalendar/timezones#the-dayjs-library)), while Bryntum relies on angular Date, which may introduce DST inconsistencies. #### Conclusion While Bryntum offers more built-in functionality out of the box, Mobiscroll provides greater flexibility, enabling tailored behavior through configuration and custom UI components: - Feel free to explore our demo page for [Timeline](https://demo.mobiscroll.com/timeline), [Scheduler](https://demo.mobiscroll.com/scheduler), [Event Calendar](https://demo.mobiscroll.com/eventcalendar), and [Agenda](https://demo.mobiscroll.com/agenda) views - featuring grouped examples, including [common use cases](https://demo.mobiscroll.com/timeline/employee-shifts), [view configuration](https://demo.mobiscroll.com/scheduler/custom-range-view), [event](https://demo.mobiscroll.com/timeline/timeline-custom-event-rendering) and [resource](https://demo.mobiscroll.com/scheduler/custom-resource-header-template) templating, and [lifecycle event handling](https://demo.mobiscroll.com/timeline/event-hooks). - We also offer comprehensive documentation for the [Timeline](/angular/eventcalendar/timeline), [Scheduler](/angular/eventcalendar/scheduler), [Event Calendar](/angular/eventcalendar/calendar), and [Agenda](/angular/eventcalendar/agenda) views. It covers [usage](/angular/eventcalendar/timezones), [APIs](/angular/eventcalendar/api), [customization options](/angular/eventcalendar/templating), and more in detail. In addition to drag & drop and custom view-switching, Mobiscroll also supports [timezone handling](https://demo.mobiscroll.com/scheduler/setting-the-timezone) and [zooming levels](https://demo.mobiscroll.com/timeline/calendar-zoom). All of our views work seamlessly across both [mobile](https://demo.mobiscroll.com/scheduler/mobile-day-view) and [desktop](https://demo.mobiscroll.com/scheduler/desktop-day-view) environments, with full support for touch interactions. As mentioned above, with some additional setup, most —if not all— features can be effectively replicated when migrating from Bryntum to Mobiscroll. If you have any specific questions or run into any issues, don’t hesitate to [reach out](https://mobiscroll.com#get-help) — we’re happy to help. ## Templating and renderers ### Event templating #### Bryntum Bryntum handles templating for events, resources, and other UI elements through a flexible system that allows developers to customize content rendering using template functions or strings. In case of Bryntum you can show any HTML structure inside an event bar using the [`eventRenderer`](https://bryntum.com/products/schedulerpro/docs/api/Scheduler/view/mixin/SchedulerEventRendering#config-eventRenderer). **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { myEvents = [ { id: 10, resourceId: 'r1', name: 'Custom Meeting', startDate: '2017-01-01 09:00', endDate: '2017-01-01 11:00', duration: 2 }, ]; customEventRenderer({ eventRecord }) { return { html: `
${eventRecord.name}
Duration: ${eventRecord.duration}h
`, }; } } ``` #### Mobiscroll You can customize many parts of the Event Calendar by writing custom templates. In the context of plain angular these templates are functions that return a string containing the html markup. You will find a comprehensive list of all the available render functions for the Event Calendar in the [API templates](/angular/eventcalendar/api#renderers) section. When you want to customize how the events look, depending on what your goal is, you have two options: - [Customize the event content](/angular/eventcalendar/templating#event-content-templating) - Mobiscroll takes care of rendering the events in the correct order and also prints basic fields, like `start`/`end`, whether it is an `allDay` event or not and also takes care of coloring the event appropriately. Everything else comes from the custom template. - [Customize the full event](/angular/eventcalendar/templating#full-event-templating) - Mobiscroll takes care of rendering the events in the correct order, but everything else comes form the template you write. To define a template, create an `` tag with a variable reference and pass it to the apropriate eventcalendar option: **app.component.html** ```html
{{eventRecord.name}}
Duration: {{eventRecord.duration}}h
 ``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... myEvents: MbscCalendarEvent[] = [ { id: 10, resourceId: 'r1', name: 'Custom Meeting', startDate: '2017-01-01 09:00', endDate: '2017-01-01 11:00', duration: 2 }, ]; } ``` Feel free to explore live examples to see how event content templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customize-label-look-and-feel#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-events#) - [Timeline](https://demo.mobiscroll.com/timeline/meal-planner#) - [Agenda](https://demo.mobiscroll.com/agenda/event-content-customization#) Feel free to explore live examples to see how full event templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customize-event-popover#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-events#) - [Timeline](https://demo.mobiscroll.com/timeline/timeline-custom-event-rendering#) - [Agenda](https://demo.mobiscroll.com/angular/agenda/customizing-calendar-header) ### Resource templating #### Bryntum You can customize cell content and styling in a column using a [renderer](https://bryntum.com/products/scheduler/docs/api/Grid/column/Column#config-renderer) function. To customize the column header, use the [`headerRenderer`](https://bryntum.com/products/scheduler/docs/api/Grid/column/Column#config-headerRenderer) option. **app.component.html** ```html ``` **app.component.ts** ```ts BryntumSchedulerProModule, BryntumSchedulerProps, } from '@bryntum/schedulerpro-angular'; const schedulerProProps: BryntumSchedulerProps = { columns: [ { text: 'Name', field: 'name', width: 130, headerRenderer: () => { return 'Name'; }, renderer: ({ record }: any) => { return { html: `${record.name}` }; }, }, { text: 'City', field: 'city', width: 90, headerRenderer: () => { return 'City'; }, renderer: ({ record }: any) => { return { html: `${record.city}` }; }, }, ], startDate: new Date(2017, 0, 1, 6), endDate: new Date(2017, 0, 1, 20), viewPreset: 'hourAndDay', }; @Component({ selector: 'app-root', imports: [BryntumSchedulerProModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { schedulerProProps = schedulerProProps; myResources = [ { id: 1, name: 'Adam', city: 'Washington' }, { id: 2, name: 'Eva', city: 'New York' }, ]; } ``` #### Mobiscroll In the case of Mobiscroll, we take a different approach. We provide various templating options (listed below), which allow you to customize the resources. This is unlike Bryntum, where customization requires modifying the columns with different renderers. #### Scheduler Use the [`resourceTemplate`](/angular/eventcalendar/scheduler#template-resourceTemplate) option to customize the resource template of the Scheduler. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](/angular/eventcalendar/scheduler#opt-resources) array. It takes a function that should return the desired markup. Check out how you can style the resources in [this example](https://demo.mobiscroll.com/scheduler/custom-resource-header-template#). #### Timeline In case of the Timeline view there are three places where you can customize the resource column: - Use the [`resourceTemplate`](/angular/eventcalendar/timeline#template-resourceTemplate) option to customize the resource template of the Timeline. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](/angular/eventcalendar/timeline#opt-resources) array. - Customize the empty cell content above the resource column with the [`resourceHeaderTemplate`](/angular/eventcalendar/timeline#template-resourceHeaderTemplate) option. - Or if you want to customize the empty cell content below the resource column you can achieve this with the [`resourceFooterTemplate`](/angular/eventcalendar/timeline#template-resourceFooterTemplate) option. This element only renders for the Timeline view, if the [`dayFooterTemplate`](/angular/eventcalendar/timeline#template-dayFooterTemplate) option is present. Check out how you can style these resource parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#). **app.component.html** ```html
Name
City
{{record.name}}
{{record.city}}
``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... myResources: MbscResource[] = [ { id: 1, name: 'Adam', city: 'Washington' }, { id: 2, name: 'Eva', city: 'New York' }, ]; } ``` ### Header templating The header of the Mobiscroll calendar can be fully customized to one's needs with the use of the [`headerTemplate`](/angular/eventcalendar/timeline#template-headerTemplate) option. Here's the list of the built in components of the default header. You can initialize these by putting the attributes on the elements: - `mbsc-calendar-prev` - Previous button component, that navigates to the previous month. - `mbsc-calendar-next` - Next button component, that navigates to the next month. - `mbsc-calendar-today` - Today button component, that navigates to the current date. - `mbsc-calendar-nav` - The title navigation button component, that opens the year/month navigation. The following example will render the prev and next buttons and a custom title. ```html
{{myTitle}}
 ``` Also, feel free to explore live examples to see how header templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customizing-header#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-header#) - [Timeline](https://demo.mobiscroll.com/timeline/switching-day-week-work-week-timeline) - [Agenda](https://demo.mobiscroll.com/agenda/customizing-calendar-header) ### Other templating/ renderer options #### Event Calendar - Date header templating - There are two approaches you can take: - Customize the date headers of the Event Calendar with the [`dayTemplate`](/angular/eventcalendar/calendar#template-dayTemplate) option by adding relevant content, labels or completely change how they look. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [`dayContentTemplate`](/angular/eventcalendar/calendar#template-dayContentTemplate) option. #### Scheduler - [Date header templating](/angular/eventcalendar/scheduler#the-date-header) - There are two approaches you can take: - Customize the date headers of the Scheduler with the [`dayTemplate`](/angular/eventcalendar/scheduler#template-dayTemplate) option by adding relevant content, labels or completely change how they look. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [`dayContentTemplate`](/angular/eventcalendar/scheduler#template-dayContentTemplate) option. Check out how you can style the date header in [this example](https://demo.mobiscroll.com/scheduler/date-header-template#). #### Timeline - [Templating the sidebar header and footer](/angular/eventcalendar/timeline#the-sidebar-their-header-and-footer) - Besides the resource template, an additional sidebar can be rendered on the opposite end of the row and there are three approaches you can take: - Use the [`sidebarTemplate`](/angular/eventcalendar/timeline#template-sidebarTemplate) option to render a custom sidebar on the right side of the Timeline. - Customize the empty cell content above the sidebar column with the [`sidebarHeaderTemplate`](/angular/eventcalendar/timeline#template-sidebarHeaderTemplate) option. - Or if you want to customize the empty cell content below the sidebar column you can achieve this with the [`sidebarFooterTemplate`](/angular/eventcalendar/timeline#template-sidebarFooterTemplate) option. Check out how you can style the sidebar parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#). - [Date header and footer templating](/angular/eventcalendar/timeline#the-date-header-and-footer) - The headers hold key information like the date, day of the week and in some cases it also holds the full date. Whenever you need to show extra information, or if you would like to change the styling or date format, time format you can use the various header templates, depending on the view configuration. You can also show a footer element, for displaying more information. Check out how you can style the date header and footer in [this example](https://demo.mobiscroll.com/timeline/hour-day-week-month-quarter-year-header-footer-template#). - [Slots](/angular/eventcalendar/timeline#the-event-slots) - Use the [`slotTemplate`](/angular/eventcalendar/timeline#template-slotTemplate) option to customize the slot template of the Timeline view. Check out how you can style the slots in [this example](https://demo.mobiscroll.com/timeline/shift-template#). - [Variable event height](/angular/eventcalendar/timeline#variable-event-height) - When using [event templating](/angular/eventcalendar/templating#event-templating), you might end up with various event heights, depending on the displayed content, e.g. larger description, list of tasks, etc. You can enable support for variable event heights by setting the `eventHeight: 'variable'` property for the timeline inside the [`view`](/angular/eventcalendar/timeline#view-timeline-eventHeight) option. Check out how you can set and style the variable event height in [this example](https://demo.mobiscroll.com/timeline/variable-event-height). #### Agenda - [Day header templating](/angular/eventcalendar/agenda#the-agenda-day-header) - Customize the day headers that appear on the agenda with the [`dayTemplate`](/angular/eventcalendar/agenda#template-dayTemplate) option. Check out how you can style the day headers in [this example](https://demo.mobiscroll.com/agenda/customizing-day-header#). - [Empty state templating](/angular/eventcalendar/agenda#the-agenda-empty-state) - Customize the look of the empty state through [`agendaEmptyTemplate`](/angular/eventcalendar/agenda#template-agendaEmptyTemplate) function. Check out how you can style the empty state in [this example](https://demo.mobiscroll.com/agenda/empty-state#). ## Localization ### Bryntum Bryntum supports localization by allowing developers to select from built-in locales or define custom ones. Key aspects include: - Locale files translate UI text, date formats, and number formats to the target language. - Custom locales can be created or modified using their locale structure. - Right-to-left (RTL) layout support is included ```ts LocaleManager.applyLocale('FrFr'); ``` ### Mobiscroll Mobiscroll [enables localization](/angular/core-concepts/localization) by letting developers set language, date, and time formats both globally (across the entire application) and locally (on individual components). Highlights: - Global settings object lets developers set locale, theme, and format across the app (first example). - Each component (e.g., Date Picker, Event Calendar) supports locale switching and custom translations with simple configuration (second example). - RTL and calendar system support (Gregorian, Jalali, Hijri) - Quick override ability for localized formats ensures that adaptations can be made case-by-case or via global settings. Example setting the locale option globally: ```ts setOptions({ // ...other config... locale: localeFr // French locale applied globally }); ``` Example setting the locale at the component level: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [MbscModule] }) export class AppComponent { myLocale = localeFr; // French locale applied globally } ``` ## Conclusion Migrating from Bryntum Scheduler to Mobiscroll Scheduler involves rethinking certain configurations, especially around views, events, and feature toggles. While Bryntum comes with richer built-in functionality out of the box (like zooming, vertical timelines, and infinite scrolling), Mobiscroll shines in flexibility, responsive design, and easier timeline and calendar customizations. The overall migration process includes: - Adjusting initialization patterns - Adapting view configurations - Mapping resources and events to Mobiscroll’s structure - Enabling features like drag-and-drop manually With a clear understanding of both libraries’ capabilities and structures, you can migrate efficiently and take full advantage of Mobiscroll’s modern UI and feature-rich environment. #### Considering migrating from Bryntum to Mobiscroll? [Schedule a call](https://calendly.com/mobiscroll/30min) and let's chat about how we can help. We're here to support you in the migration process. --- ## Migrating from DHTMLX to Mobiscroll ## Overview This article provides a comprehensive guide for migrating your scheduling solution from DHTMLX to Mobiscroll. DHTMLX Scheduler can be integrated into Angular by using a custom wrapper component around the plain Javascript scheduler instance, whereas Mobiscroll provides native Angular components that plug directly into templates through standard bindings. If you are currently using DHTMLX Scheduler in Angular via a custom wrapper, or using it within another framework and planning to migrate to Mobiscroll’s Angular components, the following guide outlines the steps required for a smooth transition. ## Installation Migrating from DHTMLX Scheduler to Mobiscroll starts with a different approach to installation, especially regarding package access and tooling. ### Mobiscroll installation steps: Install the [Mobiscroll CLI](/angular/getting-started/installation#install-the-cli) (only needed once): ```bash npm install -g @mobiscroll/cli ``` [Configure Mobiscroll](/angular/getting-started/installation#installing-from-npm) in your project (navigate to your project root folder and run): ```bash mobiscroll config angular ``` Alternatively, Mobiscroll also supports [manual installation](/angular/getting-started/installation#installing-manually) if you’re not using NPM. However, using NPM is generally the recommended approach for simplicity and maintainability. ## Initialization ### DHTMLX Scheduler: ```js scheduler.init('scheduler_here'); ``` ### Mobiscroll: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { } ``` ## View configuration Key Differences: - With Mobiscroll, you get precise control over time ranges on [Scheduler](https://demo.mobiscroll.com/scheduler/show-hide-hours-days) and [Timeline](https://demo.mobiscroll.com/timeline/daily-weekly-monthly-yearly-timeline) views, plus feature-rich [Event Calendar](https://demo.mobiscroll.com/eventcalendar) and [Agenda](https://demo.mobiscroll.com/agenda) views for seamless scheduling. - DHTMLX uses deeply nested angular objects or HTML for defining views, layouts, templates, and event sources. Views like “Day,” “Week,” “Month,” and custom configurations are declared in the scheduler initialization with specific settings for each widget, often grouped into sections and requiring manual wiring for advanced customization. ### DHTMLX Scheduler - Timeline view: For the DHTMLX you have to use the [`createTimelineView`](https://docs.dhtmlx.com/scheduler/api__scheduler_createtimelineview.html) method for customizing the Timeline view ```js scheduler.plugins({ timeline: true, }); scheduler.createTimelineView({ name: 'timeline', x_unit: 'minute', // measuring unit of the X-Axis. x_date: '%H:%i', // date format of the X-Axis x_step: 30, // X-Axis step in 'x_unit's x_size: 24, // X-Axis length specified as the total number of 'x_step's x_start: 16, // X-Axis offset in 'x_unit's x_length: 48, // number of 'x_step's that will be scrolled at a time y_unit: [ { key: 1, label: 'Resource 1' }, { key: 2, label: 'Resource 2' }, { key: 3, label: 'Resource 3' }, { key: 4, label: 'Resource 4' }, ], render: 'bar', // view mode }); scheduler.init('scheduler_here'); ``` ### Mobiscroll Timeline view: In the Mobiscroll Timeline view, the `timeline` object within the [`view`](/angular/eventcalendar/timeline#configuring-the-view) option allows you to customize the visible days and the timeline’s scale. You can specify which days to display (e.g., weekdays), set the time scale (e.g., 30-minute intervals), and define the frequency of the labels shown (e.g., every 15 minutes). **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { myView: MbscEventcalendarView = { timeline: { type: 'day', size: 1, startTime: '06:00', endTime: '20:00', } }; } ``` Check out how you can configure the Timeline view in [this live example](https://demo.mobiscroll.com/timeline/daily-weekly-monthly-yearly-timeline#). ### DHTMLX Scheduler view: In case of DHTMLX Scheduler the Week view is added to the [basic scheduler's markup](https://docs.dhtmlx.com/scheduler/scheduler_markup.html) by default. That's why you don't need to provide any extra code for adding the view to the scheduler. ```js scheduler.init('scheduler_here',new Date(2019,0,10),"week"); ``` ### Mobiscroll Scheduler: You can customize the visible days and hours, as well as the time grid scale, using the `schedule` object under the [`view`](/angular/eventcalendar/scheduler#configuring-the-view) option. This allows you to define which days are shown (e.g., weekdays), set the visible time range (e.g., 8 AM to 6 PM), adjust the time scale (e.g., 30-minute intervals), and control the frequency of the labels (e.g., every 15 minutes). **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', imports: [MbscModule], templateUrl: './app.component.html', styleUrl: './app.component.scss', }) export class AppComponent { myView: MbscEventcalendarView = { scheduler: { type: 'week' } }; mySelectedDate: MbscDate = '2019-01-10'; // if you want to set the initial view to a specific date } ``` Check out how you can configure the Scheduler view in [this live example](https://demo.mobiscroll.com/scheduler/show-hide-hours-days#). ## Resource configuration Both DHTMLX Scheduler and Mobiscroll support resource-based scheduling (e.g., rooms, employees, assets), but they use different configuration models and event data structures. In DHTMLX Scheduler, resource assignment depends on the view you use: - Timeline view uses `y_property` to decide which row an event belongs to. - Unit view uses `property` to decide which column an event belongs to. You pick the event field name yourself (e.g. `room_id`, `employee_id`), and Scheduler groups events accordingly. In Mobiscroll, resources are defined once in a global `resources` array. Mobiscroll can handle multiple resources inside a single instance. Mobiscroll also supports multi-resource assignment out of the box. ### DHTMLX Scheduler - Timeline view – resource definition: ```js scheduler.plugins({ timeline: true, }); scheduler.createTimelineView({ name: 'timeline', y_property: 'section_id', // mapped data property y_unit: [ { key: 1, label: 'Mike' }, { key: 2, label: 'Linda' }, // ... ], }); scheduler.init('scheduler_here'); ``` ### DHTMLX Scheduler - Units view – resource definition: The DHTMLX Units view uses the `list` parameter of the [`createUnitsView`](https://docs.dhtmlx.com/scheduler/api__scheduler_createunitsview.html) option to set values/ units for the X-Axis. To be correctly processed, `list` items must have 2 mandatory properties: - `key` - the item's id - `label` - the item's label ```js scheduler.plugins({ units: true, }); scheduler.createUnitsView({ name: 'unit', property: 'unit_id', //the mapped data property list: [ //defines the units of the view { key: 1, label: 'Mike' }, { key: 2, label: 'Linda' }, // ... ], }); scheduler.init('scheduler_here'); ``` ### Mobiscroll Timeline view/ Scheduler – resource definition Mobiscroll uses the [`resources`](https://mobiscroll.com/docs/angular/eventcalendar/timeline#opt-resources) array with `id` and `name` properties. ```ts myResources: MbscResource[] = [ { id: 'r1', name: 'Mike' }, { id: 'r2', name: 'Linda' }, // ... ]; ``` Mobiscroll offers significantly more resource manipulation flexibility, including fixed rows, reorder, and external drag & drop. For more advanced use cases, refer to the [Mobiscroll documentation](/angular/eventcalendar/resources) for additional options, including [custom rendering and templating of resources](/angular/eventcalendar/timeline#the-resource-their-header-and-footer). You can also explore our demo page for [detailed resource configuration](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer) examples. ## Event migration As shown below, there are clear differences in how events are structured between DHTMLX and Mobiscroll: - The basic DHTMLX event structure is a JSON object with a unique event `id`, `start_date` and `end_date` (that defines the event period), an event title defined by `text` property, and optional custom properties like `room_id` to link to resources - this defines how events are internally represented and loaded in the scheduler. - In contrast, Mobiscroll uses the [`data`](https://demo.mobiscroll.com/timeline/event-data-structure#) option in which `start` and `end` define the event period, the `title` property represents the event’s title, and an event `id` property is also available. Additionally, you can use the `resource` property to specify which resource the event should be assigned to. ### Event structure comparison #### DHTMLX Scheduler: ```js scheduler.parse([ { id: 1, text: 'Conference', start_date: '2012-09-17 12:00', end_date: '2012-09-28 21:00', room_id: 1, // Custom property to associate event with a resource (e.g., room) }, ]); ``` #### Mobiscroll: ```ts myEvents: MbscCalendarEvent[] = [ { id: 1, resource: 'r1', start: '2012-09-17T12:00', end: '2012-09-18T21:00', title: 'Conference' } ]; ``` ### Converting DHTMLX Scheduler events to Mobiscroll Format Here’s a simple example of how to convert DHTMLX-style events into the format used by Mobiscroll: ```ts this.mobiscrollEvents = this.dhtmlxEvents.map(event => { const start = new Date(event.start_date); const end = new Date(event.end_date); return { id: event.id, title: event.text, start, end, resource: event.room_id // based on `property` option }; }); ``` Every project may have its own unique data format and requirements, so this script serves only as a basic starting point. You’ll likely need to adapt your transformation logic to fit your application’s specific needs. ### Loading and saving data When selecting a scheduling or calendar UI component, one of the most important factors to evaluate is how the component loads and saves data. The chosen approach can significantly influence performance, scalability, and integration complexity. We will examine how each framework handles: - Loading data from local or remote sources. - Saving or synchronizing changes to a backend system. ### Loading data DHTMLX: In DHTMLX Scheduler, loading data works by calling `scheduler.parse()` or `scheduler.load()` after initialization: - `scheduler.load(url, format)` - fetches events from a server (JSON, XML, or iCal). - `scheduler.parse(data, format)` - loads events directly from a angular object. Once loaded, Scheduler automatically renders the events into the current view. Mobiscroll: - Mobiscroll components accept static arrays, which can be [inline](/angular/eventcalendar/data-binding#local-data) (preloaded in memory) or [dynamically fetched](/angular/eventcalendar/data-binding#remote-data) from remote APIs. - The [`onPageLoading`](/angular/eventcalendar/api#event-onPageLoading) event plays a central role in incremental data loading, enabling applications to [request only the events needed](https://demo.mobiscroll.com/timeline/load-events-on-demand) for the current view (e.g., the current month or week) as the user navigates. - Mobiscroll also offers [integration with external calendar services](/angular/eventcalendar/calendar-integrations/) ([Google Calendar](https://demo.mobiscroll.com/eventcalendar/sync-events-google-calendar#), [Outlook](https://demo.mobiscroll.com/eventcalendar/sync-events-outlook-calendar#)) via plugins, handling data retrieval and format conversion internally. Let’s see an example for each case: ### Local data #### DHTMLX Scheduler: ```js scheduler.init('scheduler_here'); scheduler.parse([ { id: 1, text: 'Conference', start_date: '2012-09-17 12:00', end_date: '2012-09-28 21:00', room_id: 1, // Custom property to associate event with a resource (e.g., room) }, ]); ``` #### Mobiscroll: Pass the event array to the [`data`](/angular/eventcalendar/api#opt-data) option. ```html ``` ### Remote data #### DHTMLX Scheduler In case of DHTMLX, `scheduler.init` initializes the scheduler in the specified HTML element, then `scheduler.load` fetches event data as a JSON array from a remote URL for display in the scheduler. ```js scheduler.init('scheduler_here', new Date(), 'day'); // enable dynamic loading BEFORE load() scheduler.setLoadMode('day'); // "day" | "week" | "month" | "year" // initial fetch for current range scheduler.load('/api/events'); ``` #### Mobiscroll You can load the data through an external request and assign it to the data-bound variable to update the eventcalendar with the newly received data. In case of Mobiscroll, you can also use the [`onPageLoading`](/angular/eventcalendar/api#event-onPageLoading) pevent to load the data (on demand) relevant to the currently active view. The event fires every time the date range of the view changes, for example, when someone navigates the event calendar. Getting the events in real time as the user interacts with the UI improves load performance and always serves the most recent data. **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: 'day' } }; myData: MbscCalendarEvent[] = []; handlePageLoading(args: MbscPageLoadingEvent) { const year = args.month.getFullYear(); const month = args.month.getMonth(); const day = args.month.getDate(); getJson( 'https://example.remotedata.com/weeklyevents/?year=' + year + '&month=' + month + '&day=' + day, (events) => { this.myData = events; }, "jsonp" ); } } ``` In case of the timeline view, data can also be [loaded dynamically during scrolling](/angular/eventcalendar/timeline#load-data-on-scroll). Scrolling vertically or horizontally triggers the [`onVirtualLoading`](/angular/eventcalendar/api#event-onVirtualLoading) lifecycle event, which can be used to [load data incrementally during scrolling](https://demo.mobiscroll.com/timeline/load-resources-on-scroll). ### Saving data #### DHTMLX In DHTMLX Scheduler, saving data works by attaching a `dataProcessor` to the scheduler that handles CRUD operations by sending changes (adds, updates, deletes) to a server-side script which updates the database accordingly. Example: ```js scheduler.init('scheduler_here'); scheduler.load('/api/events'); const dp = scheduler.createDataProcessor({ url: '/api/events', mode: 'REST', }); ``` #### Mobiscroll - Persistence is managed by listening to Mobiscroll’s [CRUD lifecycle events](/angular/eventcalendar/crud). - The Event Calendar exposes a [variety of events](/angular/eventcalendar/api#events) that are triggered on certain actions made on calendar events. These events can be used to send your data to your API or save it to persistent storage. Example for saving, updating, and deleting an event through an API: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}) export class MyComponent { myView: MbscEventcalendarView = { schedule: { type: "week" }, }; myEvents: MbscCalendarEvent[] = [ { id: 'id1' start: '2023-09-24', end: '2023-09-30', title: 'Short trip!'}, ]; saveEvent(args: MbscEventCreatedEvent) { fetch('add.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); }, updateEvent(args: MbscEventUpdatedEvent) { fetch('update.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); }, deleteEvent(args: MbscEventDeletedEvent) { fetch('delete.php', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args.event) }); } }); ``` Mobiscroll offers a flexible, event-driven approach suitable for both lightweight client-side setups and API-driven applications. Developers are responsible for implementing their own persistence logic, allowing for high adaptability but requiring more manual integration effort. Both libraries are capable of handling modern scheduling needs, but the choice depends largely on application scale, data complexity, and desired control over the persistence layer. ## Lifecycle events Both libraries, DHTMLX and Mobiscroll, provide a comprehensive set of lifecycle event hooks, enabling deep customization and integration with your application logic. These events are emitted at various stages of a component’s lifecycle, offering developers full control to inject custom behavior and extend default functionality. Whether you’re looking to manipulate data before rendering, respond to user interactions, or perform cleanup tasks, Mobiscroll’s event system offers the flexibility to tailor components to your specific needs. When migrating between DHTMLX and Mobiscroll, it’s important to note that most lifecycle events follow similar patterns across both libraries. This alignment minimizes friction during the transition process and helps preserve custom behaviors with minimal adjustments. One such example is how each library handles a double-click on a cell. Below is a comparison of the respective event handlers and their parameters. ### DHTMLX In DHTMLX Scheduler, lifecycle events such as creating, updating, or deleting an event are handled through the `scheduler.attachEvent()` method. This API allows you to subscribe to internal scheduler callbacks — for example: `onEventAdded`, `onEventChanged`, or `onEventDeleted` — and execute custom logic when these actions occur. For example the `onXScaleDblClick` event is triggered when the user makes a double click on a cell on the x-axis (the Timeline view only). This event provides access to several key objects that describe the interaction and `contextDblClick`: - `index`: number - the column index of the clicked cell (zero-based numbering) - `value`: object - Date object of the start time stamp of the clicked cell - `e`: event - native event object Example: ```js scheduler.attachEvent('onCellDblClick', function (x_ind, y_ind, x_val, y_val, e) { console.log('Cell double-clicked:', x_ind, y_ind, x_val, y_val, e); // Example: open a new event creation dialog // showCreateEventDialog(x_val, y_val); }); ``` ### Mobiscroll Mobiscroll components (e.g., Event Calendar, Scheduler, Timeline) expose a similar [`onCellDoubleClick`](/angular/eventcalendar/api#event-onCellDoubleClick) event, which is fired when a cell is double-clicked. It includes contextual information that allows for granular control over the interaction: - `args` - The event argument with the following properties: - `date`: Date - The date of the clicked cell. - `domEvent`: Event - The DOM event of the click. - `events`: Array - The events for the clicked date. - `resource`: string | number - The id of the resource where the cell was clicked, if resources are set. - `selected`: boolean - Specifies if the day is currently selected or not (before it was clicked). - `source`: 'calendar' | 'schedule' | 'timeline' - The view where the cell was clicked. - `target`: HTMLElement - The DOM element of the clicked cell. - `inst` - The component instance. Example: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ...other options... handleCellDblClick(args: MbscEventClickEvent) { console.log('Cell double-clicked:', args.date, args); // Example: open a new event creation dialog // showCreateEventDialog(args.date, args.resource); } } ``` To explore the full list of available Mobiscroll lifecycle events and understand how they can be leveraged, please refer to the [documentation](/angular/eventcalendar/api#events). Additionally, you can see these events in action through live, interactive examples for the following Mobiscroll components: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/event-hooks) - [Scheduler](https://demo.mobiscroll.com/scheduler/event-hooks) - [Timeline](https://demo.mobiscroll.com/timeline/event-hooks) - [Agenda](https://demo.mobiscroll.com/agenda/event-hooks) These examples provide hands-on insights into how lifecycle events work in practice. ## Feature migration As a final step, let’s explore how core features from DHTMLX can be replicated using Mobiscroll. While some capabilities are available out of the box in DHTMLX, Mobiscroll often requires more explicit setup but offers much more flexibility. ### Drag & Drop functionality - DHTMLX Scheduler enables drag-and-drop operations by default with no extra configuration needed. - In Mobiscroll, the [D&D features](https://demo.mobiscroll.com/timeline/move-resize-drag-drop-to-create-events#) must be enabled explicitly via [configuration options](/angular/eventcalendar/drag-and-drop). #### Enabling Drag & Drop in Mobiscroll: ```html ``` This configuration allows users to create, move, resize, and delete events in Mobiscroll. ### Switching Views (Calendar/Scheduler/Agenda) - DHTMLX Scheduler enables switching views by default with no extra configuration needed. - Mobiscroll doesn’t include a built-in view-switching UI by default. However, it offers greater flexibility by allowing you to implement a custom header where you can design the view-switching experience to fit your needs. For example, you can use a [dropdown menu](https://demo.mobiscroll.com/select) or [segmented controls](https://demo.mobiscroll.com/forms/segmented) to let users switch between views like Calendar, Scheduler, Agenda, or any other layout that fits your use case. #### DHTMLX Scheduler: ```js scheduler.init('scheduler_here', new Date(2020,8,12), "week"); ``` #### Mobiscroll: In Mobiscroll, switching between views like Day, Week, or Month requires setting up a custom header along with event listeners to handle the view changes. You can see an example of this implementation [here](https://demo.mobiscroll.com/scheduler/switching-calendar-scheduler-agenda). **app.component.html** ```html
Month Week Day Agenda
``` **app.component.ts** ```ts setOptions({ theme: 'ios', themeVariant: 'light' }); @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [CommonModule, FormsModule, MbscModule], }) export class AppComponent implements OnInit { constructor(private http: HttpClient) {} myEvents: MbscCalendarEvent[] = []; view = 'month'; calView: MbscEventcalendarView = { calendar: { labels: true }, }; ngOnInit(): void { this.http.jsonp('https://trial.mobiscroll.com/events/?vers=5', 'callback').subscribe((resp) => { this.myEvents = resp; }); } changeView(): void { setTimeout(() => { switch (this.view) { case 'year': this.calView = { calendar: { type: 'year' }, }; break; case 'month': this.calView = { calendar: { labels: true }, }; break; case 'week': this.calView = { schedule: { type: 'week' }, }; break; case 'day': this.calView = { schedule: { type: 'day' }, }; break; case 'agenda': this.calView = { calendar: { type: 'week' }, agenda: { type: 'week' }, }; break; } }); } } ``` ### Timezones Handling time zones accurately is crucial in calendar and scheduling applications, especially when working across regions or coordinating international events. Mobiscroll and DHTMLX take significantly different approaches. Mobiscroll is clearly superior in timezone management, while DHTMLX only operates with native JS Date objects, which limits its ability to handle complex timezone scenarios.  #### DHTMLX DHTMLX Scheduler only operates with native JS Date objects. #### Mobiscroll By default, Mobiscroll will not do any timezone conversion, will display the dates without modification, handling them as timezone-less. If your use case requires interpreting or displaying data in a different time zone, you can achieve this by using one of the supported third-party libraries for time zone conversion: - [Moment-Timezone](/angular/eventcalendar/timezones#the-moment-timezone-library) - [Luxon](/angular/eventcalendar/timezones#the-luxon-library) - [Day.js](/angular/eventcalendar/timezones#the-dayjs-library) Mobiscroll exposes two configuration options to handle time zones: - `dataTimezone` [option](/angular/eventcalendar/api#opt-dataTimezone) – the time zone in which your event data is stored (e.g., 'utc') - `displayTimezone` [option](/angular/eventcalendar/api#opt-displayTimezone) – the time zone in which you want the data to be presented (e.g., 'Europe/Stockholm') So, let’s say you want to use the Day.js timezone library. After [installing](/angular/eventcalendar/timezones#the-dayjs-library) it into your project, you can pass the `dayjsTimezone` object to the Timeline’s [`timezonePlugin`](/angular/eventcalendar/api#opt-timezonePlugin) option: **app.component.html** ```html ``` **app.component.ts** ```ts dayjs.extend(utc); dayjs.extend(timezone); dayjsTimezone.dayjs = dayjs; @Component({...}) export class MyComponent { myDayjsTimezone: MbscTimezonePlugin = dayjsTimezone; } ``` Also, feel free to explore live examples to see how time zones work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/setting-the-timezone#) - [Scheduler](https://demo.mobiscroll.com/scheduler/setting-the-timezone#) - [Timeline](https://demo.mobiscroll.com/timeline/setting-the-timezone#) - [Agenda](https://demo.mobiscroll.com/agenda/setting-the-timezone#) Or you can also check advanced demos such as: - [switching timezones (on the fly) from the header](https://demo.mobiscroll.com/eventcalendar/multiple-timezone-support) - [display time for multiple timezones](https://demo.mobiscroll.com/scheduler/show-multiple-timezones) - [create a meeting planner across multiple timezones](https://demo.mobiscroll.com/timeline/timezone-meeting-planner) You can also store the timezone inside the event data, using the [`timezone`](/angular/eventcalendar/api#opt-data) property. As a conclusion, Mobiscroll is clearly superior in timezone management, DHTMLX only operates with native JS Date objects. #### Conclusion DHTMLX Scheduler offers stronger server-side capabilities and export options, while Mobiscroll excels in multi-calendar systems and flexible component design: - Feel free to explore our demo page for [Timeline](https://demo.mobiscroll.com/timeline), [Scheduler](https://demo.mobiscroll.com/scheduler), [Event Calendar](https://demo.mobiscroll.com/eventcalendar), and [Agenda](https://demo.mobiscroll.com/agenda) views - featuring grouped examples, including [common use cases](https://demo.mobiscroll.com/timeline/employee-shifts), [view configuration](https://demo.mobiscroll.com/scheduler/custom-range-view), [event](https://demo.mobiscroll.com/timeline/timeline-custom-event-rendering) and [resource](https://demo.mobiscroll.com/scheduler/custom-resource-header-template) templating, and [lifecycle event handling](https://demo.mobiscroll.com/timeline/event-hooks). - We also offer comprehensive documentation for the [Timeline](/angular/eventcalendar/timeline), [Scheduler](/angular/eventcalendar/scheduler), [Event Calendar](/angular/eventcalendar/calendar), and [Agenda](/angular/eventcalendar/agenda) views. It covers [usage](/angular/eventcalendar/timezones), [APIs](/angular/eventcalendar/api), [customization options](/angular/eventcalendar/templating), and more in detail. In addition to drag & drop and custom view-switching, Mobiscroll also supports [timezone handling](https://demo.mobiscroll.com/scheduler/setting-the-timezone) and [zooming levels](https://demo.mobiscroll.com/timeline/calendar-zoom). All of our views work seamlessly across both [mobile](https://demo.mobiscroll.com/scheduler/mobile-day-view) and [desktop](https://demo.mobiscroll.com/scheduler/desktop-day-view) environments, with full support for touch interactions. As mentioned above, with some additional setup, most —if not all— features can be effectively replicated when migrating from DHTMLX to Mobiscroll. If you have any specific questions or run into any issues, don’t hesitate to [reach out](https://mobiscroll.com#get-help) — we’re happy to help. ## Templating and renderers ### Event templating #### DHTMLX In DHTMLX Scheduler, you can customize the content of events and define which data should be displayed by using templates. Each view relies on its own set of templates, so to determine which templates a particular view uses, refer to the article [Formatting Labels, Dates, Styles](https://docs.dhtmlx.com/scheduler/templates.html) article. Most views use the following two templates for customizing event text: - [`event_header`](https://docs.dhtmlx.com/scheduler/api__scheduler_event_header_template.html) - defines the text shown in the event header - [`event_text`](https://docs.dhtmlx.com/scheduler/api__scheduler_event_text_template.html) - defines the main text displayed inside the event DHTMLX also recommends redefining templates inside the `onTemplatesReady` event handler. Doing so ensures that your custom templates are not overwritten by the default ones. Below is an example of how to display the event location together with the event text in the event box: ```js scheduler.attachEvent('onTemplatesReady', function () { scheduler.templates.event_text = function (start, end, event) { return `
${event.text}
Location: ${event.location}
`; }; }); scheduler.init('scheduler_here', new Date(2019, 5, 5), 'week'); scheduler.parse([ { id: 1, text: 'Custom Meeting', start_date: '2019-06-05 09:00', end_date: '2019-06-05 11:00', location: 'Room 1', }, ]); ``` #### Mobiscroll You can customize many parts of the Event Calendar by writing custom templates. In the context of plain angular these templates are functions that return a string containing the html markup. You will find a comprehensive list of all the available render functions for the Event Calendar in the [API templates](/angular/eventcalendar/api#renderers) section. When you want to customize how the events look, depending on what your goal is, you have two options: - [Customize the event content](/angular/eventcalendar/templating#event-content-templating) - Mobiscroll takes care of rendering the events in the correct order and also prints basic fields, like `start`/`end`, whether it is an `allDay` event or not and also takes care of coloring the event appropriately. Everything else comes from the custom template. - [Customize the full event](/angular/eventcalendar/templating#full-event-templating) - Mobiscroll takes care of rendering the events in the correct order, but everything else comes form the template you write. To define a template, create an `` tag with a variable reference and pass it to the apropriate eventcalendar option: **app.component.html** ```html
{{eventRecord.name}}
Duration: {{eventRecord.duration}}h
 ``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... myEvents: MbscCalendarEvent[] = [ { id: 10, resourceId: 'r1', name: 'Custom Meeting', startDate: '2017-01-01 09:00', endDate: '2017-01-01 11:00', duration: 2 }, ]; } ``` Feel free to explore live examples to see how event content templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customize-label-look-and-feel#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-events#) - [Timeline](https://demo.mobiscroll.com/timeline/meal-planner#) - [Agenda](https://demo.mobiscroll.com/agenda/event-content-customization#) Feel free to explore live examples to see how full event templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customize-event-popover#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-events#) - [Timeline](https://demo.mobiscroll.com/timeline/timeline-custom-event-rendering#) - [Agenda](https://demo.mobiscroll.com/angular/agenda/customizing-calendar-header) ### Resource templating #### DHTMLX In case of DHTMLX Scheduler - Timeline view the resources can be customized through the columns property of the timeline configuration object: ```js scheduler.plugins({ timeline: true, }); scheduler.createTimelineView({ name: 'timeline', y_unit: [ { key: 1, label: 'Adam', city: 'Washington' }, { key: 2, label: 'Eva', city: 'New York' }, ], columns: [ { label: 'Name', width: 130, template: function (obj) { return '' + obj.label + ''; }, }, { label: 'City', width: 90, template: function (obj) { return '' + obj.city + ''; }, }, ], }); scheduler.init('scheduler_here'); ``` #### Mobiscroll In the case of Mobiscroll, we take a different approach. We provide various templating options (listed below), which allow you to customize the resources. #### Scheduler Use the [`resourceTemplate`](/angular/eventcalendar/scheduler#template-resourceTemplate) option to customize the resource template of the Scheduler. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](/angular/eventcalendar/scheduler#opt-resources) array. It takes a function that should return the desired markup. Check out how you can style the resources in [this example](https://demo.mobiscroll.com/scheduler/custom-resource-header-template#). #### Timeline In case of the Timeline view there are three places where you can customize the resource column: - Use the [`resourceTemplate`](/angular/eventcalendar/timeline#template-resourceTemplate) option to customize the resource template of the Timeline. Customize how the resource headers look and what they show. Utilize properties passed in the [resources](/angular/eventcalendar/timeline#opt-resources) array. - Customize the empty cell content above the resource column with the [`resourceHeaderTemplate`](/angular/eventcalendar/timeline#template-resourceHeaderTemplate) option. - Or if you want to customize the empty cell content below the resource column you can achieve this with the [`resourceFooterTemplate`](/angular/eventcalendar/timeline#template-resourceFooterTemplate) option. This element only renders for the Timeline view, if the [`dayFooterTemplate`](/angular/eventcalendar/timeline#template-dayFooterTemplate) option is present. Check out how you can style these resource parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#). **app.component.html** ```html
Name
City
{{record.name}}
{{record.city}}
``` **app.component.ts** ```ts @Component({...}); export class AppComponent { // ... myResources: MbscResource[] = [ { id: 1, name: 'Adam', city: 'Washington' }, { id: 2, name: 'Eva', city: 'New York' }, ]; } ``` ### Header templating #### DHTMLX In DHTMLX Scheduler, the header (the top navigation area containing the date, navigation buttons, and view tabs) is generated from a combination of HTML markup and Scheduler’s template system. The header area corresponds to this block in your code: ```js
 
 
``` Scheduler fills these elements using built-in templates, which you can override to control what appears in the header. #### Mobiscroll The header of the Mobiscroll calendar can be fully customized to one's needs with the use of the [`headerTemplate`](/angular/eventcalendar/timeline#template-headerTemplate) option. Here's the list of the built in components of the default header. You can initialize these by putting the attributes on the elements: - `mbsc-calendar-prev` - Previous button component, that navigates to the previous month. - `mbsc-calendar-next` - Next button component, that navigates to the next month. - `mbsc-calendar-today` - Today button component, that navigates to the current date. - `mbsc-calendar-nav` - The title navigation button component, that opens the year/month navigation. The following example will render the prev and next buttons and a custom title. ```html
{{myTitle}}
 ``` Also, feel free to explore live examples to see how header templating work in action: - [Event Calendar](https://demo.mobiscroll.com/eventcalendar/customizing-header#) - [Scheduler](https://demo.mobiscroll.com/scheduler/customizing-header#) - [Timeline](https://demo.mobiscroll.com/timeline/switching-day-week-work-week-timeline) - [Agenda](https://demo.mobiscroll.com/agenda/customizing-calendar-header) ### Other templating/ renderer options #### Event Calendar - Date header templating - There are two approaches you can take: - Customize the date headers of the Event Calendar with the [`dayTemplate`](/angular/eventcalendar/calendar#template-dayTemplate) option by adding relevant content, labels or completely change how they look. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [`dayContentTemplate`](/angular/eventcalendar/calendar#template-dayContentTemplate) option. #### Scheduler - [Date header templating](/angular/eventcalendar/scheduler#the-date-header) - There are two approaches you can take: - Customize the date headers of the Scheduler with the [`dayTemplate`](/angular/eventcalendar/scheduler#template-dayTemplate) option by adding relevant content, labels or completely change how they look. - If you are looking to customize only the content and don't want to bother with the styling of the event, you can use the [`dayContentTemplate`](/angular/eventcalendar/scheduler#template-dayContentTemplate) option. Check out how you can style the date header in [this example](https://demo.mobiscroll.com/scheduler/date-header-template#). #### Timeline - [Templating the sidebar header and footer](/angular/eventcalendar/timeline#the-sidebar-their-header-and-footer) - Besides the resource template, an additional sidebar can be rendered on the opposite end of the row and there are three approaches you can take: - Use the [`sidebarTemplate`](/angular/eventcalendar/timeline#template-sidebarTemplate) option to render a custom sidebar on the right side of the Timeline. - Customize the empty cell content above the sidebar column with the [`sidebarHeaderTemplate`](/angular/eventcalendar/timeline#template-sidebarHeaderTemplate) option. - Or if you want to customize the empty cell content below the sidebar column you can achieve this with the [`sidebarFooterTemplate`](/angular/eventcalendar/timeline#template-sidebarFooterTemplate) option. Check out how you can style the sidebar parts in [this example](https://demo.mobiscroll.com/timeline/timeline-resource-details-side-panel-footer#). - [Date header and footer templating](/angular/eventcalendar/timeline#the-date-header-and-footer) - The headers hold key information like the date, day of the week and in some cases it also holds the full date. Whenever you need to show extra information, or if you would like to change the styling or date format, time format you can use the various header templates, depending on the view configuration. You can also show a footer element, for displaying more information. Check out how you can style the date header and footer in [this example](https://demo.mobiscroll.com/timeline/hour-day-week-month-quarter-year-header-footer-template#). - [Slots](/angular/eventcalendar/timeline#the-event-slots) - Use the [`slotTemplate`](/angular/eventcalendar/timeline#template-slotTemplate) option to customize the slot template of the Timeline view. Check out how you can style the slots in [this example](https://demo.mobiscroll.com/timeline/shift-template#). - [Variable event height](/angular/eventcalendar/timeline#variable-event-height) - When using [event templating](/angular/eventcalendar/templating#event-templating), you might end up with various event heights, depending on the displayed content, e.g. larger description, list of tasks, etc. You can enable support for variable event heights by setting the `eventHeight: 'variable'` property for the timeline inside the [`view`](/angular/eventcalendar/timeline#view-timeline-eventHeight) option. Check out how you can set and style the variable event height in [this example](https://demo.mobiscroll.com/timeline/variable-event-height). #### Agenda - [Day header templating](/angular/eventcalendar/agenda#the-agenda-day-header) - Customize the day headers that appear on the agenda with the [`dayTemplate`](/angular/eventcalendar/agenda#template-dayTemplate) option. Check out how you can style the day headers in [this example](https://demo.mobiscroll.com/agenda/customizing-day-header#). - [Empty state templating](/angular/eventcalendar/agenda#the-agenda-empty-state) - Customize the look of the empty state through [`agendaEmptyTemplate`](/angular/eventcalendar/agenda#template-agendaEmptyTemplate) function. Check out how you can style the empty state in [this example](https://demo.mobiscroll.com/agenda/empty-state#). ## Localization ### DHTMLX DHTMLX Scheduler supports scheduler's localization by providing a number of predefined locales and means of creating custom ones. By default, DHTMLX Scheduler uses [English locale](https://docs.dhtmlx.com/scheduler/api__scheduler_locale_other.html). To set the desired language for the scheduler, you need to activate the necessary locale via the `setLocale` method of the [`scheduler.i18n`](https://docs.dhtmlx.com/scheduler/api__scheduler_i18n_other.html) object. ```js scheduler.i18n.setLocale("fr"); ``` You can use and update any of the [predefined locales](https://docs.dhtmlx.com/scheduler/localization.html#includedlocales) that are bundled with the `dhtmlxscheduler.js` file or define a custom locale. The locale can be switched dynamically but the changes will be applied only after a complete redrawing of the Scheduler either with the `scheduler.render()` or `scheduler.init()` call. ```js scheduler.i18n.setLocale("fr"); scheduler.init("scheduler_here"); ``` ### Mobiscroll Mobiscroll [enables localization](/angular/core-concepts/localization) by letting developers set language, date, and time formats both globally (across the entire application) and locally (on individual components). Highlights: - Global settings object lets developers set locale, theme, and format across the app (first example). - Each component (e.g., Date Picker, Event Calendar) supports locale switching and custom translations with simple configuration (second example). - RTL and calendar system support (Gregorian, Jalali, Hijri) - Quick override ability for localized formats ensures that adaptations can be made case-by-case or via global settings. Example setting the locale option globally: ```ts setOptions({ // ...other config... locale: localeFr // French locale applied globally }); ``` Example setting the locale at the component level: **app.component.html** ```html ``` **app.component.ts** ```ts @Component({ selector: 'app-root', templateUrl: './app.component.html', standalone: true, imports: [MbscModule] }) export class AppComponent { myLocale = localeFr; // French locale applied globally } ``` ## Conclusion Migrating from DHTMLX Scheduler to Mobiscroll involves rethinking certain configurations, especially around views, events, and feature toggles. While DHTMLX Scheduler offers strong server-side capabilities and comprehensive export options, Mobiscroll stands out as a modern, developer-friendly, and highly adaptable calendar and scheduling solution. Its superior framework support, refined UX, accessibility readiness, and deep customization make it the better long-term choice for teams building maintainable and scalable scheduling experiences. The overall migration process includes: - Adjusting initialization patterns - Adapting view configurations - Mapping resources and events to Mobiscroll’s structure - Enabling features like drag-and-drop manually With a clear understanding of both libraries’ capabilities and structures, you can migrate efficiently and take full advantage of Mobiscroll’s modern UI and feature-rich environment. #### Considering migrating from DHTMLX Scheduler to Mobiscroll? [Schedule a call](https://calendly.com/mobiscroll/30min) and let's chat about how we can help. We're here to support you in the migration process. --- ## Unit testing Mobiscroll in Angular ## Overview Unit testing is an essential part of Test Driven Development. Usually the "units" are the smallest testable parts of an application. In the context of the Mobiscroll library however, we consider these units the Mobiscroll Components, because these cannot be broken up further by our users. The purpose of this guide is to give examples of how the Mobiscroll Components can be tested autonomously in Angular apps, to achieve high confidence that they work as intended. We are using the [@testing-library/angular](https://testing-library.com/docs/angular-testing-library/intro/) because it helps test UI components in a user-centric way. ## Setup In the following examples, we are using [Analog + Vitest](https://analogjs.org/docs/features/testing/vitest) as the testing environment. This provides a modern Angular setup with built-in Vitest support. :::info To use the examples below, make sure you have the Angular Testing Library installed. For installation instructions, see the official [@testing-library/angular](https://testing-library.com/docs/angular-testing-library/intro/) docs. If you're setting up a new project with **Analog + Vitest**, follow the [Analog testing guide](https://analogjs.org/docs/features/testing/vitest) to get started. ::: ### Why Vitest + Testing Library? By default, Angular projects use Jasmine with Karma as the testing framework and runner. While this works, many teams prefer using **Vitest** together with **Testing Library** because it offers several advantages: - **Faster feedback loop** – Vitest is built on Vite, which provides lightning-fast test runs and near-instant watch mode compared to Karma. - **Modern developer experience** – Vitest supports TypeScript, ESM, and modern tooling out of the box, reducing configuration overhead. - **Improved DX in the editor** – Vitest integrates seamlessly with IDEs, giving instant inline results and better debugging. - **Closer to user behavior** – Testing Library encourages writing tests that interact with components the way users do (via queries like `getByRole` or `getByText`), making tests more reliable and less coupled to implementation details. - **Lightweight & simpler setup** – No browser-based test runner (like Karma) is required, reducing complexity. - **Rich ecosystem** – Shared ecosystem with tools like Playwright, Vite, and modern CI/CD pipelines. ### Requirements The only requirement for the Mobiscroll Components to be testable is to install the [vitest-canvas-mock](https://www.npmjs.com/package/vitest-canvas-mock) package. The following command should install it: ```bash npm install vitest-canvas-mock --save-dev ``` After the package is installed, it has to be imported in the setup file (e.g. `src/setup.ts`): ```ts title="src/setup.ts" BrowserTestingModule, platformBrowserTesting, } from "@angular/platform-browser/testing"; getTestBed().initTestEnvironment( BrowserTestingModule, platformBrowserTesting(), ); ``` After the import above, the components can be tested without errors using: ```bash npm test ``` ## Targeting elements ### Smoke tests Smoke tests or sanity tests are used to determine if the code compiles and the component runs, without doing any further fine-grained tests. A simple test like this would consist of rendering the Eventcalendar and then querying the DOM if the elements are there. Querying a particular DOM element with the @testing-library is not encouraged, because it is considered an implementation detail. For example, the Eventcalendar renders a div element with the css class `.mbsc-eventcalendar`. This is indeed an implementation detail, and this class could be changed later in the code which would make our test useless. But for a simple smoke test in the case of the Eventcalendar it is the easiest way to assert that the component actually works. #### Eventcalendar ```ts title="eventcalendar.spec.ts" describe("Mobiscroll Eventcalendar", () => { it("renders an empty calendar", async () => { const { container } = await render( "", { imports: [MbscEventcalendarModule], }, ); expect(container.querySelector(".mbsc-eventcalendar")).toBeInTheDocument(); }); }); ``` #### Datepicker The Datepicker renders an input element with a label, which makes it possible to test using accessible queries. ```ts title="datepicker.spec.ts" describe("Mobiscroll Datepicker", () => { it("renders the Datepicker", async () => { await render('', { imports: [MbscDatepickerModule], }); const label = screen.getByLabelText("My Date picker"); expect(label).toBeInTheDocument(); }); }); ``` ## Targeting event elements Here is an example of how to test if an event is rendered on the Eventcalendar timeline view for today. ```ts title="eventcalendar-event.spec.ts" describe("Mobiscroll Eventcalendar with events", () => { it("renders an event for today", async () => { const viewOption = { timeline: { type: "day" } }; const today = new Date(2023, 0, 31); const eventData = [ { start: new Date(2023, 0, 31, 10), end: new Date(2023, 0, 31, 11, 30), text: "My Today Event", }, ]; await render( '', { imports: [MbscEventcalendarModule], componentProperties: { view: viewOption, date: today, data: eventData, }, }, ); const eventElement = screen.getByText(/^My Today Event$/i); expect(eventElement).toBeInTheDocument(); }); }); ``` A few notes worth mentioning here: 1. The Eventcalendar uses in some cases defaults that are calculated at run time. For example the selected date that defaults to today. These defaults can easily fail the test if not provided explicitly. 2. In the `getByText()` function we used a regular expression that queries elements with the exact same content. The eventcalendar might render elements that contain the event title and other information for screen readers. The test need to be specific for the event text, otherwise it might fail due to multiple elements with the same content. #### Targeting elements that are not in the DOM The following is a more complex example, where the event passed to the Eventcalendar is not rendered due to the Eventcalendar's virtual scrolling feature. The event is only expected to be in the DOM when the selected date is close to the event date. How close it should be is an implementation detail of the component and cannot be configured externally. In the example below we use two different selected dates to illustrate this behavior. First, the Eventcalendar is rendered with the selected date set to January 17th, 2023, while the event itself is on January 19th. In this case, due to virtual scrolling, the event is not yet present in the DOM. After re-rendering the component with the selected date updated to January 19th, the event becomes visible and can be queried. ```ts title="Eventcalendar navigation and rendering event" describe("Eventcalendar with navigation", () => { const viewOption = { timeline: { type: "day" } }; const eventData = [ { start: new Date(2023, 0, 19, 10), end: new Date(2023, 0, 19, 11, 30), text: "My Dayaftertomorrow Event", }, ]; const dayAfterTomorrow = new Date(2023, 0, 19); const today = new Date(2023, 0, 17); it("renders an event for the day after tomorrow only when navigated there", async () => { const { rerender } = await render( ` `, { imports: [MbscEventcalendarModule], componentProperties: { view: viewOption, selectedDate: today, data: eventData, }, }, ); // event not in DOM yet expect( screen.queryByText(/^My Dayaftertomorrow Event$/i), ).not.toBeInTheDocument(); // re-render with dayAfterTomorrow as selected date await rerender({ componentProperties: { view: viewOption, selectedDate: dayAfterTomorrow, data: eventData, }, }); // now the event should appear expect( screen.queryByText(/^My Dayaftertomorrow Event$/i), ).toBeInTheDocument(); }); }); ``` In this example, the Eventcalendar’s selected date is initially set to the 17th, which is in the same week as the 19th. However, because of virtual scrolling, the events on the 19th are not included in the DOM yet. After updating the selected date to the 19th, the event is rendered and can be queried successfully. :::info When querying an element that is not expected to be in the DOM, always use the `queryBy`... methods instead of the `getBy`... methods, otherwise the test will fail immediately. ::: Re-rendering a component with different props can be done using the returned `rerender` function from the initial render. ## Firing events The `@testing-library/angular` provides functions to simulate events. In the following example we use a click event to open a Datepicker and check whether the picker elements are in the DOM. ```ts title="datepicker-open.spec.ts" describe("Mobiscroll Datepicker interactions", () => { it("opens the Datepicker when clicking the label", async () => { const { container } = await render( '', { imports: [MbscDatepickerModule], }, ); const label = screen.getByLabelText("Date picker"); fireEvent.click(label); waitFor(() => { const datepickerDiv = container.querySelector(".mbsc-datepicker"); expect(datepickerDiv).toBeInTheDocument(); }); }); }); ``` ### Events fired by the Mobiscroll components The Mobiscroll components have lifecycle events that are fired during various phases. For example, the Datepicker fires an `onOpen` event when opened. ```ts title="datepicker-onopen.spec.ts" describe("Mobiscroll Datepicker events", () => { it("fires onOpen when the Datepicker is opened", async () => { const openHandler = vi.fn(); // create a mock function with jest await render( '', { imports: [MbscDatepickerModule], componentProperties: { onOpen: openHandler }, }, ); expect(openHandler).not.toHaveBeenCalled(); // not called before open const label = screen.getByLabelText("Date picker"); fireEvent.click(label); expect(openHandler).toHaveBeenCalled(); // called after open }); }); ``` :::info Here we are using Vitest’s `vi.fn()` to create a mock function and assert that it was called after the Datepicker was opened. ::: --- ## Updating to the latest Mobiscroll In this guide you will learn how to update an already installed package in your project to the latest version. If you are looking for how to install Mobiscroll for the first time, you can check the [getting started guide](../getting-started/installation), if you want to upgrade from trial to a licensed version you can check out our [upgrade guide](./upgrade-from-trial). :::caution In order to have access to the latest version, you will need an [active maintenance](http://help.mobiscroll.com/en/articles/666557-maintenance-explained). ::: There are multiple options on how to update to the latest version, depending on how you installed Mobiscroll in your project in the first place and what kind of license you have: 1. [Updating from our NPM repository](#npm-update) 2. [Updating with the Mobiscroll CLI](#cli-update) 3. [Updating with the Mobiscroll CLI using a downloaded package](#download-update) ## Updating from our NPM repository ### Prerequisites * Mobiscroll was set up with the Mobiscroll CLI before * You own one of the following [types of licenses](https://mobiscroll.com/pricing): - Date & Time picking - Scheduling & Calendaring - Complete - Enterprise (SaaS) * You have an [active maintenance](http://help.mobiscroll.com/en/articles/666557-maintenance-explained) ### Update Steps Running the following command in your project root folder will update your package to the latest: ```bash npm update @mobiscroll/angular ``` ## Updating with the CLI ### Prerequisites * Mobiscroll was set up with the Mobiscroll CLI before * You have the Mobiscroll CLI installed globally * You own one of the following [types of licenses](https://mobiscroll.com/pricing): - Date & Time picking - Scheduling & Calendaring - Complete - Enterprise (SaaS) * You have an [active maintenance](http://help.mobiscroll.com/en/articles/666557-maintenance-explained) ### Update Steps Running the following command in your project root folder will update your package to the latest: ```bash mobiscroll config angular ``` ## Updating from a downloaded package This option can be used if you are using a downloaded package in your project. ### Prerequisites * Mobiscroll was set up with the Mobiscroll CLI before * You have access to the [Download page](https://download.mobiscroll.com) with a licensed account ### Update Steps #### 1. Download a new package The first step is to download a new package from the [download page](https://download.mobiscroll.com). There is a version dropdown at the top right corner of the screen. You can check there that you selected the latest version. After selecting the components, themes, languages and icon packs you need, hit the download button and wait for the package to download. :::caution Make sure you select all the components and themes you used in your project, otherwise they will not work after the update. ::: :::tip You can save / bookmark the download page URL to keep track the download configuration you used. ::: #### 2. Copy the resources to your project Unzip the downloaded package into a temporary folder. After that, create a folder with the following path `src/lib/mobiscroll` from your projects root directory. Copy the `src`, `js`, `css`, `esm5` folders from the temp folder to your project's `src/lib/mobiscroll` folder you created. #### 3. Run the config command Running the following command will update the package in your project: ```bash mobiscroll config angular --no-npm ``` --- ## How to upgrade from the trial version ## Requirements ### Acquiring a license When upgrading from a trial license to a commercial, the first step is to purchase the commercial license. This can be done from our [pricing page](https://mobiscroll.com/pricing) among other areas of our website. If you are still looking for which license to choose or if you have any questions, [let us know](mailto:support@mobiscroll.com)! We are here to help! ### Assigning the license to the developer After the purhcase of the commercial license, it should be assigned to the developer, who will do the development. This can be done immediately after the purchase, or later from the [licenses page](https://mobiscroll.com/account/licenses). When the buyer and the developer is the same person, the license can be self-assigned as well. ## Upgrading the library in your project There are two options how to upgrade, depending on how did you install the trial in your project and what type of license did you purchase. 1. [Upgrade to the full package](#upgrade-to-full) 2. [Upgrade to a custom package](#upgrade-to-custom) ### Upgrading to the full package This method will include a Mobiscroll package into your project from NPM. In order for this to work, you will need a license from the following types of licenses with an [active maintenance](http://help.mobiscroll.com/en/articles/666557-maintenance-explained): * Date & Time picking * Scheduling & Calendaring * Complete * Enterprise (SaaS) :::info The package installed will contain all the components of the framework, except for the Date & Time license. In that case only the associated components will be included in the package. Check out the [pricing page](https://mobiscroll.com/pricing) for more details on which components are included in the Date & Time picking license. ::: To upgrade the trial package in your project, the commercial license needs to be assigned to your account. If you are the developer, but somebody else purchased the license, then the buyer can assign the license to your account. You should instruct the buyer to log in to his account and proceed to the [licenses page](https://mobiscroll.com/account/licenses). From there, he can assign the license to you account. After the license is assigned to your account, run the following commands in your project root directory to upgrade the package: **1. Log in to your account** If you are using the same account for the commercial license that you were using with the trial, then you can skip this step. ```bash mobiscroll login ``` When you are asked, please provide your credentials. If you haven't set a password yet, you can set one from your [account page](https://mobiscroll.com/account). **2. Configure the project** ```bash mobiscroll config angular ``` At this point the trial package should be replaced with the commercial package, and building and running your project should work. ### Upgrading to a Component license With this method, you will download a package from our website, then you will use the Mobiscroll CLI to install that package to your project. If you don't have access to the Full Framework, or if you want to customize your package to only contain specific components, this is the way to go. **1. Download your package** Access the [download page](https://download.mobiscroll.com), by logging in to your account. The commercial license needs to be assigned to your account. If you are the developer, but somebody else purchased the license, then the buyer can assign the license to your account. You can instruct the buyer to loggin into his account and proceed to the licenses page. After selecting the components, themes, custom themes and font icon packs that you need, hit the download button and download your package. If you have multiple licenses and have access to multiple frameworks, you might need to select the framework as well. **2. Copy the library to your project** Extract the zip file you just downloaded, then grab the `js`, `src` and `css` folders and copy it into the `src/lib/mobiscroll` folder of your project. If there is no such folder available, you should create it. **3. Configure the project** Run the config command in your project's root folder with the `--no-npm` flag to proceed with the upgrade. ```bash mobiscroll config angular --no-npm ``` The Mobiscroll CLI under the hood will create and install a local NPM package from the lib folder. After the installation is complete, your package.json file should have an entry for a dependency like this: ```json "@mobiscroll/angular": "file:./src/lib/mobiscroll-package/mobiscroll-angular-5.27.1.tgz", ``` The `.tgz` file referenced here is the Mobiscroll package and it should be added to your repository too. At this point the trial package should be replaced with the commercial package, and building and running your project should work. --- ## Mobiscroll 5 upgrade guide ## Overview Introducing Mobiscroll 5 - a complete rewrite and retooling that enables better extensibility and performance. We moved away from the wrapper approach for Angular & React, and so with the new architecture we can ship native components for those frameworks. Below is the list of the breaking changes introduced with Mobiscroll v4. ## Browser support Starting from Mobiscroll 5.0 we no longer support Android < 5.0 and iOS < 9. ## Frameworks AngularJS (Angular 1.x) integration is not maintained anymore. Please use the plain Javascript version instead. Angular 2 is no longer supported. Please upgrade to Angular 4+ to continue using Mobiscroll. ## Themes The Mobiscroll theme is no longer available. The available themes are iOS, Material and Windows, in light and dark variants. ## General ### Global options We removed the `mobiscroll.settings` object, and added the `setOptions` function instead. The `setOptions` function can be called any time, and will update the options for the existing components. **Old code** ```jsx // Mobiscroll 4.x mobiscroll.settings = { theme: 'ios' }; ``` **New code** ```jsx // Mobiscroll 5.x mobiscroll.setOptions({ theme: 'ios' }); ``` **ES6 module** ```jsx // Mobiscroll 5.x setOptions({ theme: 'ios' }); ``` ### `option` method rename We renamed the `option` method to `setOptions` for each component. **Old code** ```jsx // Mobiscroll 4.x mobiscrollInst.option({ theme: 'ios' }); ``` **New code** ```jsx // Mobiscroll 5.x mobiscrollInst.setOptions({ theme: 'ios' }); ``` ### `lang` option rename We renamed the `lang` option to `locale` for localizing the components. Instead of a string now it accepts an object containing the localization settings. **Old code** ```jsx // Mobiscroll 4.x mobiscroll.settings = { lang: 'de' }; ``` **New code** ```jsx // Mobiscroll 5.x mobiscroll.setOptions({ locale: mobiscroll.localeDe }); ``` **ES6 module** ```jsx // Mobiscroll 5.x setOptions({ locale: localeDe }); ``` ### `getJson` util function location We moved the `getJson` function to `mobiscroll.util.http.getJson`. In ES6 it can also be `imported directly: import { getJson } from './path/to/mobiscroll';`. **Old code** ```jsx // Mobiscroll 4.x mobiscroll.util.getJson('http://example.com/method', callback); ``` **New code** ```jsx // Mobiscroll 5.x mobiscroll.util.http.getJson('http://example.com/method', callback); ``` **ES6 module** ```jsx // Mobiscroll 5.x getJson('http://example.com/method', callback); ``` ## Datepicker We merged the date, datetime, time, calendar and range components into a single datepicker component. Use this instead of the v4 standalone components. You can specify the appearance using the [controls](/angular/datepicker/api#opt-controls) option, and the select mode (date or range) using the [select](/angular/datepicker/api#opt-select) option. **Old code** ```jsx Date Time Date & time Date & time Calendar Calenda & time Range ``` **New code** ```jsx Range ``` ### Removed We removed the `calendarHeight` option, use the [maxHeigth](/angular/datepicker/api#opt-maxHeight) option instead. We removed the `calendarWidth` option, use the [maxWidth](/angular/datepicker/api#opt-maxWidth) option instead. We removed the `layout` option, use the [maxWidth](/angular/datepicker/api#opt-maxWidth) and [maxHeigth](/angular/datepicker/api#opt-maxHeight) options instead. We removed the `outerMonthChanged` option, this is now handled automatically. We removed the `selectType` option, week selection is currently not supported in v5. We removed the `showLabel` option, wheel labels are currently not supported in v5. We removed the `showScrollArrows` option, wheel scroll arrows are currently not supported in v5. We removed the `yearChange` option, now the calendar has a re-designed navigation. We removed the `weekDays` option, this is now handled automatically. We removed the `onBeforeClose` event. We removed the `onBeforeShow` event. We removed the `tap` method, which was a utility function used to attach the tap event to arbitrary elements, handling the 300ms click delay on older devices. On today's devices this is no longer needed, simply use the native `click` event. ### Changed We renamed the `animate` option to [animation](/angular/datepicker/api#opt-animation) to specify the show / hide animation of the picker. We renamed the `counter` option to [selectCounter](/angular/datepicker/api#opt-selectCounter) to specify the show / hide number of selected dates in the header. We renamed the `defaultValue` option to [defaultSelection](/angular/datepicker/api#opt-defaultSelection) to specify the initial selection, for better compatibility with React, where `defaultValue` refers to the actual value instead of a pre-selection in case of uncontrolled usage. We renamed the `height` option to [itemHeight](/angular/datepicker/api#opt-itemHeight) for setting the height of the wheel items. We renamed the `width` option to [wheelWidth](/angular/datepicker/api#opt-wheelWidth) for setting the exact width of the wheels. We renamed the `maxWidth` option to [maxWheelWidth](/angular/datepicker/api#opt-maxWheelWidth) for setting the maximum width of the wheels. We renamed the `minWidth` option to [minWheelWidth](/angular/datepicker/api#opt-minWheelWidth) for setting the minimum width of the wheels. We renamed the `months` option to [pages](/angular/datepicker/api#opt-pages), because it sets the number of displayed pages in case of week view as well, not just month view. We've broken up the `select` option into [selectMultiple](/angular/datepicker/api#opt-selectMultiple) and [selectMax](/angular/datepicker/api#opt-selectMax). We renamed the `showOnTap` option to [showOnClick](/angular/datepicker/api#opt-showOnClick) and the `showOnOverlayTap` option to `showOnOverlayClick` for the sake of simplicity and to make it more obvious. We've broken up the `steps` option into [stepHour](/angular/datepicker/api#opt-stepHour), [stepMinute](/angular/datepicker/api#opt-stepMinute) and stepSecond. We renamed the `weekCounter` option to [showWeekNumbers](/angular/datepicker/api#opt-showWeekNumbers) for showing the week numbers on the calendar. We changed the behavior of the `weeks` option, `weeks: 6` no longer means month view automatically. Month or week view needs to be set with the [calendarType](/angular/datepicker/api#opt-calendarType) option. We updated the format of the [dateFormat](/angular/datepicker/api#localization-dateFormat) and [timeFormat](/angular/datepicker/api#localization-timeFormat) options to avoid some common confusions we met. See the API docs for the new formatting tokens. We renamed the `onChange` event to [onTempChange](/angular/datepicker/api#event-onTempChange). This was part of the lifecycle event cleanup we performed. We renamed the `onDayChange` event to [onCellClick](/angular/datepicker/api#event-onCellClick). This was part of the lifecycle event cleanup we performed. We renamed the `onLabelTap` event to [onLabelClick](/angular/datepicker/api#event-onLabelClick). This was part of the lifecycle event cleanup we performed. We renamed the `onSet` event to [onChange](/angular/datepicker/api#event-onChange) for more clarity. This was part of the lifecycle event cleanup we performed. We renamed the `onShow` event to [onOpen](/angular/datepicker/api#event-onOpen) This was part of the lifecycle event cleanup we performed. We renamed the `show` method to `open` and the `hide` method to `close`. ## Event calendar ### Removed We removed the following options: `anchor`, `animate`, `buttons`, `closeOnOverlayTap`, `display`, `focusOnClose`, `focusTrap`, `formatDuration`, `headerText`, `showOnFocus`, `showOnTap`, `yearChange`. We removed the following events: `onBeforeClose`, `onBeforeShow`, `onClose`, `onPosition`, `onShow`. We removed the following methods: `hide`, `isVisible`, `position`, `redraw`, `refresh`, `show`, `tap`. ### Changed We improved our recurring event support. More complex [recurrence rules](/angular/core-concepts/recurrence) can be passed through the `recurring` property of an event as an object or as a string in RRULE format. Currently daily, weekly, monthly and yearly repeats are supported. We slightly changed the structure of [event objects](/angular/eventcalendar/api#opt-data). Instead of `text`, `title` should be used, and instead of the `d` property use the `recurring` property to create recurring events. We slightly changed the structure of the [marked](/angular/eventcalendar/api#opt-marked), [labels](/angular/eventcalendar/api#opt-labels) and [colors](/angular/eventcalendar/api#opt-colors) objects. To specify the date, use the `date` property, or the `start` and `end` properties for multiple days, and use the `recurring` property to specify multiple occurrences. We updated the format of the [dateFormat](/angular/eventcalendar/api#localization-dateFormat) and [timeFormat](/angular/eventcalendar/api#localization-timeFormat) options to avoid some common confusions we met. See the API docs for the new formatting tokens. As part of the the lifecycle event cleanup, we renamed the `onEventSelect` event to [onEventClick](/angular/eventcalendar/api#event-onEventClick), the `onDayChange` event to [onCellClick](/angular/eventcalendar/api#event-onCellClick) and the `onSetDate` event to [onSelectedDateChange](/angular/eventcalendar/api#event-onSelectedDateChange). We renamed the `calendarHeight` option to [height](/angular/eventcalendar/calendar#opt-height) and changed its scope to the full calendar with header and everything. We renamed the `calendarWidth` option to [width](/angular/eventcalendar/calendar#opt-width). We moved the `calendarScroll` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.scroll`. We moved the `eventBubble` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.popover`. We moved the `showEventCount` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.count`. We moved the `showOuterDays` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.outerDays`. We moved the `weeks` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.size`. We moved the `weekCounter` option into the [view](/angular/eventcalendar/api#opt-view) option under `view.calendar.weekNumbers`. We renamed the `eventList` property of the [view](/angular/eventcalendar/api#opt-view) option to `agenda`. ## Scheduler We added the brand new scheduler to the Event Calendar product line for displaying the events on a 24-hour grid. Can be enabled using the [view](/angular/eventcalendar/scheduler#configuring-the-view) option. ## Timeline We added the brand new timeline to the Event Calendar product line for displaying a timeline with its related events. Can be enabled using the [view](/angular/eventcalendar/timeline#configuring-the-view) option. ## Select ### Removed We removed the `counter` option. This is currently not supported in v5. We removed the `dataGroup`, `dataHtml`, `dataValue` and `dataText` options. These are currently not supported in v5. We removed the `inputClass` option. The rendered element can be entirely customized with the `inputElement` option. We removed the `layout` option, use the [maxWidth](/angular/select/api#opt-maxWidth) and [maxHeigth](/angular/select/api#opt-maxHeight) options instead. We removed the `multiline` option. This is currently not supported in v5. We removed the `showScrollArrows` option, wheel scroll arrows are currently not supported in v5. ### Changed We renamed the `animate` option to [animation](/angular/select/api#opt-animation) to specify the show / hide animation of the picker. The `data` option only supports an array of items with the `text`, `value`, `group` and `disabled` properties. HTML content for options is supported from version 5.12.0 using the [itemTemplate](/5.35.0/angular/select/api#template-itemTemplate) option. Read the [Templating](/angular/select/templating) section for more details. Remote data source is not supported out of the box in v5. You will have to manually get the remote data and pass that to the select. For remote filtering the [onFilter](/angular/select/api#event-onFilter) event can be used to get the filter text. By returning false in the onFilter handler, the filtering is left for the developer to be carried out. Then the text can be used to query the filtered data in any way you see fit and update the select. We changed the `group` option to [showGroupWheel](/angular/select/api#opt-showGroupWheel). It no longer accepts an object, but only a boolean, which controls if the group wheel is shown or not. When available, the group headers are always shown and the `clustered` property is not longer supported. We renamed the `height` option to [itemHeight](/angular/select/api#opt-itemHeight) for setting the height of the wheel items. We renamed the `width` option to [wheelWidth](/angular/select/api#opt-wheelWidth) for setting the exact width of the wheels. We renamed the `maxWidth` option to [maxWheelWidth](/angular/select/api#opt-maxWheelWidth) for setting the maximum width of the wheels. We renamed the `minWidth` option to [minWheelWidth](/angular/select/api#opt-minWheelWidth) for setting the minimum width of the wheels. We changed the `input` option to `inputElement` option, which accepts a HTMLElement. Selectors are not supported, but can be used to query the element and pass the element to the option. We renamed the `select` option to [selectMultiple](/angular/select/api#opt-selectMultiple), which became a boolean indicating multiple select when true. We no longer support a fix number of selected items. We renamed the `showOnTap` option to [showOnClick](/angular/select/api#opt-showOnClick) and the `showOnOverlayTap` option to [showOnOverlayClick](/5.35.0/angular/select/api#opt-showOnOverlayClick) for the sake of simplicity and to make it more obvious. ## Popup ### Removed We removed the `tap` method, which was a utility function used to attach the tap event to arbitrary elements, handling the 300ms click delay on older devices. On today's devices this is no longer needed, simply use the native `click` event. We removed the `layout` option, giving better control with the [width](/angular/popup/api#opt-width), [height](/angular/popup/api#opt-height), [maxWidth](/angular/popup/api#opt-maxWidth), [maxHeight](/angular/popup/api#opt-maxHeight) and [fullScreen](/angular/popup/api#opt-fullScreen) options options. We removed the `onBeforeClose` event. We removed the `onBeforeShow` event. ### Changed We renamed the `animate` option to [animation](/angular/popup/api#opt-animation) to specify the show / hide animation of the popup. For the sake of clarity we renamed the `showOnOverlayTap` option to `showOnOverlayClick`, and the onShow event to [onOpen](/angular/popup/api#event-onOpen). We renamed the `show` method to [onOpen](/angular/popup/api#event-onOpen) and the `hide` method to [onClose](/angular/popup/api#event-onClose). ## Forms In version 5 the Form component is no longer present, you need to use the individual form components instead. ## Button ### Changed Instead of the `flat` and `outline` attributes we added the `variant` option to the button, which can be `'standard'`, `'flat'`, or `'outline'`. ## Checkbox ### Changed Instead of specifying the label text as the component content, it can be passed using the `label` option. **Old code** ```jsx // Mobiscroll 4.x Label text ``` **New code** ```jsx // Mobiscroll 5.x ``` ## Dropdown We removed the `iconAlign` option, and added the [startIcon](/angular/forms/dropdown#opt-startIcon) and [endIcon](/angular/forms/dropdown#opt-endIcon) options instead to specify the input icons. ## Image There is no Image component in v5, instead the functionality can be achieved with the select component by customizing the select items. Starting from version 5.12.0 the select component items can be customized to any custom markup using the [itemTemplate](/5.35.0/angular/select/api#template-itemTemplate) option. Please refer to the [Templating](/angular/select/templating) section for more details. ## Input ### Changed Instead of specifying the label text as the component content, it can be passed using the `label` option. **Old code** ```jsx // Mobiscroll 4.x Label text ``` **New code** ```jsx // Mobiscroll 5.x ``` We removed the `iconAlign` option, and added the [startIcon](/angular/forms/input#opt-startIcon) and [endIcon](/angular/forms/input#opt-endIcon) options instead to specify the input icons. ## Radio ### Changed Instead of specifying the label text as the component content, it can be passed using the `label` option. **Old code** ```jsx // Mobiscroll 4.x Label text ``` **New code** ```jsx // Mobiscroll 5.x ``` ## Switch ### Changed Instead of specifying the label text as the component content, it can be passed using the `label` option. **Old code** ```jsx // Mobiscroll 4.x Label text ``` **New code** ```jsx // Mobiscroll 5.x ``` --- ## Using Mobiscroll v4 alongside v5 The 5th major version of Mobiscroll contains a [limited number of components](http://help.mobiscroll.com/en/articles/4703511-what-s-the-difference-between-v4-and-v5), compared to v4. If you need to keep using some components from v4, which are not present in the newer version, please follow [this guide](http://help.mobiscroll.com/en/articles/4656790-using-mobiscroll-v4-alongside-v5). --- ## Utility functions ## Utils A collection of general purpose utility functions which can be used independently from Mobiscroll component instances. ## Platform ```jsx ``` ### Description Information about the current platform. ### name String Possible values: * `ios` * `android` * `windows` ### majorVersion Number The major version of the platform ### minorVersion Number The minor version of the platform ## Format date ```jsx ``` ### Description Format a date into a string value with a specified format. ```jsx title="Example" formatDate('yy-mm-dd', new Date(2015, 1, 19)); // Produces '2015-02-19' ``` ### Parameters ### format String The format can be combinations of the following: * `M` - month of year (no leading zero) * `MM` - month of year (two digit) * `MMM` - month name short * `MMMM` - month name long * `D` - day of month (no leading zero) * `DD` - day of month (two digit) * `DDD` - day of week (short) * `DDDD` - day of week (long) * `YY` - year (two digit) * `YYYY` - year (four digit) * `h` - 12 hour format (no leading zero) * `hh` - 12 hour format (leading zero) * `H` - 24 hour format (no leading zero) * `HH` - 24 hour format (leading zero) * `m` - minutes (no leading zero) * `mm` - minutes (leading zero) * `s` - seconds (no leading zero) * `ss` - seconds (leading zero) * `a` - lowercase am/pm * `A` - uppercase AM/PM * `'...'` - literal text * `''` - single quote * anything else - literal text ### date Date The date value to format ### settings Object A set of key/value pairs that configure the format. All settings are optional: * **amText** (default: `'am'`) - Text for AM * **dayNames** (default: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']`) - The list of long day names, starting from Sunday. * **dayNamesShort** (default: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']`) - The list of abbreviated day names, starting from Sunday. * **monthNames** (default: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']`) - The list of full month names. * **monthNamesShort** (default: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']`) - The list of abbreviated month names. * **pmText** (default: `'pm'`) - Text for PM * **shortYearCutoff** (default: `'+10'`) - Set the cutoff year for determining the century for a date (used in conjunction with dateFormat 'y'). If a numeric value (0-99) is provided then this value is used directly. If a string value is provided then it is converted to a number and added to the current year. Once the cutoff year is calculated, any dates entered with a year value less than or equal to it are considered to be in the current century, while those greater than it are deemed to be in the previous century. ## Parse date ```jsx ``` ### Description Extract a date from a string value with a specified format. ```jsx title="Example" parseDate('yy-mm-dd', '2015-02-19')); // returns date object ``` ### Parameters ### format String The format can be combinations of the following: * `M` - month of year (no leading zero) * `MM` - month of year (two digit) * `MMM` - month name short * `MMMM` - month name long * `D` - day of month (no leading zero) * `DD` - day of month (two digit) * `DDD` - day of week (short) * `DDDD` - day of week (long) * `YY` - year (two digit) * `YYYY` - year (four digit) * `h` - 12 hour format (no leading zero) * `hh` - 12 hour format (leading zero) * `H` - 24 hour format (no leading zero) * `HH` - 24 hour format (leading zero) * `m` - minutes (no leading zero) * `mm` - minutes (leading zero) * `s` - seconds (no leading zero) * `ss` - seconds (leading zero) * `a` - lowercase am/pm * `A` - uppercase AM/PM * `'...'` - literal text * `''` - single quote * anything else - literal text ### value String The string value to parse ### settings Object A set of key/value pairs that configure the format. All settings are optional: * **amText** (default: `'am'`) - Text for AM * **dayNames** (default: `['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']`) - The list of long day names, starting from Sunday. * **dayNamesShort** (default: `['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']`) - The list of abbreviated day names, starting from Sunday. * **monthNames** (default: `['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']`) - The list of full month names. * **monthNamesShort** (default: `['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']`) - The list of abbreviated month names. * **pmText** (default: `'pm'`) - Text for PM * **shortYearCutoff** (default: `'+10'`) - Set the cutoff year for determining the century for a date (used in conjunction with dateFormat 'y'). If a numeric value (0-99) is provided then this value is used directly. If a string value is provided then it is converted to a number and added to the current year. Once the cutoff year is calculated, any dates entered with a year value less than or equal to it are considered to be in the current century, while those greater than it are deemed to be in the previous century. --- ## Using Mobiscroll with the source code ## Overview The following guide will help in using the development packages (a.k.a. source code) of Mobiscroll. :::info To have access to the source code you will need a Complete License or a License with the Source Code Addon. You can find more details on licenses on the [pricing page](https://mobiscroll.com/pricing). ::: The source code can be downloaded from the [download page](https://download.mobiscroll.com/). If you have access to the development packages, a dropdown will be there with the compression level label. Select the development level if it's not selected already from the dropdown. After selecting the components, themes, languages and icon packs you want to include hit the download button. You will get a zip file with the source code in it. :::info Before you can use the development package inside an angular app, the Mobiscroll library must be built from the downloaded package. ::: ## Building the library The development package contains the scripts and dependencies it requires to build it to an NPM package. After the library is built, it can be installed as an npm package to an Angular project. After unzipping the downloaded package, running the following command will install the dependencies and builds the library: ```jsx $ npm start ``` After the library is built, a file called `mobiscroll-angular-5.25.1.tgz` fill be created in the `dist` directory. This file is the NPM package containing the library. Copy this file to your angular project and install with the following command: ```jsx $ npm install .\mobiscroll-angular-5.25.1.tgz ``` The installed package is a production ready package. After installing it, you can import and use the individual modules from it: ### Using standalone components ```ts title="app.component.ts" @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], standalone: true, imports: [ MbscEventcalendarModule, MbscDatepickerModule, FormsModule, BrowserModule ], }) export class AppComponent { } ``` ```html title="app.component.html" ``` ### Using modules ```ts title="app.module.ts" @NgModule({ declarations: [ AppComponent ], imports: [ MbscEventcalendarModule, MbscDatepickerModule, FormsModule, BrowserModule ], providers: [], bootstrap: [AppComponent] }) export class AppModule { } ``` ```html title="app.component.html" ```