Naysayers Promote Misery

    @openmrs/openmrs-contrib-uicommons

    1.0.0 • Public • Published

    OpenMRS

    # OpenMRS Reference Application UI Library

    Build StatusCodacy Badge

    This repository contains the Reference Application UI library.

    It contains common utilities for developing OpenMRS UI.

    Menu

    Quick Start

    To get this library You can:

    • Clone the repo: git clone https://github.com/PawelGutkowski/openmrs-contrib-refapp-ui-lib/tree/v0.1.5.
    • Install with Bower: bower install openmrs-contrib-uicommons --save.
    • Install with npm: npm install openmrs-contrib-uicommons --save.

    What's included

    Release contains CSS stylesheets, precompiled SCSS files for them and angular reusable components.

    Stylesheets

    OpenMRS css stylesheets are automatically linked to Your html file, when You import bundle javascript file.

    You can find OpenMRS Reference Application styleguide here.

    Angular

    To use components, make sure You use Angular 1 version v1.5.2 or higher. You can inject all partial modules at once, by injecting openmrs-contrib-uicommons module as follows:

    angular.module('YourAngularModule',['openmrs-contrib-uicommons']);

    OpenMRS Rest Module

    OpenMRS Rest module allows You to make requests to Your server Rest API super fast and easy. First You have to inject its module to Your module, and controller where You want to use it

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.header']).controller('controller', controller);
    
    controller.$inject = ['openmrsRest']
    function controller(openmrsRest) {
    	var vm = this;
    	vm.items;
    	vm.resourceName = "class" //name of resource You want to make request at
    	vm.params = {includeAll: true} //request params
    	openmrsRest.listFull(vm.resourceName, vm.params).then(function(response)(
    		vm.items = response.results; //store response in variable
    	));
    }

    OpenMRS Rest API returns multiple objects wrapped in single "results" object. There are multiple functions avalaible: list, listFull, listRef, get, getFull, getRef, create, update, remove, retire, unretire, purge.

    For further information, check OpenMRS Rest API docs here.

    Header Component

    Header component adds default OpenMRS header to Your web page. To use it, You have to inject it's module in Your module, as follows:

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.header']);

    create variable in Your controller, which will hold title of Your application:

    angular.module('YourAngularModule').controller('controller', controller);
    
    function controller() {
    	var vm = this;
    	vm.appTitle = "Your app title";
    }

    And insert component in html file, binding appTitle variable to it:

    <html ng-app="YourAngularModule">
      	<div ng-controller="controller as vm">
    		<openmrs-header title="vm.appTitle"></openmrs-header>
    	</div>
    </html>

    Breadcrumbs Component

    Breadcrumbs component adds Reference Application-styled breadcrumbs to Your web page. To use it, You have to inject it's module in Your module, as follows:

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.breadcrumbs']);

    create variable in Your controller, which will hold map of Your links and labels:

    angular.module('YourAngularModule').controller('controller', controller);
    
    function controller() {
    	var vm = this;
        vm.links = {};
        vm.links["label1"] = "link1/";
        vm.links["label2"] = "link1/link2/";
    }

    And insert component in html file, binding links variable to it:

    <html ng-app="YourAngularModule">
      	<div ng-controller="controller as vm">
    		<openmrs-breadcrumbs links="vm.links"></openmrs-breadcrumbs>
    	</div>
    </html>

    Concept Autocomplete Component

    Concept autocomplete component adds concept input box to Your page. It suggests names of existing concepts by current user input, allows user to choose one of sugestions, and shows warning message, when query doesn't match any concept. You can choose if it searches drug concepts, or any concepts. To use it, You have to inject it's module in Your module, as follows:

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.concept-autoComplete']);

    create variables in Your controller:

    angular.module('YourAngularModule').controller('controller', controller);
    
    function controller() {
    	var vm = this; 
    	vm.required = false; //if truthy, input box will be required
    	vm.limitToClass = 'Drug'; //component will search only drug concepts
    	vm.isConceptCorrect;	//flag, if current query matches any concept name
    	vm.updateConcept = updateConcept;
    	//item is object with property "display", which is passed to component at activation (make it empty if there has to be no initial state)
    	vm.item = {
    			display: 'ItemName'
    	}
    	//function, which will be invoked at any change of component model, in this example it
    	function updateConcept(isCorrect, concept) {
    	    vm.isConceptCorrect = isCorrect;
    	    vm.item = concept;
    	 };
    }

    And insert component in html file, binding variables to it:

    <html ng-app="YourAngularModule">
      	<div ng-controller="controller as vm">
    		<concept-auto-complete required='vm.required' concept='vm.item' limit-to-class='vm.limitToClass' on-update='vm.updateConcept(isCorrect, concept)'>
    		</concept-auto-complete>
    	</div>
    </html>

    List Component

    List Component is used to insert lists and tables filled with specified OpenMRS REST resources.

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.openmrs-list']);

    To configure attributes of this components, its recommended to pass values from controller to component attributes placed in `` tags.

    List Component attributes documentation:

    • resource="<String>" - Resource name for REST Service.
      Example: "conceptsource" or "conceptclass" (see REST WS API Documentation)
    • columns="<Object>" - Object that tells component how to divide columns of table/list and which label/property should it use.
      Example:
    vm.columns= [
            {
                "property": "name", // Name of variable that is contained inside all resource objects placed in table
                "label": "Name" // Label of column header for specified property (its possible to pass translate value here)
            },
            {
                "property": "hl7Code",
                "label":"HL7 Code"
            },
            {
                "property": "description",
                "label":"Description"
            }];
    • type="<String>" - Default 'table', defines if component should look like 'list' (i.e. like conceptSearch view) or 'table' (i.e. like referenceSearch view).
    • actions="<Object>" - Default [{"action":"view", "label":"View"}], defines which actions can be performed on object via list/table.
      Example:
    vm.actions = [
            {
                "action":"edit", //Action name, possible values: 'edit', 'view', 'retire', 'unretire' and 'purge'.
                "label":"Edit", //Label that is shown when user hovers action button, when not defined it takes action name value.
                "link":"#/source/{uuid}" //Link pattern that is used to redirect to proper 'edit' or 'view' page ({uuid} is automaticly replaced with specific uuid)
            },
            {
                "action":"retire", //Retire action needs to be implemented along with unretire action
                "label":"Retire"
            },
            {
                "action":"unretire",
                "label":"unretire"
            },
            {
                "action":"purge",
                "label":"Delete",
                "icon":"icon-trash delete-action" // Icon from OpenMRS CSS (See http://demo.openmrs.org/openmrs/uicommons/icons.page for more). Has default values for all actions, 'delete-action' means that it will be red-colored when hovering button.
            }
        ];
    • enable-search="<boolean>" - Default false, defines if there should be search panel instead of table/list only.
      Example: type true for referenceSearch-like panel or type false for sourceList-like panel
    • limit="<int>"- Default 10, defines how many entries should be seen per page of list/table (Note that navigation buttons aren't visible when all entries fits in one page)
    • list-all="<boolean>" - Default false, defines if there should be retired entries visible on table/list

    Example controller:
    angular.module('YourAngularModule').controller('controller', controller);
    
    function controller() {
    	var vm= this;
    	vm.resource = "conceptsource";
            vm.columns= [
                {
                    "property": "name",
                    "label": "Name"
                },
                {
                    "property": "hl7Code",
                    "label":"HL7 Code"
                },
                {
                    "property": "description",
                    "label":"Description"
                }];
            vm.actions = [
                {
                    "action":"edit",
                    "label":"Edit",
                    "link":"#/source/{uuid}"
                },
                {
                    "action":"retire",
                    "label":"Retire"
                },
                {
                    "action":"unretire",
                    "label":"unretire"
                },
                {
                    "action":"purge",
                    "label":"Delete",
                    "icon":"icon-thumbs-down delete-action"
                }
            ];
    }

    Passing example values to component:

    <html ng-app="YourAngularModule">
      	<div ng-controller="controller as vm">
    				<openmrs-list resource="vm.resource" columns="vm.columns" actions="vm.actions" list-all="true"></openmrs-list>
    	</div>
    </html>

    Notification service

    Notification service is wrapper for angular-toastr, with adjusted stylesheets and managed dependencies. To use it, inject it's module to Your module:

    angular.module('YourAngularModule',['openmrs-contrib-uicommons.notification']);

    inject openmrsNotification service to Your controller:

    angular.module('YourAngularModule').controller('controller', controller);
    
    controller.$inject('openmrsNotifiation');
    function controller(openmrsNotification) {
    	var vm = this;
    	//...
    }

    to show toast message, call from Your controller one of methods - info, error, warning, success, eg.

    //shows info message
    openmrsNotification.info(content, title);

    It's allowed to pass only content parameter to show message without title.

    Production Build

    You need to have NodeJS in version 5.3.x installed. We recommend using nvm or nvm-windows to install and manage different versions of Node.

    Once you have NodeJS installed, install the dependencies (first time only):

    npm install
    

    Build the distributable using webpack as follows:

    npm run build
    

    This will create a lib directory, which will contain Your bundled library files.

    Development

    Demo Application

    The easiest way to develop components is to use the demo application.

    To create development environment, first You have to install dependencies as described in Production Build. Project contains demo app, where You can see components and modules in action. To use it, You have to run OpenMRS server locally with Open Web Apps and Webservices modules. You can find how to do that here.

    To deploy directly to your local Open Web Apps directory, run:

    npm run build:deploy

    This will build and deploy the app to directory specified in LOCAL_OWA_FOLDER value in ./config.json, created by dev. If config.json is absent, app will be deployed to /dist directory.

    It is also possible to configure the project so that whenever a file is changed it is deployed to a server and a browser is refreshed. First please make sure the APP_ENTRY_POINT is set in config.json as follows:

    {
      "LOCAL_OWA_FOLDER": "C:\\\\Users\\\\rafal\\\\openmrs\\\\serverName\\\\owa\\\\",
      "APP_ENTRY_POINT":"http://localhost:8080/openmrs/owa/openmrs-contrib-uicommons/index.html"
    }

    Next run:

    npm run watch

    While it runs, it watches all files for changes and automatically updates your browser.

    External Client Application

    You can develop and test Openmrs-contrib-uicommons in other application, using npm link feature. In order to do this, You just need to run

    npm link

    in Your openmrs-contrib-uicommons directory. Npm will add link to this package to its global node_modules. Then run

    npm link openmrs-contrib-uicommons

    in Your client application directory. From now on, every change You make in uicommons will be reflected in client application node_modules. Remember to build openmrs-contrib-uicommons, as client code use bundle from lib/ directory and then build Your application.

    To break the link, in client directory run

    npm unlink openmrs-contrib-uicommons

    To unlink openmrs-contrib uicommons, in its directory run

    npm unlink

    Release Procedure

    To release new version of Openmrs-contrib-uicommons, run from master branch:

    npm version patch

    It will automatically increment package version in package.json file, create git release commit and tag with names corresponding to current version. Then push tags:

    git push remote_repo_name master
    git push --tags remote_repo_name

    where 'remote_repo_name' refers to https://github.com/PawelGutkowski/openmrs-contrib-uicommons.git.

    Tag will be automatically built on Travis-CI and deployed to npm.

    License

    MPL 2.0 w/ HD © OpenMRS Inc.

    Install

    npm i @openmrs/openmrs-contrib-uicommons

    DownloadsWeekly Downloads

    4

    Version

    1.0.0

    License

    MPL-2.0

    Last publish

    Collaborators

    • ibacher
    • mogoodrich
    • openmrs-bot
    • rkorytkowski
    • psbrandt
    • djazayeri
    • joeldenning
    • fatmali
    • mksd
    • rrameshbtech
    • brandones
    • jdick
    • bmamlin
    • dkibet
    • florianrappl
    • mdubey
    • dennisforthewin