Classes Files

Classes

Class JBlocks

Represents a jBlocks layout context

Class Summary
Constructor Attributes Constructor Name and Description
 
JBlocks(anchor)

A jBlocks context defines a rectangular viewport in which smaller sized blocks are layouted.

Method Summary

Class Detail

JBlocks(anchor)

A jBlocks context defines a rectangular viewport in which smaller sized blocks are layouted. Depending on the the setup, vertical or horizontal scrolling is managed. If no scrolling is defined, some blocks may not be shown if they can’t fit into the space.

jBlocks can be used recursively by defining blocks that are themselves jBlocks contexts handling their own layout. This is convenient to define structured blocks containing several zones, like for instance a header, content area and footer.

A viewport has a virtual size, for instance 18x12. jBlocks adapts the real pixel size to the device physical geometry. This virtual size can be controlled by the application but jBlocks provides a default behavior to adjust to the actual device. For instance, on a full size big desktop screen, the size might be 30x24, causing many blocks to be seen, while when run on a mobile phone, it can become 12x15 and scrolling must be performed to see some blocks. jBlocks handles device rotation so the 12x15 size might become 15x12 causing the library to calculate a new layout dynamically.

Parameters:
{jQuerySet} anchor Optional
the DOM element jQuery representation where to attach the JBlocks object. If omitted, the JBlock will attach to the page body when available.

Method Detail

  • addBlock(block)
    Adds a new block to the JBlocks and schedules a layout.
    Parameters:
    {Object} block
    a block object previously created using JBlocks#newBlock
  • addNewBlock(blockClass, layout, options)
    Executes in sequence JBlocks#newBlock then JBlocks#addBlock.
    Parameters:
    {String} blockClass
    the class the new block is an instance of.
    {Object} layout
    the layout for the new block.
    {Object} options
    for the new block. The options fields depends on the block class being instantiated.
    Returns:
    the newly created Block object.
  • <static> JBlocks.addSound(tag, name, path)
    Associates a tag to a sound so that it can be played later using the JBlocks.playSound method. Two sound files must be created per sound (mp3 and ogg).
    Parameters:
    {String} tag
    the logical name for the sound
    {String} name
    the main part of the files name (without the extension). If name is null, the sound is removed.
    {String} path
    the optional URL directory path where to get the sound files from. If not specified, res/sounds is added to the current script location directory path.
  • <static> JBlocks.addTranslation(translation)
    Adds the given tag/text pairs to the current translation set.
    Parameters:
    {Object} translation
    an object where keys represent the text string tag and the corresponding value the text to be used in the user interface.
    See:
    JBlocks.translate
  • <static> JBlocks.autoSyncContentSize()
    Setup handlers so that the jBlocks context will match automatically the page and respond to page resizing and rotation. This currently works only in jQuery Mobile pages.
  • blocksByTag(tag)
    Returns all the block instances marked with the given tag.
    Parameters:
    {String} tag
    the tag to search for.
    Returns:
    an array containing all the matching blocks.
  • {Boolean} canFullScreen()
    Check fullscreen availability.
    Returns:
    Whether the browser supports fullscreen
  • checkLayout()
    Check whether the JBlocks object needs a layout and schedules this layout if necessary. The layout does not happen immediately but after a delay to prevent multiple layouts to be calculated in a very short time.
  • <static> JBlocks.click()
    The function returns click or touchstart if that event is available on the platform. Using a call to $.jBlocks("click") should be preferred to using the string "click" when binding a jQuery object to the click event as "touchstart" reacts much better on a mobile or tablet.
  • <static> JBlocks.defineBlockClass(className, baseClassName, classDefinition)
    Defines a block class so blocks of that class can then be instantiated.
    Parameters:
    {String} className
    the name of the new block class
    {String} baseClassName
    the name of the block class the new class extends. To extend the top level block class, use “Block”
    {Object} classDefinition
    an object defining the new methods for that class or the methods to overload * Defines a new
  • focusBlockId(blockId)
    Ensure the specified Block object will be visible after the next layout.
    Parameters:
    {String} blockId
    the id of the block to be focused. The id can be obtained from the Block object using block.id.
    See:
    Block#focus
  • fullscreen(widget, function(entering))
    Make fullscreen the block content or part of it.
    Parameters:
    {jQuerySet} widget Optional
    the element to make fullscreen. If omitted, this.content is used.
    {Function} function(entering)
    to be called when fullscreen is entered or exited.
  • <static> JBlocks.getFrameData()
    If the current page has been opened from an IFrame block, getFrameData allows accessing some parameters from the opener. Using this method is preferred over the classical method of using URL parameters that does not support the file:// protocol.
    Returns:
    the data object from the IFrame opener block.
    See:
    IFrame#init
  • getSelf()
    Returns the JBlocks object itself so its methods can be invoked directly. 
    var jb=$.jBlocks("getSelf");
jb.addNewBlock(...);
    Returns:
    the JBlocks object.
  • hideAllBlocks()
    Makes all blocks invisible.
  • init()
    jBlocks init function.
  • <static> JBlocks.log()
    Log whatever strings or objects. The method takes any number of arguments and log each argument separated by a space. If the argument is a string it displays the string without any modification, otherwise a JSON representation of the argument is displayed. The method can be invoked as soon as the jBlocks script is loaded even if the DOM is not loaded yet.
    Parameters:
    {Stringifiable object|String} ...
  • newBlock(blockClass, layout, options)
    Creates a new block. A block is generally created with JBlocks#newBlock then immediately added with JBlocks#addBlock so it might be more convenient to use directly JBlocks#addNewBlock.
    Parameters:
    {String} blockClass
    the class the new block is an instance of.
    {Object} layout
    the layout for the new block.
    {Object} options
    for the new block. The options fields depends on the block class being instantiated.
    Returns:
    the newly created Block object.
  • <static> JBlocks.playSound(tag)
    Play a sound that has already been added by JBlocks.addSoundSound. If the sound is not available, the function silently returns.
    Parameters:
    {String} tag
    the logical name for the sound
  • popLayout()
    Restore a previously saved layout from the layouts stack.
  • pushLayout()
    Saves the current JBlocks layout into the layouts stack so that it can be later retrieved using JBlocks#popLayout.
  • removeAllBlocks()
    Remove all the blocks in the JBlocks.
  • removeBlock(blockId)
    Removes a block from a JBlocks and schedules a layout.
    Parameters:
    {String} blockId
    the id of the block to be removed. The id can be obtained from a Block object using block.id.
  • removeBlocksByTag(tag)
    Remove all the blocks matching the given tag.
    Parameters:
    {String} tag
    the tag to search for.
  • <static> JBlocks.translate(tag, placeHolders)
    Generates a translated string based on the given string tag and optional placeholders.
    Parameters:
    {String} tag
    the string tag identifying the text to be be returned.
    {Object} placeHolders Optional
    an object containing the placeholders and corresponding values to be replaced in the returned text.
    Returns:
    the full text to be used in the interface or the string tag itself if no translation has been found for this tag.
    See:
    JBlocks.addTranslation
  • updateOptions(options)
    Modifies some options parameters.
    Parameters:
    {Object} options
    an object containing the options properties to be modified. Other options properties are left unchanged.
    {Number} options.resizeDelay Optional, Default: 50
    the number of milliseconds to wait before requesting a layout when the container is resized.
    {Number} options.layoutDelay Optional, Default: 50
    the number of milliseconds to wait before doing an actual layout after it has been requested.
    {Number} options.resizeAnimateDelay Optional, Default: 400
    the number of millisecond for the blocks move animation.
    {Number} options.scrollAnimateDelay Optional, Default: 400
    the number of millisecond to animate a scroll of the viewport.
    {Boolean} options.scrollable Optional, Default: false
    is the JBlocks scrollable.
    {String} options.blockClass Optional
    class for the block HTML element.
    {String} options.blockContentClass Optional
    class for the block content HTML element.
    {Function} options.onResize Optional
    function(geometry,viewport) to be called when the viewport has been resized.
    {NumberArray} options.margin Optional, Default: [.05,.05,.05,.05]
    the margins [top,right,bottom,left] for each inner block expressed relatively to the block size.
    {NumberArray} options.padding Optional, Default: [.05,.05,.05,.05]
    the paddings [top,right,bottom,left] for each inner block expressed relatively to the block size. This is an opportunity to recalculate the viewport virtual size.
    {Boolean} options.updateFontSize Optional, Default: true
    if set, the default font size is set for the JBlocks container relatively to the size of a unit.
    {Float} options.blockShadow Optional, Default: 0
    defines a shadow for each block (i.e. 0.15).
    {Boolean} options.ownWorker Optional, Default: false
    if set to true, the JBlocks object has its own worker for solving layouts, otherwise, layout operations are performed sequencially by a global worker.
    {String} options.workerURL Optional, Default: null
    the URL of the worker script file. If set to null the worker script URL is built using the directory path of the current script and adding jblocks.worker.js.
    {Function} options.preInit Optional
    if set, this function is called just prior to attaching the jBlocks to its anchor.
    {Function} options.postInit Optional
    if set, this function is called just after attaching the jBlocks to its anchor.
  • updateSize()
    Adjust the size of the jBlocks to the current size of its anchor.
  • updateViewport(viewport)
    Modifies some viewport parameters like the virtual width or height. If the changes affect the JBlocks geometry, a layout will be performed.
    Parameters:
    {Object} viewport
    an object containing the viewport properties to be modified. Other viewport properties are left unchanged.
    {Integer} viewport.r Optional
    the top-most visible row.
    {Integer} viewport.c Optional
    the left-most visible column.
    {Integer} viewport.w Optional
    the visible virtual width of the viewport.
    {Integer} viewport.h Optional
    the visible virtual height of the viewport.
    {Boolean} viewport.fillHoles Optional, Default: true
    should holes be filled by expanding neighbor blocks
    {String} viewport.fixed Optional, Default: "width"
    which dimension(s) are fixed: width, height or both for a non-scrollable JBlocks.