hashtags 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 33fc78eb48ce5269728d1563af3c3b11ee111bef
+  data.tar.gz: 0058045a7c502225c75d5aed8ff55d9a5877f99a
+SHA512:
+  metadata.gz: bcaaf2905df844fd53b1924e48a600e08a3fbcf35d32d961fedcb876fc2c761d86a52db3cf7fd2d07277ab9f029478f3bb358457f046a3ef43bd8eec729e9aab
+  data.tar.gz: cf7962a04cf7bbae1281f4fb8426471d62d85d32d645c120f1fd650472dde90bf606d6e58da938ada8c32b1056cb845dec8330e5a768cf94bb8a40525cc44ffb

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,25 @@
+sudo: false
+language: ruby
+dist: trusty
+services:
+  - mongodb
+before_install:
+  - sudo add-apt-repository --yes ppa:ubuntu-sdk-team/ppa
+  - sudo apt-get update -qq
+  - sudo apt-get install -qq libqt5webkit5-dev qtdeclarative5-dev
+  - export QMAKE=/usr/lib/x86_64-linux-gnu/qt5/bin/qmake
+before_script:
+  - "export DISPLAY=:99.0"
+  - "sh -e /etc/init.d/xvfb start"
+  - sleep 3 # give xvfb some time to start
+script: 'xvfb-run -a bundle exec rake'
+rvm:
+  - 2.2.5
+before_install:
+  - gem install bundler -v 1.12.5
+notifications:
+  email:
+    recipients:
+      - tomas.celizna@gmail.com
+    on_failure: change
+    on_success: never

data/Gemfile

@@ -0,0 +1,33 @@
+source 'https://rubygems.org'
+source 'https://rails-assets.org'
+
+# Specify your gem's dependencies in hashtags.gemspec
+gemspec
+
+group :test do
+  gem 'rails'
+  gem 'sassc'
+  gem 'sassc-rails', '~> 1.3'
+  gem 'uglifier'
+  gem 'coffee-rails'
+  gem 'jquery-rails'
+  gem 'jbuilder', '~> 2.0'
+
+  source 'https://rails-assets.org' do
+    gem 'rails-assets-jquery-textcomplete'
+    gem 'rails-assets-handlebars'
+  end
+
+  gem 'capybara-screenshot'
+  gem 'capybara-webkit'
+  gem 'database_cleaner'
+  gem 'launchy'
+  gem 'mongoid'
+  gem 'mongoid-minitest'
+  gem 'minitest-around'
+  gem 'minitest-fail-fast'
+  gem 'minitest-matchers_vaccine'
+  gem 'minitest-rails'
+  gem 'minitest-rails-capybara'
+  gem 'minitest-reporters'
+end

data/Guardfile

@@ -0,0 +1,5 @@
+guard :minitest do
+  watch(%r{^lib/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
+  watch(%r{^test/.+_test\.rb$})
+  watch(%r{^test/test_helper\.rb$})                       { 'test' }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Tomas Celizna
+
+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,253 @@
+# Hashtags
+
+[![Build Status](https://travis-ci.org/tomasc/hashtags.svg)](https://travis-ci.org/tomasc/hashtags) [![Gem Version](https://badge.fury.io/rb/hashtags.svg)](http://badge.fury.io/rb/hashtags) [![Coverage Status](https://img.shields.io/coveralls/tomasc/hashtags.svg)](https://coveralls.io/r/tomasc/hashtags)
+
+Rails engine to facilitate inline text hashtags.
+
+- hashtags are entered inline in text, for example as `@tomasc`, `#location:Home(12345)` or `$my_variable`
+- when rendered, they are replaced by actual values, for example HTML tags, images, links etc.
+
+Additionally:
+
+- the user can be assisted with a dropdown triggered by a special character (`#`, `@`, `$`, ...)
+- a Mongoid field option add support for `.to_markup` and `.to_hashtag` methods and more
+- hashtags typically have `cache_key` defined on class so corresponding fragment cache can be easily expired
+
+TODOs:
+
+- There's an implicit support for Mongoid, but it should be very easy to make that conditional ev. add support for other ORMs or libs such as Virtus etc.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hashtags'
+```
+
+And then execute:
+
+```
+$ bundle
+```
+
+Or install it yourself as:
+
+```
+$ gem install hashtags
+```
+
+## Usage
+
+The three following types are included in this gem, however the gem's design allows for definition of new types and their subclassing.
+
+### Hash tag types
+
+#### User hash tag
+
+```
+@tomasc
+```
+
+#### Resource hash tag
+
+These typically include human-readable version of the resource (in the example below it would be `Home`).
+
+```
+#location:Home(12345)
+```
+
+#### Variable hash tag
+
+```
+$number_of_users
+```
+
+### Adding new hash tags in your application
+
+The following are quick examples. It is advised to read the source code of `Hashtags::User`, `Hashtags::Resource` and `Hashtags::Variable` and their superclass `Hashtags::Builder` in order to fully understand the possibilities and flexibility of this gem.
+
+#### User
+
+See `Hashtags::User` and override its methods on your subclass as necessary. Typically it would be at least the following:
+
+```ruby
+class UserTag < Hashtags::User
+  def self.resource_class
+    # User
+  end
+
+  def self.tag_attribute
+    # name of attribute to be used in the tag
+    # @<tag_attribute>
+    # for example :username
+  end
+
+  def self.result_attribute
+    # the tags will be replaced by this attribute
+    # for example :full_name
+  end
+
+  def self.resources_for_query(query)
+    # return resources matching query
+    # this will be called from the controller as user types
+  end
+
+  def resource(tag_attribute_value)
+    # this should find and return resource object
+    # self.class.resource_class.find(value)
+  end
+end
+```
+
+Implement the `values` class method instead of the `resources_for_query` to preload values.
+
+#### Resource
+
+See `Hashtags::Resource` and override its methods on your subclass as necessary. Typically it would be at least the following:
+
+```ruby
+class LocationTag < Hashtags::Resource
+  def self.resource_class
+    # Location
+  end
+
+  def self.tag_attribute
+    # name of attribute to be used in the tag
+    # #<tag_attribute>(id)
+    # for example :to_s
+  end
+
+  def self.result_attribute
+    # the tags will be replaced by this attribute
+    # for example :to_s
+  end
+
+  def self.resources_for_query(query)
+    # return resources matching query
+    # this will be called from the controller as user types
+  end
+
+  def resource(value)
+    # this should find and return resource object
+    # self.class.resource_class.find(value)
+  end
+end
+```
+
+Implement the `values` class method instead of the `resources_for_query` to preload values.
+
+#### Variable
+
+See `Hashtags::Variable` and override its methods on your subclass as necessary. Typically it would be at least the following:
+
+```ruby
+class VariableTag < Hashtags::Resource
+  def self.values(hashtag_classes = Hashtags::Variable.descendants)
+    # %w(
+    #   variable_1
+    #   variable_2
+    # )
+  end
+
+  def markup(match)
+    # case name(match)
+    # when 'variable_1' then 'foo'
+    # when 'variable_2' then 'bar'
+    # end
+  end
+end
+```
+
+### Usage in an app
+
+#### Core
+
+```ruby
+str = 'Current document: #doc:Foo(123).'
+Hashtags::Builder.to_markup(str) # => 'Current document: Foo.'
+```
+
+Since the hashtags might contain human-readable values (as in the `Resource` tags), it is often helpful to update them:
+
+```ruby
+doc.title = 'Bar'
+Hashtags::Builder.to_hashtag(str) # => 'Current document: #doc:Bar(123).'
+```
+
+Optionally, a list of only/except classes can be specified, useful for example for limiting available hashtags in certain situations.
+
+```ruby
+Hashtags::Builder.to_markup(str, only: [LocationTag])
+Hashtags::Builder.to_hashtag(str, except: [UserTag])
+```
+
+#### With Mongoid Extension
+
+In case you are using Mongoid, you can use the `hashtags` options to enable hashtags processing and additional helpers. The hashtags will be also automatically processed whenever you save your data to the database (using the above-mentioned `to_hashtag` method).
+
+```ruby
+class MyDoc
+  include Mongoid::Document
+  field :text, type: String, hashtags: true # or { only: … } or # { except: … }
+end
+
+my_doc.text.to_markup # => field value with hashtags converted to markup
+my_doc.text.to_hashtag # => field value with hashtags updated
+```
+
+Next to that the following helper class methods will be defined:
+
+```ruby
+MyDoc.hashtags['text'].dom_data # => outcome of builder's dom_data method
+MyDoc.hashtags['text'].help # => outcome of builder's help method
+MyDoc.hashtags['text'].options # => hashtags builder options { only: … } or { except: … }
+```
+
+#### With JS textcomplete plugin
+
+Finally, it is fairly straightforward to add support for JS textcomplete that assists the user when inserting tags.
+
+Require the `hashtags` javascript.
+
+```javascript
+// application.js
+//= require hashtags
+```
+
+In routes:
+
+```ruby
+mount Hashtags::Engine => '/'
+```
+
+Optionally add default CSS.
+
+```css
+/* application.css */
+/*
+ *= require hashtags
+*/
+```
+
+In a form:
+
+```slim
+fieldset
+  = form.text_area :text, data: form.object.class.hashtags['text'].dom_data
+  = render_help_for(form.object.class, :text)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/tomasc/hashtags>.
+
+## 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,19 @@
+# begin
+#   require 'bundler/setup'
+# rescue LoadError
+#   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+# end
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+# APP_RAKEFILE = File.expand_path('../test/dummy/Rakefile', __FILE__)
+# load 'rails/tasks/engine.rake'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/app/controllers/hashtags/resources_controller.rb

@@ -0,0 +1,28 @@
+module Hashtags
+  class ResourcesController < ApplicationController
+    def index
+      respond_to do |format|
+        format.json { render json: resources_as_json, root: false }
+      end
+    end
+
+    private
+
+    def resources_as_json
+      return unless hashtag_class.present?
+      @resources_as_json ||= hashtag_class.resources_for_query(query)
+    end
+
+    def query
+      URI.decode(params.fetch(:q, nil).to_s)
+    end
+
+    def hashtag_class
+      class_name.safe_constantize
+    end
+
+    def class_name
+      params[:class_name]
+    end
+  end
+end

data/app/helpers/hashtags/view_helper.rb

@@ -0,0 +1,8 @@
+module Hashtags
+  module ViewHelper
+    def render_help_for(cls, field_name)
+      return unless help = cls.hashtags[field_name.to_s].help
+      render 'hashtags/help', help: help
+    end
+  end
+end

data/app/views/hashtags/_help.slim

@@ -0,0 +1,8 @@
+div.hashtags.help
+  - help.each do |item|
+    span.trigger_group
+      => I18n.t(:type, scope: %i(hashtags/builders help))
+      span.trigger => item.trigger
+      => I18n.t(:for, scope: %i(hashtags/builders help))
+      - item.help_values.each_with_index do |value, index|
+        span.item = value

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hashtags"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start