You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/03/20 03:15:55 UTC
[45/50] incubator-guacamole-manual git commit: GUAC-1378: Document
modifying existing HTML with extensions.
GUAC-1378: Document modifying existing HTML with extensions.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/34ef2103
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/34ef2103
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/34ef2103
Branch: refs/heads/master
Commit: 34ef210366ffec5ab9b063d604d659112cde86f3
Parents: 3cc4e23
Author: Michael Jumper <mi...@guac-dev.org>
Authored: Fri Feb 19 16:28:51 2016 -0800
Committer: Michael Jumper <mi...@guac-dev.org>
Committed: Fri Feb 19 16:28:51 2016 -0800
----------------------------------------------------------------------
src/chapters/guacamole-ext.xml | 112 +++++++++++++++++++++++++++++++++++-
1 file changed, 111 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/34ef2103/src/chapters/guacamole-ext.xml
----------------------------------------------------------------------
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index 49364af..b42f967 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -41,7 +41,7 @@
<filename>.jar</filename> relative to the root, as well.</para>
<para>Beyond this, the semantics and locations associated with all other resources within
the extension are determined by the extension manifest alone.</para>
- <section>
+ <section xml:id="extension-manifest">
<title>Extension manifest</title>
<para>The Guacamole extension manifest is a single JSON file,
<filename>guac-manifest.json</filename>, which describes the location of each
@@ -123,6 +123,21 @@
</entry>
</row>
<row>
+ <entry><property>html</property></entry>
+ <entry>
+ <para>An array of all HTML files within the extension that should be
+ used to update or replace existing HTML within the Guacamole
+ interface. All paths within this array must be relative paths,
+ and will be interpreted relative to the root of the
+ archive.</para>
+ <para>HTML files declared here will be automatically applied to
+ other HTML within the Guacamole interface when the web
+ application loads within the user's browser. The manner in which
+ the files are applied is dictated by <tag><meta ...></tag>
+ within those same files.</para>
+ </entry>
+ </row>
+ <row>
<entry><property>translations</property></entry>
<entry>
<para>An array of all translation files within the extension. All
@@ -178,6 +193,8 @@
"css" : [ "theme.css" ],
+ "html" : [ "loginDisclaimer.html" ],
+
"resources" : {
"images/logo.png" : "image/png",
"images/cancel.png" : "image/png",
@@ -187,6 +204,99 @@
}</programlisting>
</informalexample>
</section>
+ <section xml:id="patch-html">
+ <title>Updating existing HTML</title>
+ <para>The existing HTML structure of Guacamole's interface can be modified by extensions
+ through special "patch" HTML files declared by the <property>html</property>
+ property in <filename>guac-manifest.json</filename>. These files are HTML fragments
+ and are identical to any other HTML file except that they contain Guacamole-specific
+ <tag>meta</tag> tags that instruct Guacamole to modify its own HTML in a
+ particular way. Each <tag>meta</tag> tag takes the following form:</para>
+ <informalexample>
+ <programlisting><meta name="<replaceable>NAME</replaceable>" content="<replaceable>SELECTOR</replaceable>"></programlisting>
+ </informalexample>
+ <para>where <replaceable>SELECTOR</replaceable> is a CSS selector that matches the
+ elements within the Guacamole interface that serve as a basis for the modification,
+ and <replaceable>NAME</replaceable> is any one of the following defined
+ modifications:</para>
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><property>before</property></entry>
+ <entry>
+ <para>Inserts the specified HTML immediately before any element
+ matching the CSS selector.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>after</property></entry>
+ <entry>
+ <para>Inserts the specified HTML immediately after any element
+ matching the CSS selector.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>replace</property></entry>
+ <entry>
+ <para>Replaces any element matching the CSS selector with the
+ specified HTML.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>before-children</property></entry>
+ <entry>
+ <para>Inserts the specified HTML immediately before the first child
+ (if any) of any element matching the CSS selector. If a matching
+ element has no children, the HTML simply becomes the entire
+ contents of the matching element.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>after-children</property></entry>
+ <entry>
+ <para>Inserts the specified HTML immediately after the last child
+ (if any) of any element matching the CSS selector. If a matching
+ element has no children, the HTML simply becomes the entire
+ contents of the matching element.</para>
+ </entry>
+ </row>
+ <row>
+ <entry><property>replace-children</property></entry>
+ <entry>
+ <para>Replaces the entire contents of any element matching the CSS
+ selector with the specified HTML.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>For example, to add a welcome message and link to some corporate privacy policy (a
+ fairly common need), you would add an HTML file like the following:</para>
+ <informalexample>
+ <programlisting><meta name="after" content=".login-ui .login-dialog">
+
+<div class="welcome">
+ <h2>Welcome to our Guacamole server!</h2>
+ <p>
+ Please be sure to read our <a href="/path/to/some/privacy.html">privacy
+ policy</a> before continuing.
+ </p>
+</div></programlisting>
+ </informalexample>
+ <para>After the extension is installed and Guacamole is restarted, the "welcome" div and
+ its contents will automatically be inserted directly below the login dialog (the
+ only element that would match <code>.login-ui .login-dialog</code>) as if they were
+ part of Guacamole's HTML in the first place.</para>
+ </section>
</section>
<section xml:id="environment">
<title>Accessing the server configuration</title>