AppSuite:Configuring portal plugins: Difference between revisions

From Open-Xchange
No edit summary
 
(13 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<!-- !!! -->
<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation -->
<!-- !!! -->
{{Stability-stable}}
{{VersionFrom|7.4.0}}
= Configuring portal plugins =
''Synopsis:'' This article covers how to configure which plugins ("tiles") are shown, whether they are mandatory or just suggested to the user.
''Synopsis:'' This article covers how to configure which plugins ("tiles") are shown, whether they are mandatory or just suggested to the user.


Line 9: Line 18:
In order to specify a tile, you will have to know about the configuration data to enter. You can use an appsuite installation to do that. If you want to configure a tile as eager or protected, navigate to the settings area of the portal page, add the tile you want and, in the JS console, enter:
In order to specify a tile, you will have to know about the configuration data to enter. You can use an appsuite installation to do that. If you want to configure a tile as eager or protected, navigate to the settings area of the portal page, add the tile you want and, in the JS console, enter:


  require["settings!io.ox/portal"].get("widgets/user")
  require("settings!io.ox/portal").get("widgets/user")


and in the list find the tile you want to suggest to or force on your users. As an example, we'll use the birthday widget:
and in the list find the tile you want to suggest to or force on your users. As an example, we'll use the birthday widget:
Line 23: Line 32:
     type: "birthdays"
     type: "birthdays"


In order to configure widgets on the backend we have o turn the above into a valid YAML structure:
In order to configure widgets on the backend we have to turn the above into a valid YAML structure:


  birthdays_0:
  birthdays_0:
Line 72: Line 81:
  io.ox/portal//widgets/eager/gen_1:
  io.ox/portal//widgets/eager/gen_1:
     birthdays_0:
     birthdays_0:
    color: "lightgreen"
        color: "lightgreen"
    enabled: true
        enabled: true
    index: "first"
        index: "first"
    inverse: false
        inverse: false
    plugin: "plugins/portal/birthdays/register"
        plugin: "plugins/portal/birthdays/register"
    type: "birthdays"
        type: "birthdays"


All the "gen_[number]" entries up the tie io.ox/portal//generation will be used for this configuration. If a tile is deleted it is deleted only in that generation so can be reintroduced in a later portal configuration generation. If you want to keep the default tiles as used as a fallback for App Suite, you need this configuration to start out with:
All the "gen_[number]" entries up the tie io.ox/portal//generation will be used for this configuration. If a tile is deleted it is deleted only in that generation so can be reintroduced in a later portal configuration generation. If you want to keep the default tiles as used as a fallback for App Suite, you need this configuration to start out with:
Line 100: Line 109:
         plugin: 'plugins/portal/birthdays/register'
         plugin: 'plugins/portal/birthdays/register'
         color: 'lightgreen'
         color: 'lightgreen'
        enabled: true
        index: 4
    facebook_0:
        plugin: 'plugins/portal/facebook/register'
        color: 'blue'
         enabled: true
         enabled: true
         index: 4
         index: 4
Line 118: Line 122:
         index: 6
         index: 6
      
      
And then modify this as wanted for your deployment
And then modify this as wanted for your deployment. Note, that LikedIn support was removed with version 7.10.


== Forcing a tile ==  
== Forcing a tile ==  
Line 124: Line 128:
Similarly to the eager tiles, tiles can be "protected", i.e. they can not be moved, removed and disabled. The configuration for this looks like that:
Similarly to the eager tiles, tiles can be "protected", i.e. they can not be moved, removed and disabled. The configuration for this looks like that:


io.ox/portal//widgets/protected:
io.ox/portal//widgets/protected:
     birthdays_0:
     birthdays_0:
         color: "lightgreen"
         color: "lightgreen"
Line 135: Line 139:
If you want to allow movement of the widget, you can enable this in the following way:
If you want to allow movement of the widget, you can enable this in the following way:


io.ox/portal//widgets/protected:
io.ox/portal//widgets/protected:
     birthdays_0:
     birthdays_0:
         color: "lightgreen"
         color: "lightgreen"
Line 150: Line 154:
One caveat in all this: After changing any of the above configuration, you will have to reload the UI *twice*, since App Suite uses read-through caching for the settings data.
One caveat in all this: After changing any of the above configuration, you will have to reload the UI *twice*, since App Suite uses read-through caching for the settings data.


[[Category:UI]][[Category:AppSuite]]
== Disabling a tile completely ==
The combination of making a tile both protected and disabling it makes it impossible for the user to enable it. From 7.6.0 on, this means it is not shown in the settings either. Before that, it was greyed out but still present.
 
io.ox/portal/:
  widgets:
    protected:
      quota_0:
        color: "red"
        id: "quota_0"
        enabled: false
        index: 1
        inverse: false
        plugin: "plugins/portal/quota/register"
        type: "quota"
 
[[Category:Backend]][[Category:AppSuite]]


[[Category:Portal]]
[[Category:Portal]]


[[Category:Administrator]][[Category:Developer]]
[[Category:Administrator]][[Category:Developer]]

Latest revision as of 06:03, 26 June 2018


API status: Stable

This information is valid from 7.4.0 on.

Configuring portal plugins

Synopsis: This article covers how to configure which plugins ("tiles") are shown, whether they are mandatory or just suggested to the user.

Configuring the portal

When running OX AppSuite you may want to specify a starting configuration for which tiles the portal shows and whether certain tiles are mandatory or not. This is especially useful when you are introducing your own tile implementations. To make this possible, the portal consists of three types of tiles: User tiles, eager tiles and protected tiles. User tiles are tiles that the user added herself to the portal page, eager tiles are those suggested by the installation which can be removed and protected tiles are set by the backend.

In order to specify a tile, you will have to know about the configuration data to enter. You can use an appsuite installation to do that. If you want to configure a tile as eager or protected, navigate to the settings area of the portal page, add the tile you want and, in the JS console, enter:

require("settings!io.ox/portal").get("widgets/user")

and in the list find the tile you want to suggest to or force on your users. As an example, we'll use the birthday widget:

birthdays_0: Object
   color: "lightgreen"
   enabled: true
   id: "birthdays_0"
   index: 6
   inverse: false
   plugin: "plugins/portal/birthdays/register"
   props: Object
   type: "birthdays"

In order to configure widgets on the backend we have to turn the above into a valid YAML structure:

birthdays_0:
   color: "lightgreen" # one of black, red, orange, lightgreen, 
                       # green, lightblue, blue, purple, pink, gray
   enabled: true       # Has to be true 
   index: "first"      # Where the widget is supposed to show up. 
                       # Possible values are numbers, "first" or 
                       # "last" 
   inverse: false      # If true, the color is applied to the body 
                       # of the tile and not the title. Can highlight 
                       # particular tiles
   plugin: "plugins/portal/birthdays/register" # The source file that contains the tile code
   type: "birthdays"   # The id of the widget type. Not the id above 
                       # has to have the form [type]_[someNumber]

Now we can use this snippet to configure the birthday widget in a variety of ways

I want to suggest a widget, but the user can remove it, if they don't like it

For this, you can use the "eager" configuration method. Not that if you specify an eager or protected widget, all default widgets from Open-Xchange will not be configured as defaults anymore, so you might want to configure them as eager tiles as well. But let's stick to the birthday widget for now.

  • Add a file /opt/open-xchange/etc/settings/portal.yml
io.ox/portal//widgets/eager/gen_0:
   birthdays_0:
       color: "lightgreen"
       enabled: true
       index: "first"
       inverse: false
       plugin: "plugins/portal/birthdays/register"
       type: "birthdays"

This means the widget will be enabled for users, but users can still disable it. If you want to, at a later time and since you've made significant improvements to the tile, want to show it to the user again, you have to increase the "generation" of the widget configuration and offer it again:

io.ox/portal/:
   generation: 1
io.ox/portal//widgets/eager/gen_0:
   birthdays_0:
       color: "lightgreen"
       enabled: true
       index: "first"
       inverse: false
       plugin: "plugins/portal/birthdays/register"
       type: "birthdays"
io.ox/portal//widgets/eager/gen_1:
   birthdays_0:
       color: "lightgreen"
       enabled: true
       index: "first"
       inverse: false
       plugin: "plugins/portal/birthdays/register"
       type: "birthdays"

All the "gen_[number]" entries up the tie io.ox/portal//generation will be used for this configuration. If a tile is deleted it is deleted only in that generation so can be reintroduced in a later portal configuration generation. If you want to keep the default tiles as used as a fallback for App Suite, you need this configuration to start out with:

io.ox/portal//widgets/eager/gen_0:
   mail_0: 
       plugin: 'plugins/portal/mail/register'
       color: 'blue'
       enabled: true
       index: 1
   calendar_0: 
       plugin: 'plugins/portal/calendar/register'
       color: 'red'
       enabled: true
       index: 2
   tasks_0: 
       plugin: 'plugins/portal/tasks/register'
       color: 'green'
       enabled: true
       index: 3
   birthdays_0:
       plugin: 'plugins/portal/birthdays/register'
       color: 'lightgreen'
       enabled: true
       index: 4
   twitter_0:
       plugin: 'plugins/portal/twitter/register'
       color: 'pink'
       enabled: true
       index: 5
   linkedin_0:
       plugin: 'plugins/portal/linkedin/register'
       color: 'lightblue'
       enabled: true
       index: 6
   

And then modify this as wanted for your deployment. Note, that LikedIn support was removed with version 7.10.

Forcing a tile

Similarly to the eager tiles, tiles can be "protected", i.e. they can not be moved, removed and disabled. The configuration for this looks like that:

io.ox/portal//widgets/protected:
   birthdays_0:
       color: "lightgreen"
       enabled: true
       index: "first"
       inverse: false
       plugin: "plugins/portal/birthdays/register"
       type: "birthdays"

If you want to allow movement of the widget, you can enable this in the following way:

io.ox/portal//widgets/protected:
   birthdays_0:
       color: "lightgreen"
       enabled: true
       index: "first"
       inverse: false
       plugin: "plugins/portal/birthdays/register"
       type: "birthdays"
       changeable:
           index: true

In which case, users will be allowed to move the tile.

One caveat in all this: After changing any of the above configuration, you will have to reload the UI *twice*, since App Suite uses read-through caching for the settings data.

Disabling a tile completely

The combination of making a tile both protected and disabling it makes it impossible for the user to enable it. From 7.6.0 on, this means it is not shown in the settings either. Before that, it was greyed out but still present.

io.ox/portal/:
  widgets:
    protected:
      quota_0:
        color: "red"
        id: "quota_0"
        enabled: false
        index: 1
        inverse: false
        plugin: "plugins/portal/quota/register"
        type: "quota"