AppSuite:Embedding your settings into AppSuite settings: Difference between revisions

From Open-Xchange
No edit summary
 
(15 intermediate revisions by 8 users not shown)
Line 1: Line 1:
''Synopsis:'' This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6.
<!-- !!! -->
<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation -->
<!-- !!! -->
 
<div class="title">Embedding your settings into AppSuite settings</div>
 
''Synopsis:'' This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6. Not to be confused with [[AppSuite:Creating_a_settings_section_in_AppSuite_settings | simply adding new settings]] into AppSuite


__TOC__
__TOC__
Line 5: Line 11:


== Declare the page you want to embed ==
== Declare the page you want to embed ==
Before you start you need to know the group where you want to add the settings (since 7.8.0):
<pre>
gerneral:
Basic Settings
Accounts
main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive
tools:
Pubications and Subscriptions
Error Log
Download
external:
Groups
Resources
</pre>
Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.


You can declare pages to embed via [[ConfigCascade|Config Cascade]] settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:
You can declare pages to embed via [[ConfigCascade|Config Cascade]] settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:
Line 10: Line 43:
  ➜ /opt/open-xchange/etc/settings/configjump.yml
  ➜ /opt/open-xchange/etc/settings/configjump.yml
  io.ox/settings/configjump//changePlans:
  io.ox/settings/configjump//changePlans:
     url: "<http://localhost/~fla/changePlans.php?token=[token]"
     url: "http://localhost/~fla/changePlans.php?token=[token]"
     title: “Change Plan”
    group: general
     after: "io.ox/mail"
     title: "Change Plan"
     before: "io.ox/settings/accounts"
    advancedMode: false # not needed anymore for 7.8.0


''io.ox/settings/configjump'' contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.
''io.ox/settings/configjump'' contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.
Line 18: Line 53:
An object of this type has the following properties:
An object of this type has the following properties:


* '''url''': The URL to be branched to. The place holder [token] will be replaced by the token you get from the [[Login variations#Token Login|token login system]]
* '''url''': The URL to be branched to. The place holder [token] will be replaced by the token you get from the token login system
* '''title''': The title as to be seen on the settings page.
* '''title''': The title as to be seen on the settings page.
* '''after''', '''before''' or '''index''': Where the page is supposed to be positioned. ''Hint:'' If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL.
* '''group''': Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools". For settings inside folders you have to use the group and the name of the config object, for example: group: main/io.ox/mail
* '''after''', '''before''' or '''index''': To define the exact location of the page. ''Hint:'' If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)
* '''requires''': A string of capabilities. Supports boolean operators like && (AND), || (OR), ! (NOT), as well as parentheses. Example: !guest.
 
It's also possible to provide custom translations for the title. Just add "title_" plus the locale:
io.ox/settings/configjump//changePlans:
    url: "http://localhost/~fla/changePlans.php?token=[token]"
    title: "Change Plan"
    title_en_US: "Change plan"
    title_de_DE: "Plan ändern"
    title_fr_FR: "..."
    ...
    after: "io.ox/mail"


== Create a secret ==
== Create a secret ==
Line 26: Line 74:
Now you just need to declare the app your are about to embed in the backend and you are good to go:
Now you just need to declare the app your are about to embed in the backend and you are good to go:


  ➜ cat tokenlogin-secrets
  ➜ cat /opt/open-xchange/etc/tokenlogin-secrets
  #
  #
  # Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
  # Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
Line 38: Line 86:


This secret, combined with the token, can be traded for a login.
This secret, combined with the token, can be traded for a login.


== Redeem a token ==
== Redeem a token ==
Line 55: Line 102:


[[Category:Administrator]][[Category:Developer]]
[[Category:Administrator]][[Category:Developer]]
== Stuck somewhere? ==
You got stuck with a problem while developing? OXpedia might help you out with the article about [https://documentation.open-xchange.com/latest/ui/miscellaneous/debugging.html debugging the UI].

Latest revision as of 10:01, 22 May 2017


Embedding your settings into AppSuite settings

Synopsis: This article explains how you can embed your own configuration page via iFrame into the AppSuite's settings and pass our session onto your implementation. This is a replacement for "Config Jump" of OX6. Not to be confused with simply adding new settings into AppSuite


Declare the page you want to embed

Before you start you need to know the group where you want to add the settings (since 7.8.0):

gerneral:
Basic Settings
Accounts

main:
Portal
Mail
Guard
Address Book
Calendar
Tasks
Drive

tools:
Pubications and Subscriptions
Error Log
Download

external:
Groups
Resources

Note: the layout of the settings page might differ depending on which packages you have installed and/or which capabilities the user has.

You can declare pages to embed via Config Cascade settings. There are several ways to do so, this example uses the most comfortable one, a YAML declaration:

➜ /opt/open-xchange/etc/settings/configjump.yml
io.ox/settings/configjump//changePlans:
   url: "http://localhost/~fla/changePlans.php?token=[token]"
   group: general
   title: "Change Plan"
   before: "io.ox/settings/accounts"
   advancedMode: false # not needed anymore for 7.8.0

io.ox/settings/configjump contains one object per embedded page (e.g. "changePlans"). If you want to add more pages, follow this pattern.

An object of this type has the following properties:

  • url: The URL to be branched to. The place holder [token] will be replaced by the token you get from the token login system
  • title: The title as to be seen on the settings page.
  • group: Settings section where the page is supposed to appear. Valid groups are: "general", "main", "tools", and "external". Default is "tools". For settings inside folders you have to use the group and the name of the config object, for example: group: main/io.ox/mail
  • after, before or index: To define the exact location of the page. Hint: If you want to name a page as reference (as opposed to using the index), you need to figure out the name. One way to do so is go to that page in the settings and check for the id parameter in the URL (for example http://my.ox/appsuite/#!!&app=io.ox/settings&folder=virtual/settings/io.ox/tasks will be io.ox/tasks)
  • requires: A string of capabilities. Supports boolean operators like && (AND), || (OR), ! (NOT), as well as parentheses. Example: !guest.

It's also possible to provide custom translations for the title. Just add "title_" plus the locale:

io.ox/settings/configjump//changePlans:
   url: "http://localhost/~fla/changePlans.php?token=[token]"
   title: "Change Plan"
   title_en_US: "Change plan"
   title_de_DE: "Plan ändern"
   title_fr_FR: "..."
   ...
   after: "io.ox/mail"

Create a secret

Now you just need to declare the app your are about to embed in the backend and you are good to go:

➜ cat /opt/open-xchange/etc/tokenlogin-secrets
#
# Listing of known Web Application secrets followed by an optional semicolon-separated parameter list
#
# e.g. 1254654698621354; accessPasword=true
#

# Dummy entry
# 1234-56789-98765-4321; accessPassword=true
12345-phpapp-54321

This secret, combined with the token, can be traded for a login.

Redeem a token

GET /login?action=redeemToken
  • token: The token you want to trade.
  • secret: A valid secret for your app.

This request can be sent by the embedded app to the AppSuite backend to get authorisation info.


Stuck somewhere?

You got stuck with a problem while developing? OXpedia might help you out with the article about debugging the UI.