Allowing Configuration Options in your Gadget

安全注意事项

记住用户偏好被存储在容器中的服务器，并传递URL参数的小工具，渲染服务器。
您可能要小心你放在那里。特别是，gadget 绝对不会想要存储用户偏好的用户名和密码，因为任何人可以通过访问共享 dashboard 访问 gadget ，将可以读取gadget所有者的登录信息。请参阅用户身份验证的指导方针。

[color=blue][b]Setting User Preferences via the UserPref Element in the Gadget XML[/b][/color]
你可以使用你的gadget XML规范的用户 preferences 部分，在这里你可以声明方式指定一组可配置的选项。请参阅我们的指南，小工具XML规范。

Each user preference has a name, a display name, a data type and a default value. You can also flag a user preference as required or optional.

通过gadget 访问用户 preferences，可以通过以下方法：

1.The user preferences JavaScript API, as described in the OpenSocial JavaScript API.
2.Specially-formatted tokens in the gadget XML file that are automatically substituted by the gadget renderer.
These tokens look like this: __UP_pref_name__.
3.JavaScript that sets the user preferences via the setprefs feature. See our guide to including features into your gadget.

这种配置方法的好处：
1.Development is easy. Just declare what you want in your gadget XML specification.
2.容器处理生成配置UI(界面)，保存设置，提供API以JavaScript的方式访问这些配置。
3.您可以使用自动替换的gadget规范的内容，包括替代gadget标题和其他元数据，以及主体内容。
4.这是很容易让用户找出如何更改设置，因为该容器处理的配置一直在 gadget 上。

这种配置方法的劣处：
1.这是不灵活的。你被限制在少数的数据类型，UI无法控制，你唯一可以做的验证是根据需要或可选设置的字段。
2.用户首选项是静态的。没有办法更改配置设置程序的数量和类型。只有被硬编码在规范文件中的枚举类型的preferences的值(呈现为一个单选按钮或选择列表)。
这意味着没有有用的事情可以做，像JIRA一样选择 project.
3.iGoogle和Atlassian产品目前刷新整个页面,当你保存一个用户偏好形式。
这意味着：
a)如果您使用的值作为文字的HTML，你一定不要 double-escape (双逃逸)它。
b)如果您使用其他方式的值(例如URL)，那么你必须 unescape (反向转义)它。

[color=blue][b]Handling Configuration Inside your Gadget[/b][/color]

另一种选择是处理自己的配置，小工具里面。这是使用记住gadget的方法。
例如。在这种情况下，您可以将设置存储在隐藏式的用户偏好，使用setprefs API作为谷歌开发者指南中所述，也可以拿出来存储设置一些其他的方式。
您可能会感兴趣的看着通过JSON API serialising 数据。

这种配置方法的好处：
1.你可以做任何你想要在你的配置界面：动态加载数据，提供花哨的UI控件，使用Flash或Java，隐藏和显示部分取决于哪些用户输入。等等。
2.你可以保存通过你想要的方式，发送它返回给应用服务器，保存在cookie中，使用谷歌Gears的数据库。
3.如果你愿意，你还可以使用用户preferences来存储值，并保存自己搞清楚在哪里放置数据的努力。
4.因为一切都发生在 gadget 中，你能避免重新加载，动态刷新gadget部分使更改配置设置受到影响。

这种配置方法的劣处：
1.这种方法需要大量的工作。你必须编写大量的代码去做容器的用户UserPref自动处理做的事情。
例如，如果你想你的gadget标题基于用户preference，你将不得不使用的setTitle功能，你自己这样做。
2.没有既定的惯例或准则去做。
3.您需要提供自己的用户界面进入配置模式，由于容器提供的编辑命令只适用于用户使用UserPref。