skip to content
Facebook

GETTING STARTED WITH MOKIO CMS

Step by step installation:

  1. Install ruby 2.1.1
  2. Install rails 4.1.1
  3. Create new rails application: rails new app_name
  4. Require mokio in your gemfile: gem 'mokio' 
  5. bundle install *
  6. Run rake mokio:install
  7. Add following line to config/routes.rb: mount Mokio::Engine => "/backend"
  8. Open: http://localhost:3000/backend
  9. Your login is admin@admin.com and password admin

Full install - with system libraries (tested on Ubuntu 12-14):

  1. Get Mokio-install.sh script from
  2. Save it in the folder where you want to have your application installed
  3. Run: bash Mokio-install.sh
  4. Provide password for root, answer Y, when prompted, provide application name and choose database adapter that you prefer
  5. Please be patient – it may take several minutes as script includes such operations as compilation and instalation of ruby and rails
  6. After script finishes, your application is ready to use, run rails s in application folder and open: http://localhost:3000/backend
  7. Your login is admin@admin.com and password admin

Add MOKIO to existing application

 
  1. Require mokio in your gemfile: gem 'mokio' 
  2. bundle install *
  3. Run rake mokio:install
  4. Open: http://localhost:3000/backend
  5. Your login is admin@admin.com and password admin

* In case some libraries are missing please use „Full install”. You can find list of needed libraries in Mokio-install.sh script.

Download above instructions as pdf


MOKIO GLOBAL CONFIGURATION

Here is how you can customize the behaviour of Mokio application:

Default language shortname for backend

Set to the shortname of the Lang record with the ID specified in :backend_default_lang_id. If you wish to change it for example to english, you need to do the following:

  1. Create Lang for english (with shortname en - shortname needs to be unique)
  2. Set backend_default_lang to "en"
config.backend_default_lang = "pl"

How many records are displayed per page

Whenever there is a need to display a list of elements in a table (contents, static modules, users) this value is used for pagination. Change this is you wish to display more or less records pew page

Please be careful, performance may decrease after increasing this value

config.backend_default_per_page = 10

Enable adding google maps for listed content types

Mentioned content types will have option to choose location. This can be displayed in frontend using Google Maps API. Available Content types: Article, PicGallery, MovGallery, Contact

Shorthand: Mokio::CONTENT_TYPES

config.backend_gmap_enabled = ["Contact"]

Enable adding meta tags for listed models

For mentioned classes it will be possible to set META tags (Facebook and Google ones). By default it is set for menu and all connent types. Menu meta tags are more important than content

meta tags if both are defined

config.backend_meta_enabled = ["Menu"] + Mokio::CONTENT_TYPES

How much records are listed in dashboard boxes

config.dashboard_size = 5

Once a photo is uploaded, four copies of this photo are created - using below values for width and height. Photo is scaled to match these dimensions

Default photo width for whole application (in px)

  • uploaded photo will be scaled to have the following width
  • photos will also be displayed with this width in the backend (when a photo in gallery is clicked -big view) and in frontend
  • please note that after you change it, you need to upload you photos again
  • otherwise uploaded photo will have previous width, only view will be scaled accordingly, what may affect photo quality
config.default_width = 500

Default photo height for whole application (in px)

Similar to default_width

config.default_height = 500

Width for photos thumb (in px)

  • photo thumb (either automatically scaled from original photo or manuallu changed to different image) will be scaled to have the following width
  • photos will also be displayed with this width in the backend (when a list of photos is displayed, when the thumb is displayed) and in frontend
  • please note that after you change it, you need to upload your photos again
  • otherwise uploaded photo thumb will have previous width, only view will be scaled accordingly, what may affect photo thumb quality
config.photo_thumb_width = 100

Height for photos thumb (in px)

Similar to photo_thumb_with

config.photo_thumb_height = 100

Other photo sizes

- works similarly to :default_width and :default_height

Medium width for scaling photos (in px)

config.photo_medium_width = 400

Medium height for scaling photos (in px)

config.photo_medium_height = 400

Big width for scaling photos (in px)

config.photo_big_width = 1000

Big height for scaling photos (in px)

config.photo_big_height = 1000

Enable placing watermarks on photos

Once set to true, all the images uploaded to the site will be marked with watermark located under :watermark_path

config.enable_watermark = false
config.watermark_path = ""

Default quality for youtube movies

You can set it to low, medium or high. It is used when getting movies from Youtube, Dailymotionand Vimeo - if only there are movies with given quality provided

config.youtube_movie_quality = "medium"

Default lang for frontend

Set to the shortname of the default frontend language

If you wish to change it for example to english, you need to do the following:

  1. Create Lang for english (with shortname en - shortname needs to be unique) - unless already created
  2. Set frontend_default_lang to "en"
  3. Create Initial menu structure for this language (unless already created)
    1. Create Menu element for lang node: en (fake: true, parent: nil, lang_id - ID of the record from point 1.)
    2. Create Menu element for menu position: top (fake: true, parent - element from point 3a, lang_id - ID of the record from point 1.)
    3. (Optional) Create Menu element for other position if you wish to have more that one menu on your site
  4. Add frontend_initial_en variable end set it to the ID of Menu record from point 3a. In your frontend views use :frontend_initial_en when calling build_menu
config.frontend_default_lang = "pl"

Id of root menu element for specific language

config.frontend_initial_pl = 1

Facebook app id to use in frontend

If you would like to have facebook comments enabled for your application you need to provide Facebook App ID - you can get it from https://developers.facebook.com/apps

config.frontend_facebook_app_id = ""

Download above instructions as pdf


CREATING A SKIN USING MOKIO SKINS*

1. Creating a skin for your website with Mokio CMS

  1. Open Mokio backend: localhost:3000/backend
  2. Login with default admin account:
    login: admin@admin.com
    password: admin
  3. Navigate to Skins → Add new skin
  4. Prepare skin packed with zip with the following structure:

[ZIP] skin_name
[FOLDER] skin_name
-[FOLDER] templates - main skin templates (currently available formats: erb, haml, slim)
--default.html.erb
--layout.html.erb
--home.html.erb
--article.html.erb
--pic_gallery.html.erb
--mov_gallery.html.erb
--contact.html.erb
--list.html.erb
-[FOLDER] js (javascripts for your skin)
--file.js --file2.js
-[FOLDER] css (css stylesheets for yous skin)
--style.css
--style2.css
-[FOLDER] images (pictures, photos, graphics for your skins) (jpg,gif,png)
--img1.jpg
--img2.png
--img3.gif

Requirements for the skin:

ZIP filename needs to be the same as skin name
Skin name has to be unique per system
Supported styles formats: css
Supported scripts formats: js
Supported pictures formats: jpg, gif, png

Skin templates are HTML files with pieces of ruby code with various helpers provided by Mokio Skins (see point 6). More information about erb, haml and slim format can be found here:
ERB: http://www.stuartellis.eu/articles/erb/
HAML: http://haml.info/
SLIM: http://slim-lang.com/

2. Activate your skin

To activate your skin, navigate to: Skins → Edit skin
a. Change Active field to On (green)
b. Save the skin

3. Edit skin

To edit your skin, navigate to: Skins → Edit skin
On the left there is a list of skin files available for edit.
Useful shortcuts:
[ Ctrl R ] - displays list of all available helpers. Selected one is copies to the editor
[ Ctrl S ] or Save File – saves your changes in given file
[ Ctrl Z ] - undo changes

* available as additional plugin to Mokio, currently only on websites created by site creator on mokio.org

Download above instructions as pdf

MOKIO FRONEND HELPERS

* Helpers marked with [S] are available only with gem mokio_skins

1. HEAD includes

- include_skin_css_all [S] – includes all css that are available in the skin (css folder)

- include_skin_css (name) [S] – includes css file with given name

- include_skin_js_all [S] – includes all javascripts files available in the skin (js folder)

- include_skin_js (name) [S] - includes javascript file with given name

- include_jquery_ui [S] – includes a file with jquery.ui.core library

- include_meta [S] – include meta tags. Values should be set in Mokio backend for given article or menu. By default, for list of contents meta is taken from menu, for home page from first content and for single content from this content.

 

2. Menu

- build_menu (initial_id, position, limit = 1, with_nav = true, nav_class="navmenu", hierarchical="false") – builds menu tree for specified arguments, returns html.
Parameters:
initial_id - root's id
position - menu position, root child name or id
limit - how deep should builder look for children, count starts after position
hierarchical - specifies if you want to use hierarchical links or not

By default Mokio has two languages enabled: polish and english
Currently selected language is kept in frontend_default_lang variable
Each language version of the site has its own menu – that can be edited from the Mokio backend
Menu is represented as tree structure. Root node is the language and its children are the positions on which menu can be displayed, i.e. PL → TOP. Only second level children are real menu elements that are displayed on the website.

If hierarchical is set to false (default behavior), generated links have the following structure:
my.domain.com/:menu_id
and to use it in frontend you need to specify following route in your routes.rb:
get “/menu:id” => “contents#show”

If hierarchical is set to true, generated links represent whole path to the root node. For example:
For following menu:

  • level1
    • level2
      • level3
  • level1a

Generated links will look as follows:
/level1
/level1/level2
/level1/level2/level3
/level1a


To handle it properly in frontend you need to add following lines to your routes.rb:
get "/*menu_path/:menu_id" => "content#show"
get "/:menu_id" => "content#show"

 

 

Menu cannot exist without a language. When you add new localization (language) in the backend - main menu structure is automatically created.

 

Adding new language

To add new language, navigate to:
Mokio → Language settings → Add new language

Adding new menu element
 

To add new menu element navigate to
Mokio → Menu → Add menu

Choose requested language.

Active – specifies is menu (link to the assigned contents) should be active – so is clicking on it in frontend actually shows the contents
Visible – specifies if menu (link to the assigned contents) should be generated when generating menu structure. If set to false (red cross), clicking on the link in frontend actually shows the contents, however link is not visible in menu. This can be usefull when you would like to have links to your contents in other contents – menu link can be pasted to HTML editor of given content's content field.

Choose if menu is an external URL or a link to contents from your site.

Parent element – parent of given menu – for yout main nodes it should be menu position (TOP from the example above).

Target – specifies whether the contents of this menu should be opened in current window (as a part of the website – default behavior), in the same window but as a whole page or in new window/tab.
Example:

Let's create new menu element and name it menu1. Then let's add to its children: menu1-a and menu1-b.
= build_menu(''top'',100)
or only menu1-a and menu1-b:
= build_menu(''menu1'',1)

- build_menu_by_name (initial_name, limit) - builds menu tree for specified arguments, returns html

Parameters:
initial_name - parent menu position name
limit - how deep should builder look for children, count starts after position
 

- build_items (item, limit, index) - recursive building menu items

Parameters:
item - Mokio::Menu object
limit - how deep should builder look for children
index - how deep is function already

- create_menu – alias for build_menu

- isMenu?(obj) - raises IsNotAMokioMenuErrorr if obj isn't a Mokio::Menu object

- menu_content_all (menu) - returns all contents added to given menu – regardless if they are active or not

- menu_content (menu, limit = nil) - returns active contents added to menu

Parameters:

menu - Mokio::Menu object
limit - Limit contents count

- menu_content_titles - returns active contents titles added to menu

Parameters:

menu - Mokio::Menu object
limit - Limit contents count

3. HTML blocks

- menu_static_modules(menu, limit) – returns static_modules added to menu

Parameters:

menu - Mokio::Menu object
limit - Limit contents count

- menu_static_modules_titles - returns static_modules titles added to menu

Parameters:

menu - Mokio::Menu object
limit - Limit static modules count

- menu_slug (menu) – returns menu slug

- menu_locale_root_id - returns menu root id for active locale (language)

- menu_root_id - returns menu root id for given name

- build_static_modules - displays HTML blocks for given position. HTML blocks are a pieces of HTML that can be associated with given pages and given positions on the page.
For one position we can have many HTML blocks. One HTML block can be associated with many positions.
Position to which HTML block is assigned can have its own template, that will be used to generate final HTML. If a position doesn't have any template, HTML block content will be displayed using default template (nothing will be added to defined HTML code).
Both position and HTML block can be activated or deactivated. To see HTML block, both position and HTML block must be active.
To display HTML block, it has to be assigned at least to one position.

Parameters:

position name – name of the position, for which HTML blocks will be displayed.

Example:

=build_static_modules (''footer'') - displays all blocks assigned to “footer” position

- build_from_content(content, with_intro = true) - builds html for a single static_module, without specific template, with or without intro

Parameters:
content - single static module from result

- build_from_view_file(content, tpl) - builds html for a single static_module with tpl template and render

- build_content(obj, position, with_intro = true) - checks visibility and generate static modules tree from Mokio::StaticModule object

Parameters:
obj - static modules object
position – module position object

4. Content

- isContent?(obj) - raises IsNotAMokioContentError if obj isn't a Mokio::Content object

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)

- content_title (obj) - returns title field for given object

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)

- content_intro (obj) - returns intro field for given object as html

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)

- content_content (obj) - returns content field for given object as html

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)

- content_main_pic(obj, version = nil) - returns main picture for given object as html

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)
version – version of the picture (version available by default are as follows: “edit” - 100px x 100px and “main_pic” - 150px x 150px)

- main_pic_url (obj, version = nil) - returns main picture url for given object as string

Parameters:
obj - Mokio::Content object (including inherited Mokio::Article etc..)
version – version of the picture (version available by default are as follows: “edit” - 100px x 100px and “main_pic” - 150px x 150px)

5. External scripts

- build_external_script (name) – includes given external_script (by its name) as javascript tag. Can be useful for instance for Google Analytics code.

Adding new external script

In Mokio backend navigate to:
Mokio → External Scripts → Add new external script

- build_all_external_scripts – includes all external scripts from mokio_external_scripts

- build_common(obj) – build a single external script from Mokio::ExternalScript object

6. Various

- render_template [S] – renders given template from templates folder

Download above instructions as pdf

 


CREATING MODULES (GEMS) FOR MOKIO

In this tutorial you will create simple gem to Mokio CMS

1. Setup

1.1 Create your own gemset and install Rails 4.1.1
 

rvm use [your ruby version] rvm gemset create [your gemset name] gem install rails -v 4.1.1

1.2 Create database schema
 

Name it i.e. mokio_products

1.2 Create your plugin with the command:
 

rails plugin new mokio_products --mountable -d [database]
([database] options: mysql/oracle/postgresql/sqlite3/frontbase/ibm_db/sqlserver/jdbcmysql/jdbcsqlite3/jdbcpostgresql/jdbc)

I.e. rails plugin new mokio_products --mountable -d mysql

It will create standard folders hierarchy.

1.3 Configure database connection
 

In your test/dummy/config/database.yml change configuration

development:
adapter: mysql2
encoding: utf8
database: mokio_products
pool: 5
username: root
password: secret_password
socket: /var/run/mysqld/mysqld.sock
1.4 Install mokio
 

First require Mokio in your Gemfile

gem 'mokio', :git => "https://github.com/versoft/mokio.git"
Then run:

bundle install
Go to mokio_products/test/dummy and run:

rake mokio:install (it will create tables and necessary data)
Open test/dummy/config/routes.rb and edit it to look like this:

Rails.application.routes.draw do
mount Mokio::Engine => "/backend"
end

Start your server and go to http://localhost:3000/backend

Welcome!

 

Your login is: admin@admin.com and password: admin

2. Creating model

2.1 Migrations (see: http://guides.rubyonrails.org/migrations.html)
 

We will create table mokio_products with 2 columns: name and part_number

rails generate migration CreateMokioProducts name:string part_number:string active:boolean
Run:

rake db:migrate

2.2 Model class

Create your model class in app/model/mokio/product.rb as following:

module Mokio
class Product < ActiveRecord::Base
include Mokio::Concerns::Models::Common
end
end


Common module add's methods commonly used in our models. I.e. standard scopes, methods, validators. In your model you must define columns editable and deletable or define methods with these names. You also have to override self.columns_for_table method which defines columns displayed in index action.

module Mokio
class Product < ActiveRecord::Base
include Mokio::Concerns::Models::Common
end

def editable
true
end

def deletable
true
end

def self.columns_for_table
%w(name active part_number)
end

end


If you set these methods to true, you will see edit and delete buttons in your model record actions.

3. Creating controllers

Add app/controlers/mokio/products_controller.rb
Extend Mokio::CommonController to add standard actions to your controller (index, new, edit, create, update, destroy) and some other methods

module Mokio
class ProductsController < Mokio::CommonController
include ActiveSupport::Concern

end
end

4. Creating views

As you can see in backend there is no button to your Products model. Mokio CMS has mechanism to extend standard views.

4.1 Routes
 

Change your app/config/routes.rb:

Mokio::Engine.routes.draw do
resources :products
end

4.2 Locales
 

Create your locale file i.e app/config/locales/en.yml:

en:
products:
products: Awesome products
index_title: Products
index_add_new: Add new product

 

4.3 Extend Mokio views
 
4.3.1 Template
 

Create file with your button template (slim, haml, erb are allowed)

app/views/my_btn.html.slim:

li
a href=products_path
span.icon16.entypo-icon-images
= bt("products", Mokio::Product)

Info: bt("products", Mokio::Product) is equal to t("products.products ")

4.3.2 Config
 

Then create app/config/views.yml:

-
original_view: "mokio/layout/sidebar"
override_path: "my_btn"
element_path: "#sidebar-ul"
type: "css"


You can use type: "xpath" to use Nokogiri selectors syntax in element path.

REMEMBER:

If you want to override partial view, the override_path should be: "path/to/view/my_partial"

but the file should have a name: "path/to/view/_my_partial"

Restart your server everty time you change views.yml file

Start server and go to localhost:3000/backend
Now you will see button to your products and working index view

 
4.4 Handle create action
 

To handle [Add new product] button you have to create partial template app/views/mokio/_form.html.slim

- cache [:form, obj] do
= f.input :name
= f.input :active, :wrapper => :active_checkbox, disabled: !obj.display_editable_field?('active')
= f.input :part_number


Add some translations:

en:
backend:
breadcrumbs:
products: Products
products_new: Creating new product
products:
products: Awesome products
index_title: Products
index_add_new: Add new product
new_title: New product
activerecord:
attributes:
mokio/product:
name: Name
active: Active
part_number: Part number
Now you can create your product.


After save you will see it on product list.

 

 

To handle active button add to en.yml

en:
products:
update_active_true: "Product '%{title}' is now active"
update_active_false: "Product '%{title}' is now inactive"


Add to routes.rb:

resources :products do
member do
post :update_active
end
end

 

 
 
4.5 Additional index buttons
 

Mokio has mechanism to simple add own action buttons. Lets add [Import products] button next to [Add new product]

4.5.1 Routes
 

Change routes.rb:

resources :products do
collection do
get '/import', to: 'products#import'
end
end

4.5.2 View
 

Create app/views/mokio/products/_import_btn.html.slim

= btn_new( bt("index_import", @obj_class), import_products_path)

4.5.3 Translations
 

Add:

en:
products:
index_import: Import products

4.5.4 Controller
 

Add import action and override method additional_index_buttons.

def import
#some logic
end

def additional_index_buttons
"mokio/products/import_btn"
end


Now you can see our [Import products] button.

 
 
4.6 Additional action buttons
 

Now lets add our own button in actions i.e. download button.

4.5.1 Routes
 

Change routes.rb:

resources :products do
collection do
get '/import', to: 'products#import'
get '/download', to: 'products#download'
end
end

4.5.2 View
 

Create json.slim view with our action button.
app/views/mokio/products/_download_btn.json.slim

= link_to import_products_path(:product_id => obj.id) do span class="icon12 entypo-icon-download"

4.5.4 Controller
 

Override method additional_action_buttons.

def additional_action_buttons
"mokio/products/download_btn"
end


Now you can see our [download] action button.

 

Download above instructions as pdf

Download source code of above example as zip


Stay in touch!

Sign up and we'll keep you informed of the cool things we do ;)