Irwi - Wiki in Rails Applications
I found that for such a seemingly standard task as adding Wiki functionality in Rails there is no full-fledged plug-in that would easily integrate with an existing application. In this regard, was written his own.
The main criteria for the development were:
What happened is a cross between a generator (which provides good extensibility and modifiability) and an engine (so that it can be easily updated).
')
For the plug-in to work (in particular, page history) a diff-lcs gem is required. RedCloth is used by default for formatting, but you can choose another formatter. In this way:
To install the plugin, run in the Rails application directory:
After installation, you need to generate a migration, model and controller ... Wait, it does not mean that you will have a bunch of someone else's code in the application, which is not clear how to support! The controller and the model contain only one line of the type acts_as_ * and is generated so that later it would be easier for you to extend the functionality. All of the wiki's own functionality is implemented in the plug-in files, which allows you to safely update it.
So, to generate the necessary files you need to call the corresponding generator:
After the generator is called into the application, the following changes will be made:
Also, the following line will be added to the routes:
As it is easy to guess, it indicates the wiki root in your application. You can easily change it to the one you like best.
Everything, working wiki in your application is generated. In principle, you can already use it, but probably you would still like to change some of its aspects under your application, for example, change the templates used for displaying or link it to your system of users and restrict the rights to edit pages. This will be discussed further.
Changing the appearance can be done in two ways:
To replace a template (including partial), you must define a template with the corresponding name in the view directory for your controller. Nothing unusual, right? If you do not know what to write there, you can look at the default templates in the source code of the plugin (they are there in app / views), since they are extremely simple.
Most likely, you will use the first method, but the first is still worth mentioning. By default, CSS is added to each default template with a description of the default style. Perhaps you want to throw it (and connect your own layout). For this, it is enough to override the wiki_page_style method in the helper with your own, which returns an empty string. This way you simply remove the styles from the pages.
What is needed to bind wiki to an existing user system in an application?
The simplest case is if your user's model is called User and you have a current_user method defined in the controller that returns the current user. Agree, this is a fairly common case. In this case, the wiki will automatically link to the users and take the current user as the author of the changes.
The only problem is that on all pages the username will appear as something like User123 . Probably, this is still not what you want. To remedy this situation, it is sufficient to define the wiki_user method in the WikiPagesHelper class. For example, as follows:
If your model is somehow called differently, you will have to add one more line when initializing the application:
I recommend creating a separate initializer for this, in order to add other options that you might want to install, but in principle, you are free to do what you want.
Most likely, you will want to add a restriction on the rights to view or edit wiki pages (generally speaking, I think this is a very good idea). For example, at a minimum, give editing rights only to registered users.
To do this, you just need to override the three methods in the controller that verify the rights: show_allowed ?, history_allowed? and edit_allowed ?. In each of the methods, it is necessary to check whether the current user has the right to perform an action (view, view history, edit) with the current page (@page) and, accordingly, return something that is regarded as esttina or as a lie. If the corresponding method returns false, the action is not performed and the controller calls the not_allowed method, which by default renders the error text, but you will most likely want to override it (for example, to redirect the user to the login page).
Thus, the approximate controller code might look like this:
I briefly described using my wiki plugin in Rails. Some moments, of course, remained outside the scope of this article, but I will describe them later. Any comments, suggestions and ideas are welcome (via the comments, github, or any of my contacts), as well as patches and forks (if someone wants to add something to the plugin).
Source code is available on GItHub: github.com/alno/irwi
The main criteria for the development were:
- The possibility of rapid integration into the application.
- Good extensibility.
- The absence of someone else's code (in the sense of the plug-in code) in the application, to which the use of generators often leads. In this sense, I tried to match up to Authlogic.
What happened is a cross between a generator (which provides good extensibility and modifiability) and an engine (so that it can be easily updated).
')
Installation and use
For the plug-in to work (in particular, page history) a diff-lcs gem is required. RedCloth is used by default for formatting, but you can choose another formatter. In this way:
gem install diff-lcs RedCloth
To install the plugin, run in the Rails application directory:
script / plugin install git: //github.com/alno/irwi
After installation, you need to generate a migration, model and controller ... Wait, it does not mean that you will have a bunch of someone else's code in the application, which is not clear how to support! The controller and the model contain only one line of the type acts_as_ * and is generated so that later it would be easier for you to extend the functionality. All of the wiki's own functionality is implemented in the plug-in files, which allows you to safely update it.
So, to generate the necessary files you need to call the corresponding generator:
script / generate irwi_wiki
After the generator is called into the application, the following changes will be made:
- Added WikiPageController and corresponding helper for page processing.
- Added WikiPage and WikiPageVersion models to present pages.
- A migration will be generated that creates tables in the database.
Also, the following line will be added to the routes:
Copy Source | Copy HTML map.wiki_root '/wiki'As it is easy to guess, it indicates the wiki root in your application. You can easily change it to the one you like best.
Everything, working wiki in your application is generated. In principle, you can already use it, but probably you would still like to change some of its aspects under your application, for example, change the templates used for displaying or link it to your system of users and restrict the rights to edit pages. This will be discussed further.
Change in appearance
Changing the appearance can be done in two ways:
- Replacing templates
- Replacing styles in default templates
To replace a template (including partial), you must define a template with the corresponding name in the view directory for your controller. Nothing unusual, right? If you do not know what to write there, you can look at the default templates in the source code of the plugin (they are there in app / views), since they are extremely simple.
Most likely, you will use the first method, but the first is still worth mentioning. By default, CSS is added to each default template with a description of the default style. Perhaps you want to throw it (and connect your own layout). For this, it is enough to override the wiki_page_style method in the helper with your own, which returns an empty string. This way you simply remove the styles from the pages.
Snapping to users
What is needed to bind wiki to an existing user system in an application?
The simplest case is if your user's model is called User and you have a current_user method defined in the controller that returns the current user. Agree, this is a fairly common case. In this case, the wiki will automatically link to the users and take the current user as the author of the changes.
The only problem is that on all pages the username will appear as something like User123 . Probably, this is still not what you want. To remedy this situation, it is sufficient to define the wiki_user method in the WikiPagesHelper class. For example, as follows:
Copy Source | Copy HTML
- module WikiPagesHelper
- include Irwi :: Helpers :: WikiPagesHelper
- def wiki_user (user)
- user? link_to (user.login, user_path (user)): "Guest"
- end
- end
If your model is somehow called differently, you will have to add one more line when initializing the application:
Irwi.config.user_class_name = 'Account' # Of course, if your model is called that way
I recommend creating a separate initializer for this, in order to add other options that you might want to install, but in principle, you are free to do what you want.
Restriction of rights to perform operations
Most likely, you will want to add a restriction on the rights to view or edit wiki pages (generally speaking, I think this is a very good idea). For example, at a minimum, give editing rights only to registered users.
To do this, you just need to override the three methods in the controller that verify the rights: show_allowed ?, history_allowed? and edit_allowed ?. In each of the methods, it is necessary to check whether the current user has the right to perform an action (view, view history, edit) with the current page (@page) and, accordingly, return something that is regarded as esttina or as a lie. If the corresponding method returns false, the action is not performed and the controller calls the not_allowed method, which by default renders the error text, but you will most likely want to override it (for example, to redirect the user to the login page).
Thus, the approximate controller code might look like this:
Copy Source | Copy HTML
- class WikiPagesController <ApplicationController
- acts_as_wiki_pages_controller
- def show_allowed ?
- true # show to all
- end
- def history_allowed ?
- true # And let everyone watch the story
- end
- def edit_allowed ?
- current_user # A is edited only by those who are logged in
- end
- def not_allowed
- redirect_to login_path # All violators redirect to login page
- end
- end
Total
I briefly described using my wiki plugin in Rails. Some moments, of course, remained outside the scope of this article, but I will describe them later. Any comments, suggestions and ideas are welcome (via the comments, github, or any of my contacts), as well as patches and forks (if someone wants to add something to the plugin).
Source code is available on GItHub: github.com/alno/irwi
Source: https://habr.com/ru/post/68235/
All Articles