Dialogs

The dialog functions offer you the opportunity to interact with the user using modal windows that appear in front of the tapp.

They can be used to inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

The dialogs are an independent part of chayns®. It's the same project loaded on all platforms.

Table of Contents

• Base Elements
• Alert Dialog
• Confirm Dialog
• Input Dialog
• Select Dialog
• Date Dialog
• Advanced Date Dialog
• Media Select Dialog
• File Select Dialog
• iFrame Dialog

Base Elements

Buttons

Buttons are base elements for nearly all dialogs and represents interaction with the user. You have different options to customize the buttons.

Property	Description	Type	Default
text	This text is printed inside the button	string	required
buttonType	This is the return value of the button. You should use chayns.dialog.buttonType for defined buttonTypes	number	required
collapseTime	After this amount of seconds the button will be pressed automatically	number
textColor	This color will be set to the text	string	#ffffff
backgroundColor	This is the color of the button	string	sideColor

Example:

   {  
      "text": "YES",
      "buttonType": chayns.dialog.buttonType.POSITIVE,
      "collapseTime": 3,
      "textColor": "#ff00ff",
      "backgroundColor": "#ff0000"
   }

ButtonType

You can use each number as buttonType but only chayns.dialog.buttonType.POSITIVE is a valid action and returns the data.

Key	Value
chayns.dialog.buttonType.CANCEL	-1
chayns.dialog.buttonType.NEGATIVE	0
chayns.dialog.buttonType.POSITIVE	1

Alert-Dialog

This dialog can be used to show an alert.

Parameter:

Property	Description	Type	Default	Required
Headline	First parameter, shows the text in a headline	string	''	false
Text	Second parameter, the text in the dialog. HTML is allowed	string	''	false

Return Value:

Value	Sense
1 (chayns.dialog.buttonType.POSITIVE)	The user pressed the OK button to remove the dialog
-1 (chayns.dialog.buttonType.CANCEL)	The user touched the background to remove the dialog

Example:

chayns.dialog.alert('Alert', 'This is the text').then(console.log);

Confirm-Dialog

This dialog can be used to show a confirm dialog. The user must make a decision.

Parameter:

Property	Description	Type	Default	Required
Headline	First parameter, shows the text in a headline	string	''	false
Text	Second parameter, the text in the dialog. HTML is allowed	string	''	false
Buttons	Third parameter, an array of Buttons	array	defaultButtons	false

Default Buttons:

[{
    'text': buttonText.YES,
    'buttonType': buttonType.POSITIVE
}, {
    'text': buttonText.NO,
    'buttonType': buttonType.NEGATIVE
}]

Return Value:

Value	Sense
1 (chayns.dialog.buttonType.POSITIVE)	The user pressed the OK button to remove the dialog
-1 (chayns.dialog.buttonType.CANCEL)	The user touched the background to remove the dialog
0 (chayns.dialog.buttonType.NEGATIVE)	The user touched the negative button to remove the dialog

Example:

chayns.dialog.confirm('Confirm', 'Confirm Dialog...', [{
        text: 'YES',
        buttonType: 1,
        collapseTime: 3
    }, {
        text: 'NO',
        buttonType: 0,
    }]).then(console.log);

Input-Dialog

This dialog can be used to ask the user for some textual information. This dialog has only the config as valid parameter.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
placeholderText	Thi text will be shown in the placeholder	string	Schreib etwas...	false
text	This is the text will be inserted as input value	string	NULL	false
textColor	The color of the text.	string	NULL	false
buttons	The buttons the user could interact with	array	defaultButtons	false
type	The type of input	number	2	false
regex	Regex for validation (type has to be set)	string	NULL	false
formatter	Function to format the input (type has to be set)	func	NULL	false
pattern	Pattern set to the input. Can be used to get another keyboard on iOS *.	string	NULL	false
disableButtonTypes	ButtonTypes to disable with regex	array of number	all buttonTypes > 0	false

* if type is set to chayns.dialog.inputTypes.NUMBER, the pattern "[0-9]*" makes an number-only keyboard.

Input types:

Key	Description	Value
chayns.dialog.inputType.PASSWORD	Input type is an password and the chars displayed as *	1
chayns.dialog.inputType.TEXTAREA	The user can write multiple lines and the texbox will fit the content	2
chayns.dialog.inputType.INPUT	The user can write text in a single line	3
chayns.dialog.inputType.NUMBER	The user can only use valid number Key for input. Attention: e is valid	4

Return Value:

Property	Description	possible Values	Type
buttonType	Information on which button the user clicked	-1, 0, 1, x	number
text	The text the user entered. This value will only be returned if the user pressed on button with type 1(chayns.dialog.buttonType.POSITIVE)		string

Example:

 chayns.dialog.input({
    title: 'Questioning',
    message: 'You may also comment this.',
    type: chayns.dialog.inputType.TEXTAREA
}).then(console.log);

Select-Dialog

This dialog is created to give the user set of Items where he can select one ore more items. This call accepts only the config parameter, which is an object.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
list	This Array contains list items	array	NULL	true
multiselect	Allows to select more than one item.	bool	false	false
quickfind	Adds a search bar above the list. Fulltextsearch on item.name	bool	false	false
type	Defines the type of selectList	number	0	false
preventCloseOnClick	Prevents Closing on item click if multiselect is disabled	bool	false	false
buttons	This Array contains an optional list of individual chayns buttons	array	NULL	false
selectAllButton	Adds a checkbox with the given text of this property which allows you to enable and disable all elements of the select list at the same time. Based on the list items isSelected state the checkbox is enabled or disabled. If all elements of the list are selected, the checkbox will be checked.	string	NULL	false

Types:

Type	Value	Description
selectType.DEFAULT	0	A list of strings.
selectType.ICON	1	A list of icons.

List item:

Property	Description	Type	Default	Required
name	The name of the item. This Name is shown in default type	string	NULL	true
value	The value that will be returned.	string|number|object	name	true
backgroundColor	A hex color like #ffff00	string	chayns__background-color	false
className	Fontawesome class name like fa-search for the shown icon	string	NULL	false
url	If you want to set an image instead of an icon	string	NULL	false
isSelected	If the item should be displayed as selected item	bool	false	false

Example list:

[{
    name: 'Item 1',
    value: 999,
    isSelected: true
}, {
    name: 'displayText3',
    value: {
        anount: 23
    },
    isSelected: true
}, {
    name: 'Item 3',
    value: {
        data: 4
    },
}, {
    name: 'Item 4'
}, {
    name: 'Item 5',
    value: 999,
}, {
    name: 'ts-ticket',
    value: 'ffgf',
    backgroundColor: '#0000ff'
}, {
    name: 'fa-university',
}, {
    name: 'fa-car',
    backgroundColor: '#00ff00'
}, {
    name: 'tobit',
    value: 30,
    url: 'https://chayns.tobit.com/storage/60038-22141/Images/icon-72.png',
    backgroundColor: '#ff00ff'
}]

Return Value:

Property	Description	possible Values	Type
buttonType	Information on which button the user clicked	1, 0, 1	number
selection	An array of selected Items		array

Selection:

Property	Description	Type
name	The name the item has	string
value	The value the item has	string|number|object

Example

chayns.dialog.select({
    title: 'Select Dialog',
    message: 'Please select one:',
    quickfind: true,
    list: [{
              name: 'Item 1',
              value: 999,
              isSelected: true
          }, {
              name: 'displayText3',
              value: {
                  anount: 23
              },
              isSelected: true
          }]
}).then((data) => {
    console.log(data);
});

Date-Dialog

This dialog allows the user to select a date, a time or both. This call accepts only the config parameter, which is an object.

Attention: You will get different return values on web, iOS and Android. The advancedDateDialog provides always the same information.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
minDate	The smallest possible value which the user could select	date | timestamp(in seconds)	0	false
maxDate	The biggest possible value which the user could select	date | timestamp(in seconds)	NULL	false
preSelect	The date which should be preselected	date | timestamp(in seconds)	new Date().getTime()/1000	true
dateType	The type of the dateDialog	number	chayns.dialog.dateType.DATE	false

DateType:

Key	Description	value
chayns.dialog.dateType.DATE	The user could only select a date in a calendar	1
chayns.dialog.dateType.TIME	The user could only select a time. (hours and minutes)	2
chayns.dialog.dateType.DATE_TIME	The user could select a date and time	3

Example:

chayns.dialog.date({
    dateType: chayns.dialog.dateType.DATE,
    title: 'Date Dialog',
    message: 'Choose a date:',
    minDate: new Date(2018, 6, 11),
    maxDate: new Date(2019, 9, 11),
    preSelect: Date.now() / 1000
}).then((data) => {
    console.log(data);
});

Return Value

A timestamp in seconds as number. Attention: The value is different on iOS, Android and the web to be compatible with the old dialog.

Advanced-Date-Dialog

This dialog allows the user to select a date, a time or both. This call accepts only the config parameter, which is an object. You can call this dialog using chayns.dialog.advancedDate.

This date dialog will return on each platform the same values. This is a big advantage of this call and there are some more features like:

• multiselect
• multiple preselects
• disabled days
• disabled intervals
• disabled intervals for weekdays
• selection of year and month to make it easier to select a date which is far away.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
buttons	The buttons the user could interact with	array	defaultDateButtons	false
minDate	The smallest possible value which the user could select	date | timestamp(in seconds)	0	false
maxDate	The biggest possible value which the user could select	date | timestamp(in seconds)	NULL	false
minuteInterval	The user can only dial e.g. every 10th minute instead of every minute.	number	1	false
preSelect	The date(s) which should be preselected	date | array of date | timestamp(in seconds)	new Date().getTime()/1000	false
multiselect	The user could select different dates. Multiple Times are not supported	bool	false	false
disabledDates	This array defines dates which the user could not select	arras of date | timestamp(in seconds)	NULL	false
textBlocks	This Blocks could be used in DATE_TIME Dialog to be displayed between the calendar and the time select	array of objects	NULL	false
yearSelect	Allows to select a year with an extra menu	bool	false	false
monthSelect	Allows to select a month with an extra menu	bool	false	false
interval	Allows to select an interval. Can't be used with multiselect	bool	false	false
minInterval	The min-interval the user has to select in minutes	number	null	false
maxInterval	The max-interval the user has to select in minutes	number	null	false
disabledIntervals	Allows to disable intervals	array of interval objects	null	false
disabledWeekDayIntervals	Allows to disable intervals for every weekday, e.g. tuesdays, 7:00-9:30	array of weekdays	null	false
getLocalTime	The dialog will return the timestamp in the local timezone with the date from preSelect	bool	false	false
dateType	The type of the dateDialog	number	chayns.dialog.dateType.DATE	false

Note: If yearSelect is set, the minDate will be set on default to 1.1.1900 and maxDate to now + 10 Years.

Interval-object

Property	Description	Type
start	start of the interval	date/timestamp(in seconds)
end	end of the interval	date/timestamp(in seconds)

Disabled interval example

[
    {
      start: Date.now() / 1000 + 60 * 60 * 24 * 2,
      end: Date.now() / 1000 + 60 * 60 * 24 * 5
    },
]

Disabled weekday example (mondays till 6:00am and from 8:00pm and wednesdays 5:00am till 7:30am):

[
  [
    {
      end: 6*60
    },
    {
      start: 20*60
    }
  ],
  null,
  [
    {
      start: 5*60,
      end: 7.5*60
    }
  ]
]

Textblock:

Property	Description	Type	Default	Required
headline	A h2 Element	string	NULL	false
text	A text which could contain html	string	NULL	false
position	The position of the Element. 0 is above the first dialog item, 1 is above the second dialog item...	number	NULL	true

MediaSelect-Dialog

This dialog allows to choose an image from Pixabay.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
multiSelect	The user could select multiple images	bool	false	false
buttons	The buttons the user could interact with	array	defaultButtons	false

FileSelect-Dialog

This dialog allows to choose a file from chayns.space.

Config:

Property	Description	Type	Default	Required
title	The headline of the dialog	string	NULL	false
message	The description below the headline	string	NULL	false
multiselect	The user could select multiple files	bool	false	false
buttons	The buttons the user could interact with	array	defaultButtons	false
contentType	Allowed mime types	array	[]	false
exclude	Excluded mime types	array	[]	false
directory	Allows to select a directory	bool	false	false

iFrame-Dialog

This dialog allows to show a website inside the dialog. It's possible to set input data for the dialog iFrame, set the result and communicate with the tapp.

Config:

Property	Description	Type	Default	Required
url	The url of the site shown in the iFrame	string	NULL	true
input	Data that will be given in the iFrame at onload. You can find it in chayns.env.dialogInput.	object	NULL	false
buttons	Buttons which displayed in iframe	array	NULL	false
seamless	Removes padding and margin	bool	false	false
transparent	Makes the dialog transparent	bool	false	false
waitCursor	Shows an waitCursor while the site is loading	bool	false	false
maxHeight	max-height for dialog content	string	NULL	false
width	width for dialog content in px	number	NULL	false
fullHeight	Sets the iFrame height to the full window size	bool	false	false
customTransitionTimeout	Disables dialog transition on close, close after timeout	number	NULL	false

Example to call iFrame:

chayns.dialog.iFrame({
    url: 'https://tobit.software/Willkommen',
    waitCursor: true,
    seamless: true,
    buttons:[{
        text: 'OK',
        buttonType: 1
    },
    {
        text: 'Abbrechen',
        buttonType: -1
    }],
    input: {
        //Insert own parameters
        id: 12345678,
        name: 'user01' 
    }
}).then(data=>{
    if(data.buttonType === 1){
        console.log("result", data.value.text);
    }    
});

If you want to write your own dialog-tapp, you need to load the dialog-chayns-js instead of the chayns-js.

<!-- css styles -->
<script src="https://api.chayns-static.space/css/v4/compatibility/compatibility.min.js" version="4.2"></script>

<!-- js api -->
<script src="https://api.chayns-static.space/js/dialog/v4.0/dialog-chayns.min.js"></script>

Example iFrame project:

chayns.ready.then(() => {
    const {id, name} = chayns.env.dialogInput;
    console.log("input", {id, name});
    
    chayns.dialog.setResult({text: "Hello World!"});
});

Dialog-chayns-js documentation

You get the full chayns environment in chayns.env, but most of the calls are not supported. The utility functions are fully available. Also, there are a few special functions for dialog iFrames.

Communication with the tapp

The communication functions are also available in the tapp to communicate with the dialog. The functions are available both in the iFrame as well as in the tapp.

ApiEvents are processed from the chayns API. They are listed here because the chayns API is also using this functions.

• chayns.dialog.sendData(data, isApiEvent)
  • Allows to send data to the tapp. If isApiEvent is set, the data will only be recognised if getApiEvents is set on the following function.
• chayns.dialog.addDialogDataListener(callback, getApiEvents)
  • Allows to get the data sent from the tapp. If getApiEvents is set, only apiEvents are recognised.
• chayns.dialog.removeDialogDataListener(callback, getApiEvents)
  • Removes the listener.

Note: There's a queue to prevent that you miss some data.

Set button result

You can set a result which will be added in the promise object returned by the dialog call in the tapp. It will only be returned if the user confirms the dialog, e.g. clicks on a button with a positive buttonType.

There are two ways to return a result:

1. You can set the result immediately after the result-changing event. It's like you refresh your result frequently.
2. If you want to set the result only when the button gets clicked, you have to register a listener using addDialogListener. After the button is clicked, the buttons will be disabled and the dialog stays open until you set a result using setResult.

• chayns.dialog.setResult(result, register)
  • Sets an result which will be given back to the tapp when user closes the dialog using a positive button. It can be set at every time. You can ignore the register-parameter because it's an internal parameter used by addDialogResultListener and removeDialogResultListener.
• chayns.dialog.addDialogResultListener(callback)
  • Registers a listener that will be notified before the dialog gets closed. After this listener get called, you have to set a result to close the dialog.
• chayns.dialog.removeDialogResultListener(callback)
  • Removes the listener.

Close dialog

You can close the dialog with a button type from your iFrame using an api function:

chayns.dialog.close(buttonType);

If you don't set the buttonType, the dialog will be cancelled (buttonType -1).

Disable buttons

In an iFrame-Dialog, you are able to enable and disable buttons of the dialog. Therefor, we added the function chayns.dialog.disableButtons(disable, buttonTypes). The first parameter has to be true if the buttons should be disabled or false if the buttons should be enabled. Pass an array of buttonTypes to the second parameter to choose which buttonTypes should be enabled or disabled.