..	*******************************************************************************
	* MetaFactory.io R2
	* Technical Documentation
	* 
	* File name   : MapiRef_Index.rst
	* Created by  : Marnix Bochove (original text)
	* Last update : 25-03-2021
	* Updated by  : Niels de Nies
	*
	* MetaFactory BV Amsterdam 
	*******************************************************************************

.. include:: /inline-images.txt


Model API Reference
===================

MetaFactory uses a strict separation of code instuctions and model data.
The higher the abstraction level of your code instructions, the more metadata your model will contain and 
the more complex your code instructions will become.
This has caused a need for a Model interaction layer that allows access to the desired data with a minimum number of calls.

The Model API was designed with exactly that in mind.
It exposes the object tree of your model with all its metadata without having to deal with the format of the model file, 
whether that would be XML or anything else.
It allows extraction of data and metadata that your code instructions requires but is also a tool to add default metadata to your model.

|Eye M| To be able to use code completion within your template, follow :ref:`these <HowTo/Configure-IDE:Configuring your IDE>` instructions.


Available context objects
-------------------------

MetaFactory provides the following set of model related objects that are available in Freemarker or Velocity templates to use:


These objects are listed in the order of the Model hierarchy – top down.

.. toctree::
   :maxdepth: 1

   MapiRef_ModelRoot
   MapiRef_ModelPackage
   MapiRef_ModelObject
   MapiRef_ModelAttribute
   MapiRef_ModelReference


Here is a visual representation of the API hierarchy:

.. figure:: images/model-api-web.png
	:name: API_hierarchy
	:scale: 100%
	
	API hierarchy

Model hierarchy
---------------

The data model is a tree of elements (objects), contained in XML or Yaml format.
Whatever format to use is up to your preference, but irrelevant when using the Model API 
because this does all interactions with the model file for you.

When you start the code generation process, MetaFactory iterates the object tree top down, 
starting with the first ModelPackage, then get the first ModelObject child of the ModelPackage, 
then get the first ModelAttribute or ModelReference (which are both children of ModelObject). 

All objects mentioned can have metadata defined.
Code instructions can easily access these objects and draw metadata from it.

|Exclam M| It is this medadata that is at the heart of code instruction intelligence.