Merge pull request #1691 from NativeScript/tgpetrov/calendar-events

docs about custom tokens in autocomplete

Author: tsonevn

docs/ui/professional-ui-components/AutoCompleteTextView/autocomplete-display-modes.md

@@ -23,7 +23,7 @@ Display mode can be changed with the {% typedoc_link classes:RadAutoCompleteText
 In plain mode **RadAutoCompleteTextView** displays chosen item as plain text. With this mode only one item can be chosen.
 
 ## Tokens Mode
-Tokens mode allows multiple choice of items. Chosen items are displayed as tokens which can be modified or completely changed with custom ones.
+Tokens mode allows multiple choice of items, which are displayed as tokens.
 
 When **RadAutoCompleteTextView**'s `displayMode` is `Tokens`, you can apply two different behaviors for token arrangement.
 
@@ -35,10 +35,10 @@ The default value of this property is {% typedoc_link enums:AutoCompleteLayoutMo
 
 <snippet id='autocomplete-layout-mode'/>
 
-## Wrap Layout
-In wrap mode tokens are arranged on multiple lines. Every  time a new line is started the **RadAutoCompleteTextView** is expanding in order to show all tokens.
+### Wrap Layout
+In wrap mode tokens are arranged on multiple lines. Every time a new line is started the **RadAutoCompleteTextView** is expanding in order to show all tokens.
 
-## Horizontal Layout
+### Horizontal Layout
 In horizontal mode tokens are displayed on single line which can be scrolled horizontally in order to display all tokens.
 
 ## References

docs/ui/professional-ui-components/AutoCompleteTextView/autocomplete-getting-started.md

@@ -10,10 +10,10 @@ publish: true
 
 # RadAutoCompleteTextView Getting Started
 
-In this article, you will learn how to initialize **RadAutoCompleteTextView** and use it with it's basic configuration.
+In this article, you will learn how to initialize **RadAutoCompleteTextView** and use it with its basic configuration.
 
 ## Installation
-Run the following command to add the plugin to your application:
+**RadAutoCompleteTextView** is distributed through the `nativescript-ui-autocomplete` package, so before using it, you need to run the following command to add the plugin to your application:
 
 ```
 tns plugin add nativescript-ui-autocomplete
@@ -26,23 +26,32 @@ Then, in order to add a {% typedoc_link classes:RadAutoCompleteTextView %} insta
 
 To create a **RadAutoCompleteTextView** you should use the RadAutoCompleteTextView tag in your .xml file.
 Once you have added the tag you should specify value for the `items` property of the control.
-The `items` property defines the collection of `TokenModel` objects which will be used to provide suggestions to the user input.
-The `hint` property allows you to provide a text that will be displayed when there is no input.
-The `text` property allows you to change the autocomplete text or get the current user input.
-The `TokenModel` object is a data model used by the autocomplete to populate the suggestion view and the chosen items.
 
 <snippet id='autocomplete-getting-started'/>
 
-Additionally you need to create, in your model, the collection of `TokenModel` objects which will be used to populate the **RadAutoCompleteTextView**.
+In order to provide suggestions that will be used by **RadAutoCompleteTextView** you need to provide a collection of items of type `TokenModel`:
 
 <snippet id='autocomplete-generate-data'/>
 
-In order to setup the suggestion view, which will be used as a holder to show possible suggestion, you need to add a `SuggestionView` tag and then provide a template for the layout of each suggestion.
+If necessarily, you can also use **RadAutoCompleteTextView**'s `hint` property to provide a text that will be displayed when there is no input; the `text` property that allows you to change the text or get the current user input or the `noResultsText` property to change the text displayed when no suggestions are found.
+
+## Customize the Suggestions
+When you start typing the input field, you will see the default suggestion view displayed below the input field. If you want, you can add a custom suggestion view and change its template (through the `suggestionItemTemplate` property) and/or fix its height (through the `suggestionViewHeight` property). Here's an example:
 
 <snippet id='autocomplete-suggestion-view-xml'/>
 
-The `suggestionViewHeight` property allows you to have control over the height of the suggestion view.
-The `suggestionItemTemplate` is the holder which is used to produce layout for each item of the suggestion view. 
+## Customize the TokenModel
+If you need, you can extend the `TokenModel` with an id to track more easily the selected items or any other information that you need that is missing from the default model. Here's an example:
+
+<snippet id='autocomplete-custom-token-model-ts'/>
+
+Then you can use the new type to populate the list of items that will be bound to  **RadAutoCompleteTextView**'s `items` property:
+
+<snippet id='autocomplete-custom-tokens-items-ts'/>
+
+You can also display the properties added to your custom model in the template of the suggestions:
+
+<snippet id='autocomplete-custom-tokens-template-xml'/>
 
 ## References
 Want to see more examples using **RadAutoCompleteTextView**?

docs/ui/professional-ui-components/AutoCompleteTextView/overview.md

@@ -10,33 +10,41 @@ publish: true
 
 # RadAutoCompleteTextView Overview
 
-**RadAutoCompleteTextView** can automatically complete user input string by comparing the text being entered to all strings in the associated data source. The control provides means for easy customization and data management.
+**RadAutoCompleteTextView** can automatically complete user input string by comparing the text being entered to all strings in the associated data source. The control provides means for easy customization and data management. It is distributed through the `nativescript-ui-autocomplete` package on [npmjs](https://www.npmjs.com/package/nativescript-ui-autocomplete).
 
 ## Features
 ### Suggest Modes
-**RadAutoCompleteTextView** supports three different suggest modes:
+**RadAutoCompleteTextView** can display drop-down list below the input field to show the suggestions for a text that is typed, directly append one of the suggestions in the input field itself or in a combination of both. This is controlled through the different acceptable values for the `suggestMode` property:
 
 - **Suggest** - Suggestions are shown in a drop-down list below the input field.
 - **Append** - Only one suggestion is shown as an appended text to the input. 
 - **SuggestAppend** - Both **Suggest** and **Append** modes are applied.
 
+[This article]({% slug autocomplete-suggest-modes %} "Describe the suggest modes in RadAutoCompleteTextView in NS") describes their usage.
+
 ### Display Modes
-**RadAutoCompleteTextView** supports two display modes.
+When a suggestion is selected, **RadAutoCompleteTextView** can display its selection in one of two ways - as a simple text or as a token. This is controlled through the different acceptable values for the `displayModes` property:
 
 - **Plain** - When **Plain** mode is active, only one item can be selected. The selected item is shown as a plain text in the input field.
 - **Tokens** - In **Tokens** mode the **RadAutoCompleteTextView** allows multiple selection of suggestions. The selected items are displayed as tokens.
 
-### Tokens Layout Modes
-**RadAutoCompleteTextView** provides two different layouts of tokens when **Tokens** display mode is used.
+[This article]({% slug autocomplete-display-modes %} "Describe the display modes in RadAutoCompleteTextView in NS") describes their usage.
+
+### Layout Modes
+When **RadAutoCompleteTextView**'s `displayMode` is **Tokens** and all selected tokens don't fit in one row, you can choose whether to layout them keep adding new token in the same (now scrollable) row, or add as many new rows as necessary to accommodate all tokens. This is controlled by the `layoutMode` property. Its acceptable values are:
 
-- **Wrap** - Tokens are aligned in a grid manner. 
-- **Horizontal** - Tokens are aligned horizontally.
+- **Wrap** - When a row is filled, another row is added to accommodate new tokens.
+- **Horizontal** - Tokens are added in a long scrollable row.
+
+The layout modes are also listed in the [article about tokens]({% slug autocomplete-display-modes %} "Describe the layout modes in RadAutoCompleteTextView in NS").
 
 ### Completion Modes
-**RadAutoCompleteTextView** has two possible modes on which the filtering function is based.
+There are two ways that **RadAutoCompleteTextView** can search for a matching suggestion for the input text - for items that start with the provided text or for items that contain the provided text but not necessarily in the beginning. This can be controlled with the `completionMode` property.
 
 - **StartsWith** - Shows only suggestions which start with the typed text.
-- **Contains** - Shows suggestions which contain the typed text.
+- **Contains** - Shows suggestions which contain the typed text but not necessarily in the beginning.
+
+More information about the completion modes is available in [this article]({% slug autocomplete-completion-modes %} "Describe the completion modes in RadAutoCompleteTextView in NS") describes their usage.
 
 #### Figure 1. RadAutoCompleteTextView (iOS/Android)
 ![RadAutoCompleteTextView: Overview](../../img/ns_ui/autocomplete-overview-ios.png "RadAutoCompleteTextView in iOS") ![RadAutoCompleteTextView: Overview](../../img/ns_ui/autocomplete-overview-android.png "RadAutoCompleteTextView in Android") 

docs/ui/professional-ui-components/Calendar/event-handling.md

@@ -18,6 +18,7 @@ publish: true
 - {% typedoc_link classes:RadCalendar,member:navigatingToDateStartedEvent %} - fired when navigation to a given date is about to happen
 - {% typedoc_link classes:RadCalendar,member:viewModeChangedEvent %} - fired when the view-mode changes to one of the modes described in [view modes]({% slug calendar-view-modes %})
 - {% typedoc_link classes:RadCalendar,member:dayViewEventSelectedEvent %} - fired when an event, part the list of events in the day view area of the calendar, has been selected
+- {% typedoc_link classes:RadCalendar,member:cellTapEvent %} - fired when a cell is tapped
 
 
 ## Providing Handlers
@@ -48,6 +49,10 @@ All events exposed by {% typedoc_link classes:RadCalendar %} provide additional
 	- `eventName` - the name of the event
 	- `object` - the sender of the event
 	- `eventData` - an instance of the {% typedoc_link classes:CalendarEvent %} class representing the selected event
+- {% typedoc_link classes:RadCalendar,member:cellTapEvent %} delivers its data by providing an instance of the {% typedoc_link classes:CalendarCellTapEventData %}. This class defines the following properties:
+	- `eventName` - the name of the event
+	- `object` - the sender of the event
+	- `date` - the date of the cell that is tapped
 
 ## References
 Want to see this scenario in action?

docs/ui/professional-ui-components/Calendar/overview.md

@@ -9,7 +9,7 @@ publish: true
 ---
 
 # RadCalendar Overview
-{% typedoc_link classes:RadCalendar %} for NativeScript is based on the corresponding native calendar components from the Progress UI for iOS and Progress UI for Android suites. It exposes a unified API covering all major features coming from the native components like:
+{% typedoc_link classes:RadCalendar %} for NativeScript is a highly customizable native calendar abstraction that exposes a unified API, covering:
 - inline events
 - different view modes
 - cells customization
@@ -19,7 +19,7 @@ publish: true
 
 ## Features
 ### View modes
-{% typedoc_link classes:RadCalendar %} supports four different view modes that are suitable for different application scenarios:
+{% typedoc_link classes:RadCalendar %} supports different view modes that are suitable for different application scenarios:
 
 - {% typedoc_link enums:CalendarViewMode,member:Week %} - displays the dates within one week
 - {% typedoc_link enums:CalendarViewMode,member:Month %} - displays the dates within one month

docs/ui/professional-ui-components/Calendar/populating-with-data.md

@@ -11,7 +11,7 @@ publish: true
 # Populating RadCalendar with Data
 RadCalendar allows you to define a list of events for a particular date. This is done by using the `eventSource` property. This article describes the steps you need to take in order to feed {% typedoc_link classes:RadCalendar %} with your custom events using a events source.
 
-### The CalendarEvent Class
+## The CalendarEvent Class
 Feeding events into {% typedoc_link classes:RadCalendar %} is done via instances of the {% typedoc_link classes:CalendarEvent %} class. The {% typedoc_link classes:CalendarEvent %} class is model describing a single event. It exposes properties allowing you to specify things like:
 
 - start time of the event
@@ -38,8 +38,17 @@ Running the application, the following is shown on iOS and Android:
 
 ![TelerikUI-RadCalendar-Populating-With-Data](../../img/ns_ui/calendar-populating-with-data_android.png "iOS") ![TelerikUI-RadCalendar-Populating-With-Data](../../img/ns_ui/calendar-populating-with-data_ios.png "Android")
 
+## Extending the CalendarEvent
+If you need, you can extend the `CalendarEvent` with an id to track more easily the selected items or any other information that you need that is missing from the default event. Here's an example:
+
+<snippet id='calendar-custom-event-model-ts'/>
+
+Then you can use the new type to populate the list of items that will be bound to  **RadCalendar**'s `eventSource` property:
+
+<snippet id='calendar-custom-event-items-ts'/>
+
 ## Event View Modes
-By default, events for each date cell are shown as dots (iOS) or squares with a summary (Android). You can customize this behavior by choosing one of the following event view modes:
+The events for each date cell are shown as dots (iOS) or squares with a summary (Android). **RadCalendar** allows you to show more information about the events by changing the **eventsViewMode** property. The default value is **None** meaning that there will be no additional event reperesentation coming out-of-the-box and the detailed information about events could be added through an additional **ListView** added below the **RadCalendar** and populated with information about events in a selected date. There are other event modes - **Inline** and **Popover** that present similar information within the calendar. Here are the available event view modes:
 
 - {% typedoc_link enums:CalendarEventsViewMode,member:None %} - the default option
 - {% typedoc_link enums:CalendarEventsViewMode,member:Inline %} - event details are displayed in a list that appears in the calendar

docs/ui/professional-ui-components/Calendar/selection-modes.md

@@ -1,7 +1,7 @@
 ---
 title: Selection modes
 page_title: RadCalendar selection modes | Progress NativeScript UI Documentation
-description: This article explains how to set the RadCalendar's selection mode  with Angular
+description: This article explains how to set the RadCalendar's selection mode
 slug: calendar-selection-modes
 tags: calendar, angular, selection, modes, nativescript, professional, ui
 position: 4
@@ -22,4 +22,15 @@ To change the selection mode of {% typedoc_link classes:RadCalendar %} you shoul
 
 For more information on how to handle selection events, you can take a look at the [Event Handling]({% slug calendar-event-handling %}) article.
 
+Depending on the currect selection mode, you can use the following properties to get/set the selected dates:
+
+- Single selection - {% typedoc_link classes:RadCalendar,member:selectedDate%}, which accepts values of type `Date`.
+- Multiple selection - {% typedoc_link classes:RadCalendar,member:selectedDates%}, which accepts values of type `Date` array.
+- Range selection - {% typedoc_link classes:RadCalendar,member:selectedDateRange%}, which accepts values of type {% typedoc_link classes:DateRange %}.
+
+To programmatically clear the selection, you can either set `null` to the relevant property, or call {% typedoc_link classes:RadCalendar,member:clearSelection %}.
+Here's an example:
+
+<snippet id='calendar-programmatic-selection-ts' />
+
 > The Selection mode functionality could be used in the cases while we use `Month` or `Week` `viewMode`

docs/ui/professional-ui-components/ng-AutoCompleteTextView/display-modes.md

@@ -26,7 +26,7 @@ The next code snippet shows how to change that default value to {% typedoc_link
 In plain mode the {% typedoc_link classes:RadAutoCompleteTextView %} displays chosen item as plain text. With this mode only one item can be chosen.
 
 ## Tokens mode
-Tokens mode allows multiple choice of items. Chosen items are displayed as tokens which can be modified or completely changed with custom ones.
+Tokens mode allows multiple choice of items, which are displayed as tokens.
 
 When **RadAutoCompleteTextView**'s `displayMode` is `Tokens`, you can apply two different behaviors for token arrangement.
 
@@ -38,10 +38,10 @@ The layout mode of the tokens can be changed with the {% typedoc_link enums:RadA
 <snippet id='angular-autocomplete-layouts-wrap-html'/>
 <snippet id='angular-autocomplete-layouts-wrap'/>
 
-## Wrap layout
-In wrap mode tokens are arranged on multiple lines. Every time a new line is started the {% typedoc_link classes:RadAutoCompleteTextView %} is expanding in order to show all tokens.
+### Wrap Layout
+In wrap mode tokens are arranged on multiple lines. Every time a new line is started the **RadAutoCompleteTextView** is expanding in order to show all tokens.
 
-## Horizontal layout
+### Horizontal Layout
 In horizontal mode tokens are displayed on single line which can be scrolled horizontally in order to display all tokens.
 
 ## References