Get started with wheely-base

wheely-base is a core library used by wheely-widgets. It holds references to 1 class: State. Furthermore it holds references to 4 objects: views, maps, fetchData and base. Each object has it own objects that can be either called or consist of multiple objects. The core functionality of wheely-base is to fetch car data based on user input and return views with it. Wheely-base has a couple of dependents each with it's own functionality and calculations. Wheely-base allows you to create a similar widget from scratch.

##Apply for your API key All fetch requests needs an API key. This key can be received by contacting the berekenautokosten.nl team at [email protected]. You can also apply for an API key by visiting: https://fixx-it.portal.azure-api.net/. You can then sign up for an API, from there the berekenautokosten team has to allow you to make a call. The Azure portal also gives a broader documentation about API usage.

##Install wheely-base

npm install wheely-base

##Usage of wheely-base Install wheely-base.

const wheelyBase = require('wheely-base');

##State You can inherit state by extending using the built-in state object.

export class LocalFeature extends wheelyBase.State {
    constructor(props) {
        super(props)
    }

    mapFields() {
        // mapping fields
    }
}

##Views There are 2 types of views: views created for callbacks (make, model, version) and views that are static (button, etc.).

###Static views 9 static views are accessible through the views.static object.

####inputView Creates an inputView based on your settings

wheelyBase.views.static.inputView(
    {
        label : 'element_name', 
        id : 'element_id'
    }
);

####buttonView Creates static button.

wheelyBase.views.static.buttonView(
    {
        label : 'element_name', 
        id : 'element_id'
    }, 
    {
        color : 'color'
    }
);

####kentekenView Creates an kentekenView based on your settings.

wheelyBase.views.static.kentekenView(
    {
        label : 'element_name', 
        id : 'element_id'
    }
);

####selectView Creates select element.

wheelyBase.views.static.selectView(
    {
        label : 'element_name', 
        id : 'element_id',
        fields : [
            {
                value : 'value',
                innerhtml : 'text'
            }
        ]
    }
);

####emptySelectView Creates an empty select element.

wheelyBase.views.static.emptySelectView(
    {
        label : 'element_name', 
        id : 'element_id'
    }
);

####optionsView Creates options inside a select element.

wheelyBase.views.static.optionsView(
    {
        fields : [
            {
                value : 'value',
                innerhtml : 'text'
            }
        ]
    }
);

####sliderView Creates a single is range view.

wheelyBase.views.static.sliderView(
    {
        label : 'element_name', 
        id : 'element_id',
        options : {
            min : 0,
            max : 100,
            default : 50
        }
    }
);

####doubleSliderView Creates a double is range view. If you required an inner checkbox, you have to create an optional inner object called options and fill the attributes innerCheckboxLabel and innerCheckboxId.

wheelyBase.views.static.doubleSliderView(
    {
        label : 'element_name', 
        id : 'element_id',
        options : {
            min : 0,
            max : 100,
            default : 50
            innerCheckboxLabel : 'checkbox_name',
            innerCheckboxId : 'checkbox_id'
        }
    }
);

####disclaimerView Creates a disclaimer.

wheelyBase.views.static.disclaimerView(
    {
        title : 'title', 
        description : 'description'
    }
);

###Callback views 3 callback views are accessible through the views.callback object. Usually those views are used by NPM wheely packages only.

####makeView Creates dropdowns for makes. Expects object from the wheely makes or wheely models api.

wheelyBase.views.callback.makeView(
    {
        data : data,
        success : success
    }
);

####ModelView Creates dropdowns for models with a listener as reference to the versions dropdown. Expects object from the wheely search api.

wheelyBase.views.callback.modelView(
    {
        data : data,
        success : success
    }
);

####VersionView Creates dropdowns for versions. Expects object from the wheely versions api.

wheelyBase.views.callback.versionsView(
    {
        data : data,
        success : success
    }
);

##Wheely Map Methods 1 map available. All methods are part of maps object.

###returnTCOMap TCO Map that holds an array where each object represent a key of the TCO API's. It's used for displaying fields, determine if a value is a currency, translating names and render static or editable HTML.

let localMap = wheelyBase.maps.TCO_MAP.slice();

returnTCOMap object example:

{
    name : 'monthlyCosts-insurance-liabilityInsurance',
    isVisible : false,
    isCurrency : true,
    isEditable : false,
    isDropdown : false,
    language : {
        'nl' : 'Verzekering WA'
    }
}

##Wheely Base Methods 4 types of base methods: layout, core, handleData and tracking. All methods are part of base object.

###Layout methods 4 layout methods. Both accessible through the base.layout object.

####updateDoubleSliderValue Update double slider value in target element.

wheelyBase.base.layout.updateDoubleSliderValue(
    document.getElementById('start'), // start element
    document.getElementById('end'), // end element
    document.getElementById('targetDiv') // Element to write the values of the double slider to
);

####ReturnSliderValue Returns slider value, used inside an event listener.

wheelyBase.base.layout.returnSliderValue(
    parent // HTMLCollection of parent, i.e. : let parent = document.getElementById(this.props.id).getElementsByTagName("*")
    e // event
);

####ToggleClass Toggle class by adding --visible to the css class.

wheelyBase.base.layout.toggleClass(
    'classname'
);

####Appendcss Append right CSS to head

wheelyBase.base.layout.appendcss(
    'tco-widget', // or bijtelling-widget, tco-merk-widget, etc.
    '' // leave empty if using wheely CDN, if using own stylesheet add url of stylesheet
);

###Wheely Core Methods 5 core methods. All accessible through the base.core object.

####Init Returns wheely widget view.

let view = wheelyBase.base.core.init(this, SETTINGS, MAP,incrementer); 

####returnCacheDataByName All searched data is cached inside the global dataLayer object. This object is based on Google's dataLayer and can be also used with a Tag Manager. You can search for certain events by using returnCacheDataByName method. Search cache for last event with given eventname and key.

let data = wheelyBase.base.core.returnCacheDataByName('eventName', 'key'); 

####returnErrorMessage Return a error message view.

wheelyBase.base.core.returnErrorMessage('Error message'); 

####licencePlateRegex returns a licence plate RegEx.

let regexValidLicencePlate = new RegExp(wheelyBase.base.core.licencePlateRegex());

####bindEvent Adds a listener to the element

wheelyBase.base.core.bindEvent(
     element, 
     eventname, 
     eventhandler
);

####Error handler Used for handling data from fetch requests

wheelyBase.base.core.handleError(
    response
);

###Wheely handleData Methods 5 handleData methods. All accessible through the base.handleData object.

####handleTCOData Returns a view based on an object where key = label and [key] = text.

wheelyBase.base.handleData.handleTCOData(
    {}
);

####updateObject Maps the given object to items inside the map that equals to true and then call the private updateTCOObject with the updated object.

wheelyBase.base.handleData.updateObject(
    {
        response // response of wheely calculate api
    },
    {
        // example map structure
        name : 'id',
        isVisible : false, // true if it will be visible
        isCurrency : false, // if true it converts to a currency
        isEditable : false, // true if a user should be able to modify the outcome
        isDropdown : false, // if isEditable is true and isDropdown is true a dropdown view will be returned
        language : {
            'nl' : 'id'
        }
    }
);

####Formatter Creates currency of integers

wheelyBase.base.handleData.formatter.format(
    10000 // returns € 10.000,00
);

####Response Transforms data to an object including : {data: data, success: success}.

wheelyBase.base.handleData.response(
    data, // object
    true // or false when in a catch
);

###Wheely tracking Methods 2 tracking methods. Both accessible through the base.tracking object.

####InitDataLayer Creates GTM snippet inside head of page

wheelyBase.base.tracking.initDataLayer(
    'GTM-string' // like GTM-000000 for add tracking
); 

####updateDataLayer Update dataLayer by pushing wanted object values

wheelyBase.base.tracking.updateDataLayer(
    {
        event : 'carTCOData',
        vehicle : {} // wanted data
    }
); 

##Usage of fetch methods Fetch methods: fetch data for different use cases. All methods are part of fetchData object. 2 types of fetch methods: calculate methods and search methods.

###Fetch calculate methods 3 Calculate methods inside the fetchData object. Those methods returns integers based on user input.

####FetchTCO Returns a promise that calculate TCO based on situation and specific car.

wheelyBase.fetchData.fetchTCO(
    {
        body : {
          ModelVersionInputs: [
                { 
                  Id: 0 // model Id given by makes API
                }
              ], 
          Period: 0, //integer
          Distance: 0, //integer
          UserSituationId: 0, //integer
          IncomeRangeId: 0, //integer
          PostCode: 0000, // Valid postcode
          InterestRate: 0 //integer
        };
        key : 'api_key'
    }
).then (
    //response
).then( (data) => {
    //callback
}
).catch(
    //error
)

//Returned data
[{
  "id": 4136,
  "kenteken": "",
  "make": {
    "id": 46,
    "name": "Tesla"
  },
  "model": {
    "id": 46002,
    "name": "Model X"
  },
  "description": "P100D",
  "cataloguePrice": 158935.0,
  "deliveryFee": 400.826446,
  "bpm": 0.0,
  "bodyType": {
    "id": 6,
    "name": "SUV/Crossover"
  },
  "engineType": {
    "id": 6,
    "name": "Elektrisch"
  },
  "transmissionType": {
    "id": 2,
    "name": "Automaat"
  },
  "taxLiabilityType": {
    "year": 2018,
    "tariff": 0.04,
    "isCalculatedTariff": false
  },
  "discountValue": 0.0,
  "doors": 5,
  "images": {
    "default": "https://wheely-api.azurewebsites.net/api/images/modelversions/tesla_model_x_2016",
    "medium": "https://wheely-api.azurewebsites.net/api/images/models/tesla_model_x_2016_m/jpg",
    "thumbnail": "https://wheely-api.azurewebsites.net/api/images/modelversions/tesla_model_x_2016_t"
  },
  "nettoPrice": 131736.0,
  "weight": 2440,
  "year": 2016,
  "totalInvestment": 132136.826446,
  "residualValue": 55200.0,
  "monthlyCosts": {
    "installment": 348.10679476529,
    "writeOff": 1441.9498622542699,
    "insurance": {
      "liabilityInsurance": 82.32275,
      "personalLiability": 364.0
    },
    "maintenance": 109.325869182,
    "fuel": 145.2,
    "roadTax": 0.0,
    "subTotal": 2345.70527620156,
    "total": 2490.90527620156
  },
  "monthlyTaxEffects": {
    "bijtelling": 240.49012833333333,
    "deductionMIA": -136.599,
    "deductionMonthlyCosts": -1296.5147360378562,
    "taxPrivateUse": 356.5125
  },
  "monthlyCostBusiness": 1414.3040401637036,
  "monthlyCostPrivate": 240.49012833333333,
  "tco": 1654.7941684970369,
  "fiscalPrice": 158450.0,
  "recommendedPrice": 0.0,
  "recommendedPriceEx": 0.0,
  "isOwner": false,
  "isMarginVehicle": false,
  "registrationDate": "2018-10-31T15:15:34.698372+00:00",
  "segment": "M"
}]

####fetchTCOKenteken Returns a promise calculate TCO based on situation and licence plate.

wheelyBase.fetchData.fetchTCOKenteken(
    {
        body : {
          ModelVersionInputs: [
                { 
                  kenteken: '00-aaa-0' // valid kenteken use wheelyBase.base.core.licencePlateRegex() as validation
                }
              ], 
          Period: 0, //integer
          Distance: 0, //integer
          UserSituationId: 0, //integer
          IncomeRangeId: 0, //integer
          PostCode: 0000, // Valid postcode
          InterestRate: 0 //integer
        };
        key : 'api_key'
    }
).then(
    //response
).then(
    //callback
).catch(
    //error
)

//Returned data
{
  "data": [{
    "id": 0,
    "kenteken": "33ppr3",
    "make": {
      "id": 14,
      "name": "Fiat"
    },
    "model": {
      "id": 0,
      "name": "PUNTO"
    },
    "cataloguePrice": 18315.0,
    "deliveryFee": 0.0,
    "bpm": 0.0,
    "bodyType": {
      "id": 7,
      "name": "MPV"
    },
    "engineType": {
      "id": 4,
      "name": "Diesel"
    },
    "transmissionType": {
      "id": 1,
      "name": "Handgeschakeld"
    },
    "taxLiabilityType": {
      "year": 2012,
      "tariff": 0.25,
      "isCalculatedTariff": false
    },
    "discountValue": 0.0,
    "doors": 4,
    "nettoPrice": 0.0,
    "weight": 1220,
    "year": 2011,
    "totalInvestment": 4297.5206611570247,
    "residualValue": 3225.0,
    "monthlyCosts": {
      "installment": 290.11707988980714,
      "writeOff": 136.01928374655645,
      "insurance": {
        "liabilityInsurance": 44.34519791666667,
        "personalLiability": 47.14915625
      },
      "maintenance": 54.519891815185566,
      "fuel": 112.01,
      "roadTax": 98.0,
      "subTotal": 670.15060961821587,
      "total": 782.16060961821586
    },
    "monthlyTaxEffects": {
      "bijtelling": 139.46109375,
      "deductionMIA": 0.0,
      "deductionMonthlyCosts": 0.0,
      "taxPrivateUse": 41.20875
    },
    "monthlyCostBusiness": 823.369359618216,
    "monthlyCostPrivate": 139.46109375,
    "tco": 0.0,
    "fiscalPrice": 18315.0,
    "recommendedPrice": 5200.0,
    "recommendedPriceEx": 4297.5206611570247,
    "odometer": 153957,
    "isOwner": false,
    "isMarginVehicle": false,
    "registrationDate": "2011-03-05T00:00:00",
    "segment": "B"
  }],
  "success": true
}

####fetchBijtelling Returns a promise that calculate bijtelling based on situation and licence plate.

wheelyBase.fetchData.fetchBijtelling(
    {
        body : {
            "VehicleCost": 0, //integer
            "BijtellingPercent": 0, //integer
            "TaxPercent": 0, //integer
            "OwnAmount": 0 //integer
        }, 
        key : 'api_key'
    }
).then(
    //response
).then(
    //callback
).catch(
    //error
)

//Returned data
30.333333333333333333333333333

###Fetch search methods 5 Search methods inside the fetchData object. Those methods returns multiple cars / models / versions.

####FetchVehicle Returns a promise that fetch vehicle info based on licenceplate

wheelyBase.fetchData.fetchVehicle(
    {
        id : '12-aaa-3', // example licenceplate
        key : 'api_key'
    }
).then(

).then(

).catch(

)

//Returned data
{
  "data": {
    "make": "Fiat",
    "model": "PUNTO",
    "registrationDate": "2011-03-05T00:00:00",
    "vehiclePrice": 18315.0,
    "emission": 95.0,
    "bijtellingPercent": 0.25,
    "errors": [],
    "hasErrors": false
  },
  "success": true
}

####fetchMakes Returns a promise that fetch all possible makes

wheelyBase.fetchData.fetchMakes(
    {
        body : {}, // post body
        key : 'api_key'
    }
).then(

).then(

).catch(

)

// Returned data
{
    data : [
        {
            "id": 0, // integer
            "name": "Abarth", // string
            "isDeleted": false // boolean
        },
        {
            "id": 1, // integer
            "name": "Alfa Romeo", // string
            "isDeleted": false // boolean
        }
    ],
    success : true // boolean
}

####fetchModels Returns a promise that fetch all possible models based on a given make. DEPRECATED : use fetchSearch instead.

wheelyBase.fetchData.fetchModels(
    {
        id : 0, //make id
        key : 'api_key'
    }
).then(

).then(

).catch(

)

// Returned data
[
    {
        "makeId": 1,
        "makeName": "Abarth",
        "id": 1001,
        "name": "124 Spider",
        "isDeleted": false
    },
    {
        "makeId": 1,
        "makeName": "Abarth",
        "id": 1002,
        "name": "595",
        "isDeleted": false
    },
    {
        "makeId": 1,
        "makeName": "Abarth",
        "id": 1003,
        "name": "595C",
        "isDeleted": false
    }
]

####fetchVersions Returns a promise that fetch all possible versions based on a given model. DEPRECATED : use fetchSearch instead.

wheelyBase.fetchData.fetchVersions(
    {
        body : {
            "ModelVersionInputs": [
                { 
                    "Id": 0 // Model id
                }
            ],
            "Period": 0, //integer
            "Distance": 0, //integer
            "UserSituationId": 0, //integer
            "IncomeRangeId": 0, //integer
            "PostCode": 0000, //integer
            "InterestRate": 0.000 //integer
        },
        key : 'api_key'
    }
).then(

).then(

).catch(

)

// Returned data
[{
  "id": 4136,
  "kenteken": "",
  "make": {
    "id": 46,
    "name": "Tesla"
  },
  "model": {
    "id": 46002,
    "name": "Model X"
  },
  "description": "P100D",
  "cataloguePrice": 158935.0,
  "deliveryFee": 400.826446,
  "bpm": 0.0,
  "bodyType": {
    "id": 6,
    "name": "SUV/Crossover"
  },
  "engineType": {
    "id": 6,
    "name": "Elektrisch"
  },
  "transmissionType": {
    "id": 2,
    "name": "Automaat"
  },
  "taxLiabilityType": {
    "year": 2018,
    "tariff": 0.04,
    "isCalculatedTariff": false
  },
  "discountValue": 0.0,
  "doors": 5,
  "images": {
    "default": "https://wheely-api.azurewebsites.net/api/images/modelversions/tesla_model_x_2016",
    "medium": "https://wheely-api.azurewebsites.net/api/images/models/tesla_model_x_2016_m/jpg",
    "thumbnail": "https://wheely-api.azurewebsites.net/api/images/modelversions/tesla_model_x_2016_t"
  },
  "nettoPrice": 131736.0,
  "weight": 2440,
  "year": 2016,
  "totalInvestment": 132136.826446,
  "residualValue": 55200.0,
  "monthlyCosts": {
    "installment": 348.10679476529,
    "writeOff": 1441.9498622542699,
    "insurance": {
      "liabilityInsurance": 82.32275,
      "personalLiability": 364.0
    },
    "maintenance": 109.325869182,
    "fuel": 145.2,
    "roadTax": 0.0,
    "subTotal": 2345.70527620156,
    "total": 2490.90527620156
  },
  "monthlyTaxEffects": {
    "bijtelling": 240.49012833333333,
    "deductionMIA": -136.599,
    "deductionMonthlyCosts": -1296.5147360378562,
    "taxPrivateUse": 356.5125
  },
  "monthlyCostBusiness": 1414.3040401637036,
  "monthlyCostPrivate": 240.49012833333333,
  "tco": 1654.7941684970369,
  "fiscalPrice": 158450.0,
  "recommendedPrice": 0.0,
  "recommendedPriceEx": 0.0,
  "isOwner": false,
  "isMarginVehicle": false,
  "registrationDate": "2018-10-31T15:15:34.698372+00:00",
  "segment": "M"
}]

####fetchSearch Returns a promise that fetch all possible versions based on a given Make, Model, AmountTo and PageSize.

wheelyBase.fetchData.fetchSearch(
    {
        body : {
            "PageSize": 1000, // Returned items
            "AmountTo" : 50000 // monthly TCO
            "Makes" : [
                0 // makes id
            ],
            "Models" : [ ] // empty will return all models including all versions
        },
        key : 'api_key'
    }
).then(

).then(

).catch(

)

//Returned data
{
    "results": [
        {
            "model": {
                "id": 13001,
                "name": "458 Spider",
                "make": {
                    "id": 13,
                    "name": "Ferrari"
                }
            },
            "items": [
                {
                    "id": 1201,
                    "description": "458 Spider",
                    "bodyType": {
                        "id": 1,
                        "name": "Cabriolet",
                        "isDeleted": false
                    },
                    "cataloguePrice": 302418,
                    "doorsCount": 2,
                    "engineType": {
                        "averageFuelPrice": 1.766,
                        "name": "Benzine",
                        "id": 2,
                        "isDeleted": false
                    },
                    "transmissionType": {
                        "id": 2,
                        "name": "Automaat",
                        "isDeleted": false
                    },
                    "taxLiabilityType": {
                        "engineType": {
                            "averageFuelPrice": 0,
                            "name": "n.v.t.",
                            "id": 0,
                            "isDeleted": true
                        },
                        "registrationDate": "2018-01-01T00:00:00",
                        "engineTypeId": 0,
                        "tariff": 0.22,
                        "emissionFrom": 1,
                        "emissionTo": 999,
                        "isCalculatedTariff": false
                    },
                    "year": 2011,
                    "monthlyCost": {
                        "residualValue": 115425,
                        "installment": 0,
                        "writeOff": 3037.8968585081111,
                        "insurance": {
                            "liabilityInsurance": 51.320666666666661,
                            "personalLiability": 692.0309375,
                            "total": 743.35160416666668
                        },
                        "fuel": 383.22,
                        "roadTax": 61,
                        "maintenanceCost": 421.955709258,
                        "subTotal": 4264.2041719327781,
                        "total": 4647.4241719327783
                    }
                },
                {
                    "id": 1200,
                    "description": "458 Speciale A",
                    "bodyType": {
                        "id": 1,
                        "name": "Cabriolet",
                        "isDeleted": false
                    },
                    "cataloguePrice": 318371,
                    "doorsCount": 2,
                    "engineType": {
                        "averageFuelPrice": 1.766,
                        "name": "Benzine",
                        "id": 2,
                        "isDeleted": false
                    },
                    "transmissionType": {
                        "id": 2,
                        "name": "Automaat",
                        "isDeleted": false
                    },
                    "taxLiabilityType": {
                        "engineType": {
                            "averageFuelPrice": 0,
                            "name": "n.v.t.",
                            "id": 0,
                            "isDeleted": true
                        },
                        "registrationDate": "2018-01-01T00:00:00",
                        "engineTypeId": 0,
                        "tariff": 0.22,
                        "emissionFrom": 1,
                        "emissionTo": 999,
                        "isCalculatedTariff": false
                    },
                    "year": 2015,
                    "monthlyCost": {
                        "residualValue": 121500,
                        "installment": 0,
                        "writeOff": 3153.9571936902353,
                        "insurance": {
                            "liabilityInsurance": 48.22045833333334,
                            "personalLiability": 728.6059375,
                            "total": 776.82639583333332
                        },
                        "fuel": 383.22,
                        "roadTax": 54,
                        "maintenanceCost": 456.495695796,
                        "subTotal": 4441.2792853195688,
                        "total": 4824.499285319569
                    }
                }
            ]
        }
    ]
}