radiant-help-extension 1.1.0

data/HELP_developer.rdoc

@@ -0,0 +1,92 @@
+Developing for Help is easy.
+
+If you'd like to include help information for your own extensions you have some options. You may
+
+1. Create plain text help files (formatted in RDoc, Markdown, or Textile syntax)
+2. Inject partials into the Help interface
+
+== Multiple Options
+
+"Why so many ways to provide help? It's overkill."
+
+They each have separate purposes and benefits. First, the purpose of Help is to provide basic information about the functions of Radiant. Second, Help allows developers to provide documentation for features added through extensions.
+
+=== The lowest barrier to entry is plain text files. 
+
+Extension developers may include the appropriate files (explained below) and if users of their extension have Help installed it will appear in the Help interface, if users do not have Help installed there is no worry about dependencies and Radiant will function normally.
+
+=== Make the Help docs your own.
+
+You may inject partials into the interface to include information about features that are tightly coupled with the existing interface and make it appear to the users as though that is what is standard.
+
+For example, suppose a developer created a category for pages such as "hot" or "cold" (perhaps to represent the mood of the author) and she added this selection to the page editing interface with a partial injection. To the average user it would appear that the "hot" or "cold" selection was a part of the CMS, so it would be important to add a reference to the new feature within the documentation for the basic pieces of Radiant.
+
+=== Features
+
+If you are building an extension and are considering using Help, keep these features in mind:
+
+1. Plain Text Files - No Failures if Help is not installed, clean slate of (role-based) information, all information (per role) is provided on one screen
+2. Partial Injection - Will fail if Help is not installed (unless you check for the objects you need properly), integrated with the standard (per role) help information, easy to break up topics in to small parts
+
+== RDoc Help Files
+
+Help looks through all of your installed extensions to find relevant HELP.rdoc files. These files must follow the naming conventions of:
+
+1. HELP.rdoc (this is for general users)
+2. HELP_developer.rdoc (this will only be shown to users with the developer role)
+3. HELP_admin.rdoc (this will only be show to users with the admin role)
+
+These files must be placed in the root of your extension. If you do not wish to provide help for a certain user group, do not create the pertinent RDoc.
+
+== Partial Injection Based Help
+
+You may inject partials into the interface by adding code such this into your extension's activate method:
+
+  admin.help.index.add :main, "client_welcome", :before => "introduction"
+
+* "admin.help.index" refers to the main help page (the help index) and ".add" is called to add information to the section provided in the next argument. 
+* ":main" is the argument that specifies which section will receive your partial. 
+* "client_welcome" is the partial that you want to add and should be located in your extension directory app/views/admin/help/_client_welcome.html.haml
+* :before => "introduction" will place your partial before the introduction region (or you could do :after). This is optional, and if left out, your partial will be appended to the ":main" section.
+
+For a list of all of the regions provided by Help, see help_extension.rb around line 65, and app/views/admin/index.html.haml for details about where they appear.
+
+When adding your partials, you may specify inline decisions about whom should see your documentation with the admin_help and developer_help helper methods. These can be used in your HAML by doing:
+
+  - admin_help do
+    %p Hello Madame Admin!
+  - developer_help do
+    %p You are special, Mr. Developer.
+
+Those helper methods make use of the admin? and developer? helpers provided by Radiant. The blocks of text will only be shown to the user if they are in those roles, but keep in mind that currently developer? returns true if the user is selected only as an admin (meaning developer_help will be seen by developers and admins).
+
+=== Dependency
+
+If you know that you extension will always have Help available, you may use the above approach without worry. If, however, your extension will be used where Help may or may not be installed, you should first check for the existence of the appropriate region into which you plan to inject partials.
+
+Here is an example:
+
+  if admin.respond_to?(:help)
+	if admin.help.index
+	  admin.help.index.add :main, "client_welcome", :before => "introduction"
+	end
+	if admin.help.role
+	  admin.help.role.add :extras, "contact_info"
+	end
+  end
+
+The nested if statements may be overkill but if for some reason Help regions change in the future, your extension will be protected from failing because a certain region does not exist.
+
+=== Expanding Documentation
+
+Each of the Radius tags displayed under the developer documentation also allows you to add more details.
+
+  admin.help.role.add 'archive:children', "all_about_archives"
+
+== Source Code
+
+Help is made freely available at http://github.com/saturnflyer/radiant-help-extension/
+
+Help was built by Saturn Flyer 
+
+http://www.saturnflyer.com

data/README.md

@@ -0,0 +1,35 @@
+# Help
+
+This extension provides documentation for Radiant and any 
+installed extensions.
+
+Installing Help is as easy as any other Radiant extension. 
+Drop it into your vendor/extensions directory.
+
+Once the extension is installed, you must ensure that your 
+application will load the Help extension before loading any 
+extensions that rely on the help regions. To do so, edit 
+your config/environment.rb to load Help first:
+
+    Radiant::Initializer.run do |config|
+      #...
+    	config.extensions = [ :help, :all ] 
+      #...
+    end
+
+Help provides basic information for the average user at 
+admin/help, but also provides documentation for tasks and 
+features available to developers and admins at 
+`admin/help_role/developer` and `admin/help_role/admin`. 
+Additionally, any extensions loaded with HELP files may be 
+found at `/admin/help_extension/:extension_name/:role` but a 
+list of links is automatically generated for your clicking 
+pleasure.
+
+For more information about developing for Help, install it 
+and go to `/admin/help_extension/help/developer` or read the 
+included `HELP_developer.rdoc`
+
+Some content taken from http://radiantcms.org/
+
+[Built by Saturn Flyer](http://www.saturnflyer.com)

data/Rakefile

@@ -0,0 +1,109 @@
+# Determine where the RSpec plugin is by loading the boot
+unless defined? RADIANT_ROOT
+  ENV["RAILS_ENV"] = "test"
+  case
+  when ENV["RADIANT_ENV_FILE"]
+    require File.dirname(ENV["RADIANT_ENV_FILE"]) + "/boot"
+  when File.dirname(__FILE__) =~ %r{vendor/radiant/vendor/extensions}
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../../../")}/config/boot"
+  else
+    require "#{File.expand_path(File.dirname(__FILE__) + "/../../../")}/config/boot"
+  end
+end
+
+require 'rake'
+require 'rdoc/task'
+require 'rake/testtask'
+
+rspec_base = File.expand_path(RADIANT_ROOT + '/vendor/plugins/rspec/lib')
+$LOAD_PATH.unshift(rspec_base) if File.exist?(rspec_base)
+require 'spec/rake/spectask'
+require 'cucumber'
+require 'cucumber/rake/task'
+
+# Cleanup the RADIANT_ROOT constant so specs will load the environment
+Object.send(:remove_const, :RADIANT_ROOT)
+
+extension_root = File.expand_path(File.dirname(__FILE__))
+
+task :default => [:spec, :features]
+task :stats => "spec:statsetup"
+
+desc "Run all specs in spec directory"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+task :features => 'spec:integration'
+
+namespace :spec do
+  desc "Run all specs in spec directory with RCov"
+  Spec::Rake::SpecTask.new(:rcov) do |t|
+    t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec', '--rails']
+  end
+  
+  desc "Print Specdoc for all specs"
+  Spec::Rake::SpecTask.new(:doc) do |t|
+    t.spec_opts = ["--format", "specdoc", "--dry-run"]
+    t.spec_files = FileList['spec/**/*_spec.rb']
+  end
+
+  [:models, :controllers, :views, :helpers].each do |sub|
+    desc "Run the specs under spec/#{sub}"
+    Spec::Rake::SpecTask.new(sub) do |t|
+      t.spec_opts = ['--options', "\"#{extension_root}/spec/spec.opts\""]
+      t.spec_files = FileList["spec/#{sub}/**/*_spec.rb"]
+    end
+  end
+  
+  desc "Run the Cucumber features"
+  Cucumber::Rake::Task.new(:integration) do |t|
+    t.fork = true
+    t.cucumber_opts = ['--format', (ENV['CUCUMBER_FORMAT'] || 'pretty')]
+    # t.feature_pattern = "#{extension_root}/features/**/*.feature"
+    t.profile = "default"
+  end
+
+  # Setup specs for stats
+  task :statsetup do
+    require 'code_statistics'
+    ::STATS_DIRECTORIES << %w(Model\ specs spec/models)
+    ::STATS_DIRECTORIES << %w(View\ specs spec/views)
+    ::STATS_DIRECTORIES << %w(Controller\ specs spec/controllers)
+    ::STATS_DIRECTORIES << %w(Helper\ specs spec/views)
+    ::CodeStatistics::TEST_TYPES << "Model specs"
+    ::CodeStatistics::TEST_TYPES << "View specs"
+    ::CodeStatistics::TEST_TYPES << "Controller specs"
+    ::CodeStatistics::TEST_TYPES << "Helper specs"
+    ::STATS_DIRECTORIES.delete_if {|a| a[0] =~ /test/}
+  end
+
+  namespace :db do
+    namespace :fixtures do
+      desc "Load fixtures (from spec/fixtures) into the current environment's database.  Load specific fixtures using FIXTURES=x,y"
+      task :load => :environment do
+        require 'active_record/fixtures'
+        ActiveRecord::Base.establish_connection(RAILS_ENV.to_sym)
+        (ENV['FIXTURES'] ? ENV['FIXTURES'].split(/,/) : Dir.glob(File.join(RAILS_ROOT, 'spec', 'fixtures', '*.{yml,csv}'))).each do |fixture_file|
+          Fixtures.create_fixtures('spec/fixtures', File.basename(fixture_file, '.*'))
+        end
+      end
+    end
+  end
+end
+
+desc 'Generate documentation for the help extension.'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HelpExtension'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# Load any custom rakefiles for extension
+Dir[File.dirname(__FILE__) + '/tasks/*.rake'].sort.each { |f| require f }

data/TODO

@@ -0,0 +1,6 @@
+1. Add images
+2. Better styling
+3. Javascript to hide/show features
+4. Integrate full tag list search for developer view
+5. Show README and TODO files to admins
+6. Tests for the views!

data/app/controllers/admin/help_controller.rb

@@ -0,0 +1,59 @@
+class Admin::HelpController < ApplicationController
+  include ActiveSupport::CoreExtensions::String::Inflections
+  
+  # only_allow_access_to :index, :show, :new, :create, :edit, :update, :remove, :destroy,
+  #   :when => :admin,
+  #   :denied_url => { :controller => 'help', :action => 'index' },
+  #   :denied_message => 'You must have administrative privileges to perform this action.'
+  
+  def index
+    @role = 'all'
+    @docs = HelpDoc.find_for(:all)
+    @file_not_found_page = Page.find(:first, :conditions => {:class_name => 'FileNotFoundPage'})
+    @layouts = Layout.find(:all)
+    @filters = TextFilter.descendants.uniq
+    @cms_name = Radiant::Config['admin.title']
+  end
+  
+  def role
+    @template_name = 'role'
+    if params[:role].nil?
+      @role = 'all'
+      flash[:error] = "Sorry. I couldn't find any documentation for your request so you've been redirected to this page."
+      redirect_to help_url
+      return
+    else
+      if params[:role] == 'admin' or params[:role] == 'designer'
+        @role = params[:role]
+      else
+        @role = 'other'
+        @custom_role = params[:role]
+      end
+    end
+    if File.exists?("#{RAILS_ROOT}/vendor/extensions/help/app/views/admin/help/_#{@role}_index.html.haml")
+      @docs = HelpDoc.find_for(@role)
+    else
+      flash[:error] = "Information for the '#{@role}' role could not be found."
+      redirect_to help_url
+      return
+    end
+  end
+  
+  def developing
+    
+  end
+  
+  def extension_doc
+    @template_name = 'extension_doc'
+    @role = params[:role].nil? ? 'all' : params[:role]
+    @docs = HelpDoc.find_for(@role)
+    if params[:extension_name] != 'all'
+      @doc_name = params[:extension_name].titleize
+      @doc_path = HelpDoc.find_for(@role,params[:extension_name]).first
+    else
+      @doc_path = @docs.first
+      @doc_name = @doc_path[/[(\w+)]\/(\w+)\/HELP/, 1].titleize
+    end
+    @doc = HelpDoc.formatted_contents_from(@doc_path)
+  end
+end

data/app/helpers/admin/help_helper.rb

@@ -0,0 +1,36 @@
+module Admin::HelpHelper
+  # This code doesn't work...
+  # ready for more roles when they appear in Radiant
+  # %{admin developer}.each do |role|
+  #   define_method("#{role}_help") do |block|
+  #      yield block if "#{role}?"
+  #   end
+  # end
+  
+  def admin_help(&block)
+    yield if admin?
+  end
+  
+  def designer_help(&block)
+    yield if designer?
+  end
+  
+  def doc_extension_dir(doc)
+    doc[/[(\w+)]\/(\w+)\/HELP/, 1]
+  end
+  
+  def all_tags
+    tags = {}
+    page_classes = [Page.descendants, Page].flatten
+    page_classes.each do |page_class| 
+      page_class.tag_descriptions.each do |name, details| 
+        if tags[name]
+          tags[name][:classes] << page_class.to_s
+        else
+          tags[name] = {:description => details, :classes => [page_class.to_s]}
+        end
+      end
+    end
+    tags
+  end
+end

data/app/models/help_doc.rb

@@ -0,0 +1,42 @@
+require 'rdoc'
+
+class HelpDoc
+  
+  def self.find_for(role_type, extension_dir="**")
+    results = [] 
+    doc_name = ''
+    doc_name = "_#{role_type.to_s}" unless role_type.to_s == 'all'
+    Dir["#{RAILS_ROOT}/vendor/extensions/#{extension_dir}/HELP#{doc_name}*"].each do |ext_help|
+      case role_type.to_s
+      when 'all'
+        re_matcher = /HELP(\.[\w]+)?$/
+      else
+        re_matcher = /HELP_[\S]+(\.[\w]+)?$/
+      end
+      results << ext_help if re_matcher.match(ext_help)
+    end
+    results
+  end
+  
+  def self.formatted_contents_from(doc_path)
+    if doc_path.end_with?('markdown') || doc_path.end_with?('md')
+      HelpDoc.parsed_markdown(doc_path)
+    elsif doc_path.end_with?('textile')
+      HelpDoc.parsed_textile(doc_path)
+    else
+      HelpDoc.parsed_rdoc(doc_path)
+    end
+  end
+  
+  def self.parsed_rdoc(doc_path)
+    RDoc::Markup::ToHtml.new.convert(File.read(doc_path))
+  end
+  
+  def self.parsed_markdown(doc_path)
+    MarkdownFilter.filter(File.read(doc_path))
+  end
+  
+  def self.parsed_textile(doc_path)
+    ::RedCloth.new(File.read(doc_path)).to_html
+  end
+end

data/app/views/admin/help/_admin_index.html.haml

@@ -0,0 +1,11 @@
+%p As an admin, you may add and remove users that have access to your website. To view the current users click on the "Users" link in the header.
+%h2 Adding a User
+%p 
+  The 
+  = link_to("new user screen", new_admin_user_path)
+  has some helpful information on it about what must or need not be entered when creating a user. When you have completed the form, click "Create User" or "Save and Continue Editing" to create the user.
+%h2 Disabling a User
+%p 
+  If you'd like to remove a certain user's access from your website, you must delete the user from the system. To do this, go to 
+  = link_to("the list of all users", admin_users_path)
+  , and click "Remove" for the appropriate user.

data/app/views/admin/help/_designer_index.html.haml

@@ -0,0 +1,20 @@
+%h2 Caching
+%p An optimization feature of Radiant is the page cache, which stops it having to rebuild pages from scratch each time they are requested. However, when you edit pages the cache will be cleared and each page will generate its cache file on the next request to the website.
+
+%h2 Radiant Tags
+%p Now the interesting bit – the tags you can use in your layouts, snippets and page bodies to pull all the bits of your site together. This list and the description of the tags is taken from the Radiant source file app/models/page_context.rb if you want to look at the underlying implementation or check for changes if you think the documentation below may be inaccurate.
+%p Tags can only be used in page, layout or snippet content, not in names or page titles.
+%p Where square brackets are used below, they indicate that the thing contained inside is optional. If you decide to include it, don’t include the square brackets – e.g.:
+%pre
+  %code= h('<r:children:each [offset="number"]>')
+%p ...indicates that you could use the following in a real layout, snippet or page:
+%pre
+  %code= h('<r:children:each offset="2">')
+
+%p Tags are created to act as containers, page content, attributes, conditional elements and miscellaneous items.  The tag reference below is also available as a popup on edit screens.
+
+%h2 All Available Tags
+.popup
+  - all_tags.sort.each do |tag_name,details|
+    - desc = RedCloth.new(Radiant::Taggable::Util.strip_leading_whitespace(details[:description])).to_html
+    = render :partial => 'tag_reference', :locals => {:tag_name => tag_name, :description => desc, :classes => details[:classes]} 

data/app/views/admin/help/_docs_introduction.html.haml

@@ -0,0 +1,2 @@
+%p 
+  Documents are available with information provided about the following extensions:

data/app/views/admin/help/_editing.html.haml

@@ -0,0 +1,64 @@
+%h2 Editing Pages
+%h3 Page Details
+- render_region :page_details do |page_details|
+  - page_details.page_details_introduction do
+    %p Each page has information that is used when your pages are generated. When you type your Page Title, the page Slug and Breadcrumb are automatically typed for you (click the 'More' link below the title to see these details). The slug is arguably the most important of these because it determines where your page will be found when visitors browse your website.
+  - page_details.slug do
+    %h4 What is the Slug? 
+    %p It's the smallest part of the page URL.
+    %p If you want your "About Us" page to be found in a location such as yoursite.com/about, then the Slug for your "About Us" page is "about".
+    %p Likewise, if the "About Us" page has any children, such as a "Management Team" page, then the location of that page might be yoursite.com/about/management-team. In this case, the Slug for the "Management Team" page is "management-team".
+    %h4 Why do I need a Slug?
+    %p You may not want to make changes to it, but if you do you may make your "About Us" page available at yoursite.com/about or yoursite.com/about-us or yoursite.com/allaboutus... It's up to you.
+  - page_details.breadcrumb do
+    %h4 Breadcrumb
+    %p Breadcrumbs trace your path from the home page to where your are. If you're on the "Management Team" page, for example, your breadcrumbs might look like this: Home > About Us > Management Team
+    %p The Breadcrumb field allows you to edit the text that will be displayed if and when your website uses breadcrumbs.
+%h3 Filter
+- render_region :filter do |filter|
+  - filter.filter_basics do
+    %p The filter that you select is used to process the text that you enter. That means that you don't need to write HTML for it to show up properly on your website. 
+    %p 
+      The filters provided for you are:
+      = @filters.collect(&:filter_name).to_sentence(:words_connector => ', ', :last_word_connector => ', and ')
+    %p To get more information about these text filters:
+    %ol
+      %li go to a page edit screen and select a filter
+      %li click on the "Filter" link next to the Filter selection
+      %li scroll through the documentation that appears to find out more about using your selected Filter.
+    %p If you ever need help with formatting your text, the information is right where you need it.
+%h3 Available Tags
+- render_region :available_tags do |available_tags|
+  - available_tags.available_tags_basics do
+    %p The typical user won't need to worry much about Tags, but you have the flexibility to display your website content in many ways. These Tags are commonly used by admins and developers. Here's a quick and limited example of what can be done:
+    %pre
+      = h %q{<r:find url="/about"><r:content part="contact" /></r:find>}
+    %p That example finds the page with "about" for the Slug, and outputs the content of the "contact" part.
+    %p Much more can be done, but these Tags should be used with caution if you are unfamiliar with them.
+%h3 Layout
+- render_region :layout do |layout|
+  - layout.layout_basics do
+    %p 
+      Different Layouts may be created for your website. For a small site you may have only one, or for a large site there may be more options. The Layouts created for your site are:
+      = @layouts.collect(&:name).to_sentence(:words_connector => ', ', :last_word_connector => ', and ')
+    %p Layouts determine how your content will be displayed. Typically a Layout is created for the Home page and all of its child pages inherit that layout from it. It's likely that you don't need to make any changes to this setting on the pages that you edit, but talk to the administrator or designer of your site to find out what layout to choose.
+%h3 Page Type
+- render_region :page_type do |page_type|
+  - page_type.page_type_basics do
+    %p 
+      The Page Type determines how the page will behave. This website, for example,
+      - unless @file_not_found_page.nil?
+        = "has the page \"#{@file_not_found_page.title}\"."
+      - else
+        doesn't have a File Not Found Page.
+      = "A #{FileNotFoundPage.display_name} page will be displayed to anyone requesting a page that does not exist. This allows you to customize the message to your website visitors if they try to find a page like yoursite.com/non-existant-page"
+    %h3 Status
+    %p The Status of a page helps to determine how it will be displayed to visitors of your site, but also helps you manage your content internally. Only 'Published' pages are displayed to the public, but if you need to hide a previously published page, you can set the Status to 'Hidden'
+    %p 'Draft' and 'Reviewed' allow you to set a Status that gives you information about the readiness of that page to be displayed to your website visitors.
+    %p One person on your team, for example may write content for one page and then set it to 'Draft'. Another team member can then check the content of the draft and set it to 'Reviewed'. When ready, you can then set the page status to 'Published'. These steps, of course, aren't necessary, but they are available if you need them.
+%h3 Saving your changes
+- render_region :saving do |saving|
+  - saving.saving_basics do
+    %p By selecting "Save Changes", your page content will be saved and you will return to the page index.
+    %p By selecting "Save and Continue Editing", your page content will be saved and you will return to the same page edit screen. This is useful if you would like to make a change to view on your public website, but continue making changes after rewiewing your change.
+    %p You may also "Cancel" any changes in which case your changes will not be saved and you will return to the page index.