README.md

This repository contains the ArrayMixer source code. ArrayMixer is a tiny javascript lib with less than 1kb made to help ordering groups of arrays in a very personalized manner. Powerful and easy to use.

Table of contents

• Common usage
• Installation
  • Node projects
  • Web projects
• Parameters
  • Aliases
  • Sequence
• Examples
  • Example 1) For every 7 photos display an ad:
  • Example 2) For every 4 paragraphs of text include 2 images:
  • Example 3) In a group of 8 related links reserve positions 5 and 6 for sponsored links:
  • Example 4) Display a list of songs including the most successful songs for every 10 songs:
  • Example 5) You can also use larger aliases and the ES6 object shorthand:
  • Example 6) View photos of puppies, kittens and penguins in sequence:
  • Example 7) Include 1 large photo for every 2 medium size photos followed by 3 small photos:
  • More examples
• Contributing
• License
• Special thanks

Common usage

Let's think we have two arrays: photos and ads.

photos.length === 12; // true
ads.length === 6; // true

Use ArrayMixer to create a new array containing 2 photos followed by 1 ad until the end of both arrays.

let mixedArray = ArrayMixer({P:photos, A:ads}, ["2P", "1A"]);

So mixedArray will contain:

Installation

ArrayMixer can be used in node projects and web projects.

Node projects

Requires node version 5.7 or later.

npm install array-mixer --save

Import it to your code using:

const ArrayMixer = require("array-mixer");

Web projects

Download latest ES5 transpiled version from unpkg.com.

Import ES5 transpiled version to your code.

<script src="https://unpkg.com/array-mixer@0.7.2/release/array-mixer.js"></script>

Parameters

ArrayMixer has only two mandatory parameters.

let aliases = {M:myArray, O:otherArray};
let sequence = ["3M", "5O"];

let mixed = ArrayMixer(aliases, sequence);

Aliases

This parameter should be an object with keys used as alias for sequence and key values pointing to avaliable arrays.

Sequence

This parameters uses the aliases defined on aliases parameter to create a sequence order to display the arrays.

Examples

ArrayMixer can be used combining different arrays, aliases and sequences. The following examples shows some ways to use it.

Example 1) For every 7 photos display an ad:

ArrayMixer({F: Photos, A: Ads}, ["7P", "1A"]);

or (as number 1 on sequence can be ommited):

ArrayMixer({F: Photos, A: Ads}, ["7P", "A"]);

Example 2) For every 4 paragraphs of text include 2 images:

ArrayMixer({P: paragraphs, I: images}, ["4P", "2I"]);

Example 3) In a group of 8 related links reserve positions 5 and 6 for sponsored links:

ArrayMixer({R: related, S: sponsored}, ["4R", "2S", "2R"]);

Example 4) Display a list of songs including the most successful songs for every 10 songs:

ArrayMixer({M: musics, H: hits}, ["10M", "2H"]);

Example 5) You can also use larger aliases and the ES6 object shorthand:

ArrayMixer({days, weekend}, ["5days", "2weekend"]);

You can manipulate more than two vectors at a time, as in the following example:

Example 6) View photos of puppies, kittens and penguins in sequence:

let mixed = ArrayMixer({puppies, kittens, penguins}, ["puppies", "kittens", "penguins"));

puppies	kittens	penguins	mixed
[🐶, 🐶, 🐶]	[🐱, 🐱, 🐱]	[🐧, 🐧, 🐧]	[🐶, 🐱, 🐧, 🐶, 🐱, 🐧, 🐶, 🐱, 🐧]

Example 7) Include 1 large photo for every 2 medium size photos followed by 3 small photos:

Tip: ArrayMixer lets you mix three or more arrays at once.

ArrayMixer({L:large, M:medium, S:small}, ["2M", "3S", "L"]);

Disclaimer: All arrays mentioned in this section must exist for the examples to work.

More examples

For more example please check the specification file.

Contributing

You may contribute in several ways like creating new features, fixing bugs, improving documentation and examples or translating any document here to your language. Find more information in CONTRIBUTING.md.

License

MIT - Jota Teles - 2017

Special thanks

• Willian Ribeiro;
• João Paulo;