Ixaris UX Framework

A set of libraries to facilitate the development of front-end applications.

Installation

npm install ixaris-uxf --save

Facilitating App Development

Internationalization

Routing

Routing is an essential mechanism we definitely need in place for all of our applications. Unlike Angular, for example, ReactJS does not offer its inbuilt routing. We want to use ReactJS but we also want our pages to cater for routing, and so as part of the UX Framework we wrote our routing mechanism.

Since multiple frameworks and libraries can co-exist within an application written in ixaris-uxf, routing needed to be uniform for all different components.

Resource and ResourceService

Resource

Defining a Resource is easy as:

var Resource = require('ixaris-uxf').Resource;
 
var MyResource = new Resource('http://localhost:8080/my-app/myResource');
 
module.exports = MyResource;

... which will give you a resource with all HTTP methods (get, post, put, patch, delete) automatically.

When you want to trigger an action (e.g. get) on your resource, you can then do:

var MyResource = require('MyResource');
MyResource.get({id : 'you'}, function(body, response) {
	//whatever when all goes well
}, function(err,res) {
	// whatever when everything fails
});

If you want to define custom actions on your resource all you need to do is pass the definition in the constructor.

var Resource = require('ixaris-uxf').Resource;
 
var MyResource = new Resource('http://localhost:8080/my-app/myResource', 
								{ myAction : { 
									url : 'http://localhost:8080/my-app/myResource/:id/myAction', 
									method : 'POST'
									}
								}
							);
module.exports = MyResource;

Then invoke it by calling MyResource.myAction({id : 'you'});

Yes - we also take care to replace path parameters.

ResourceService Features

With ResourceService you can define default headers for your app, for instance:

// default headers for ALL POST calls in the application
ResourceService.defaults.headers.post['Content-Type'] = 'application/json';
// default headers for ALL CALLS in the application
ResourceService.defaults.headers.common['Content-Type'] = 'application/json';

You can also define interceptors:

ResourceService.interceptors.push({
    request : function(req) {
            // whatever...
        }
    },
	response : function(err, res, req) {
		// response 
	}
});

StyleService

StyleService embraces use of Radium, for which we suggest you use radium-stylify to pre-compile in Javascript.

Branding allows you to load and access a set of application wide variables (stile LESS or SASS).

	{
		"vars" : {
			"@color-bg-main" : "blue",
			"@padding-header-logo" : "10px"
		}
	}

We can then call the variable as follows:

var Menu = React.createClass({
 ...
 render : function() {
    var styles = {
        myStyle : {
            backgroundColor : [Branding.get('@color-bg-main'), 'blue']
        }
    }
 }
});

Locale adjusts the style to conform the document direction. If, in the styles or in the style-config.json you want to define a padding-left (for example) which you want to react according to whether the language is LTR or RTL - define it as paddingStart. The StyleService.localizeStyle(_styleObject) will change it for you.

This applies for padding,margin,border,float.

Metadata

In v0.1.1 Metadata is a higher order component which uses the given metadata to define a React component. The following is the spec:

var MyComponent = React.createClass({
    // normal React Component API hooks such as componentWillMount, componentDidMount, etc
     
    metaData : {
        documentation : 'In here I document what MyComponent does, and cool things about it',
        displayName : 'MyComponentDisplayName',  //defaults to `MyComponent` (extracted from the variable name) if undefined
        keywords : ['my','component','keywords'],
        type : MetaData.ComponentType.BLOCK, // This can be either BLOCK or INLINE or FLEX
        props : {
            propertyOne : {
                documentation : 'In here I document why this property is useful, etc',
                type : React.PropTypes.string.isRequired, //Normal React property validation usually used in propTypes
                defaultValue : 'Default Value Goes Here'
            }//,
            //propertyTwo: ...
        }
        children : {
            childValidationOne : {
                documentation : 'I want to validate that MyComponent gets at exactly 3 div children',
                type : ChildValidation.Exactly(3).ofType('div')
            }//,
            //childValidationTwo: ...
        }
    }
 
});
 
module.exports = MetaData(MyComponent);

The aim of Metadata is to:

• enforce documentation of reusable components and their attributes (props, child-nodes, etc)
• group propTypes and their defaultValue as prop definition`
• validate child nodes

ChildValidation

Allows you to validate the DOM nodes given as child elements.

First you can validate the number of nodes:

| Validation | Parameters | Description | | ------------- |:-------------:| ------| | ExactlyOne | | Checks for exactly one child element | | Exactly | n - integer |Checks for exactly n child elements| | AtLeastOne | |Checks that there is at least one child element| | AtLeast | n - integer | Checks that there are at least n child elements| |AtMostOne| |Checks that there is no more than one child element| |AtMost| n - integer |Checks that there are no more than n child elements| |Any| |Accepts any number of child elements|

Then you can validate the type. If you leave types out, type checking is not done.

| Validation | Parameters | Description | | ------------- |:-------------:| ------| | ofType | String elementType |Checks that child elements are of the specified elementType - matching to the native element.type, such as div, a, p, span and so on.| | ofType | [String] elementTypes |Checks that child elements are either of the specified types specified in the Array elementTypes - matching to the native element.type, such as div, a, p, span, and so on.| | ofType |Constructor reactComponentType|Checks that the child elements are of the particular type as defined by the Constructor specified in reactComponentType. Although this can be any Function, this feature has been tested specifically with React Constructor.|

Example

children : {
    additionalDivs : {
        documentation : 'Checks that the child elements follow the additional child div elements specified by this spec',
        type : ChildValidation.Exactly(5).ofType('div')
    },
	additionalChildren : {
        documentation : 'Checks that the child elements are not more than a specified number',
        type : ChildValidation.Exactly(5)
    },
	anyNumberOfSpanOrDiv : {
        documentation : 'Accepts any number of children as long as they are either div or span',
        type : MetaData.ChildValidation.Any.ofType(['div','span'])
    }
}

TestUtils

We provide some testing utilities that will help you write your component tests.

| Function Name | Parameters | Description | | ------- |------------------------| ------| |captureLog| fn - function which will be run and tested for logs | Captures any console.log while a given function fn is being called. Returns array of captured logs.| |captureInfoLog| fn - function which will be run and tested for info logs | Captures any console.info while a given function fn is being called. Returns array of captured info logs.| |captureWarnLog | fn - function which will be run and tested for warn logs | Captures any console.warn while a given function fn is being called. Returns array of captured warn logs.| |captureErrorLog| fn - function which will be run and tested for errors | Captures any error logs while a given function fn is being called. Returns array of captured error logs.| |initiateGlobals| |Initiates document and window global variables with proper values which can be used for DOM manipulation.| |testAsync| fn - function which contains asynchronous code to be asserted upon; done - the Mocha done function for the test. This is used in case fn fails; timeout - a timeout used to wait until the callback function is to be executed. (warning) Defaults to 10ms, and should be not more than 2000ms; |Returns a Promise whose then method is already chained with a catch reporting any errors occurred in assertions. Used to test asynchronous code. On success callback make sure you insert the done method.| |ComponentInteractionTest| API is a Constructor. Takes no arguments| Returns a set of APIs which allow you to interact with a browser while testing your components.| |ComponentInteractionTest.engine | | Determines the engine (whether Gecko, WebKit, Trident or jsdom)| |ComponentInteractionTest.takeScreenshot | -dirname : Name of directory where the screenshot will be saved; -filename : Filename for screenshot; | Takes a screenshot from the headless browser and saves it in the given directory, under the given name| |ComponentInteractionTest.sendEvent| | Sends event to the browser. See mocha-phantomjs-core| |ComponentInteractionTest.changeViewportSize| width,height - for browser viewport | Changes the browser's viewport size. See mocha-phantomjs-core| |ComponentInteractionTest.React.render| | Calls the render function depending on the environment the test is being run. If the test is run on jsdom then ReactTestUtils.renderIntoDocument is used. Otherwise, (i.e. if PhantomJS or SlimerJS are invoked), React.render.

Contribute

You are encouraged to discuss and contribute - make sure you run and comply to the test suite before:

npm test

Release History

• 0.1.1 Initial release
• 0.1.2 Added better documentation in README.md
• 0.1.3 Updated react-styling

License

ISC