Skip to content
This repository was archived by the owner on May 9, 2019. It is now read-only.

Usage

Jump to bottom
nerde edited this page Oct 13, 2014 · 23 revisions

Usage guide for gollum_rails

GollumRails actually acts like a normal Rails model. You can use the same methods you usually use on a regular ActiveRecord model.

Install

The initializer is used to set the path of your git directory. It should point to a bare repository, but it should also be possible to use a regular one.

To install this initializer use this predefined Rails generator:

rails g gollum_rails:install

It should generate the file config/initializers/gollum.rb for you.

Configure

Just edit config/initializers/gollum.rb as described below:

Using absolute paths

config.repository = '/Users/nirnanaaa/code/wiki.git/'

Using relative paths (relative to Rails.root)

config.repository = 'db/development.git/'

Using environmental settings (default in versions >= 1.5.9)

config.repository = :application

Now goto your environment configuration files config/environments/<environment>.rb and add the following contents to it:

config.wiki_repository = '<path>'

Where path is either a String or a Pathname such as Rails.root.join.

Path

The path must be an existing directory and must point to an existing git repository. GollumRails will check for the following things on startup:

  • does the path exist?
  • is it a valid path name?
  • is it not an empty value?

If you first make use of the GollumRails::Page class it will also check if the provided path is a valid git repository.

The model

The model is the main class, used to interact with your Git repository. It provides an interface for you to integrate it as easy as possible into your existing environment.

It acts nearly the same as your database models but there are some differences:

  • you cannot use belongs_to, has_many, has_and_belongs_to_many or any kind of associations, as a page in your Git repository isn't a database table.
  • It is still work in progress.

Install a model class

To install a new GollumRails model class just run the generator shipped with the gollum_rails gem:

rails g gollum_rails:model Page

This generates the file app/models/page.rb which should be pretty useable out of the box.

Interacting with the model

Get all Pages
Page.all
=> [#<Gollum::Page:70353808112360 cheatsheet markdown (markdown) @wiki="/Users/nirnanaaa/code/test/.git">, #<Gollum::Page:70353808111860 home (markdown) @wiki="/Users/nirnanaaa/code/test/.git">]

Page.all(folder: 'articles')
=> #TODO: fix this

Create a new Page:

Page.create!(name: 'test_page', content: 'content', format: :markdown, commit: { name: 'nirnanaa', email: '[email protected]', message: 'created page page'})

=> #<GollumRails::Page:0x007feafbb792b8 @name="test_page", @content="content", @format=:markdown, @commit={:name=>"nirnanaa", :email=>"[email protected]", :message=>"created page page"}, @validation_context=nil, @errors=#<ActiveModel::Errors:0x007feafbb78de0 @base=#<GollumRails::Page:0x007feafbb792b8 ...>, @messages={}>, @gollum_page=#<Gollum::Page:70323610905400 test_page (markdown) @wiki="/Users/nirnanaaa/code/test/.git">>

Delete a Page:

page = Page.find('content')

page.delete( name: 'nirnanaa', email: '[email protected]', message: 'deleted a page')
"16f3ed21fefd3e1883f306238aac108cf8e88656"

Update a Page:

page = Page.find('content')

page.update_attributes('newcontent', 'newname', :markdown, {name: 'nirnanaa', email: '[email protected]', message: 'updated a page'})
=> #<Gollum::Page:70323596905780 newname (markdown) @wiki="/Users/nirnanaaa/code/test/.git">

Get the Pages content:

page = Page.find('content')
puts page.raw_data

=> "content"

Get the Pages format:

page = Page.find('content')
puts page.format

=> :markdown

Get the Pages formatted content (as HTML):

page = Page.find('content')
page.html_data

=> "<p>content</p>"

Get the Pages URL:

page = Page.find('another_page')
page.url

=> "another_page"

Get the Pages title:

page = Page.find('another_page')
page.title

=> "another_page"

Get the Pages history:

page = Page.find('another_page')
page.history
=> []

page.update_attributes(format: :markdown, commit: { name: 'nirnanaa', email: '[email protected]', message: 'created page page'})
=> #<Gollum::Page:70323619028140 another_page (markdown) @wiki="/Users/nirnanaaa/code/test/.git">

page.history
=> [#<Grit::Commit "d030d27e855d54a727f87064bc97c5de4bc7b2ce">]

Get the Last committer on a page:

page = Page.find('another_page')

page.last_changed_by
=> "nirnanaa <[email protected]>"

Display a preview of the page:

page = Page.new(name: 'another_page', content: 'content', format: :markdown, commit: { name: 'nirnanaa', email: '[email protected]', message: 'created page page'}) 
=> #<Page:0x007feafc972b58 @name="another_page", @content="content", @format=:markdown, @commit={:name=>"nirnanaa", :email=>"[email protected]", :message=>"created page page"}>

page.preview
=> "<p>content</p>"

# specify different format:

page.preview(:mediawiki)
=> "content"

Verify that the file already has been saved:

page = Page.new(name: 'another_page', content: 'content', format: :markdown, commit: { name: 'nirnanaa', email: '[email protected]', message: 'created page page'}) 
=> #<Page:0x007feafc972b58 @name="another_page", @content="content", @format=:markdown, @commit={:name=>"nirnanaa", :email=>"[email protected]", :message=>"created page page"}>

page.persisted?
=> false

page.save
=> #<Page:0x007feafc972b58 @gollum_page=#<Gollum::Page:70323618550700 another_page (markdown) @wiki="/Users/nirnanaaa/code/test/.git">, @name="another_page", @content="content", @format=:markdown, @commit={:name=>"nirnanaa", :email=>"[email protected]", :message=>"created page page"}, @validation_context=nil, @errors=#<ActiveModel::Errors:0x007feafc9782b0 @base=#<Page:0x007feafc972b58 ...>, @messages={}>>

page.persisted?
=> true
Clone this wiki locally