AppSuite:UI manifests explained - Revision history

Khgras: Replaced content with "The content on this page has moved to https://documentation.open-xchange.com/latest/ui/customize/manifests.html Note: Open-Xchange is in the process of migrating all its..."

2017-05-22T09:34:27Z

Replaced content with "The content on this page has moved to https://documentation.open-xchange.com/latest/ui/customize/manifests.html Note: Open-Xchange is in the process of migrating all its..."

← Older revision		Revision as of 09:34, 22 May 2017
Line 1:		Line 1:
	~~<!-- !!! -->~~		The content on this page has moved to https://documentation.open-xchange.com/latest/ui/customize/manifests.html
	~~<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION~~: ~~wd/frontend~~/~~web~~/documentation -->
	~~<!-- !!! -->~~

	~~{{Stability~~-~~experimental}}~~		Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.

	~~<div class="title">Manifests</div>~~

	~~'''Abstract:''' Manifest files~~ in the app suite declare either apps or plugins. They tell the AppSuite runtime which files to load when, so the code in it can take effect at the appropriate time. This document should be read by everyone that wants to either build a plugin or an app and contains a description of ~~how to get app suite~~ to ~~run your code.~~

	~~== Declaring apps ==~~

	~~The minimal declaration for an app looks like this:~~

	~~<pre class="language-javascript">~~
	{
	~~"title": "My App",~~
	~~"path": "com.example/myapp/main"~~
	}
	~~</pre>~~
	~~It consists of~~ a ~~title for the app~~ and ~~the path to the main entry file, by convention always called main~~.js. This declaration is usually found in the file manifest.json right next to the app in question, but could theoretically be located anywhere. If the file is located in the same directory as the main entry file and the file is, as is the convention, called main.js you can leave out the path as it will be added automatically by the buildsystem, so the minimal definition then becomes:

	~~<pre class="language~~-~~javascript">~~
	{
	~~"title": "My App"~~
	}
	~~</pre>~~

	~~== Declaring a plugin ==~~

	~~In turn, this is the definition of a plugin file:~~
	~~<pre class="language-javascript">~~
	{
	~~"namespace": "io~~.~~ox/contacts/view-detail",~~
	~~"path": "~~com.~~example/myapp/contacts/register"~~
	}
	~~</pre>~~

	~~The namespace contains the name of a frontend module for which the plugin is relevant. Declaring a plugin like this has the effect, that the plugin is loaded before the file named~~ as the namespace is loaded, so it can affect what the core file is doing, commonly by extending an extension point. The convention is to always put plugins into the file register.js, so again, the path can be omitted if the manifest.json is placed alongside the register.js containing the plugin. A plugin may be associated with more ~~than one namespace, in that case, just use a list as the value for the namespace attribute:~~

	~~<pre class="language-javascript">~~
	{
	~~"namespace": ["io.ox/contacts/view-detail", "io.ox/contacts/edit/view-form"]~~
	}
	~~</pre>~~

	~~Whichever module is loaded first~~ will ~~trigger the plugin to~~ be ~~loaded.~~

	~~== Capabilities ==~~

	~~Sometimes a plugin or an app is only~~ available ~~if either the backend has a certain bundle installed or~~ the ~~user must have a certain permission. Both permissions~~ and ~~backend capabilities are rolled into the concept of a "capability"~~. If your ~~plugin, for example, is only relevant when the user has access to the calendar module, you can add a requires attribute to the declaration:~~

	~~<pre class="language-javascript">~~
	{
	~~"namespace": "io.ox/contacts/view-detail",~~
	~~"requires": "calendar"~~
	}
	~~</pre>~~

	~~Which capabilities are available can be checked by either reading through existing manifests or by running~~ this ~~in the javascript console once logged into appsuite:~~

	~~<pre class="language-javascript">~~
	~~_(ox.serverConfig.capabilities).pluck("id")~~
	~~</pre>~~

	~~== Device tests ==~~

	~~If a plugin is designed only for specific devices, screen sizes or languages, then its loading can be disabling by specifying the criteria in a <tt>device</tt> attribute:~~

	~~<pre class="language-javascript">~~
	{
	~~"namespace": "io.ox/contacts/view-detail",~~
	~~"device": "ja_JP"~~
	}
	~~</pre>~~

	~~The full list of available device tests is documented in the [[AppSuite:Device reference\|Device reference]].~~

	~~== Multiple declarations in one file ==~~

	~~If you need more than declaration in a manifest.json file, you can include them in a list:~~
	~~<pre class="language-javascript">~~
	[
	{
	~~"namespace": "io.ox/contacts/view-detail",~~
	~~"path": "com.example/myapp/contacts/viewPlugin"~~
	},
	{
	~~"namespace": "io.ox/contacts/view-form",~~
	~~"path": "com.example/myapp/contacts/formPlugin"~~
	}
	]
	~~</pre>~~

	~~== What happens to these files? ==~~

	During a build run the buildsystem picks up these manifest files and consolidates them into a single file build/manifests/[myapp].json. This file, either by creating a symlink to a locally run backend or by installing the app package on a remote backend, winds up in the manifests directory of the backend and is processed and sent to the frontend. You can see all manifest declarations, that have been sent by the backend by looking at
	~~ox.serverConfig.manifests~~
	~~in the javascript console.~~

	~~== Special namespaces ==~~

	~~=== signin ===~~

	~~Plugins that choose "signin" as (or amongst) their namespace, are loaded when the login page is shown. The code can be used to rearrange parts~~ of ~~the signin page or add custom behaviour to it.~~

	~~=== core ===~~

	~~Core plugins are loaded as soon as the frontend starts up after successfully logging in or reauthenticating with the autologin. This is useful if you need to run code very early~~.

	~~[[Category:AppSuite]]~~
	~~[[Category:UI]]~~

Frank.paczynski at 05:46, 10 February 2016

2016-02-10T05:46:07Z

← Older revision		Revision as of 05:46, 10 February 2016
Line 1:		Line 1:
			<!-- !!! -->
			<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation -->
			<!-- !!! -->

	{{Stability-experimental}}		{{Stability-experimental}}

Viktor.Pracht: Added double quotes to strings, manifests must be proper JSON now.

2015-02-05T13:19:28Z

Added double quotes to strings, manifests must be proper JSON now.

← Older revision		Revision as of 13:19, 5 February 2015
Line 11:		Line 11:
	<pre class="language-javascript">		<pre class="language-javascript">
	{		{
	title: "My App",		"title": "My App",
	path: "com.example/myapp/main"		"path": "com.example/myapp/main"
	}		}
	</pre>		</pre>
Line 19:		Line 19:
	<pre class="language-javascript">		<pre class="language-javascript">
	{		{
	title: "My App"		"title": "My App"
	}		}
	</pre>		</pre>
Line 28:		Line 28:
	<pre class="language-javascript">		<pre class="language-javascript">
	{		{
	namespace: "io.ox/contacts/view-detail",		"namespace": "io.ox/contacts/view-detail",
	path: "com.example/myapp/contacts/register"		"path": "com.example/myapp/contacts/register"
	}		}
	</pre>		</pre>
Line 37:		Line 37:
	<pre class="language-javascript">		<pre class="language-javascript">
	{		{
	namespace: ["io.ox/contacts/view-detail", "io.ox/contacts/edit/view-form"]		"namespace": ["io.ox/contacts/view-detail", "io.ox/contacts/edit/view-form"]
	}		}
	</pre>		</pre>
Line 49:		Line 49:
	<pre class="language-javascript">		<pre class="language-javascript">
	{		{
	namespace: "io.ox/contacts/view-detail",		"namespace": "io.ox/contacts/view-detail",
	requires: "calendar"		"requires": "calendar"
	}		}
	</pre>		</pre>
Line 79:		Line 79:
	[		[
	{		{
	namespace: "io.ox/contacts/view-detail",		"namespace": "io.ox/contacts/view-detail",
	path: "com.example/myapp/contacts/viewPlugin"		"path": "com.example/myapp/contacts/viewPlugin"
	},		},
	{		{
	namespace: "io.ox/contacts/view-form",		"namespace": "io.ox/contacts/view-form",
	path: "com.example/myapp/contacts/formPlugin"		"path": "com.example/myapp/contacts/formPlugin"
	}		}
	]		]

Viktor.Pracht: /* Device tests */

2015-02-05T13:17:53Z

Device tests

@@ Line 59: / Line 59: @@
      _(ox.serverConfig.capabilities).pluck("id")
 </pre>
 == Multiple declarations in one file ==

Tierlieb: /* Loading custom manifest during development */ removed

2014-09-25T11:48:44Z

Loading custom manifest during development: removed

@@ Line 81: / Line 81: @@
     ox.serverConfig.manifests
 in the javascript console.
 == Special namespaces ==

Tierlieb: /* Loading custom manifest during development */

2014-09-25T11:47:23Z

Loading custom manifest during development

← Older revision		Revision as of 11:47, 25 September 2014
Line 83:		Line 83:

	== Loading custom manifest during development ==		== Loading custom manifest during development ==
	{{VersionTo:7.4.2}}		{{VersionTo\|7.4.2}}
	During development you can use a custom manifest file to avoid restarting the backend or, in case of a remote backend, updating it every time the manifests change. Just add '''customManifests=true''' to the URL so that the UI loads the file '''src/manifests.js'''. All manifests in that file will be added to the ones provided by the backend. The file is supposed to be an anonymous require module that returns the array of manifest entries:		During development you can use a custom manifest file to avoid restarting the backend or, in case of a remote backend, updating it every time the manifests change. Just add '''customManifests=true''' to the URL so that the UI loads the file '''src/manifests.js'''. All manifests in that file will be added to the ones provided by the backend. The file is supposed to be an anonymous require module that returns the array of manifest entries:

Tierlieb: /* Loading custom manifest during development */

2014-09-25T11:47:06Z

Loading custom manifest during development

← Older revision		Revision as of 11:47, 25 September 2014
Line 83:		Line 83:

	== Loading custom manifest during development ==		== Loading custom manifest during development ==
			{{VersionTo:7.4.2}}
	During development you can use a custom manifest file to avoid restarting the backend or, in case of a remote backend, updating it every time the manifests change. Just add '''customManifests=true''' to the URL so that the UI loads the file '''src/manifests.js'''. All manifests in that file will be added to the ones provided by the backend. The file is supposed to be an anonymous require module that returns the array of manifest entries:		During development you can use a custom manifest file to avoid restarting the backend or, in case of a remote backend, updating it every time the manifests change. Just add '''customManifests=true''' to the URL so that the UI loads the file '''src/manifests.js'''. All manifests in that file will be added to the ones provided by the backend. The file is supposed to be an anonymous require module that returns the array of manifest entries:

Daniel.rentz: missing headline formatting

2014-01-15T10:16:17Z

missing headline formatting

← Older revision		Revision as of 10:16, 15 January 2014
Line 42:		Line 42:

	Whichever module is loaded first will trigger the plugin to be loaded.		Whichever module is loaded first will trigger the plugin to be loaded.
	Capabilities
			== Capabilities ==

	Sometimes a plugin or an app is only available if either the backend has a certain bundle installed or the user must have a certain permission. Both permissions and backend capabilities are rolled into the concept of a "capability". If your plugin, for example, is only relevant when the user has access to the calendar module, you can add a requires attribute to the declaration:		Sometimes a plugin or an app is only available if either the backend has a certain bundle installed or the user must have a certain permission. Both permissions and backend capabilities are rolled into the concept of a "capability". If your plugin, for example, is only relevant when the user has access to the calendar module, you can add a requires attribute to the declaration:

Mark.schmidts at 09:08, 24 October 2013

2013-10-24T09:08:02Z

← Older revision		Revision as of 09:08, 24 October 2013
Line 3:		Line 3:
	<div class="title">Manifests</div>		<div class="title">Manifests</div>

	'''Abstract:''' Manifest files in the app suite declare either apps or plugins. They tell the ~~app suite~~ runtime which files to load when, so the code in it can take effect at the appropriate time. This document should be read by everyone that wants to either build a plugin or an app and contains a description of how to get app suite to run your code.		'''Abstract:''' Manifest files in the app suite declare either apps or plugins. They tell the AppSuite runtime which files to load when, so the code in it can take effect at the appropriate time. This document should be read by everyone that wants to either build a plugin or an app and contains a description of how to get app suite to run your code.

	== Declaring apps ==		== Declaring apps ==

Tierlieb at 14:26, 25 April 2013

2013-04-25T14:26:20Z

← Older revision		Revision as of 14:26, 25 April 2013
Line 1:		Line 1:
			{{Stability-experimental}}

	<div class="title">Manifests</div>		<div class="title">Manifests</div>