FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

MockDataCFC

v3.4.0+35 Public

Build Status

MockData CFC

This is a ColdFusion version of the MockData Node.js service.

MockData is a simple service to generate fake JSON data as a JSON REST service, a ColdBox Module or a simple CFC Service API. The idea being that you may be offline, may not have access to an API, or simply need some fake data to test on your front end or seed a complete database with fake data.

MockDataCFC allows you to define the return JSON model in a very deterministic and simple modeling DSL. Read on 🚀 for some modeling goodness!

Requirements

  • ColdFusion 2016+
  • Lucee 5+

Installation

Leverage CommandBox and type box install mockdatacfc

Usage

Once installed you can leverage it in different ways:

  1. CFC : Install it into your CFML application, instantiate the MockData.cfc and call the mock method using the mocking argument DSL: new mockdatacfc.models.MockData().mock().
  2. REST Service : Startup a CommandBox server in the root of the package once installed (box server start) and execute it via port: 3000. You can execute GET commands and pass the mocking DSL via the query string or execute a POST command with the mocking DSL as the body in JSON.
  3. ColdBox Module : Install it via CommandBox in a ColdBox app and hit the service via /mockdataCFC with a GET using the query string mocking DSL or a POST using the mocking DSL as the body in JSON. You can also get access to the mocking instance via the WireBox ID: [email protected] and call the mock method using the mocking argument DSL.

Customizing the service port

To specify a port or change the port, just add it an argument to the server start command or modify the server.json port configuration to your liking. You can even add SSL if you need to.

box server start port=XXXX

Getting Data

To get data from the REST service, point your XHR or cfhttp calls to the following entry points and either pass the mocking DSL via the query string or as a JSON POST body.

# Standalone Service
http://localhost:3000/

# ColdBox Module Service
http://localhost:8080/mockdataCFC

By default it will produce a glorious array of 10 objects of nothing! Since we did not specify any modeling data. So let's continue.

Note: MockData uses CORS so if you're running a virtual domain then you will still be able to hit the service.(As long as you have a decent browser.)

Number of objects ($num)

The number of objects to be returned by the service is determined by the $num argument, which defaults to 10 items:

# service call
http://localhost:3000/?$num=5

# ColdBox Module Service
http://localhost:8080/mockdataCFC?$num=5

# Module API
var data = getInstance( "MockData[email protected]" )
    .mock(
        $num = 5
    );

Random Numbers

You can also specify a random return number by using the following forms:

  • $num:rand: 10 - A random number between 1-10.
  • $num:rand: 5:20 - A random number between 5-20.
# service call
http://localhost:3000/?$num=rand:10

# ColdBox Module Service
http://localhost:8080/mockdataCFC?$num=rand:10

# object
var data = getInstance( "[email protected]" )
    .mock(
        $num = "rnd:10: 20"
    );

Available return types ($returntype)

By default the service/method call will return X amount of records in the form of an array. However, if you would like to just return an object literal representation you can do so via the $returnType argument.

Available return types:

  • array - Default, returns an array of objects
  • struct - Returns an object literal struct
// Method Call
var data = getInstance( "[email protected]" )
    .mock(
		$returnType = "struct",
		name = "name",
		age = "age",
		id = "uuid",
		email = "email"
	);
// Service call
http://127.0.0.1:60299/MockDataCFC?$returnType=struct&name=name&age=age&id=uuid&email=email

// The output will be something like this
{
    "id": "91659091-A489-4706-BAC64FA8E1665509",
    "name": "Danny Tobias",
    "age": 33,
    "email": "[email protected]"
}

Available Mocking Types

The available types MockDataCFC supports are:

  • age: Generates a random "adult" age of 18 to 75.
  • all_age: Generates a random age of 1 to 100.
  • autoincrement : Returns an incremented index starting from 1
  • baconlorem: Returns bacon lorem ipsum text. If used as baconlorem:N, returns N paragraphs. If used as baconlorem❌ Y, returns a random number of paragraphs between X and Y.
  • date: Generates a random date
  • datetime: Generates a random date and time value
  • email: Generates a random email.
  • fname: Generates a random first name.
  • imageurl : Generates a random image URL with a random protocol
  • imageurl_http : Generates a random image URL with http only protocol
  • imageurl_https : Generates a random image URL with https only protocol
  • ipaddress : Generates an ipv4 address
  • name: Generates a random name.
  • lname: Generates a random last name.
  • lorem: Returns lorem ipsum text. If used as lorem:N, returns N paragraphs. If used as lorem❌ Y, returns a random number of paragraphs between X and Y.
  • num: By default, a number from 1 to 10. You can also use the form num:X for a random number between 1 and X. Or num❌ Y for a random number between X and Y.
  • oneof❌ y: Requires you to pass N values after it delimited by a colon. Example: oneof:male: female. Will return a random value from that list.
  • rnd:N, rand:N, rnd❌ y, rand❌ y : Generate random numbers with a specific range or range cap.
  • sentence: Generates a sentences. If used as sentence:N, returns N sentences. If used as sentence❌ Y, returns a random number of sentences beetween X and Y.
  • ssn: Generates a random Social Security number.
  • string: Generates a random string of length 10 by default. You can increase the length by passing it string:length.
  • string-alpha : Generates a random alpha string of length 10 by default. You can increase the length by passing it string-alpha:length.
  • string-numeric : Generates a random numeric string of length 10 by default. You can increase the length by passing it string-numeric:length.
  • string-secure : Generates a random secure (alpha+numeric+symbols) string of length 10 by default. You can increase the length by passing it string-secure:length.
  • tel: Generates a random (American) telephone number.
  • uuid: Generates a random UUID
  • url : Generates a random URL with a random protocol
  • url_http : Generates a random URL with http only protocol
  • url_https : Generates a random URL with https only protocol
  • website : Generates a random website with random protocol
  • website_http : Generates a random website, http only protocol
  • website_https : Generates a random website, https only protocol
  • words: Generates a single word. If used as word:N, returns N words. If used as words❌ Y, returns a random number of words beetween X and Y.

Calling Types By Function Name

Please check out the apidocs at : https://apidocs.ortussolutions.com/#/coldbox-modules/MockDataCFC/ for the latest methods, but you can also use the mocking methods instead of going via the mock() method.

  • baconLorem()
  • dateRange()
  • email()
  • firstName()
  • imageUrl()
  • ipAddress()
  • lastName()
  • lorem()
  • num()
  • oneOf()
  • sentence()
  • ssn()
  • string()
  • telephone()
  • uri()
  • websiteUrl()
  • words()

Supplier Type (Custom Data)

You can also create your own content by using a supplier closure/lambda as your type. This is a function that will create the content and return it for you.

Please note that this only works when using the direct function call approach, not the service

"name" : function( index ){
	return "luis";
}

The function receives the currently iterating index as an argument as well. All you need to do is return back content.

Mocking DSL

In order to define the type of data returned, you must specify one or more additional query string variables or arguments. The form is name_of_field=type, where name_of_field will be the name used in the result and type is the type of data to mock the value with.

http://localhost:3000/?$num=3&author=name

# object
var data = getInstance( "[email protected]" )
    .mock(
        $num = 3,
        "author" = "name"
    );

This tells the service to return 3 objects with each containing an author field that has a type value of name. (More on types in a minute.) The result then would look something like this:

[
    {
        author: "Frank Smith"
    },
    {
        author: "Gary Stroz"
    },
    {
        author: "Lynn Padgett"
    }
]

Additional fields for the object model can just be appended to the URL or method call:

http://localhost:3000/?$num=3&author=name&gender=oneof:male:   female

# object
var data = getInstance( "[email protected]" )
    .mock(
        $num = 3,
        "author" = "name",
        "gender" = "oneOf:male:   female"
    );

Which gives...

[
    {
        author : "Lisa Padgett",
        gender : "male"
    },
    {
        author : "Roger Clapton",
        gender : "male"
    },
    {
        author : "Heather Degeneres",
        gender : "male"
    }
]

Nested Data

Since version v3.0.0, MockDataCFC supports the nesting of the field models to represent rich and complex JSON return structures. We currently support the following nested types:

  • array of objects - name = [ { ... } ]
  • array of values - name = [ { $type = "" } ]
  • object - name = { ... }

Let's imagine the following object graph:

Author
    Has Many Books
        Has Many Categories
    Has Keywords
    Has A Publisher

I can then use this mocking DSL to define it:

getInstance( "[email protected]" )
    .mock(

        fullName    = "name",
        description = "sentence",
        age         = "age",
        id          = "uuid",
        createdDate = "datetime",
        isActive	= "oneof:true: false",

        // one to many complex object definitions
        books = [
            {
                $num = "rand:1:      3",
                "id" = "uuid",
                "title" = "words:1:      5",
                "categories" = {
                    "$num"      = "2",
                    "id"        = "uuid",
                    "category"  = "words"
                }
            }
        ],

        // object definition
        publisher = {
            "id" 	= "uuid",
            "name" 	= "sentence"
        },

        // array of values
        keywords = [
            {
                "$num" 	= "rand:1:      10",
                "$type" = "words"
            }
        ]
    );

Nested Array of Values

To create nested array of values you will define the name of the property and then an array with a struct defining how many and of which type using the special keys: $num, $type

// array of values
keywords = [
    {
        "$num" 	= "rand:1:      10",
        "$type" = "words"
    }
]

Nested Array of Objects

To create nested array of objects you will define the name of the property and then an array with a struct defining how many and the definition of the object (Not there will be no type key):

// array of objects
books = [
    {
        $num = "rand:1:      3",
        "id" = "uuid",
        "title" = "words:1:      5",
        "categories" = {
            "$num"      = "2",
            "id"        = "uuid",
            "category"  = "words"
        }
    }
]

Nested Object

To create a nested object you will define the name of the property and then a struct defining it:

// object definition
publisher = {
    "id" 	= "uuid",
    "name" 	= "sentence"
}

Dependencies (0)


Dev Dependencies (0)


Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


[3.4.0] => 2020-JUN-03

Added

  • string type re-architected to produce more randomness and more permutations according to our new generation pattern: string[-(secure|alpha|numeric):max] #6
  • More formatting rules
  • Changelog standards
  • Auto publishing to github (artifacts and changelogs)
  • Types are now case-insensitive when called: num,oneof,lorem,baconlorem,sentence,words #5
  • generateFakeData() is now public
  • All generators can now be called individually by function name
  • lorem,baconlorem,words,sentence you can now produce random sizes with them via min:max notation
  • Optimized generation by using arrays instead of strings
  • Included libraries for nouns and adjectives

Changed

  • Access variables according to scopes instead of lookup
  • Internal data generation names to avoid method conflicts

Fixed

  • Access variables according to scopes
  • $returnType is not documented #8

[3.3.1] => 2020-APR-16

Fixed

  • param the default method when executing via URL instead of setting it.

[3.3.0] => 2020-JAN-28

New Features

  • ipaddress : Generates an ipv4 address
  • New type: string which generates random hash strings of certain length. Default is 10 characters.
  • New type: website to generate random protocol based websites
  • New type: website_http to generate http only based websites
  • New type: website_https to generate https only based websites
  • New type: imageurl : Generates a random image URL with a random protocol
  • New type: imageurl_http : Generates a random image URL with http only protocol
  • New type: imageurl_https : Generates a random image URL with https only protocol
  • New type: url : Generates a random URL with a random protocol
  • New type: url_http : Generates a random URL with http only protocol
  • New type: url_https : Generates a random URL with https only protocol

Improvements

  • Added new domains for more random generation
  • Removed spacing from words

[3.2.0] => 2020-JAN-08

New Features

  • Added the ability for a type to be a closure/lambda to act as a supplier. This way, this function will be called every time for you to supply the result. It receives the current iterating index as well: function( index ){}

Improvements

  • Formatting of source via cfformat
  • Fixes for api doc creations to use the project mapping
  • Functional update of json service to filter out reserved rc keys
  • TestBox 3 upgrade
  • More direct scoping of the arguments scope

[3.1.0] => 2019-MAY-19

  • CommandBox ability to execute
  • Template updates to standards

[3.0.0] => 2018-SEP-4

  • Compatibility : num arguments have been dropped and you must use $num as the identifier for how many items you like
  • Introduction of nested mocking. You can now declare nested mocks as structs and the mock data will nest accordingly:
getInstance( "[email protected]" )
	.mock(
		books=[{
			num=2,
			"id"="uuid",
			"title"="words:1: 5"
		}],
		fullName="name",
		description="sentence",
		age="age",
		id="uuid",
		createdDate="datetime"
	);

This will produce top level mock data with 2 books per record.

  • Nested Data for array of objects, array of values and simple objects
  • ACF Compatibilities
  • Updated readmes and syntax updates for modern engines
  • Upgraded to new ColdBox module Harness

[2.4.0]

  • Added auto-incrementing ID's FOR REAL this time

[2.3.0]

  • Added auto-incrementing ID's
  • Update on build control
  • Syntax Ortus Updates, addition of private methods
  • allow for use of rand or rnd for num generators
  • Add CORS support for ColdBox REST Module
  • Bug on isDefault() always returning true.
  • Added tests and automation

[2.2.0]

  • Made it a module as well for ColdBox apps.

[2.0.0]

  • Added support for words, sentences, uuid, bacon lorem, date and datetime
  • Added CommandBox Support
  • Added Documentation
  • Added ability to execute as a CFC instead of only via web service

[1.0.0]

Original by Ray Camden

 

$ box install mockdatacfc

No collaborators yet.
     
  • Oct 19 2016 08:52 AM
  • Jun 04 2020 08:17 AM
  • 1,942
  • 1,755
  • 19,542