mindmap 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d48f12770e8cd94db047051cd34ef88e0f8034566cb6807baefd3e482992df4d
+  data.tar.gz: 7db3a47094521a723d4fb86626800b041160a4a1f662646354bfe12da1aac64b
+SHA512:
+  metadata.gz: 6ca4ae555fad394b6450ff6e8cbc20902dda34e500d768388aff67cb38ada04695aebd8351a18ec304bc125ae2fce07678b1afde9a2764f8b655c641f2697667
+  data.tar.gz: dab7e80341f957a989d3e64dae687db8677164bb1767cc8e141deddc002cf810f6f4f32f2031aa6a9c8763d6b8d9b7de1858166bbbc05cc0681b64f9ccce2552

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Emad Elsaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,207 @@
+# Mindmap
+
+Mindmap is a tiny framework to render and browser a graph like structure,
+assuming you have set of simple classes that are related to each other.
+
+# Rational
+
+It started with another project I'm working on called
+[rubrowser](https://github.com/emad-elsaid/rubrowser) it statically analyse your
+ruby code and visualize it in a graph, I thought that this kind of data
+(tree/graph like) is everywhere, like my servers, that I can see files,
+processes and other open sockets on it, through it I can open another server in
+my network, browse through it, open a process there...and so on.
+
+Or Imagine how many times you went to wikipedia and you found yourself on a page
+and you can't remember what makes you land here after couple hours of reading.
+
+so I wanted a setup that does the following:
+
+* A shared library that visualize a data structure of nodes linked to each other
+* every node could be rendered in any form
+* I need to see where I was and the trail that led me to that point and I can
+  get back and take another path
+* it should be as simple as possible to generate new graph project and put my
+  files in it.
+* I wanted to have ready made views, and the ability to override them and define
+  my own views.
+
+At first I thought of D3 and visualizing these nodes and make it interactive,
+but I had to discard this idea as visualizing nodes in different forms will be
+extermily hard for users, not to mention the graph will be very crowded.
+
+So I settled on a page that renders the root node children first, then when you
+try to open a node, I append children to the page and the path goes on
+endlessly, you can scroll back at any time and open another node it'll clear
+every thing under it's level then showing you the node children...and so on.
+
+## Installation
+
+Install it with
+
+    $ gem install mindmap
+
+## Usage
+
+First create a new project, like you do with rails
+
+    $ mindmap new hello
+
+That will create a new directory `hello` with some skeleton in it.
+
+```
+example/
+├── config.ru
+├── Gemfile
+├── nodes
+│   ├── directory_node.rb
+│   ├── file_node.rb
+│   └── root_node.rb
+├── public
+└── views
+
+3 directories, 5 files
+```
+
+it's a rack application you can start it by `rackup` or
+
+    $ mindmap server
+
+the project contains an example nodes to browse the file system content, you can
+start the server and open `http://localhost:9292` in your browser to see it in
+action.
+
+## Project structure
+
+* config.ru : a rack config file that starts mindmap application and serves
+  files from the public directory in both the gem and your project, with your
+  project public directory having precedence, so any file you put there will
+  override the library file.
+* Gemfile : the project has only one direct depedency `mindmap`
+* nodes : a directory that has your classes that needs to be visualized, by
+  default it contains classes that visualize the file system.
+* public : the public directory, you can serve any files from there
+* views : that directory will hold your custom node views, if you'll use the
+  library views then you don't need that directory
+
+## How to write your Nodes
+
+the `ndoes` directory holds your nodes, they're all loaded by default when
+starting the mindmap server, the following is a commented example for a node class
+
+```ruby
+# a node class name MUST end with "Node"
+class DirectoryNode
+  # node class MUST include the Node module
+  # it include methods to render the node and
+  # an initializer for the class
+  include Mindmap::Node
+
+  # you can define attributes/member variables as you wish
+  # if you're using one of the library views you'll need to defind
+  # a specific methods to make it works
+  attr_accessor :path
+
+  def name
+    File.basename(path)
+  end
+
+  # children_title is the title that will be displayed on this
+  # node children container when opened
+  def children_title
+    path
+  end
+
+  # it must return an array of other nodes that this node is related to
+  def children
+    Dir
+      .entries(path)
+      .sort
+      .reject! { |file| ['.', '..'].include?(file) }
+      .map { |file| child(File.expand_path(file, path)) }
+  end
+
+  # returns the view ERB file name to render this node
+  # if you didn't define this method the default value will be
+  # the class name underscored, so a DirectoryNode class
+  # will be rendered using `directory_node.html.erb` template
+  # here we use a library view called tag
+  def view
+    :tag
+  end
+
+  private
+
+  def child(file_path)
+    return DirectoryNode.new(path: file_path) if File.directory?(file_path)
+
+    FileNode.new(path: file_path)
+  end
+end
+```
+
+# How it works?
+
+when you start the mindmap server, it loads all library code then loads the
+project nodes, it serves files from library public and project public
+directories.
+
+when browsing to `localhost:9292` it'll serve the `public/index.html` which is
+an empty page that load jquery and bulma css framework and
+`public/assets/index.js`
+
+`index.js` is what does the interaction part of the page, it request the `root`
+node, so your `nodes` directory must contain that class, mindmap will handle the
+request, creating `RootNode` object givving it all `parameters` sent with the
+request as a hash, `Mindmap::Node#initializer` will assign any key value to the
+object if the `key=` method is public, then mindmap will call the node children.
+
+for every child we'll render it and return the result to the page, the page will
+append the response, then wait until you click on any link that refer to a local
+page, whe you do it'll handle the request, will request the link content with
+ajax sending the `data-params` of the link as parameters to the ajax POST
+request.
+
+mindmap will know the node from the page, for example requesting `/file` will
+signal mindmap to create a `FileNode` object with the passed arguments,
+`/directory/specific_dir` will create a `Directory::SpecificDir` object...etc
+
+
+# How rendering nodes works
+
+the renderer will get the view name by calling `view` method, then search for a
+file first in the project views directory then in the library directory, when
+found it'll be rendered as an ERB template with the node as a bounding context,
+so any method called in the view will be executed from the node.
+
+# How to form links in your views
+
+any link that points to a URL that starts with '/' is concidered an AJAX link
+and mindmap javascript will call the URL with a post request passing the
+`data-params` attribute as parameters in the request, so it's a good idea that
+you set some hash there that when gets assigned to the object it'll tell him
+what to do, an ID in most cases, or for our example nodes the file path, for
+others maybe UUID, by default the views will serialize the object as JSON and
+put it in the attribute, you can be selective with your views implementation if
+you wish, also `data-children-title` attribute is used by the mindmap javascript
+to use it as a title for the response when appended to the page, it's a good
+idea to print the node `children_title` in it.
+
+The example nodes are really simple and can give you some help in understanding
+how it works.
+
+# Root Node
+
+every graph must have an entry point, `RootNode` is our entry point, this nodes
+doesn't have to have any views, an object is created from that class when the
+page loads, and the children will be called an rendered, so the node itself
+doesn't have to do anything but implmenting `children` method returning an array
+of nodes to start with.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/emad-elsaid/mindmap.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'mindmap'
+require 'irb'
+
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install

data/example/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'mindmap'

data/example/config.ru

@@ -0,0 +1,3 @@
+require 'mindmap'
+
+run Mindmap.application

data/example/nodes/directory_node.rb

@@ -0,0 +1,33 @@
+class DirectoryNode
+  include Mindmap::Node
+
+  attr_accessor :path
+
+  def name
+    File.basename(path)
+  end
+
+  def children_title
+    path
+  end
+
+  def children
+    Dir
+      .entries(path)
+      .sort
+      .reject! { |file| ['.', '..'].include?(file) }
+      .map { |file| child(File.expand_path(file, path)) }
+  end
+
+  def view
+    :tag
+  end
+
+  private
+
+  def child(file_path)
+    return DirectoryNode.new(path: file_path) if File.directory?(file_path)
+
+    FileNode.new(path: file_path)
+  end
+end

data/example/nodes/file_node.rb

@@ -0,0 +1,13 @@
+class FileNode
+  include Mindmap::Node
+
+  attr_accessor :path
+
+  def name
+    File.basename(path)
+  end
+
+  def view
+    :tag
+  end
+end

data/example/nodes/root_node.rb

@@ -0,0 +1,5 @@
+class RootNode < DirectoryNode
+  def initialize(*)
+    super(path: '/')
+  end
+end

data/exe/mindmap

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.push File.expand_path('../lib', __dir__)
+
+require 'mindmap'
+
+Mindmap::CLI.source_root(File.expand_path('../', __dir__))
+Mindmap::CLI.start(ARGV)

data/lib/mindmap.rb

@@ -0,0 +1,22 @@
+require 'active_support/all'
+
+Dir[File.expand_path('./mindmap/**/*.rb', __dir__)].each { |fl| require fl }
+Dir[File.expand_path('./nodes/**/*.rb', Dir.pwd)].each { |fl| require fl }
+
+module Mindmap
+  def self.application
+    apps = []
+
+    apps.unshift Application.new
+    apps.unshift Rack::Static.new(apps.first, urls: [''], root: File.expand_path('../public', __dir__), index: 'index.html')
+
+
+    project_public = File.expand_path('./public', Dir.pwd)
+
+    if File.exist?(project_public)
+      apps.unshift Rack::Static.new(apps.first, urls: [''], root: project_public, index: 'index.html')
+    end
+
+    Rack::Cascade.new(apps)
+  end
+end

data/lib/mindmap/application.rb

@@ -0,0 +1,28 @@
+require 'json'
+
+module Mindmap
+  class Application
+    def call(env)
+      request = Rack::Request.new(env)
+
+      [200, headers, [render_page(request)]]
+    end
+
+    private
+
+    def render_page(request)
+      node_name = request.path.camelize + 'Node'
+      node_klass = node_name.constantize
+
+      params = request.params.with_indifferent_access
+      node = node_klass.new(params)
+      node.children.map(&:render).join
+    end
+
+    def headers
+      {
+        'Content-Type' => 'text/html;charset=utf-8'
+      }
+    end
+  end
+end

data/lib/mindmap/cli.rb

@@ -0,0 +1,23 @@
+require 'thor'
+require 'fileutils'
+
+module Mindmap
+  class CLI < Thor
+    include Thor::Actions
+
+    desc 'new PROJECT_NAME', 'Create a new mindmap project'
+    def new(name)
+      directory('example', name)
+
+      inside(name) do
+        run('bundle install')
+      end
+    end
+
+    desc 'server', 'Start a web server'
+    def server
+      trap(:INT) { exit }
+      run('rackup', verbose: false)
+    end
+  end
+end

data/lib/mindmap/node.rb

@@ -0,0 +1,36 @@
+require 'erb'
+
+module Mindmap
+  # a module that must be encluded to any graph node
+  # it has methods needed by the framework to render the node
+  module Node
+    include ERB::Util
+
+    def initialize(params = {})
+      assign_params(params)
+    end
+
+    # assign a hash values to params with the same name
+    def assign_params(params)
+      params.each do |key, value|
+        public_send("#{key}=", value) if self.class.public_method_defined?("#{key}=")
+      end
+    end
+
+    # renders the node ERB view file and returns the result
+    def render
+      Renderer.render(view, binding)
+    end
+
+    # The path to the view file relative to the "views" directory
+    # by default the file is the class name underscored e.g
+    # if node class is `Graph::NodeName` it returns `graph/node_name`
+    def view
+      self.class.name.underscore
+    end
+
+    def url
+      '/' + self.class.name.underscore.gsub('_node', '')
+    end
+  end
+end

data/lib/mindmap/renderer.rb

@@ -0,0 +1,33 @@
+require 'erb'
+
+module Mindmap
+  # Renders a view file from either the library views
+  # or the project views with a binding
+  class Renderer
+    class << self
+      def render(view, binding)
+        erb(view).result(binding)
+      end
+
+      private
+
+      def erb(view)
+        @erb ||= {}
+        @erb[view] ||= ERB.new(view_content(view))
+      end
+
+      def view_content(view)
+        view_path = view_paths(view).find { |file| File.exist?(file) }
+        raise(StandardError, "#{view} view file not found") unless view_path
+        File.read(view_path)
+      end
+
+      def view_paths(view)
+        [
+          File.expand_path("./views/#{view}.html.erb", Dir.pwd),
+          File.expand_path("../../views/#{view}.html.erb", __dir__)
+        ]
+      end
+    end
+  end
+end

data/lib/mindmap/version.rb

@@ -0,0 +1,3 @@
+module Mindmap
+  VERSION = '0.1.0'
+end

data/mindmap.gemspec

@@ -0,0 +1,28 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mindmap/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'mindmap'
+  spec.version       = Mindmap::VERSION
+  spec.authors       = ['Emad Elsaid']
+  spec.email         = ['emad.elsaid@blacklane.com']
+
+  spec.summary       = 'A very specific and opinionated web framework to traverse a graph data structure'
+  spec.description   = 'A very specific and opinionated web framework to traverse a graph data structure'
+  spec.homepage      = 'https://github.com/emad-elsaid/mindmap'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'rack'
+  spec.add_dependency 'thor'
+  spec.add_development_dependency 'bundler', '~> 1.16'
+  spec.add_development_dependency 'rake', '~> 10.0'
+end

data/public/assets/index.js

@@ -0,0 +1,53 @@
+const childrenContainer = function (title, content){
+  var contents = $('<div class="card">')
+
+  if( title ){
+    contents.append('<div class="card-header"><p class="card-header-title">'+ title +'</p></div>')
+  }
+
+  contents.append('<div class="card-content">' + content + '</div>')
+
+  var children = $("<div>", {class: "children"}).html(contents)
+
+  return children
+}
+
+const insertChildren = function (content, element){
+  var parentContainer = $(element).parents(".children")
+
+  parentContainer
+    .nextAll()
+    .remove()
+
+  var title = $(element).data('children-title'),
+      children = childrenContainer(title, content)
+
+  children.insertAfter(parentContainer)
+
+  $('html, body').animate({
+    scrollTop: children.offset().top
+  }, 500);
+}
+
+$.get("/root", function(response){
+  $('body').html(childrenContainer(null, response));
+})
+
+$(document).on('click', 'a[href^="/"]', function(evt){
+  var element = this,
+      params = $(this).data('params')
+  evt.preventDefault()
+  evt.stopPropagation()
+
+  $.ajax({
+    type: "POST",
+    url: this.href,
+    data: params,
+    success: function (data, text) {
+      insertChildren(data, element)
+    },
+    error: function (request, status, error) {
+      insertChildren(request.responseText, element)
+    }
+  });
+})

data/public/index.html

@@ -0,0 +1,19 @@
+<!DOCTYPE HTML>
+<html>
+
+  <head>
+    <title></title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <script defer src="https://use.fontawesome.com/releases/v5.0.7/js/all.js"></script>
+    <script type="application/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
+    <script type="application/javascript" src="/assets/index.js"></script>
+
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/bulma/0.7.0/css/bulma.css" rel="stylesheet"/>
+  </head>
+
+  <body>
+    <div id="content" class="section"></div>
+  </body>
+
+</html>

data/views/tag.html.erb

@@ -0,0 +1,15 @@
+<div class="content is-inline-block">
+  <div class="tags has-addons">
+
+    <span class="tag is-dark is-medium">
+      <%= name %>
+    </span>
+
+    <% if respond_to?(:children) %>
+      <a href="<%= url %>" class="tag is-link is-medium" data-params="<%= html_escape(to_json) %>" data-children-title="<%= children_title %>">
+        <i class="fas fa-folder"></i>
+      </a>
+    <% end %>
+
+  </div>
+</div>

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: mindmap
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Emad Elsaid
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-04-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: A very specific and opinionated web framework to traverse a graph data
+  structure
+email:
+- emad.elsaid@blacklane.com
+executables:
+- mindmap
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- example/Gemfile
+- example/config.ru
+- example/nodes/directory_node.rb
+- example/nodes/file_node.rb
+- example/nodes/root_node.rb
+- example/public/.gitkeep
+- example/views/.gitkeep
+- exe/mindmap
+- lib/mindmap.rb
+- lib/mindmap/application.rb
+- lib/mindmap/cli.rb
+- lib/mindmap/node.rb
+- lib/mindmap/renderer.rb
+- lib/mindmap/version.rb
+- mindmap.gemspec
+- public/assets/index.js
+- public/favicon.ico
+- public/index.html
+- views/tag.html.erb
+homepage: https://github.com/emad-elsaid/mindmap
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.3
+signing_key: 
+specification_version: 4
+summary: A very specific and opinionated web framework to traverse a graph data structure
+test_files: []