How To

Description

This page shows the utilities provided to modify and personalize the 3DHOP viewer interface and aspect.

Interface and dimensioning

Click to run live demo
Customizing the 3DHOP viewer

Set Up

3DHOP is provided as an HTML element, and thus it follows the rules that govern this kind of entity: i.e. is possible to modify the style through a CSS file or to manage the user interaction using scripting methods.
However with the aim to facilitate the setting and the personalization of the viewer environment, 3DHOP provides a couple of tools able to make easier the work of less experienced users, without preventing advanced users from modifying interface and adding functionality.
These tools operate on two different sides of the viewer: the interface and the external aspect. Let's start to observe what has been done concerning the first issue.

To improve the 3DHOP usability experience together with the basic version of the viewer we provide an useful toolbar. This toolbar, recognizable by the "toolbar" identification tag, is no more than a simple HTML element, superimposed on the CANVAS (using the "absolute" value for the CSS position property), and defined inside the proper 3DHOP DIV element, in this way: 

<div id="3dhop" class="tdhop" onmousedown="if (event.preventDefault) event.preventDefault()">
 <div id="toolbar">
  <img id="home"       title="Home"                  src="skins/dark/home.png"         /><br/> 
  <img id="zoomin"     title="Zoom In"               src="skins/dark/zoomin.png"       /><br/>
  <img id="zoomout"    title="Zoom Out"              src="skins/dark/zoomout.png"      /><br/>
  <img id="light_on"   title="Disable Light Control" src="skins/dark/lightcontrol_on.png" 
                                                          style="position:absolute; visibility:hidden;"/>
  <img id="light"      title="Enable Light Control"  src="skins/dark/lightcontrol.png" /><br/>
  <img id="full_on"    title="Exit Full Screen"      src="skins/dark/full_on.png" 
                                                          style="position:absolute; visibility:hidden;"/>
  <img id="full"       title="Full Screen"           src="skins/dark/full.png"         />
 </div>
 <canvas id="draw-canvas" style="background-image: url(skins/backgrounds/light.jpg)"/>
</div>

As can be seen in the code in the above box, the toolbar in his basic appearance is formed by four button icons (represented by HTML images), related with the appropriate actions by their tag id.
The actions specification occurs then in a JavaScript function (called "actionsToolbar") placed in an express scripting block: 

function actionsToolbar(action) {
  if(action=='home')
    presenter.resetTrackball();
  else if(action=='zoomin') 
    presenter.zoomIn();
  else if(action=='zoomout') 
    presenter.zoomOut(); 
  else if(action=='light' || action=='light_on') { 
    presenter.enableLightTrackball(!presenter.isLightTrackballEnabled()); lightSwitch(); } 
  else if(action=='full'  || action=='full_on') 
    fullscreenSwitch(); 
}

From the above code is easy to see that in the method which drives the toolbar actions, basically we have just connected the toolbar button id tags ("home", "zoomin", "zoomout", …) with the appropriate function provided by our viewer ("resetTrackball()", "zoomIn()", "zoomOut()", …).
Thanks to this structure, highly schematic and easy to understand, the toolbar functionalities initially given can be freely modified by the user just adding or removing HTML buttons (i.e. images) from the "toolbar" DIV earlier defined, and then consequently changing the id-action associations placed in the "actionsToolbar" JavaScript function (of course several other action methods are provided further those shown here, a complete list of whom can be found in the documentation section).
However this toolbar is only one of the possible interfaces achievable, in reality the CANVAS interaction methods provided by 3DHOP and previously listed, can be used in multiple ways, changing the performing mode, or using different HTML elements whom connect them (like for example text links placed along the Web page, or more broadly, any other HTML element that user likes).

Well, as said at the beginning, another possible personalization of our viewer regards his external aspect. Two immediate methods are provided to the user, avoiding him to edit the elements style properties inline in the HTML code or in the CSS file.
The proposed functions have an effect on the CANVAS size and on the toolbar DIV positioning, and can be used to modify the default given values after the viewer initialization and setup, as shown below: 

$(document).ready(function(){
  init3dhop();

  setup3dhop();
  
  resizeCanvas(800,600);

  moveToolbar(20,20);  
});

As is easy to imagine "resizeCanvas" set in the CANVAS size (adaptive to the 3DHOP parent element, by default), taking in input the news horizontal and vertical sides dimensions (in pixels).
The method deputed to move the toolbar DIV around the screen is instead "moveToolbar". His displacement is related to the 3DHOP position in the page, in fact the function takes as input the horizontal and vertical shift (still in pixels) from the left-up corner of the CANVAS (notice that the toolbar movement is not confined in the viewer space, but can overcome his edges).

A Word On 3DHOP Dimensioning

It is important to say something about the dimensioning of the 3DHOP viewer.
By default the 3DHOP element behaves like a fluid, adapting itself to the container. This means that its width and height will be the same as its parent element (excluding margins and paddings). But the 3DHOP dimensioning has been also designed to be responsive, meaning that the interactive resize of its parent element will result in the real-time resizing of the 3DHOP viewer (equivalent to set up its width and height to 100%).
It worth noting that if no container elements are defined the 3DHOP size will be "full browser". In this case, the real-time resizing of the browser window will produce the real-time resizing of the 3DHOP element.
So, to assign to 3DHOP a fixed size it is sufficient to enclose it in a parent element (for instance a DIV) defined by fixed width and height. Alternatively, can be used the "resizeCanvas" function above specified (in this case no parent element are required). Of course, with both these last two settings, the dimensioning of 3DHOP will stop to be responsive.

Reassuming 3DHOP is provided by default with a toolbar as interface and with two express methods to modify its appearance in the web page. To exploit these features it is only necessary to add to the base code the toolbar instantiation (both HTML and JavaScript side), while the aspect related functions are directly available (without addictions needed).

The complete sources of this example are provided together the 3DHOP code in the download section.

If you want instead to learn more about how to load the 3D models inside 3DHOP please click here and go to the next HOWTO.