Feral by inRainbows - Documentation

# Feral by inRainbows

## Documentation

- created: 09/16/2014
- latest update: 10/07/2014
- by: Mathijs
- email: mh@inrainbo.ws

Feral is a web application that brings you and your coworkers/friends/family/etc. together in a closed online environment. All members can share items in 4 categories: news, calendar, files and forum. Each member gets a profile with all their contact information, which is available to all other members. Feral is build on the framework CakePHP. This makes it easy to customize and extend Feral to your own needs.

### Introduction

#### Thank you

First of all we would like to thank you for purchasing Feral!

#### About inRainbows

We are a small club of developers located in Eindhoven (The Netherlands) with deep passion for building great looking, super user friendly web applications. We are perfectionists. Our goal with our software is to make life a little bit easer.

#### About Feral

Feral is a web application that brings you and your coworkers/friends/family/etc. together in a closed online environment. All members can share items in 4 categories: news, calendar, files and forum. Each member gets a profile with all their contact information, which is available to all other members.
Feral is build on the framework CakePHP. This makes it easy to customize and extend Feral to your own needs.

#### Customize Feral

If you want to customize Feral and you can’t do it on your own, we’ll be happy to do it for you. You can send you request to support@inrainbo.ws.

#### Questions / Support

If you have a question and you can’t find the answer in this documentation or on our support page (http://support.inrainbo.ws), please contact us through support@inrainbo.ws or https://inrainbows.zendesk.com/hc/en-us/requests/new.
We are aware that some people obtain software through illegal sources. We will only deliver support to customers who actually bought Feral. Therefore, please provide the product name and your purchase code with your request.

### Requirements

#### Web server

Feral is fast and easy to install. The minimum requirements are a web server and a copy of Feral, that’s it! In order to run Feral you will need the following:

- Apache web server. mod_rewrite is preferred, but by no means required.
- PHP 5.2.5 or greater
- MySQL (4 or greater)

#### Knowledge

In order to install Feral you need some basic knowledge about FTP, file permissions and how to set up a database.

### Installation

#### Preparing your server

In order to run Feral you need an empty root directory on your domain or subdomain. You also need a MySQL database. You can create a database in the control panel from your hosting provider.

#### Uploading files

Upload all the files in the folder 'Upload' from your downloaded package. You must upload the files to the root of your domain or a subdomain. Make sure that your upload contains all hidden files.

#### Setting permissions

You need to set some permission in order to make Feral work. Make sure the following files and (sub)directories are writeable by the web server user:

- app/tmp (and all subfolders)
- app/Config/core.php
- app/Config/database.php
- app/Config/email.php
- app/webroot/data (and all subfolders)

#### Running the installation wizard

Navigate your browser to yourdomain.com/install/.
Over here you will get a confirmation if you have set all permissions correctly. If so you can run the installation wizard by clicking the button 'Start Installation'.

### Installation Wizard

#### Check

If all required files and folders exist and all permissions are set correctly, you can run the installation wizard by clicking the button Start Installation.

Form Field | Input | Required
Datasource | At this moment only MySQL is available | yes
Host | Database hostname; This is almost always localhost | yes
Port | Leave blank if unknown | no
User | Database username | yes
Password | Database password | yes
Name | Database name | yes
Prefix | Not required; Always end with an underscore (e.g. feral_) | no

#### Database

In this step the datasource connection gets set up. If everything is filled in correctly the connection will be made and the tables will be imported.

#### General

Form Field | Input | Required
Website URL | Where Feral is located (e.g. feral.inrainbo.ws) | yes
Website name | Used for header title on mobile devices; Used for frontend homepage; Used in outgoing email subject line | yes
Website short name | Used for header title on tablets, desktops; Used for web app title on iOS | yes
Website window title | User for title in browser window | yes
Website description | Used for frontend homepage | no
Show fronted | Whether or not to show the front end homepage when a member is not logged in | yes

#### Display

Form Field | Input | Required
Default language | Choose default language for frontend/login/register pages etc. Members can choose their own language | yes
Default time zone | Choose default time zone for frontend/login/register pages etc. Members can choose their own time zone | yes
Date format | Choose sitewide date format | yes
Time format | Choose sitewide time format | yes

#### Email

##### Incoming

Form Field | Input | Required
Email address | Used for all incoming mail (e.g. Request Account) | yes

##### Outgoing

Form Field | Input | Required
Name | Used for all outgoing mail (e.g. Add Member, Request Account, Forgot Password, Add item notifications) | yes
Email address | Used for all outgoing mail (e.g. Add Member, Request Account, Forgot Password, Add item notifications) | yes

#### User

In this step you are going to create the first member for Feral. With this account you can login to Feral after you complete this installation. This account has admin privileges.

##### Settings

Form Field | Input | Required
Visitors can sign up | Yes: visitor can register their own account No: visitors can request an account; administrators have to add members | yes
Members can follow eachother | Yes: members see only the items from the members they follow No: members see all items from all members | yes

##### Account

Form Field | Input | Required
First name | Enter your first name | yes
Last name | Enter your last name | yes
Email address | Enter you email address | yes
Password | Choose a password with a minimum length of 6 characters | yes
Language | Choose your preferred language | yes
Time zone | Choose your time zone | yes

#### Finish

After you press finish you will get redirected to the login screen.

### Login

#### Login to Feral

Navigate your browser to yourdomain.com/users/login/.
This is where all members login to Feral. You can login using the account you created in the installation wizard. This account has admin privileges.
When you tick 'Keep me logged in', a cookie will be set and your login status will be remembered.
People who want to join Feral can submit their personal info by clicking the button 'Request Account'. When members forget their password they can reset it by clicking 'Forgot your password?’.

Form Field | Input | Required
Email address | Enter you email address | yes
Password | Enter your password | yes

#### First login

When members login for the first time, they go directly to Edit Profile and get the following alert: „Before you can use this system, you must fill in your profile.”. This behavior is build in so that all profiles get filled immediately.

#### Request Account

If Feral is set to "Visitors can not sign up" and people want to join Feral, they can submit their personal info on this page. The information will be send to the incoming email address provided in the installation wizard.

Form Field | Input | Required
Company | Company which applicant works for | no
First name | First name from applicant | yes
Last name | Last name from applicant | yes
Email address | Email address from applicant | yes

#### Sign Up

If Feral is set to "Visitors can sign up", people can sign up on this page. When the form is submitted, the members gets an email with a confirmation link. The member has to confirm the account before they can login.

Form Field | Input | Required
First name | First name from applicant | yes
Last name | Last name from applicant | yes
Email address | Email address from applicant | yes
Password | Password from applicant | yes
Language | Preferred language from applicant | yes
Time zone | Time zone from applicant | yes

#### Forgot your password?

When members forget their password they can request a new one on this page. A new password will be generated en send by email.

Form Field | Input | Required
Email address | New password will be send to this email address; Member with email address must exist | yes

#### Logout

To log out from Feral click on your name in the top-right menu and choose 'Log Out'.

### Members

#### User roles

Users are able to:

- Edit their profile
- Change their password
- Add items in all categories
- Edit/delete their own items
- Comment on items
- Edit/delete their own comments

#### Index

On this page all members are displayed ordered by name. To view the full profile click on the button 'View Profile'.

#### View Member

On this page the full profile from the member is shown. Also all items added by the member are shown ordered by date, newest first. All members can download an vCard file to place the contact information in their own address book.

#### Add Member

To add a member click in the top-right menu on Add => Member.
Note: only administrators can add members.

##### Login

Form Field | Input | Required
Email address | Email address from member | yes
Password | Password for member; You can generate one by clicking the button on the right of the input | yes
Type | Type of member: User or Administrator | yes

##### Personal Information

Form Field | Input | Required
First name | First name from member | yes
Last name | Last name from member | yes
Language | Language from user | yes
Time zone | Time zone from user | yes
Send email with… | If you check this box an email with all (login) information will be send to membe | no

#### Edit Member (Profile)

To edit a member click in the cover photo from the member on the pencil.

##### Personal Information

Form Field | Input | Required
First name | First name from member | yes
Last name | Last name from member | yes
Company | Company which member works for | no
Function | Job from member | no
* Type | Type of member: User or Administrator | yes

* Only available for administrators

##### Contact information

Form Field | Input | Required
Street | Address from member/company | yes
City | Address from member/company | yes
Zip/Postal Code | Address from member/company | yes
Country | Address from member/company | yes
Phone number | Phone number from member/company | yes
Email address | Email address from member; Note: Email address is used by member for login | yes

##### Accounts

Form Field | Input | Required
LinkedIn | Link to LinkedIn account from member | no
Twitter | Link to Twitter account from member | no
Facebook | Link to Facebook account from member | no

##### Footage

Form Field | Input | Required
Profile photo | Profile photo from member; Used sitewide | yes
Cover photo | Cover photo from member; User for profile personalization | yes

##### Other

Form Field | Input | Required
About me | Displayed on profile from member | no
Hobbies | Displayed on profile from member | no
Knowledge | Displayed on profile from member | no

#### Edit Password

To edit your/a member’s password click in the cover photo from the member on the key.

#### Member Settings

To change users settings (Language, Time zone, Date format, Time format) from Feral click as on your name in the top-right menu and click 'Settings'. A dialog will open in which you can change all settings. Click 'Save' when you are done.

#### Delete Member

To delete a member click in the cover photo from the member on the X. Only administrators can delete members.

### Administrators

#### User roles

Administrators can do the same as users, in addition:

- Change core settings
- Add/edit members
- Change password from all members
- Edit/delete items from all members
- Edit/delete comments from all members

#### Feral Settings

To change the settings from Feral click as an administrator on your name in the top-right menu and click 'Admin Settings'. A dialog will open in which you can change all settings. Click 'Save' when you are done.

#### Items only for administrators

Items marked with a lock are only visible for administrators.
Administrators have the option to post items which are only available for administrators.

### Navigation

#### Main navigation

The main navigation consists of:

- Dashboard
- News
- Calendar
- Files
- Forum
- Members

#### Top-right navigation

The top-right navigation consists of:

- Add
  - News
  - Event
  - File
  - Message
  - Member *
- User name
  - Profile
  - Settings *
  - Log Out

* Only available for administrators

### Dashboard

Dashboard is a gathering of all items on Feral from all categories ordered by date, newest first.

#### Colors

Each category (news, calendar, files, forum) has it’s own color. This way it’s very easy to tell which item belongs to which category.

Color | Category
Yellow | News
Red | Calendar
Green | Files
Blue | Forum

#### News

#### Event (calendar)

#### File

#### Message (forum)

### News

News is a category where members can share interesting news stories.

#### Index

On this page all news items are displayed ordered by date, newest first. To view the full item click on the button 'More info'.

#### View News

On this page the full news item with all it’s comments is shown. It’s possible for all members to add comments.

#### Add News

To add news click in the top-right menu on Add => News. All members can add news.

Form Field | Input | Required
Title | Item title | yes
Content | Item content | no
Notify other members | Notify all members/followers that new item is posted | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Edit News

To edit news click on the pencil on the right in the item header. Members can edit their own news. Administrators can edit all news.

Form Field | Input | Required
Title | Item title | yes
Content | Item content | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Delete News

To delete news click on the X on the right in the item header. Members can delete their own news. Administrators can delete all news.

### Calendar

Calendar is a category where members can share events. It’s possible for members to indicate their attendance (present/absent).

#### Index

On this page all events are displayed in a full calendar. To view an item click on the event.

#### View Event

On this page the full news item with all it’s comments is shown. Members can download an ICS file to place the event in their own Agenda. It’s possible for all members to add comments.

#### Presence

It’s possible for members to indicate their attendance for an event. To do this click on the button 'Present' or 'Absent'. The status on the right will automatically refresh.

#### Add Event

To add an event click in the top-right menu on Add => Event. All members can add events.

Form Field | Input | Required
Start date | Item start date | yes
Start time | Item start time | yes
End date | Item end date; this must be later or the same as start date | yes
End time | Item location; If start date en end date are the same this must be later then start time | yes
Location | Item location | no
Title | Item title | yes
Description | Item description | no
Notify other members | Notify all members/followers that new item is posted | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Edit Event

To edit an event click under event view on the pencil on the right in the item header. Members can edit their own events. Administrators can edit all events.

Form Field | Input | Required
Start date | Item start date | yes
Start time | Item start time | yes
End date | Item end date; this must be later or the same as start date | yes
End time | Item location; If start date en end date are the same this must be later then start time | yes
Location | Item location | no
Title | Item title | yes
Description | Item description | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Delete Event

To delete an event click under event view on the X on the right in the item header. Members can delete their own events. Administrators can delete all events.

### Files

Files is a category where members can share files. It’s possible upload max 10 files per item. The max size per item is 10MB.

#### Index

On this page all file items are displayed ordered by date, newest first. To view the full item click on the button 'More info'.

#### View File

On this page the full file item with all it’s comments is shown. Members can download an files to their device. It’s possible for all members to add comments.

#### Add File

To add files click in the top-right menu on Add => File. All members can add files.

Form Field | Input | Required
Title | Item title | yes
Description | Item description | no
Add Files… | With this button you can select files from your device; Max 10 files; Max 10MB per item | yes
Notify other members | Notify all members/followers that new item is posted | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Edit File

To edit a file item click on the pencil on the right in the item header. Members can edit their own files. Administrators can edit all files.

Form Field | Input | Required
Title | Item title | yes
Description | Item description | no
Add Files… | With this button you can select files from your device; Max 10 files; Max 10MB per item | yes
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Delete File

To delete a file item click on the X on the right in the item header. Members can delete their own files. Administrators can delete all files.

### Forum

Forum is a category where members can communicate with each other.

#### Index

On this page all messages are displayed ordered by date, newest first. To view the full message click on the table row.

#### View Message

On this page the full message with all it’s replies is shown. It’s possible for all members to add replies.

#### Add Message

To add a message click in the top-right menu on Add => Message. All members can add messages.

Form Field | Input | Required
Subject | Message subject | yes
Message | Message content | no
Notify other members | Notify all members/followers that new item is posted | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Edit Message

To edit a message click under message index on the pencil in the table row or under message view on the pencil on the right in the item header. Members can edit their own messages. Administrators can edit all messages.

Form Field | Input | Required
Subject | Message subject | yes
Message | Message content | no
* Only available for administrators | Item will only be available/visible for administrators | no

* Only available for administrators

#### Delete Message

To delete a message click under message index on the X in the table row or under message view on the X on the right in the item header. Members can delete their own messages. Administrators can delete all messages.

### Comments / Replies

All members can add comments/replies to items in all categories. For message it’s called reply, for news, calendar and files it’s called comment. From now own we are going to call it comments.

#### Add Comment

To add a comment click in the item view in the bottom right on 'Add Comment'. A window will appear under the item. All members can add comments.

#### Edit Comment

To edit a comment click in the item view in the comment section on the pencil on the right of the comment. A window will appear above the comments. Members can edit their own comments. Administrators can edit all comments.

#### Delete Comment

To delete a comment click in the item view in the comment section on the X on the right of the comment. Members can delete their own comments. Administrators can delete all comments.

### Front end

It’s possible to activate Feral’s front end. This page is displayed when members are not logged in. Front end must be activated in Feral Settings.
All administrators are automatically shown on the front end page. The content under the welcome to title can be edited in Feral Settings. Change the content under General => Website description
You can edit the front end page by editing the following files:

- app/View/Layouts/home.ctp.
- app/webroot/assets/css/home.css

### iOS Web App

Web App icons en startup images are located in the folder: app/webroot/assets/images/apple-touch/.
You can edit them to your own needs.

#### Add to homescreen

It’s possible to add Feral to the homescreen from iOS. This way Feral functions as a Web App.
To do this follow this steps:

Step 1 | Step 2

### Update

#### Version 1.2 (7 October 2014)

This update contains improvements and bug fixes, including:

- New: Time zone support
- New: Multi language support (English, Dutch, German for now; other languages follow soon); POT files included
- New: Optionally members can follow eachother
- New: Optionally visitors can sign up
- Fix for the users being able to view items which are marked "for administrators only" by navigating to item directly
- Fix for users receiving notification email for new items which are marked "for administrators only"
- Small bug fixes

##### To update from 1.1 to 1.2:

This update contains a lot of changes so we recommend to do a clean install. If you necessarily must update, follow these instructions:
1. Read all the following steps before you begin.
2. Make sure you are logged out of Feral.
3. Go to phpMyAdmin and run the following sql. Make sure to change all %prefix% to your chosen prefix during installation! If you left the prefix blank simply remove all %prefix%.

    ALTER TABLE `%prefix%users`
    ADD `confirmed` TINYINT( 1 ) NOT NULL DEFAULT '1' AFTER `role`,
    ADD `confirm_token` VARCHAR( 50 ) NOT NULL AFTER `confirmed`;

    CREATE TABLE `%prefix%user_follows` (
      `id` int(11) NOT NULL AUTO_INCREMENT,
      `user_id` int(11) NOT NULL,
      `follow_user_id` int(11) NOT NULL,
      `deleted` tinyint(4) NOT NULL DEFAULT '0',
      `created` datetime NOT NULL,
      `modified` datetime NOT NULL,
      PRIMARY KEY (`id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

    CREATE TABLE `%prefix%user_settings` (
      `id` int(11) NOT NULL AUTO_INCREMENT,
      `user_id` int(11) NOT NULL,
      `date_format` varchar(255) NOT NULL,
      `time_format` varchar(255) NOT NULL,
      `language` varchar(10) NOT NULL,
      `timezone` varchar(255) NOT NULL,
      `created` datetime NOT NULL,
      `modified` datetime NOT NULL,
      PRIMARY KEY (`id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=latin1;

    INSERT INTO `%prefix%configurations` (`id`, `key`, `value`, `created`, `modified`)
    VALUES(17, 'language', 'eng', '2014-01-01 00:00:00', '2014-01-01 00:00:00');
    INSERT INTO `%prefix%configurations` (`id`, `key`, `value`, `created`, `modified`)
    VALUES(18, 'timezone', 'Europe/Amsterdam', '2014-01-01 00:00:00', '2014-01-01 00:00:00');
    INSERT INTO `%prefix%configurations` (`id`, `key`, `value`, `created`, `modified`)
    VALUES(19, 'users_register', '0', '2014-01-01 00:00:00', '2014-01-01 00:00:00');
    INSERT INTO `%prefix%configurations` (`id`, `key`, `value`, `created`, `modified`)
    VALUES(20, 'users_follow', '0', '2014-01-01 00:00:00', '2014-01-01 00:00:00');

    UPDATE `%prefix%activities` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%configurations` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%events` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%event_attendees` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%event_comments` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%files` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%file_attachments` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%file_comments` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%messages` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%message_comments` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%news` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%news_comments` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%profiles` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%users` SET `created` = CONVERT_TZ(`created`, '+02:00', '+00:00'), `modified` = CONVERT_TZ(`modified`, '+02:00', '+00:00');
    UPDATE `%prefix%events` SET
    `start_date` = CONVERT_TZ(concat(`start_date`,' ',`start_time`), '+02:00', '+00:00'),
    `start_time` = CONVERT_TZ(concat(`start_date`,' ',`start_time`), '+02:00', '+00:00'),
    `end_date` = CONVERT_TZ(concat(`end_date`,' ',`end_time`), '+02:00', '+00:00'),
    `end_time` = CONVERT_TZ(concat(`end_date`,' ',`end_time`), '+02:00', '+00:00');

4. Add/Replace the following files/folders:

- .htaccess
- app/Config/bootstrap.php
- app/Config/core.php
- app/Controller
- app/Lib
- app/Locale
- app/Model
- app/View
- app/webroot/assets

5. Edit line 353 from file app/config/core.php:
Configure::write('install', true);
change into
Configure::write('install', false);
6. Delete the following files/folders:

- app/database.sql

#### Version 1.1 (20 September 2014)

This update contains improvements and bug fixes, including:

- New: Search items in Dashboard
- New: Pagination on the pages Dashboard, News, Calendar, Files, Forum and Members
- Fix for the return key not working in forms as it’s supposed to
- Fix for an error when saving an item with ‘Notify other members’ checked

##### To update from 1.0 to 1.1:

Go to phpMyAdmin and change the following field names from the table (yourprefix_)activities:

- controller => model
- action => method

Add/Replace the following files/folders:

- app/Config/email.php
- app/Controller
- app/Lib
- app/Model
- app/View
- webroot/assets/css
- webroot/assets/js

#### Version 1.0 (17 September 2014)

Initial release