module Flammarion::Writeable
Attributes
@api private
Public Instance Methods
Adds a horizontal rule
# File lib/flammarion/writeable.rb, line 290 def break(options = {}) send_json({action:'break'}.merge(options)) end
Creates a string representing a hyperlink that when clicked will call the given block. @macro string_representation @param label [String] The text to become the link @return a string representing the html for the link.
# File lib/flammarion/writeable.rb, line 173 def callback_link(label, options = {}, &block) id = @engraving.make_id @engraving.callbacks[id] = block %|<a href="#" onClick="$ws.send({id:'#{id}', action:'callback', source:'link'})">#{label}</a>| end
Creates a new checkbox which the user can click. @param label [String] The placeholder text for the input @macro escape_options @overload checkbox(label, options = {})
@return [DeferredValue] An object representing the current value of the checkbox. Use +#checked?+ to get the state of the checkbox.
@overload checkbox(label, options = {})
@yield [message_hash] Invokes the block every time the checkbox is toggled. Use the "checked" field of +message_hash+ to get the new state of the checkbox.
# File lib/flammarion/writeable.rb, line 276 def checkbox(label, options = {}, &block) id = @engraving.make_id send_json({action:'checkbox', label:label, id:id}.merge(options)) if block_given? @engraving.callbacks[id] = block else d = DeferredValue.new d.__setobj__(options[:value] || options['value']) @engraving.callbacks[id] = Proc.new {|v| d.__setobj__(v["checked"])} return d end end
Clears the contents of the writeable area
# File lib/flammarion/writeable.rb, line 105 def clear send_json({action:'clear'}) return nil end
Closes the pane or window
# File lib/flammarion/writeable.rb, line 111 def close send_json({action:'closepane'}) return nil end
Creates a dropdown menu for a user to choose a list of options @param items [Array<#to_s>] The possible choices @overload dropdown(items, options = {})
@return [DeferredValue] An object representing the currently selected item, which can be retrieved using {DeferredValue#value}
@overload dropdown(item, options = {})
@yield [message_hash] Invokes the block every time the user selects a different option. Current item text can be obtained from the +"text"+ key of the +message_hash+
# File lib/flammarion/writeable.rb, line 252 def dropdown(items, options = {}, &block) id = @engraving.make_id send_json({action:'dropdown', id:id, options:items}.merge(options)) if block_given? @engraving.callbacks[id] = block else d = DeferredValue.new d.__setobj__(items[0]) if items.is_a? Array d.__setobj__(items[items.keys.first]) if items.is_a? Hash @engraving.callbacks[id] = Proc.new {|v| d.__setobj__ v["value"]} return d end end
Returns the list of currently installed emoji from Emojione
# File lib/flammarion/writeable.rb, line 535 def emoji @@emoji ||= JSON.parse(File.read(File.join(File.dirname(__FILE__), "../html/source/javascripts/vendor/emojione.js")).each_line.find{|l| l.start_with?(" ns.emojioneList")}.scan(/= (\{[^;]+);/).flatten.first) return @@emoji end
Prompts the user for a sting. Blocks until a string has been entered. @param prompt [String] A prompt to tell the user what to input. @param options Same as {#input} @return [String] The text that the user has entered. @see input
# File lib/flammarion/writeable.rb, line 488 def gets(prompt = "", options = {}) str = nil input(prompt, {once:true, focus:true}.merge(options)) {|msg| str = msg["text"]} sleep 0.1 while str.nil? return str end
Hides (but doesn’t close) the pane. This allows the pane to be written to without it opening up again. @see show
# File lib/flammarion/writeable.rb, line 386 def hide send_json({action:'hidepane'}) end
Adds a pretty-printed, colorful display of data or code @overload highlight(data, options)
Adds a pretty-printed, highlighted display of data @param text [Hash, Array] A dataset to be displayed @macro escape_options
@overload highlight(text, options)
Adds syntax-highlighted code to the writeable area @param text [String] Code to be highlighed @macro escape_options
# File lib/flammarion/writeable.rb, line 137 def highlight(text, options = {}) output = text output = JSON.pretty_generate(text) if text.is_a? Hash or text.is_a? Array send_json({action:'highlight', text:output}.merge(options)) nil end
Renders raw html into the writeable area by replacing the previous content
# File lib/flammarion/writeable.rb, line 295 def html(data) send_json({action:'replace', text:data, raw:true}) end
Creates a string representing a emoji or Font Awesome icon. @macro string_representation @param name [String] The name of a Font Awesome icon class. See @see fortawesome.github.io/Font-Awesome/icons/ @see github.com/twitter/twemoji
# File lib/flammarion/writeable.rb, line 184 def icon(name, additional_classes = []) e = emoji[":#{name}:"] if e.nil? then return %|<i class="fa fa-#{name} #{additional_classes.collect{|c| "fa-#{c}"}.join(" ")}"></i>| else return %|<img class="emoji" alt="#{name}" src="images/emoji/#{e['unicode'].last.downcase}.png">| end end
# File lib/flammarion/writeable.rb, line 193 def image(url, options = {}) puts(%|<img src="#{url}">|, {escape_html: false}.merge(options)) end
Creates a new text-input field into which the user can enter text. If a block is given, the block will be called when ever the text is changed. If a block is not given, it will return a DeferredValue
object which can be used to get the value at any time. @param label [String] The displayed placeholder text for the input. This
does not set the actual value of the input field or the returned {DeferredValue}. Use the +:value+ option for that.
@option options [Boolean] :multiline (false) Creates a large text box if
true; otherwise creates a single line input box.
@option options [Boolean] :password (false) Creates a password input text box if
true; otherwise creates a normal single line input box.
@option options [Boolean] :autoclear (false) Automatically clears the
input field every time the user changes the value. The callback will only be called for user initiated changes, not for auto-clear changes.
@option options [Boolean] :history (false) Keeps track of entered values,
letting the user choose betwen them with the up and down keys.
@option options [String] :value Sets the starting value of the field and
the returned {DeferredValue}.
@option options [Boolean] :once (false) If true, then the input box will
be converted into a normal line of text once the user has changed it. The callback will still be called, but the user will no longer be able to change the text.
@option options [Boolean] :keep_label (false) If :once
is also set, this
will prepend +label+ when converting the input to plain text.
@option options [Boolean] :enter_only (false) Only accept the users input
when the enter key is pressed, not merely when it changes.
@overload input(label, options = {})
@return [DeferredValue] An object representing the current value of the input, which can be converted to text using +#to_s+.
@overload input(label, options = {})
@yield [message_hash] Invokes the block every time the text changes. The new text of the input can be obtained from the +"text"+ key of the +message_hash+.
# File lib/flammarion/writeable.rb, line 230 def input(label, options = {}, &block) id = @engraving.make_id send_json({action:'input', label:label, id:id}.merge(options)) if block_given? @engraving.callbacks[id] = block else d = DeferredValue.new d.__setobj__(options[:value] || options['value']) @engraving.callbacks[id] = Proc.new {|v| d.__setobj__ v["text"] } return d end end
# File lib/flammarion/writeable.rb, line 319 def js(text, options = {}, &block) script(text, options.merge(coffee:false), &block) end
Adds an interactive street map of a specified location. @option options [Integer] :zoom (13) The initial zoom level @option options [Boolean] :marker (true) Display a marker on the
identified address or coordinates
@macro add_options @overload map(options) @overload map(address, options = {})
@param address [String] The address or landmark to look up and display.
@overload map(latitude, longitude, options = {})
@param latitude [Float] The latitude to display @param longitude [Float] The longitude to display
@note Street map provided by openstreetmap.org
# File lib/flammarion/writeable.rb, line 507 def map(*args) case (args.size) when 1 if args[0].respond_to? :keys then options = args[0] else options = {address:args[0].to_s} end when 2 if args[1].respond_to? :keys then options = {address:args[0]}.merge(args[1]) else options = {latitude:args[0], longitude:args[1]} end when 3 options = {latitude:args[0], longitude:args[1]}.merge(args[2]) else raise ArgumentError.new("Expected 1..3 arguments") end send_json({action:'map'}.merge(options)) end
Renders the given markdown text into the pane. @param text [String] The markdown text to render. @option options [Hash] :markdown_extensions Additional Redcarpet
extensions to enable.
@macro add_options
# File lib/flammarion/writeable.rb, line 368 def markdown(text, options = {}) # if defined?(Redcarpet::Markdown) then # markdown_html = Redcarpet::Markdown.new(Redcarpet::Render::HTML, { # tables: true, # fenced_code_blocks: true, # autolink: true, # strikethrough: true, # superscript: true, # }.merge(options[:markdown_extensions] || {})).render(text) # else # markdown_html = Kramdown::Document.new(text, {input: 'GFM', hard_wrap: false, syntax_highlighter: nil}.merge(options)).to_html # end send_json({action:'markdown', text: text, hard_wrap:false}.merge(options)) end
Changes the orientation of the panes within this Writeable
area. If orientation
is :vertical
(the default), the panes will be stacked on top of each other, each occupying 1/nth of the height (where n is the number of panes) and 100% of the width. If orientation
is :horizontal
, the panes will be placed next to each other, with each pane occupying 1/n of the width (where n is the number of panes) and 100% of the heigh. @note This applies only to panes, not to subpanes. @see pane
@param orientation [Symbol] can be :horizontal
or :vertical
@raise ArgumentError if the orientation is not one of the allowed values
# File lib/flammarion/writeable.rb, line 442 def orientation=(orientation) raise ArgumentError.new("Orientation must be :horizontal or :vertical") unless [:horizontal, :vertical].include?(orientation) send_json({action:'reorient', orientation:orientation}) end
Creates a scaled pane within the current writeable area. Where it goes depends on the orientation. @param name [String] an identifier for the subpane. All panes and subpanes
share the same scope, so you want to be careful with your naming.
@return [Pane] The newly created or already existing pane. @macro pane_difference @see pane
@see orientation=
# File lib/flammarion/writeable.rb, line 427 def pane(name, options = {}) send_json({action:'addpane', name:name}.merge(options)) return Pane.new(@engraving, name) end
Creates a new plot to display data. Uses Plotly javascript library for plotting, options are passed directly to Plotly, so all types of plots and options are supported. @macro add_options @see Flammarion::Plot.plot
# File lib/flammarion/writeable.rb, line 121 def plot(data, options = {}) id = @engraving.make_id p = Plot.new(id, @pane_name, @engraving) p.plot(data, options) return p end
Adds text to the writeable area and appends a newline. @param str [String] The text to append @macro escape_options
# File lib/flammarion/writeable.rb, line 83 def puts(str = "", options = {}) send str, options send "\n" return nil end
Adds raw html to the writeable area without appending a newline. @param data [String] The raw html to append @see html
in case you want to replace rather than append html
# File lib/flammarion/writeable.rb, line 92 def raw(data) send data, raw: true end
Replaces the contents of the writeable area with text @param str [String] The text to append @macro escape_options
# File lib/flammarion/writeable.rb, line 99 def replace(str, options = {}) send_json({action:'replace', text:str}.merge(options)) return nil end
Runs a script in the engraving window. @param text [String] The script to run. Lanuage of the script depends on
the options given. Defaults to CoffeeScript
@option options [Boolean] :coffee (true) If true, will compile text
from
CoffeeScript to JavaScript. If false, will pass text as plain JavaScript
# File lib/flammarion/writeable.rb, line 304 def script(text, options = {}, &block) return script_src(text) if !options.fetch(:no_file, false) && File.exist?(text) data = options.fetch(:coffee, true) ? CoffeeScript.compile(text) : text id = @engraving.make_id d = nil if block_given? @engraving.callbacks[id] = block else d = DeferredValue.new @engraving.callbacks[id] = Proc.new {|v| d.__setobj__(v["result"])} end send_json({action:'script', data:data, id: id}.merge(options)) return d end
# File lib/flammarion/writeable.rb, line 323 def script_src(src) if File.exist?(src) then html("<script>#{File.read(src)}</script>") else html("<script src='#{src}'></script>") end end
Searches for and highlights the string in the engraving.
# File lib/flammarion/writeable.rb, line 530 def search(string) send_json({action:'search', text: string}) end
Adds text to the writeable area without appending a newline. @param str [String] The text to append @macro escape_options
# File lib/flammarion/writeable.rb, line 75 def send(str, options = {}) @engraving.send_json({action:'append', text:str, target:@pane_name}.merge(options)) end
@api private
# File lib/flammarion/writeable.rb, line 68 def send_json(hash) @engraving.send_json({target: @pane_name}.merge(hash)) end
Shows a hidden pane. @see hide
# File lib/flammarion/writeable.rb, line 392 def show send_json({action:'showpane'}) end
Displays a message to the bottom status bar. @param str [String] The message to display @overload status(str, position)
@param position [Symbol] Where to put it. May be +:left+ or +:right+
@overload status(str, options = {})
@option options [Symbol] :position Where to put it. May be +:left+ or +:right+ @escape_options
# File lib/flammarion/writeable.rb, line 464 def status(str, options = {}) options = {position: options} if options.is_a? Symbol @engraving.send_json({action:'status', text: str}.merge(options)) end
Sets CSS styles attributes on the current pane. @overload style(attribute, value)
@param attribute [String] The css attribute to set. Currently does not support selectors or anything. @param value [#to_s] The value to set the attribute to. (Don't forget units!)
@overload style(attributes)
@param attributes [Hash] Table of css attribute to value mapping to set.
# File lib/flammarion/writeable.rb, line 339 def style(*args) case args.length when 1 # @todo Pass this as a whole hash, rather than individually. args[0].each{|a,v| send_json({action: 'style', attribute: a, value: v})} when 2 send_json({action: 'style', attribute: args[0], value: args[1]}) else raise ArgumentError.new("Invalid number of arguments (Expected 1 or 2)") end end
Creates a writeable area within the current writeable area. This lets you update the contents of the writeable later, without disturbing the rest of the curent pane. If a pane or subpane with the given name already exists, it will just use that one instead. @param name [String] an identifier for the subpane. All panes and subpanes
share the same scope, so you want to be careful with your naming.
@return [Pane] The newly created or already existing pane. @macro pane_difference @see pane
# File lib/flammarion/writeable.rb, line 414 def subpane(name, options = {}) send_json({action:'subpane', name:name}.merge(options)) return Pane.new(@engraving, name) end
Displays a table of data @param rows [Array<Array<#to_s>>] an array of rows, where each row is an
array of objects which will be converted to a string and diplayed in the table.
@macro escape_options @option options [Array<#to_s>] :headers An array of column headers to put
at the top of the table.
@option options [Boolean] :interactive (true) Allows the user to mouse
over the table and have it styled. Set to false if you experience performance issues with large datasets.
# File lib/flammarion/writeable.rb, line 479 def table(rows, options = {}) send_json({action:'table', rows: rows}.merge(options)) end
Will render the given Slim template into the Writeable
area. This is useful for creating complex or custom application layouts components beyond what’s built into Flammarion
. @note If you just want to include html (or outut from another template
engine, you can just use {#html})
@param file [String] Path to the Slim file to render @see slim-lang.com/
# File lib/flammarion/writeable.rb, line 358 def template(file) data = Slim::Template.new(file).render send_json({action:'replace', text:data, raw:true}) end