EGO CRM does not use static modal windows, i.e. windows pre-rendered in HTML and hidden until a button is pressed. Any modal window is rendered at least once at the first call of the modal window. Rendering can happen directly via JS code or via ajax.

Scenarios for opening a modal (popup) window:

In all modal window operations, the following parameters are used:

Additionally, we consider ways to close the modal window (if necessary in the scenario):

To render the button that opens the modal window, the method "btn" of the class "ui::" is used.
The method receives the parameter "btn_open_modal" with an array of modal window parameters or simply a string as the modal window content.

The simplest example, pass a string as the «btn_open_modal» parameter — the modal window content.

$args = array();
$args['btn_open_modal'] = '<p>My modal content, only string.</p>';
$args['text'] = 'Open modal';
$args['icon'] = array('window', 'far');
$str .= ui::btn($args);

In this example, we pass an array with modal window parameters to «btn_open_modal».

$modal_args = array();
$modal_args['body'] = '<p>My modal content.</p>';
$modal_args['header'] = 'My modal title';
$modal_args['footer'] = 'My footer';
$modal_args['size'] = 'full';
$modal_args['theme'] = 'info';
//===
$args = array();
$args['btn_open_modal'] = $modal_args;
$args['text'] = 'Open modal';
$args['icon'] = array('window', 'far');
$str .= ui::btn($args);

In this example, we also use:
- draggable: the window can be moved around the screen
- backdrop=FALSE: the window does not close when clicking outside the window.

$modal_args = array();
$modal_args['body'] = '<p>My modal content.</p><p><input name="my_input" class="form-control"></p>';
$modal_args['header'] = 'My modal title';
$modal_args['footer'] = 'My footer';
$modal_args['theme'] = 'warning';
$modal_args['placement'] = 'right';
$modal_args['draggable'] = true;
$modal_args['backdrop'] = false;
//===
$args = array();
$args['btn_open_modal'] = $modal_args;
$args['text'] = 'Open modal';
$args['icon'] = array('window', 'far');
$str .= ui::btn($args);

The same as the previous example, only the parameter "oneshot" with the value TRUE is added.
Note, when using the "oneshot" parameter it is mandatory to provide the "id" parameter.
Move the window to another place. Enter some text in the modal window field, then close it and open it again.

$modal_args = array();
$modal_args['body'] = '<p>My modal content.</p><p><input name="my_input" class="form-control"></p>';
$modal_args['header'] = 'My modal title';
$modal_args['footer'] = 'My footer';
$modal_args['theme'] = 'warning';
$modal_args['placement'] = 'right';
$modal_args['draggable'] = true;
$modal_args['backdrop'] = false;
$modal_args['id'] = set_id('my_modal_with_oneshot_ui');
$modal_args['oneshot'] = true;
//===
$args = array();
$args['btn_open_modal'] = $modal_args;
$args['text'] = 'Open modal';
$args['icon'] = array('window', 'far');
$str .= ui::btn($args);

We open the modal window using JS.
We create a button and assign it a handler. We create a js handler, and in the handler we use the helper $$.oj_modal() with the modal window parameters.

Note that the helper "$$.oj_modal()" returns the jQuery object of the modal window.
This is important if you need to do some work later with the modal window object.
In our example, we output the modal window object to the console.

$args = array();
$args['handler_click'] = 'my_open_modal';
$args['text'] = 'Open modal';
$args['icon'] = array('blinds-open', 'far');
$str .= ui::btn($args);
$$.my_open_modal = function(){
	var modal_pars={};
	modal_pars.body = 'My content in modal from js.';
	modal_pars.size = 'sm';
	var modalObj = $$.oj_modal(modal_pars);
	console.log('modalObj', modalObj);
	return true;
}
$args = array();
$args['handler_click'] = 'my_open_modal_variant';
$args['text'] = 'Open modal';
$args['icon'] = array('blinds-open', 'far');
$str .= ui::btn($args);
$$.my_open_modal_variant = function(){
	var modal_pars={};
	modal_pars.body = 'My content in modal from js.';
	modal_pars.size = 'lg';
	modal_pars.draggable = true;
	modal_pars.backdrop = false;
	$$.oj_modal(modal_pars);
	return true;
}

In this example, in the js handler we will close the modal window after 1 second using the helper "$$.oj_modal_close()".
If no parameters are passed to the helper, all modal windows will be closed.
If you have multiple modal windows open and need to close only a specific one, pass the modal window ID or the jQuery object of the modal window to the helper.

$args = array();
$args['handler_click'] = 'my_open_modal_and_close';
$args['text'] = 'Open modal';
$args['icon'] = array('blinds-open', 'far');
$str .= ui::btn($args);
$$.my_open_modal_and_close = function(){
	var modal_pars={};
	modal_pars.body = 'My content in modal from js.';
	modal_pars.theme = 'info';
	var modalObj = $$.oj_modal(modal_pars);
	setTimeout(function(){
		$$.oj_modal_close(modalObj);
	}, 1000);
	return true;
}

The content of the future modal window is placed in a hidden HTML element.
Instead of the "body" parameter in the modal window parameters array, we use the parameter "body_from", to which we pass the ID of the DOM element containing the modal window content.

In this example, we create a button to open the modal window using the class

My modal content from hidden block.

Double-click to clear the fieldPress ENTER to save
//=== Hidden block with content for modal
$str .= '<div id="'.set_id('my_modal_content').'" class="d-none">';
	$str .= e_p('My modal content from hidden block.', 'mb-3');
	$args = array();
	$args['name'] = 'my_input';
	$str .= ui::input_with_save($args);
$str .= '</div>';

//=== Button
$modal_args = array();
$modal_args['body_from'] = find_ele('my_modal_content');
$modal_args['header'] = 'My modal title';
$modal_args['draggable'] = true;
//===
$args = array();
$args['btn_open_modal'] = $modal_args;
$args['text'] = 'Open modal';
$args['icon'] = array('code', 'far');
$str .= ui::btn($args);

In the example, we open a modal window using JS.

My modal content from hidden block.

Double-click to clear the fieldPress ENTER to save
//=== Hidden block with content for modal
$str .= '<div id="'.set_id('my_modal_content').'" class="d-none">';
	$str .= e_p('My modal content from hidden block.', 'mb-3');
	$args = array();
	$args['name'] = 'my_input';
	$str .= ui::input_with_save($args);
$str .= '</div>';

//=== Button
$args = array();
$args['handler_click'] = 'my_open_modal_body_from';
$args['text'] = 'Open modal';
$args['icon'] = array('code', 'far');
$str .= ui::btn($args);
$$.my_open_modal_body_from = function(){
	var modal_pars={};
	modal_pars.body_from = $$.find_ele('my_modal_content');
	modal_pars.size = false;
	modal_pars.theme = 'secondary';
	$$.oj_modal(modal_pars);
	return true;
}

The content of the modal window is formed on the server in PHP code.
We assign a handler to the button.
In the handler on the server we use the helper "oj_modal()" to return the prepared content to the modal window.

In the server handler, we build the modal window string and pass an array of modal parameters to the helper «oj_modal()».

$args = array();
$args['handler_click'] = 'my_open_modal_ajax';
$args['text'] = 'Open modal';
$args['icon'] = array('server', 'far');
$str .= ui::btn($args);
public function my_open_modal_ajax() {
	$str = '';
	$str .= e_p('Modal content');
	$str .= e_p('Time: '.time());
	$header_str = mlang('my_header', 1);
	//===
	$modal_pars = array(
			'body'=>$str
		, 'header'=>$header_str
		, 'size'=>'lg'
		, 'theme'=>'primary'
		, 'draggable'=>true
	);
	oj_modal($modal_pars);
}

The same as before, only we add the parameter "oneshot".
Note, when using the "oneshot" parameter it is mandatory to provide the "id" parameter.
Notice the Time in the modal window after closing and reopening the window.

$args = array();
$args['handler_click'] = 'my_open_modal_ajax_oneshot';
$args['text'] = 'Open modal';
$args['icon'] = array('server', 'far');
$str .= ui::btn($args);
public function my_open_modal_ajax_oneshot() {
	$str = '';
	$str .= e_p('Modal content');
	$str .= e_p('Time: '.time());
	$header_str = mlang('my_header', 1);
	//===
	$modal_pars = array(
			'body'=>$str
		, 'header'=>$header_str
		, 'size'=>'lg'
		, 'theme'=>'primary'
		, 'draggable'=>true
		, 'id'=>set_id('my_modal_with_oneshot_ajax')
		, 'oneshot'=>true
	);
	oj_modal($modal_pars);
}

In the server handler, we build the modal window string and pass only the built string to the helper «oj_modal()».

$args = array();
$args['handler_click'] = 'my_open_modal_ajax_only_string';
$args['text'] = 'Open modal';
$args['icon'] = array('server', 'far');
$str .= ui::btn($args);
public function my_open_modal_ajax_only_string() {
	$str = '';
	$str .= e_p('Modal content');
	$str .= e_p('Time: '.time());
	oj_modal($str);
}

We use the «_close_parent_modal» parameter in various scenarios to close the parent modal window containing the button or field with the handler when the handler executes.

In this example, we use ajax to form the modal window content.
In the modal window, we create a field using the class "ui::", passing the parameter "_close_parent_modal" to the field creation method.
The modal window will close only if there is no error.
Try to save an unfilled field.

$args = array();
$args['handler_click'] = 'my_open_modal_close_parent_modal_1';
$args['text'] = 'Open modal';
$args['icon'] = array('eye', 'far');
$str .= ui::btn($args);
public function my_open_modal_close_panent_modal_1() {
	$str = '';
	$args = array();
	$args['name'] = 'my_input_1';
	$args['_close_parent_modal'] = true;
	$str .= ui::input_with_save($args);
	//===
	oj_modal($str);
}
public function save_my_input_1() {
	$val = ui::get_post_VAL();
	if(!empty($val)) {
		$success_text = 'VALUE: '.$val;
		//===
		ojsucc($success_text);
	}
	else ojerr(mlang('s_error__field_empty_warn', 1));
}

In this example, we also use ajax to form the modal window content.
However, when creating a field for the modal window using the class "ui::", we do not use the parameter "_close_parent_modal".
We use the parameter "_close_parent_modal" in the return helper "oj_ret()" directly in the save handler.
Thus, the modal window will close only if an instruction to close it is received in the return data after processing.
In this example, we close the window only in case of a successful operation.

$args = array();
$args['handler_click'] = 'my_open_modal_close_parent_modal_2';
$args['text'] = 'Open modal';
$args['icon'] = array('eye', 'far');
$str .= ui::btn($args);
public function my_open_modal_close_panent_modal_2() {
	$str = '';
	$args = array();
	$args['name'] = 'my_input_2';
	$str .= ui::input_with_save($args);
	//===
	oj_modal($str);
}
public function save_my_input_2() {
	$val = ui::get_post_VAL();
	if(!empty($val)) {
		$success_text = 'VALUE: '.$val;
		//===
		oj_ret('_close_parent_modal', true);
		//===
		ojsucc($success_text);
	}
	else ojerr(mlang('s_error__field_empty_warn', 1));
}

Same as the previous example, but now we use «oj_ret('_close_parent_modal')» to close the modal window in all cases, even on error.

$args = array();
$args['handler_click'] = 'my_open_modal_close_parent_modal_3';
$args['text'] = 'Open modal';
$args['icon'] = array('eye', 'far');
$str .= ui::btn($args);
public function my_open_modal_close_panent_modal_3() {
	$str = '';
	$args = array();
	$args['name'] = 'my_input_3';
	$str .= ui::input_with_save($args);
	//===
	oj_modal($str);
}
public function save_my_input_3() {
	$val = ui::get_post_VAL();
	//===
	oj_ret('_close_parent_modal', true);
	//===
	if(!empty($val)) {
		$success_text = 'VALUE: '.$val;
		//===
		ojsucc($success_text);
	}
	else ojerr(mlang('s_error__no_data', 1));
}

Special parameters similar to «btn_open_modal» for opening media files (audio, video, text, and PDF) in a modal window, considering media type.

Open an image in a modal window.
We use the same modal window parameters array for the "btn_open_img" parameter except:
"body" and "body_from". Instead, the parameter "src" with the link to the image (see documentation for image links) must be passed.

We use a button created by the class "ui::".
We pass an array with modal window parameters to the "btn_open_img" parameter.

$img_args = array();
$img_args['src'] = media_link('3e1861d3864ba55b27a8');
$img_args['theme'] = 'primary';
$img_args['draggable'] = true;
$img_args['id'] = set_id('my_modal_100');
$img_args['oneshot'] = true;
//===
$args = array();
$args['btn_open_img'] = $img_args;
$args['text'] = 'Open image';
$args['icon'] = array('image', 'far');
$str .= ui::btn($args);

We use a button created by the class "ui::".
We pass only a string with the link to the "btn_open_img" parameter.

$args = array();
$args['btn_open_img'] = media_link('c1c3ad469424684ae939');
$args['text'] = 'Open image';
$args['icon'] = array('image', 'far');
$str .= ui::btn($args);

We use ajax instructions to open the image in a modal window, for this in the server handler we use the helper "oj_img()".
In this example, we pass the helper an array with modal window parameters.
Note that the helper "oj_img()" is conditionally finalizing, i.e. by default it ends script execution and sends data via ajax (exit). To prevent script termination, pass the second argument as "FALSE", as done in this example, so that after executing the helper a message (ojsucc()) is also sent.

$args = array();
$args['handler_click'] = 'my_handler_and_open_img_3';
$args['text'] = 'Action';
$args['icon'] = array('image', 'far');
$str .= ui::btn($args);
public function my_handler_and_open_img_3() {
	$img_pars = array(
			'src'=>media_link('674f1e5c680c360b6d64')
		, 'header'=>'My image'
		, 'size'=>'lg'
		, 'theme'=>'warning'
		, 'draggable'=>true
		, 'auto_close'=>1200
	);
	oj_img($img_pars, false);
	ojsucc(true, 1200);
}

Also, like the previous example, we use the helper "oj_img()".
However, in this example, we pass the helper only the image link.

$args = array();
$args['handler_click'] = 'my_handler_and_open_img_4';
$args['text'] = 'Action';
$args['icon'] = array('image', 'far');
$str .= ui::btn($args);
public function my_handler_and_open_img_4() {
	oj_img(media_link('011ab21242e86e7d7635'));
}

We open the image directly from JS code.
For this, in the JS handler we use the helper "$$.oj_img()".
The helper can be passed either an object with modal window parameters or just a link to the image, similar to previous examples.

$args = array();
$args['handler_click'] = 'my_open_img_in_js';
$args['text'] = 'Open image';
$args['icon'] = array('image', 'far');
$str .= ui::btn($args);
$$.my_open_img_in_js = function(){
	var img_pars={};
	img_pars.src = $$.media_link('d0123b5368a11f8fed76');
	img_pars.theme = 'secondary';
	img_pars.draggable = true;
	img_pars.id = $$.set_id('my_modal_img_js');
	img_pars.oneshot = true;
	$$.oj_img(img_pars);
	return true;
}

Open Youtube video in a modal window.
We use the same modal window parameters array for the "btn_open_youtube" parameter except:
"body" and "body_from". Instead, the parameter "src" with the Youtube video identifier must be passed.

Special additional parameters.

  • Video aspect ratio parameter «aspect_ratio». You can pass one of the following values to this parameter:

    «21by9», «16by9», «4by3», «1by1» Default: «16by9».

  • Youtube player parameters. See Youtube player documentation.

    These parameters include:

    «youtube_autoplay», «youtube_cc_load_policy», «youtube_controls», «youtube_disablekb», «youtube_end», «youtube_fs», «youtube_iv_load_policy», «youtube_rel», «youtube_showinfo», «youtube_start»

We use a button created by the class "ui::".
We pass an array with modal window parameters to the "btn_open_youtube" parameter.

$youtube_args = array();
$youtube_args['src'] = 'zpOULjyy-n8';
$youtube_args['draggable'] = true;
$youtube_args['youtube_disablekb'] = true;
//===
$args = array();
$args['btn_open_youtube'] = $youtube_args;
$args['text'] = 'Open youtube video';
$args['icon'] = array('tv', 'far');
$str .= ui::btn($args);

We use a button created by the class "ui::".
We pass only a string with the Youtube video identifier to the "btn_open_youtube" parameter.

$args = array();
$args['btn_open_youtube'] = 'zpOULjyy-n8';
$args['text'] = 'Open youtube video';
$args['icon'] = array('tv', 'far');
$str .= ui::btn($args);

We use ajax instructions to open the Youtube video in a modal window, for this in the server handler we use the helper "oj_youtube()".
In this example, we pass the helper an array with modal window parameters.
Note that the helper "oj_youtube()" is conditionally finalizing, i.e. by default it ends script execution and sends data via ajax (exit). To prevent script termination, pass the second argument as "FALSE", as done in this example, so that after executing the helper a message (ojsucc()) is also sent.

$args = array();
$args['handler_click'] = 'my_handler_and_open_youtube_3';
$args['text'] = 'Action';
$args['icon'] = array('tv', 'far');
$str .= ui::btn($args);
public function my_handler_and_open_youtube_3() {
	$youtube_pars = array(
			'src'=>'zpOULjyy-n8'
		, 'header'=>'My Youtube video'
		, 'size'=>'lg'
		, 'theme'=>'warning'
		, 'draggable'=>true
		, 'auto_close'=>2500
		, 'youtube_autoplay'=>false
	);
	oj_youtube($youtube_pars, false);
	ojsucc(true, 1200);
}

Also, like the previous example, we use the helper "oj_youtube()".
However, in this example, we pass the helper only the Youtube video identifier.

$args = array();
$args['handler_click'] = 'my_handler_and_open_youtube_4';
$args['text'] = 'Action';
$args['icon'] = array('tv', 'far');
$str .= ui::btn($args);
public function my_handler_and_open_youtube_4() {
	oj_youtube('zpOULjyy-n8');
}

Open Youtube video directly from JS code.
In the JS handler, use the helper «$$.oj_youtube()».
The helper, like previous examples, can receive an object with modal parameters or just the Youtube video ID.
Note, in this example we also use the parameter «oneshot» (the «id» parameter must also be passed), so the Youtube video window will not be destroyed but only closed, allowing pause of video playback.

$args = array();
$args['handler_click'] = 'my_open_youtube_in_js';
$args['text'] = 'Open youtube video';
$args['icon'] = array('tv', 'far');
$str .= ui::btn($args);
$$.my_open_youtube_in_js = function(){
	var youtube_pars={};
	youtube_pars.src = 'zpOULjyy-n8';
	youtube_pars.id = $$.set_id('my_modal_youtube_oneshot');
	youtube_pars.oneshot = true;
	youtube_pars.theme = 'secondary';
	youtube_pars.draggable = true;
	$$.oj_youtube(youtube_pars);
	return true;
}

Opens audio, video, or text files depending on their type.
We use the same modal window parameters array for the "btn_open_youtube" parameter except:
"body" and "body_from". Instead, the parameter "src" with the file link must be passed.

Special additional parameters.

  • * Required parameter, media type «media_ident». This parameter tells scripts how to open the file. Use one of the following types:

    • audio: open to play audio file
    • video: open to watch video file
    • text: open to view text file
    • pdf: open to view PDF file

Thus, the «btn_open_media» parameter can only receive an array with two required parameters: «src» and «media_ident».

We use a button created by the class "ui::".
In this example, we listen to audio.

$media_args = array();
$media_args['src'] = media_link('dffe554669f542d8c1d2');
$media_args['media_ident'] = 'audio';
$media_args['theme'] = 'primary';
$media_args['draggable'] = true;
$media_args['id'] = set_id('my_modal_audio');
$media_args['oneshot'] = true;
//===
$args = array();
$args['btn_open_media'] = $media_args;
$args['text'] = 'Open audio';
$args['icon'] = array('music', 'far');
$str .= ui::btn($args);

We use a button created by the class "ui::".
In this example, we will open a text file.

$media_args = array();
$media_args['src'] = media_link('11a22a2a4488978d63a2');
$media_args['media_ident'] = 'text';
$media_args['size'] = 'lg';
//===
$args = array();
$args['btn_open_media'] = $media_args;
$args['text'] = 'Open text file';
$args['icon'] = array('file-alt', 'far');
$str .= ui::btn($args);

We use ajax instructions to open a media file in a modal window, for this in the server handler we use the helper "oj_media()".
Note that the helper "oj_media()" is conditionally finalizing, i.e. by default it ends script execution and sends data via ajax (exit). To prevent script termination, pass the second argument as "FALSE", as done in this example, so that after executing the helper a message (ojsucc()) is also sent.
In this example, we will open a pdf file.

$args = array();
$args['handler_click'] = 'my_handler_and_open_media_3';
$args['text'] = 'Open PDF-file';
$args['icon'] = array('file-pdf', 'far');
$str .= ui::btn($args);
public function my_handler_and_open_media_3() {
	$media_pars = array(
			'src'=>media_link('1e43b08a10407efcc57a')
		, 'media_ident'=>'pdf'
		, 'header'=>'My PDF'
		, 'theme'=>'primary'
		, 'draggable'=>true
	);
	oj_media($media_pars, false);
	ojsucc(true, 1200);
}

We open the media file directly from JS code.
For this, in the JS handler we use the helper "$$.oj_media()".
In this example, we will open video file playback.

$args = array();
$args['handler_click'] = 'my_handler_and_open_media_4';
$args['text'] = 'Open video file';
$args['icon'] = array('video', 'far');
$str .= ui::btn($args);
$$.my_handler_and_open_media_4 = function(){
	var media_pars={};
	media_pars.src = $$.media_link('a83d9e3079530dc4edc2');
	media_pars.media_ident = 'video';
	media_pars.theme = 'secondary';
	media_pars.id = $$.set_id('my_media_video');
	media_pars.oneshot = true;
	$$.oj_media(media_pars);
	return true;
}