Creating a community app

== Community apps in collabs ==

Community apps are services developed by the EBRAINS community of users.The services run are deployed by their respective developers on a server online. Community apps differ from other services in that they can be added to the navigation of any collab with easier integration. For this, the app needs to be registered in a space called the "[[Community Apps Catalogue>>https://wiki.ebrains.eu/bin/view/Apps/]]". Once the app is registered, instantiating such an app in the Wiki navigation of a collab is as simple as creating a new Wiki page in the collab.

4

5

6

== Becoming a contributor ==

7

8

The first step for an EBRAINS user to creating a community app is to **get the service developer accreditation**. Contributors can register and manage apps within the Community Apps Catalogue.

9

10

Users can request service developer accreditation by performing both of the following 2 steps:

11

12

1. opening an EBRAINS support ticket at [[https:~~/~~/ebrains.eu/support>>https://ebrains.eu/support]] with a short motivation for the request, and

13

1. navigating to the [[app-collaboratory-iam~~-~~-service-providers>>https://wiki.ebrains.eu/bin/view/Identity/#/groups/app-collaboratory-iam--service-providers]] Group and clicking the big green "request to join" button.

14

15

The support team will apply the permissions to your user.

16

17

18

HBP accredited members will automatically be approved. Other EBRAINS users will be required to sign an an agreement in order to obtain service developer accreditation.

== Making your app available to users ==

23

24

In order for users to install your app, it needs to be registered in the Community Apps Catalogue.

25

26

27

Warning: EBRAINS tolerates that service developers create test instances in the Community Apps Catalogue on the conditions that:

28

29

1. The app is marked with the "under development" tag (see below), and

30

1. Test apps are removed after no more than 2 weeks (10 working days).

31

32

Failure to respect these conditions may lead to a user having their service developer accreditation suspended and/or to the app being deleted from the catalogue by the Collaboratory team without notification.

33

34

35

If the users of your app need to be authenticated, see [[managing authorisation in the Collaboratory>>doc:Collabs.the-collaboratory.Documentation IAM.FAQ.Managing Authorizations.WebHome]] or[[ OIDC clients explained>>doc:Collabs.the-collaboratory.Documentation IAM.FAQ.OIDC Clients explained.WebHome]] and its sub-pages for a more detailed overview of authenticating EBRAINS users and creating an OIDC client.

36

37

38

=== Register your app in the Community Apps Catalogue ===

39

40

To register an app in the catalogue, navigate to the catalogue [[https:~~/~~/wiki.ebrains.eu/bin/view/Apps/>>https://wiki.ebrains.eu/bin/view/Apps/]] and click the "Create App" button. If the button does not appear, you are either not logged in or you do not yet have the service developer accreditation (see above).

41

42

43

(% style="text-align:center" %)

44

[[image:create-app.png||height="518" width="1250"]]

45

46

47

Then, create a new space in the Community Apps Catalogue for your app using the "Community App" type.

48

49

50

(% style="text-align:center" %)

51

[[image:create-app-2.png||height="982" width="1250"]]

52

53

54

Fill the form with the following information:

55

56

* **main URL**: the URL of the homepage of your app. This is where the users will be directed when they open your app in a collab.

57

* **settings URL**: the URL of your app's settings management page, if there is one.

58

* **description**: a description of what your app does. This helps users choose the apps they install.

59

* **under development?**: if checked, your app will not be available to other users.

60

* **category**: a category to help structure the list of apps.

61

* **maintainers**: a list of EBRAINS users who maintain the app. The users need to have logged in to the Wiki service at least once to appear in the list. Maintainers are granted the right to modify the app's registration.

62

* **documentation URL**: if your app has online user documentation, a link to this URL will be provided to users when they use your app.

63

* **repository**: a URL to a public repository so users can access the source code of your app.

64

65

Note that only users registered in the "maintainers" field will be able to edit this form. Do not forget to **add yourself as a maintainer**. When done, click on the "Save & View" button; it displays a summary of information you have just filled. Your app is now available to be used in the Wiki.

66

67

=== Add a logo (optional) ===

68

69

Some of users like to add a logo to their app. The logo is only visible when browsing the catalogue. To do so, the user has to add a PNG file attachment with the filename "logo.png" in the attachment tab at the bottom of the summary page displayed after the "Save & View" action above.

70

71

72

== Add an app to your collab ==

73

74

Adding an app to a collab is as simple as creating a new wiki page. As an admin or editor of a collab, a user can add a community app by clicking the "+ Create" button at the top of any wiki page, and selecting the "Community App" type.

75

76

(% style="text-align:center" %)

77

[[image:add.png||height="617" width="1250"]]

78

79

Then click the Create button and the app will be added in the collab's navigation menu.

80

81

82

== Getting instance context information in your app ==

83

84

Instances of your apps will be installed by collab owners in their respective collabs. In order to let the app developer customise the user experience based on context, the Collaboratory will automatically pass the following query string parameters to your app:

85

86

* **clb-collab-id**: the id of the collab, also know as the collab's name or slug, e.g. //my-collab-name//.

87

* **clb-doc-path**: the (relative) path to your app instance within the collab. If your app is at the root of a collab, this value will be empty. E.g. for this page the path is //"Documentation Wiki/FAQ"//

88

* **clb-doc-name**: the name of the document where your app instance is installed. E.g. the name for this wiki page is "//Creating a community app//".

89

* **clb-drive-id**: the unique identifier of the Drive of the collab. This uuid is made up of hex digits and dashes. This id is used to fetch or store documents within the Drive of the collab.

90

91

Additional query string parameters can also be passed from the community app manager with constant fields.

92

93

94

== Storing app settings in the Collaboratory ==

95

96

The app settings are the values the collab owners can modify to change the behaviour of your app within their collabs. The Collaboratory comes with a mechanism to let your app store its settings directly in the Collaboratory.

97

98

=== Writing settings ===

99

100

In order for your app to store settings in the Collaboratory, your app needs to use the [[postMessage javascript API>>url:https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage]] to send the settings to be stored to the Collaboratory. The settings are key/value pairs as in the example below. To update any setting, you need to rewrite all the settings fields.

101

102

103

window.parent.postMessage({

104

topic: '/clb/community-app/settings',

105

data: {

106

setting1: 'setting 1 value',

107

setting2: 'setting 2 value',

108

// ...

109

},

110

// reload: false // avoid page reload on settings change

111

}, 'https://wiki.ebrains.eu');

112

113

114

=== Reading settings ===

115

116

The Collaboratory will get the settings from its key/value store and pass them to your app through query string parameters.

117

118

(% class="wikigeneratedid" %)

119

120

121

== Your app with hash-based URL ==

122

123

The app you are developing might be a single page app that needs to handle some routing between views. This is typically done with a hash-based URL using the [[fragment>>https://en.wikipedia.org/wiki/URI_fragment]] at the end of the URL to track the view in the page.

124

125

{{{URI = scheme:[//authority]path[?queryStringParams][#fragment]}}}

126

127

The Community Apps environment gives you the ability to update the parent frame fragment.

128

129

It uses the [[postMessage() javascript API>>url:https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage]] to communicate from your app's iframe to the wiki (parent) frame.

130

131

132

window.parent.postMessage({

133

topic: '/clb/community-app/hashchange',

134

data: 'the_fragment_value'

135

}, 'https://wiki.ebrains.eu');

136

137