====== GeoGebrEmbed ======

---- plugin ----
description: Embed GeoGebra applets into DokuWiki
author     : Philipp Imhof
email      : dev@imhof.cc
type       : syntax
lastupdate : 2021-10-19
compatible : Hogfather, 2020-07-29
depends    :
conflicts  : ggb
similar    : ggb
tags       : math, geogebra

downloadurl: https://github.com/PhilippImhof/GeoGebrEmbed/zipball/main
bugtracker : https://github.com/PhilippImhof/GeoGebrEmbed/issues
sourcerepo : https://github.com/PhilippImhof/GeoGebrEmbed/
donationurl: none
----


===== Description =====

This plugin allows for quick, easy and HTML5 compatible embedding of GeoGebra applets in DokuWiki pages.


===== Examples/Usage =====


In its most basic form, you can just include some activity from GeoGebra.org (formerly known as GeoGebraTube):

  <ggb>17499</ggb>
  
The plugin will use the pre-configured default values (see below).


In reality, you will most certainly want to set at least a few options. Or you might prefer to directly use an existing GGB file rather than upload it to GeoGebra.org:

  <ggb 450x300>17499</ggb>
  <ggb>{{:path:to:your:file.ggb}}</ggb>
  <ggb appName="geometry" pb></ggb>

== Screenshot == 

{{https://user-images.githubusercontent.com/52650214/136657931-be18ce11-58f3-4582-95d2-f4538c23a2c4.png|Screenshot}}


===== Syntax =====

==== General syntax ====

All parameters are optional. If you make use of the **size** parameter, it MUST come first. Other than that, parameters can appear in any order.

<code><ggb size htmlparams ggbparams>source</ggb>
< ggb size htmlparams ggbparams>source</ggb></code>
  * using ''< ggb>'' instead of ''<ggb>'' will center the applet on the page
  * **size** can be one of these:
    * //width//
    * //width//''x''//height//, e.g. ''800x600''
  * **htmlparams** can currently be ''class="..."''. The classes will be added to the ''div'' as is.
  * **ggbparams** will be forwarded to the GeoGebra applet; please note:
    * if the parameter is a numeric value, no quotes are needed, e.g. ''scale=2''
    * if the parameter is a boolean value, no quotes are needed, e.g. ''showMenuBar=true''
    * if the parameter is a string, you MUST use quotes, e.g. ''appName="graphing"''
  * **source** can be one of these:
    * GeoGebra.org material ID (formely known as GeoGebraTube ID)
    * a (previously uploaded) file, as inserted by DokuWiki's Media Manager
    * a base64 encoded string containing the necessary data


== Please note == 
  * If you want to upload and insert a GeoGebra file using the Media Manager, you will have to add the following to ''<wikiroot>/conf/mime.local.conf'': \\ <code>ggb	application-x/geogebra-file</code> If that file does not exist, you will have to create it. Without this setting, Media Manager will prevent you from uploading ''*.ggb'' files.
  * If the **source** is an alphanumeric string //not longer// than 12 chars (default), it will automatically interpret it as a material ID. Longer strings will be considered as base 64. The threshold can be configured.
  * Regardless of the auto-detection mentioned above, you can always provide an ID explicitly by writing ''id:XXXXXX''. There is currently no need for that, but one never knows, i.e. GeoGebra.org could decide to change the format of its material IDs. This would give you a workaround while waiting for an update to the plugin.
  * When embedding a GeoGebra applet using its material ID, this ID can be found in the page's source code. If you do not want the ID to become public, you cannot use this variant. Embedding is no protection, it is just a convenience.
  * When inserting a GGB file via the Media Manager, you will have trailing chars, i. e. ''{{ :path:to:file.ggb |}}''. This is normally used to provide an alternative text for images.. The GeoGebrEmbed plugin does not make use of this feature. However, you do not have to remove the ''|}}'' part. This means, you can just select a GGB file from the Media Manager and it will work.
  * Floating text around a GeoGebra applet (like you might do with an image) will not work, because applets are embedded in multiple ''<div>''s and we do not have full control over the styling.


==== Short forms ====

Some common parameters can be set using short forms:

^ short form ^ replaced by ^
| border / bc | borderColor |
| sb / nosb | allowStyleBar=true / false|
| ld / nold | enableLabelDrags=true / false|
| rc / norc | enableRightClick=true / false|
| sdz / nosdz | enableShiftDragZoom=true / false|
| pb / nopb | playButton=true / false|
| ai / noai | showAlgebraInput=true / false|
| ab / noab | showAnimationButton=true / false|
| fsb / nofsb | showFullscreenButton=true / false|
| mb / nomb | showMenuBar=true / false|
| ri / nori | showResetIcon=true / false|
| tb / notb | showToolBar=true / false|
| zb / nozb | showZoomButtons=true / false|


== Examples ==
  * In order to set a red border using the short form, you could write ''bc="#FF0000"'' or ''border="#FF0000"''. 
  * In order to activate the reset icon, you write ''ri''. Alternatively, if you have the reset icon globally enabled (see configuration options), you can write ''nori'' in order to disable it for the given applet.

If you feel a parameter would deserve a short form, please [[https://github.com/PhilippImhof/GeoGebrEmbed/issues/new|open an issue]] on the bug tracker.

==== Full list of supported parameters ====

Please see the [[https://wiki.geogebra.org/en/Reference:GeoGebra_App_Parameters|GeoGebra reference page]] for a complete list of parameters.

The plugin will forward any parameter to GeoGebra without further treatment, except for
  * short forms, which will be converted to the corresponding official parameter and then passed on to GeoGebra
  * the ''class'' parameter, which is passed to the ''<div>'' that will contain the applet



===== Configuration and Settings =====

You can specify a set of default options that will be used for applets where you did not locally set the corresponding parameters. Also, the first two parameters allow you to change default settings of the plugin.

^ option ^ explanation ^
| config_url | Path to GeoGebra's ''deployggb.js'' script. This script is needed in order to inject the applet(s) you want to include. It is generally fine to leave this option as is, but you might want to use your own copy of that script, e.g. for privacy reasons or for testing purposes. | 
| config_threshold | As explained above, the plugin will try to guess whether you supplied a GeoGebra material ID or base64 encoded data. All alphanumeric input //not longer// than this threshold will be treated as material ID. You normally do not have to change this value, but these IDs could suddenly become much longer in the future. | 
| default_width | This will be used if you do not specify a width for your applet. |
| default_height | This will be used if you do not specify a width and height for your applet. If you specify a width, but no height, this parameter is not used, because the plugin will ask GeoGebra to calculate the height accordingly. |
| default_appName | If you know that your wiki will use a certain GeoGebra app most of the time, you can use this option to save some typing. Remember that you can specify the app to be used for any given applet. | 
| default_borderColor | Default border color to be used if you do not specify a color for your applet. |
| default_enableRightClick | Whether the right click functionality should be activated for applets where you do not specify this option. |
| default_enableLabelDrags | Whether the dragging of labels should be possible for applets where you do not specify this option. |
| default_enableShiftDragZoom | Whether zooming and dragging should be possible using the mouse for applets where you do not specify this option. |
| default_showZoomButtons | Whether zoom buttons should be shown in applets where you do not specify this option. |
| default_showMenuBar | Whether the menubar should be shown in applets where you do not specify this option. |
| default_showToolBar | Whether the toolbar should be shown in applets where you do not specify this option. |
| default_showAlgebraInput | Whether the input bar should be shown in applets where you do not specify this option. |
| default_showResetIcon | Whether the applet should contain a reset icon in cases where you do not specify this option. |
| default_playButton | Whether the applet should show just a preview image and a play button instead of the full content. You can always override this for any given applet. |
| default_showAnimationButton | Whether the animation button (play/pause) should be shown in applets where you do not specify this option. If the applet does not contain animations, the button will not be shown regardless of this option. |
| default_showFullscreenButton | Whether the applet should contain a button that allows switching to full-screen mode. You can always override this for any given applet. |



===== Development =====

  * If you encounter a bug, please [[https://github.com/PhilippImhof/GeoGebrEmbed/issues/new|open an issue]].
  * If you have a suggestion, please make a [[https://github.com/PhilippImhof/GeoGebrEmbed/pulls|pull request]]. If you do not know what that means, just [[https://github.com/PhilippImhof/GeoGebrEmbed/issues/new|open an issue]] and describe your suggestion.


=== Change Log ===

{{rss>https://github.com/PhilippImhof/GeoGebrEmbed/commits/main.atom date}}




===== FAQ =====

=== What method does this plugin use? ===

The plugin embeds GeoGebra apps using JavaScript and HTML5 as suggested by [[https://wiki.geogebra.org/en/Reference:GeoGebra_Apps_Embedding|the relevant GeoGebra support page]].