User Interface Development
Overview
- Page to begin organizing the new user interface development standards. Can check out some standards on the following page also:
https://github.com/openemr/openemr/blob/master/interface/README.md
How to create expandable page
Expandable Pages in openEMR
There are 3 categories of responsive restyled pages in openEMR
- non-expandable centered pages - non-expandable full screen pages - expandable pages
The non-expandable centered pages are designed to show the data in a Bootstrap 3 div with the class = "container". This the default for most pages and helps with the display of just the needed data by focusing the viewer's attention to the center of the screen.
The non-expandable full screen pages show data, generally tabular data that has a lot of information per line and needs to use the full screen width to display the data in an easy to read manner. It is generally wrapped up in a bootstrap 3 container div with the class = "container-fluid"
The third type of page is the expandable page. This page can exist in two modes - Expanded and Centered. The page is designed to be viewed in the default Centered mode but has the ability to be viewed in the full screen or Expanded mode if the user so chooses. The user can toggle between the two states by clicking on the Expand/Contract icon that is present as a superscript to the title or heading of the page.
The system default is for all the pages to open in the Centered mode, this can be set instead to open all expandable pages in the Expanded mode by the administrator - Administration > Globals > Features > Expand Form.
Additionally the initial default for each individual user can be set at User Name > Edit User Settings > Features > Expand Form. If the user expands a page then that state is remembered by the system and henceforth the page will always open in the expanded mode unless it is changed by toggling to the opposite state.
If there are pages that are functionally linked to that page they too will open in the same state - Expanded or Centered as the case may be.
The basic mechanism to toggle between the Expanded and Contracted states is brought about by a jQuery function $('.expand_contract').click(function() ); located in interface /expand_contract_js.php and has to be included in each page using a require statement require_once("$include_root/expand_contract_js.php");
Two PHP functions setUserSetting() and getUserSetting() located in library/user.inc are needed and have to be included using require_once "$srcdir/options.inc.php"; on each page. These functions are used to set the user's choice and write the values to table user_settings. These functions are run before the page is returned by the server.
To determine and set the page to open in the desired state - expanded or centered, any selection the user makes will become the user-specific default for that page.
The current user's preference for that page is retrieved by the function collectAndOrganizeExpandSetting($filenames = array()) located in library/user.inc. It takes a single indexed array as an argument, containing one or more elements, the name of the current file is the first element, if there are linked pages they should be listed thereafter.
In order to distinguish these entries in the table_user settings from other entries that may reference the same page all such page names used for targeting the expandable feature should have a _xpd suffix is added to the file name e.g. file_name_xpd.
The collectAndOrganizeExpandSetting() function processes the array received as the argument and using the getUserSetting() function located in library/user.inc to retrieve the current state for the current page and then using the setUserSetting() function located in library/user.inc sets the value for any linked files to the current state of the current file.
The value returned by collectAndOrganizeExpandSetting() function, 0 or 1, reflects the current stored value of the page or the system/user default value if the page had never been accessed before by the user. It is passed to a script library/expand_contract_inc.php that sets the value of three variables $container, $expand_title and $expand_icon_class that determines the state of the page on page load.
To dynamically change the state values for the current page the jQuery function $('.expand_contract').click(function() ...); located in interface/expand_contract_js.php toggles the class of the container div from "container" to "container-fluid" based on the value of the title of the expand/contract icon and POSTs the changed value to library/ajax/user_settings.php where it gets written to the table user_settings using the setUserSetting() function by looping through the array arrFiles that contains the names of the current file and linked files. If there are no linked files the array has only one file name - that of the current page.
The process of making a bootstrapped page expandable consists of the following steps:
1. Make sure that the following line is included at the top of the script
require_once "$srcdir/options.inc.php";
2. Copy the PHP code to assign the correct current state, container class, the title for tooltip and the correct font-awesome icon to display on page load and place it in the <head></head> section.
Edit the array $arr_files_php to reflect the relevant pages being targeted.
<?php
//to determine and set the form to open in the desired state - expanded or centered, any selection the user makes will
//become the user-specific default for that page. collectAndOrganizeExpandSetting() takes a single indexed array as an
//argument, containing one or more elements, the name of the current file is the first element, if there are linked
//files they should be listed thereafter, please add _xpd suffix to the file name
$arr_files_php = array("external_data_patient_xpd", "stats_full_patient_xpd", "patient_ledger_patient_xpd");
$current_state = collectAndOrganizeExpandSetting($arr_files_php);
require_once("$srcdir/expand_contract_inc.php");
$GLOBALS['enable_help'] = 0; // temporary till help file is written
?>
3. Change the class of the container div from
4. Add the Expand Contract icon to the title of the page <i id="exp_cont_icon" class="fa <?php echo attr($expand_icon_class);?> oe-superscript-small expand_contract" title="<?php echo attr($expand_title); ?>" aria-hidden="true">
5. include the jQuery code between <script>
<?php require_once("$include_root/expand_contract_js.php");//jQuery to provide expand/contract icon toggle if form is expandable ?>
</script>
Troubleshooting
P: The page opens in the Centered mode and not in the Expanded mode despite the system /user default being set for Expanded mode
A: Make sure require_once "$srcdir/options.inc.php"; is include at the top of the page or else functions setUserSetting() and getUserSetting() won't be available
P: Despite including require_once "$srcdir/options.inc.php"; the page is still not opening in the set default mode
A: Check that the variable $arr_files_php contains the correct file names, the current file being the first name
P: I do not see the Expand/Collapse icon
A: The page must include Bootstrap and font-awesome files, check to see if the following exists on the page
use OpenEMR\Core\Header;
<?php Header::setupHeader();?>
P: They exist but I still do not see the icon
A: Make sure <i id="exp_cont_icon" class="fa <?php echo attr($expand_icon_class);?> oe-superscript-small expand_contract" title="<?php echo attr($expand_title); ?>" aria-hidden="true"> exists on the title header
P: The Expand/Contract icon exists but nothing happens when I click on the icon
A: Make sure that the jQuery to provide the ability to toggle the expand/contract icon exists between <script> tags <?php require_once("$include_root/expand_contract_js.php");?>
P: The jQuery expand_contract_js.php exists between <script> tags, the expand/contract icon toggles but the page does not toggle
A: Make sure that the class for the container div is set to <div class="<?php echo $container;?> expandable">
