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

.. include:: /inline-images.txt

External package
====================

An external package functions like an include, which may be used to include a pattern from a code instruction library.
You should definately use this if you want to reuse code between projects.
View more information on external libraries :ref:`here <Reference/CodeInstructionsXML/CIX_JCIE_ExternalLibraries:External libraries>`.

.. rubric:: Usage

External packages are functionally equivalent to a :ref:`package <Reference/CodeInstructionsXML/CIX_JCIE_Package:Package>` directly defined in the main code instruction file.

The syntax of the id attribute is as follows:

.. code-block:: xml

	id="libName/pathInsideLibraryToFile"


.. code-block:: xml
	:caption: <external package/> definition syntax
	:name: external package-01
	:linenos:
	:emphasize-lines: 4

	<pattern>
		...
		
		<external.package
		    id="libName/pathInsideLibraryToFile"
		    name=""
		    path=""
		    foreach="package|object|attribute|reference"
		    condition=""
		    package=""
		    skip="true|false">
		</external.package>
		
		...
	</pattern>


.. rubric:: Example

Say there is an external library defined with name: lib1. You want to use a pattern file with the name *authentication.xml* located in 
the folder: packages/seam/component/ under the patternFolder of lib1.
The value of the id attribute must then be defined as follows:

.. code-block::

	<external.package id="lib1/packages/seam/component/authentication.xml" />
	

|Eye M| In the external package id path you should not repeat the value of <patternFolder> as defined in the <externalLibrary>.

.. rubric:: Other attributes of <external.package/>


..	list-table:: **attributes of <external package/>**
	:widths: 20 80
	:header-rows: 1
	:class: tight-table

	*	-	Name
		-	Details
	*	-	name
		-	The name of the generated Java package.
	*	-	path
		-	Path pointing to the Java output folder.
	*	-	foreach
		-	Indicates whether the generation process should be iterative, and if so: what the iteration scope should be be.
			Possible values: package, object, attribute, reference
	*	-	package
		-	The name of the package in the model (model.xml) that must be used to apply the foreach attribute.
	*	-	object
		-	The name of the object in the model (model.xml) that must be used to apply the foreach attribute.
	*	-	condition
		-	An expression that can be either true or false. The package is generated only If the condition evaulates to *true*.
			
			Example:
			
			.. code-block::
			
				condition="${object.name}=Person"
			
			In this case, the package is generated only if the current model object has the name: Person.
			Naturally you can’t use this if there is no foreach defined on object.
	*	-	skip
		-	True or false. 
			This works as a flag to prevent generation of this package whenever the “Use @skip of packages” checkbox of the MetaFactory tool
			(located inside the menu Transform) is checked. Choosing not to generate specific packages every time can reduce processing time.
			You might also want to use this when you work on one specific package.
			Setting its flag to true while false for the other packages allows generation of the package that you are working on only.