diff options
| -rw-r--r-- | .gitignore | 8 | ||||
| -rw-r--r-- | Makefile.am | 10 | ||||
| -rw-r--r-- | configure.ac | 16 | ||||
| -rw-r--r-- | docs/reference/webhelper/Makefile.am.inc | 44 | ||||
| -rw-r--r-- | docs/reference/webhelper/eos.css.in | 46 | ||||
| -rw-r--r-- | webhelper/webhelper.js | 114 |
6 files changed, 224 insertions, 14 deletions
@@ -10,6 +10,7 @@ endless/eosresource-private.h data/eos-wikipedia-domain.gresource wikipedia/config.js tools/eos-run-test +docs/reference/webhelper/eos.css *.py[cod] @@ -133,3 +134,10 @@ nosetests.xml # Editor stuff *~ *.swp + +# NaturalDocs project files +/docs/reference/webhelper/Data/ +/docs/reference/webhelper/Languages.txt +/docs/reference/webhelper/Menu.txt +/docs/reference/webhelper/Topics.txt +/docs/reference/webhelper/html/ diff --git a/Makefile.am b/Makefile.am index b856f5d..013493e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -23,7 +23,7 @@ AM_CFLAGS = @STRICT_CFLAGS@ # Make sure to run Gtk-doc tests and build the documentation when doing # 'make distcheck' -DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-gir-doc +DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-gir-doc --enable-js-doc # Generated files that 'make clean' should erase CLEANFILES = @@ -35,8 +35,8 @@ dist-hook: else dist-hook: @echo "***" - @echo "*** You must configure with --enable-gtk-doc and --enable-gir-doc" - @echo "*** to run make dist or make distcheck." + @echo "*** You must configure with --enable-gtk-doc, --enable-gir-doc, and" + @echo "*** --enable-js-doc to run make dist or make distcheck." @echo "***" @false endif @@ -123,6 +123,10 @@ CLEANFILES += \ docs/reference/endless-js/html/*.js endif +# # # PURE JAVASCRIPT MODULE DOCUMENTATION # # # + +include $(top_srcdir)/docs/reference/webhelper/Makefile.am.inc + # # # SECONDARY GRESOURCES # # # wikipedia_resource_files = $(shell $(GLIB_COMPILE_RESOURCES) --sourcedir=$(srcdir)/data --generate-dependencies $(srcdir)/data/eos-wikipedia-domain.gresource.xml) diff --git a/configure.ac b/configure.ac index a74e3e0..057f98e 100644 --- a/configure.ac +++ b/configure.ac @@ -115,6 +115,8 @@ AC_PATH_PROG([GIRDOCTOOL], [g-ir-doc-tool], [notfound]) AC_ARG_VAR([GIRDOCTOOL], [Path to g-ir-doc-tool]) AC_PATH_PROG([YELPBUILD], [yelp-build], [notfound]) AC_ARG_VAR([YELPBUILD], [Path to yelp-build]) +AC_PATH_PROG([NATURALDOCS], [naturaldocs], [notfound]) +AC_ARG_VAR([NATURALDOCS], [Path to naturaldocs]) GLIB_COMPILE_RESOURCES=`$PKG_CONFIG --variable glib_compile_resources gio-2.0` AC_SUBST(GLIB_COMPILE_RESOURCES) @@ -175,12 +177,22 @@ AS_IF([test "x$enable_gir_doc" = "xyes"], [ [AC_MSG_ERROR([yelp-build must be installed for --enable-gir-doc])])]) AM_CONDITIONAL([ENABLE_GIR_DOC], [test "x$enable_gir_doc" = "xyes"]) -# For 'make dist' or 'make distcheck', both --enable-gtk-doc and -# --enable-gir-doc are required +# --enable-js-doc: Build pure Javascript module documentation. +AC_ARG_ENABLE([js-doc], + [AS_HELP_STRING([--enable-js-doc], + [Build documentation for pure Javascript modules @<:@default=no@:>@])]) +AS_IF([test "x$enable_js_doc" = "xyes"], [ + AS_IF([test "x$NATURALDOCS" = "xnotfound"], + [AC_MSG_ERROR([NaturalDocs must be installed for --enable-js-doc])])]) +AM_CONDITIONAL([ENABLE_JS_DOC], [test "x$enable_js_doc" = "xyes"]) + +# For 'make dist' or 'make distcheck', all three of --enable-gtk-doc, +# --enable-gir-doc, and --enable-js-doc are required AC_MSG_CHECKING([whether this configuration allows building distributions]) can_make_dist=yes AM_COND_IF([ENABLE_GTK_DOC], [], [can_make_dist=no]) AM_COND_IF([ENABLE_GIR_DOC], [], [can_make_dist=no]) +AM_COND_IF([ENABLE_JS_DOC], [], [can_make_dist=no]) AM_CONDITIONAL([CAN_MAKE_DIST], [test "x$can_make_dist" = "xyes"]) AC_MSG_RESULT([$can_make_dist]) diff --git a/docs/reference/webhelper/Makefile.am.inc b/docs/reference/webhelper/Makefile.am.inc new file mode 100644 index 0000000..0d99169 --- /dev/null +++ b/docs/reference/webhelper/Makefile.am.inc @@ -0,0 +1,44 @@ +if ENABLE_JS_DOC + +# This is for moving eos.css into the NaturalDocs project dir, which is in the +# build tree rather than the source tree. +docs/reference/webhelper/eos.css: docs/reference/webhelper/eos.css.in + $(AM_V_GEN)$(MKDIR_P) $(@D) + cp $< $@ + +docs/reference/webhelper/html/index.html: webhelper/webhelper.js docs/reference/webhelper/eos.css + $(MKDIR_P) $(@D) + naturaldocs -i $(<D) -o HTML $(@D) -p $(@D)/.. -s Default eos -hl All + +all-local: docs/reference/webhelper/html/index.html + +webhelper_docs_files = \ + docs/reference/webhelper/html/index.html \ + docs/reference/webhelper/html/files/webhelper-js.html \ + docs/reference/webhelper/html/index/Classes.html \ + docs/reference/webhelper/html/index/Functions.html \ + docs/reference/webhelper/html/index/General.html \ + docs/reference/webhelper/html/index/Properties.html \ + docs/reference/webhelper/html/javascript/main.js \ + docs/reference/webhelper/html/javascript/prettify.js \ + docs/reference/webhelper/html/javascript/searchdata.js \ + docs/reference/webhelper/html/search/*.html \ + docs/reference/webhelper/html/styles/*.css \ + $(NULL) +webhelper_extra_clean_files = \ + docs/reference/webhelper/Data/*.nd \ + docs/reference/webhelper/Menu.txt \ + docs/reference/webhelper/Topics.txt \ + docs/reference/webhelper/Languages.txt \ + docs/reference/webhelper/eos.css \ + $(NULL) +EXTRA_DIST += \ + $(webhelper_docs_files) \ + docs/reference/webhelper/eos.css.in \ + $(NULL) +CLEANFILES += \ + $(webhelper_docs_files) \ + $(webhelper_extra_clean_files) \ + $(NULL) + +endif diff --git a/docs/reference/webhelper/eos.css.in b/docs/reference/webhelper/eos.css.in new file mode 100644 index 0000000..7307859 --- /dev/null +++ b/docs/reference/webhelper/eos.css.in @@ -0,0 +1,46 @@ +* { + font-family: "Source Sans Pro"; +} + +p { + font-size: 16pt; + text-indent: 0; + margin-bottom: 1em; +} + +.STitle, +.CTitle, +.CGroup .CTitle { + font-size: 18pt; +} + +.CHeading { + font-size: 14pt; +} + +.SMain td, +.SClass td, +.STable, +.CDLEntry, +.CDLDescription { + font-size: 12pt; +} + +.ContentPage #Content, +.IndexPage #Index { + margin-left: 55ex; +} + +.ContentPage #Menu, +.IndexPage #Menu { + font-size: 12pt; + width: 41ex; +} + +.Prototype *, +.prettyprint *, +.CBody pre, +.CDLEntry { + font-family: "DejaVu Sans Mono"; + font-size: 13pt; +}
\ No newline at end of file diff --git a/webhelper/webhelper.js b/webhelper/webhelper.js index ccce9e7..1992973 100644 --- a/webhelper/webhelper.js +++ b/webhelper/webhelper.js @@ -5,21 +5,71 @@ const WebKit = imports.gi.WebKit; const EOS_URI_SCHEME = 'endless://'; - +/** + * Namespace: WebHelper + * Convenience library for running web applications + * + * WebHelper is a convenience library for displaying web applications inside a + * GTK container running WebKitGTK (currently WebKit 1, not 2.) + * Although WebKit provides an easy way of communicating from GTK code to + * the in-browser Javascript, through the execute_script() method, it is not so + * easy to communicate the other way around. + * + * WebHelper solves that problem by detecting when the web page navigates to a + * custom action URI. + * The custom URI corresponds to a function that you define in + * <Application._webActions>, and you can pass parameters to the + * function. + * + * Another often-encountered problem is localizing text through the same API as + * your main GTK program. + * WebHelper solves this problem by allowing you to mark strings in your HTML + * page and translating them through a function of your choice when you run + * <Application.translate_html()>. + */ + +/** + * Class: Application + * Main application class for a WebHelper application + * + * The application class in GJS for your web application should extend + * WebHelper.Application. + * + * You should set up any WebViews that you create, by connecting + * <web_actions_handler()>, so that they can handle custom action URIs. + */ const Application = new Lang.Class({ Name: 'WebApplication', Extends: Endless.Application, -// Set of actions that may be invoked from a WebView. -// Declare them as function(dict), and use links with the format -// "endless://actionName?parameter=value" - + /** + * Property: _webActions + * Set of actions that may be invoked from a WebView + * + * Declare them as a function that takes a dict as a parameter, and use + * links with the format "endless://actionName?parameter=value" + * + * *Note* This API will likely disappear and be replaced by a method + * add_web_action(). + * That is the reason for the underscore starting the name. + */ _webActions: { }, - // This callback does the translation from URI to action - // webview.connect('navigation-policy-decision-requested', - // Lang.bind(this, this.web_actions_handler)); - + /** + * Callback: web_actions_handler + * Navigation callback which routes the custom URIs to actions + * + * When you create a web view in which you want to run a web application + * that uses custom action URIs, remember to set it up by connecting this + * callback to its "navigation-policy-decision-requested" signal. The + * following code will do this: + * + * > webview.connect('navigation-policy-decision-requested', + * > Lang.bind(app, app.web_actions_handler)); + * + * where 'webview' is the web view, and 'app' is the WebHelper.Application + * instance. + */ web_actions_handler: function(webview, frame, request, action, policy_decision) { let uri = request.get_uri(); @@ -68,6 +118,52 @@ const Application = new Lang.Class({ return dom.get_element_by_id(id); }, + /** + * Property: _translationFunction + * Function which transforms all translatable text + * + * When you plan to use the <translate_html()> function to translate text in + * your web application, set this property to the translation function. + * The function must take one parameter, a string, and also return a + * string -- for example, gettext(). + * + * *Note* This API will likely disappear and be replaced by a read-write + * translation_function property. + * That is the reason for the underscore starting the name. + */ + + /** + * Method: translate_html + * Translate all translatable text currently showing in a web view + * + * Parameters: + * webview - the WebView containing the text to translate. + * + * Another problem with running web applications inside a GTK container is + * keeping all the localization data in the same place. + * For example, the most obvious way to do localization in a GTK application + * is to use gettext(), but that does not work so easily inside a web view. + * + * In a <WebHelper.Application>, you can mark strings in your HTML for + * translation by enclosing them in + * > <span name="translatable">String to be translated</span> + * or just putting the "translatable" name directly on the element + * containing the string, e.g. <p> or <h1>. + * + * Then after the web view has finished loading, call <translate_html()> on + * it, and each of the marked strings will be passed to the function that + * you specify using the <_translationFunction> property. + * The return value from <_translationFunction> will be substituted into the + * HTML instead of the original string. + * + * Example: + * > app._translationFunction = _; + * > webview.connect('notify::load-status', + * > Lang.bind(app, function(webview) { + * > if(webview.load_status == WebKit.LoadStatus.FINISHED) + * > this.translate_html(webview); + * > })); + */ translate_html: function(webview) { let dom = webview.get_dom_document(); |