Class: RSence::Plugins::Plugin__

Inherits:
Object
  • Object
show all
Includes:
PluginBase
Defined in:
lib/rsence/plugins/plugin.rb

Overview

The Plugin__ is actually available as Plugin from plugin bundles using the Plugin class mimic method.

The Plugin class is the base class for extending server logic. A single Plugin instance serves the requests of all sessions, which makes them very cpu and memory efficient compared to systems, where the server classes are constructed and destructed for each request.

Plugins are designed to be contained in a plugin directory bundle and to be loaded by the main RSence::PluginManager, which is also responsible for delegating the events and other calls throughout the system.

Anatomy of a plugin bundle

First read about the Plugin Bundles.

The plugin bundle contains all data needed to run the plugin. Design your plugin without any hard-coded paths, remember that it’s intended to be installed by moving or copying the whole plugin into one of the “plugins” directories. Use RSence::Plugins::PluginBase#bundle_path to construct paths.

The RSence::PluginManager looks for these bundles and evaluates them into an anonymous Module namespace. The contents of the ruby source file is then responsible for including its libraries, constructing an instance of itself and registering itself as a part of the system.

Use the GUIPlugin class for plugins that handle user interfaces. Use the Plugin class for plugin bundles that provide supplemental functionality, value responders and other utilities that supplement the user interface.

Extension hooks for server events

These methods are provided as the basic server event hooks:

  • #init – Use instead of initialize

  • #open – Extend to open objects

  • #flush – Extend to write the state and to flush buffers

  • #close – Extend to close objects

Extension hooks for session events

  • #idle – Extend to implement logic for each client data synchronization and “idle poll” request.

  • #init_ses – Extend to implement logic when a new session is created. A new session is created, when a user enters accesses the server the first time, or the first time after the previous session expired.

  • #restore_ses – Extend to implement logic when an old session is restored. A session is restored, when the user returns to the page or reloads the page before the session is expired.

Extension hooks for session events, If the server is configured to restore and clone previous sessions (default):

When sessions are cloned, the previous session is not invalidated and exists until timing out as a result of the web browser window being closed or client computer losing network connectivity for a certain (configurable) time frame.

  • #cloned_target – Extend to implement logic in the request when session is a clone of the original session.

  • #cloned_source – Extend to implement logic in the next request of the original session after it has been cloned.

If the server is configured to not clone sessions:

When the user accesses the same page using the same browser (in different tabs or windows), only the most recently restored one is valid, while the previous ones are immediately invalidated. This is a more secure mode of operation, but has several drawback to usability, so it’s not enabled by default.

Utility methods

These are general utility methods not intended to be extended.

Client-support

These methods are intended for server-client interaction. Namely, commanding the client.

  • #read_js Returns a javascript source file.

  • #read_js_once Returns a javascript source file once per session.

  • #values_js Returns a javascript source snippet containing references to values.

  • #include_js Tells the client to load a library package.

See also

Direct Known Subclasses

GUIPlugin__

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from PluginBase

#bundle_path, #close, #file_exist?, #file_read, #file_write, #flush, #httime, #json_read, #method_missing, #open, #yaml_read, #yaml_write

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class RSence::Plugins::PluginBase

Instance Attribute Details

#info ⇒ Hash (readonly)

Returns The meta-information of the plugin bundle.

Returns:



81
82
83
 
# File 'lib/rsence/plugins/plugin.rb', line 81

def info
  @info
end

#name ⇒ Symbol (readonly)

Returns The name of the plugin bundle.

Returns:

  • (Symbol) —

    The name of the plugin bundle



75
76
77
 
# File 'lib/rsence/plugins/plugin.rb', line 75

def name
  @name
end

#path ⇒ String (readonly)

Returns The absolute path of the plugin bundle.

Returns:

  • (String) —

    The absolute path of the plugin bundle.



78
79
80
 
# File 'lib/rsence/plugins/plugin.rb', line 78

def path
  @path
end

Instance Method Details

#brew_coffee(path) ⇒ Object

Returns coffee compiled to js



251
252
253
 
# File 'lib/rsence/plugins/plugin.rb', line 251

def brew_coffee( path )
  client_pkg.coffee( file_read( path ) )
end

#cloned_source(msg, target_sessions) ⇒ nil

Extend this method to invoke actions, when the session has been cloned to another session. It’s called once, just before #restore_ses is called on the first request after the cloning happened.

A session is cloned, when a user opens a another browser window or tab, while the previous session is still active.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • target_session (Hash) —

    The actual cloned session object, which is a copy of the current session.

Returns:

  • (nil) 


156
157
 
# File 'lib/rsence/plugins/plugin.rb', line 156

def cloned_source( msg, target_sessions )
end

#cloned_target(msg, source_session) ⇒ nil

Extend this method to invoke actions, when the session is a clone of another session. It’s called once, just before #restore_ses is called.

A session is cloned, when a user opens a another browser window or tab, while the previous session is still active.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • source_session (Hash) —

    The actual previous session object, which was used as the source of the clone.

Returns:

  • (nil) 


145
146
 
# File 'lib/rsence/plugins/plugin.rb', line 145

def cloned_target( msg, source_session )
end

#get_ses(msg, key = false) ⇒ Hash

This method returns (or creates and returns) the entry in the session based on the name your plugin is registered as. It’s advised to use this call instead of manually managing msg#session in most cases.

Uses the first name registered for the plugin and converts it to a symbol.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • key (Symbol) (defaults to: false) —

    (optional) returns a ses key, if defined.

Returns:

  • (Hash) —

    Plugin-specific session hash



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/rsence/plugins/plugin.rb', line 190

def get_ses( msg, key=false )
  name_sym = name_with_manager_s.to_sym
  if msg.class == RSence::Message
    session = msg.session
  elsif msg.class == Hash
    session = msg
  else
    warn "Invalid class (#{msg.class}) for get_ses in #{name_sym.inspect}!"
    return nil
  end
  unless session.has_key?( name_sym )
    session[ name_sym ] = {}
  end
  ses = session[ name_sym ]
  return ses[key] if key
  return ses
end

#guess_js_path(js_name) ⇒ Object

Returns an array of type (:js/:coffee/:none), path (string)



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/rsence/plugins/plugin.rb', line 209

def guess_js_path( js_name )
  has_slash = js_name.include?('/')
  is_coffee = false
  is_js = false
  if has_slash
    js_fn = js_name.split('/')[-1]
  else
    js_fn = js_name
  end
  if js_fn.include?('.')
    js_ext = js_fn.split('.')[-1]
    if js_ext == 'coffee'
      is_coffee = true
    elsif js_ext == 'js'
      is_js = true
    end
  end
  if has_slash
    sub_ptah = false
  else
    sub_path = 'js'
  end
  if is_coffee or is_js
    path = bundle_path( js_name, sub_path, '.'+js_ext )
    found = file_exist?( path )
  else
    path = bundle_path( js_name, sub_path, '.coffee' )
    found = file_exist?( path )
    if found
      is_coffee = true
    else
      is_js = true
      path = bundle_path( js_name, sub_path, '.js' )
      found = file_exist?( path )
    end
  end
  foundtype = found ? ( is_coffee ? :coffee : ( is_js ? :js : :none ) ) : :none
  path = false if foundtype == :none
  [ foundtype, path ]
end

#idle(msg) ⇒ nil

Extend this method to do any tasks every time the client makes a request.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

Returns:

  • (nil) 


112
113
 
# File 'lib/rsence/plugins/plugin.rb', line 112

def idle( msg )
end

#include_js(msg, dependencies = []) ⇒ nil

Tells the js client framework to load a list of pre-packaged client libraries.

It keeps track of what’s loaded, so nothing library loaded twice.

Examples:

include_js( msg, [ 'default_theme', 'controls' ] )

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • dependencies (Array) (defaults to: []) —

    A list of package names.

Returns:

  • (nil) 


335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/rsence/plugins/plugin.rb', line 335

def include_js( msg, dependencies=[] )
  ses = msg.session
  # check, if the session has a dependency array
  if not ses.has_key?( :deps )
    # make an array of dependencies for this session, if not already done
    ses[:deps] = []
  end
  dependencies = [dependencies] if dependencies.class == String
  # Check the required dependencies until everything is loaded.
  dependencies.each do |dependency|
    unless ses[:deps].include?( dependency )
      if RSence.config[:client_pkg][:compound_packages].include?( dependency )
        RSence.config[:client_pkg][:compound_packages][dependency].each do |pkg_name|
          ses[:deps].push( pkg_name )
          msg.reply(%{jsLoader.loaded("#{pkg_name}");})
        end
      end
      ses[:deps].push( dependency )
      msg.reply(%{jsLoader.load("#{dependency}");})
    end
  end
end

#init ⇒ nil

Extend this method to do any initial tasks before other methods are called.

By default #init_values is called to load the values.yaml configuration file.

Returns:

  • (nil)

See Also:



103
104
105
 
# File 'lib/rsence/plugins/plugin.rb', line 103

def init
  @values = init_values
end

#init_ses(msg) ⇒ nil

Extend this method to invoke actions, when a new session is created.

By default #init_ses_values is called to initialize values defined in the values.yaml configuration file.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

Returns:

  • (nil) 


122
123
124
 
# File 'lib/rsence/plugins/plugin.rb', line 122

def init_ses( msg )
  init_ses_values( msg )
end

#name_with_manager_s ⇒ Object 



174
175
176
177
178
179
180
 
# File 'lib/rsence/plugins/plugin.rb', line 174

def name_with_manager_s
  if @info[:manager]
    return "#{@info[:manager].to_s}:#{@name.to_s}"
  else
    return @name.to_s
  end
end

#read_js(js_name) ⇒ String, false

Returns the source code of the javascript file js_name in the ‘js’ subdirectory of the plugin bundle. Use it to send raw javascript command code to the client. Use #read_js_once for libraries.

Parameters:

  • js_name (String) —

    Javascript source file name without the ‘.js’ suffix.

Returns:

  • (String) —

    The source of the file.

  • (false) —

    Returns false, when file was not found.



265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/rsence/plugins/plugin.rb', line 265

def read_js( js_name )
  ( type, path ) = guess_js_path( js_name )
  if type == :none
    warn "File not found: #{js_name}"
    return ''
  end
  return brew_coffee( path ) if type == :coffee
  # return squeezed_js( path ) if type == :js
  return file_read( path ) if type == :js
  warn "read_js: unknown type #{type.inspect}"
end

#read_js_once(msg, js_name) ⇒ String, false

Like #read_js, but reads the file only once per session. Use for inclusion of custom library code.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • js_name (String) —

    Javascript source file name without the ‘.js’ suffix.

Returns:

  • (String) —

    The source of the file on the first call in a session, or an empty string on the subsequent calls.

  • (false) —

    Returns false, when file was not found.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/rsence/plugins/plugin.rb', line 284

def read_js_once( msg, js_name )
  ses = msg.session
  if not ses.has_key?(:deps)
    ses[:deps] = []
  end
  ( found, path ) = guess_js_path( js_name )
  return false if found == :none
  unless ses[:deps].include?( path )
    ses[:deps].push( path )
    return read_js( path )
  else
    return ''
  end
end

#restore_ses(msg) ⇒ nil

Extend this method to invoke actions, when a previous session is restored.

By default #restore_ses_values is called to perform actions on values as defined in the values.yaml configuration file.

Parameters:

  • msg (Message) —

    The message is supplied by the system.

Returns:

  • (nil) 


133
134
135
 
# File 'lib/rsence/plugins/plugin.rb', line 133

def restore_ses( msg )
  restore_ses_values( msg )
end

#restore_ses_value(msg, value_name, value_properties) ⇒ Object 



713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
 
# File 'lib/rsence/plugins/plugin.rb', line 713

def restore_ses_value( msg, value_name, value_properties )
  ses = get_ses( msg )
  if ses.has_key?( value_name ) and ses[ value_name ].class == HValue
    if value_properties.has_key?(:responders)
      init_responders( msg, ses[value_name], value_properties[:responders] )
    else
      release_responders( msg, ses[value_name] )
    end
    unless value_properties[:restore_default] == false
      if value_properties.has_key?(:value_call)
        default_value = init_value_call( msg, value_properties[:value_call] )
      elsif value_properties.has_key?(:value)
        default_value = value_properties[:value]
      else
        default_value = 0
      end
      ses[value_name].set( msg, default_value )
    end
  else
    init_ses_value( msg, value_name, value_properties )
  end
end

#squeezed_js(path) ⇒ Object 



255
256
257
 
# File 'lib/rsence/plugins/plugin.rb', line 255

def squeezed_js( path )
  client_pkg.squeeze( file_read( path ) )
end

#values_js(msg, ses = false) ⇒ String

Extracts HValue references as javascript from the session Hash.

Examples:

values_js( msg, get_ses(msg) )

Parameters:

  • msg (Message) —

    The message is supplied by the system.

  • ses (Hash) (defaults to: false) —

    Used for supplying a Hash with the HValue instances. It’s optional and defaults to the current plugin node in the active session.

Returns:

  • (String) —

    A string representing a javascript object similar to the ruby Hash ses.



308
309
310
311
312
313
314
315
316
317
318
319
320
 
# File 'lib/rsence/plugins/plugin.rb', line 308

def values_js( msg, ses=false )
  # backwards-compatible with pre-1.3 behavior
  ses = msg if msg.class == Hash
  # gets the session automatically, if false
  ses = get_ses( msg ) unless ses
  js_references = []
  ses.each_key do |key_name|
    if ses[key_name].class == HValue
      js_references.push( "#{key_name.to_s}:HVM.values['#{ses[key_name].val_id}']" )
    end
  end
  return "{#{js_references.join(',')}}"
end