Moving dev guide

Author: Dieter Wyns

.gitignore

@@ -0,0 +1 @@
+.DS_Store

module guide/ajax.md

@@ -0,0 +1,55 @@
+# Ajax
+
+## URL
+Before you continue, be sure to have taken a good look at the previous javascript code. Mind the parameters we're calling:
+
+```
+data: 
+{ 
+	fork: { module: 'mini_blog', action: 'this_is_awesome' }, 
+	post_id: arg 
+},
+```
+
+Because we're on the frontend, we call the frontend ajax.php supply it with a couple of arguments. The first two are always mandatory:
+
+* module    →  the module in which our action file is located
+* action    → the name of the action file, without the php-extension
+
+Because we're working in a multilingual site, the language argument is mandatory as well, although you might not need to use it in the action itself. We fetched the language through splitting the url that's currently opened in our browser.
+
+* language    → the language code (nl, en, fr, ...)
+   
+Other arguments are action depended. In case of the this_is_awesome action, we need to supply the id of the blog post (post_id) of which we want to increment the awesomeness.
+
+## Action
+
+The action file itself is a .php file located in the ajax-folder. The structure of an Ajax action is the same as an other action file, meaning, there has to be a public “execute” function.
+
+```
+class FrontendMiniBlogAjaxThisIsAwesome extends FrontendBaseAJAXAction
+{
+	public function execute()
+	{
+		$post_id = (int) SpoonFilter::getPostValue('post_id', null, '', 'int');
+
+		if($post_id == 0)
+		{
+			$this->output(self::BAD_REQUEST, null, 'invalid post_id-parameter.');
+		}
+
+		FrontendMiniBlogModel::addAwesomeness($post_id);
+
+		$this->output(self::OK);
+	}
+}
+```
+
+
+The difference with other types of actions can be found when given special attention to the naming of the class.
+
+*ApplicationModule**Ajax**Action*
+
+Also note that the class extends FrontendBaseAJAXAction. This is necessary do define constants such as "self::OK" and the output-method.
+
+Depending on the post_id being valid or not, the addAwesomeness method defined in the model is called, and the output-method is called. This function outputs JSON data which is read by the Javascript success-function we saw earlier.

module guide/api.md

@@ -0,0 +1,42 @@
+# API
+
+When you want to link your website to the outside world, it might be a good idea to provide an API to this outside world. By using the API, other programmers connect there applications, iPhone Apps, websites, ... with your website, or perhaps you could write your own iPhone App (and sell it for just € 9,99 in the AppStore) which allows to post blog posts to your website.
+We'll use an other, less complicated example to illustrate the principles of an API.
+
+## Engine
+
+First you create a file named "api.php" in the /backend/modules/module_name/engine folder. In this file you define a class called `BackendModuleNameAPI`.
+
+Then, for every action external applications should be able to perform you define a public static method.
+
+In our case we'll just have one method, `show_top_awesome`. This method will return the most (number) awesome posts of the last (days) days.
+
+```
+class BackendMiniBlogAPI
+{
+	public static function showTopAwesome()
+	{
+		$number = (int) SpoonFilter::getGetValue('number', null, 10);
+		$days = (int) SpoonFilter::getGetValue('days', null, 7);
+
+		API::output('200', BackendMiniBlogModel::getTopAwesome($number, $days));
+	}
+}
+```
+
+As you can see we expect the data to be GET-variables but if you feel like working with POST-variables,... your choice.
+
+## Return
+
+When you want to use the method above, you need to call the following url:
+  /api/1.0/?method=mini_blog.showTopAwesome&format=json&number=10&days=7
+
+The first parameter is the name of the module and the name of the action separated with a dot. This action is the real method name, not the "reversed" camelCased name as it's used with class- and filenames.
+
+When you're using the output function, you need to supply the format parameter, which has to be equal to "json" or "xml". The data we fetched and passed on the output method will be converted to one of these two formats.
+
+The last two parameters are "number" and "days". They are used only in this action. Should they be omitted, then the default value, given as the third parameter of the getGetValue-method, is used.
+
+> **Don't return**
+> In our example the API is supposed to return some data, but of course you can create method's that will not be returning any data (f.e. posting a new blog post). In that case, just don't call the output method.
+> Although you could provide some feedback wether to post was successful.

module guide/applications_&_library.md renamed to module guide/applications_and_library.md

@@ -0,0 +1,14 @@
+# Breadcrumbs
+
+Each blog article will have a proper page title. Adding this title to the breadcrumb allows users to easily keep track of their location.
+
+To add data to the breadcrumb, you'll add the following lines to the parse method in detail.php.
+
+```
+// add into breadcrumb
+$this->breadcrumb->addElement($this->record['title'], $this->record['full_url']);
+```
+
+This way, we'll add the title to the breadcrumb and if this is not the last item (e.g. if we're using categories), the second parameter will be activated and it will become a link so the user can navigate back to that.
+
+The first parameter is manditory, the second is optional.

module guide/assets/detail.png

@@ -0,0 +1,17 @@
+# Creating a module.zip file
+
+When you've finished your module, you will probably want to be able to easily install this in other websites. Since Fork CMS 3.0.0, it is possible to install packaged modules. Therefor, you'll need to create a .zip file.
+
+## The .zip file
+
+The zip file contains the absolute paths to the module, as you can see in the image below. This means that you should always have a structure that starts in the base directory of you project.
+
+![Zip structure](assets/zip_structure.png)
+
+## Required files
+
+To install the module, some files are required. Each module should have a config.php file in both the backend and frontend.
+
+In the backend, you also need an installer folder that contains an installer.php file. Next to this, you also need an info.xml file. This file is used to display information on the Extensions page in the backend. 
+
+To create these files, we recommend you to take a look in the 'Module development' section.

module guide/assets/how_apple_push_works.png

@@ -0,0 +1,103 @@
+# Creating an installer
+
+To create an installer, you need some basic files. First of all, you need the installer file. This is located in the backend installer folder. For our module this would be /backend/modules/mini_blog/installer/installer.php.
+
+Next to this file, depending on the module, you can have some other files, mostly used are the install.sql file and the locale.xml file. We'll put these in the subdirectory /data. 
+
+## Installer
+
+In the installer file we load the database tables (if required) and the locale (if required). Besides this, we also make sure our users have rights to access our module.
+
+```
+class MiniBlogInstaller extends ModuleInstaller
+{
+	/**
+	 * Install the module
+	 */
+	public function install()
+	{
+		$this->importSQL(dirname(__FILE__) . '/data/install.sql');
+
+		$this->addModule('mini_blog');
+
+		$this->importLocale(dirname(__FILE__) . '/data/locale.xml');
+```
+
+Now we want to make sure that our module can be accessed for the search module and for other users that aren't god users. We do this by adding some rules:
+
+```
+$this->makeSearchable('mini_blog');
+$this->setModuleRights(1, 'mini_blog');
+
+$this->setActionRights(1, 'mini_blog', 'index');
+$this->setActionRights(1, 'mini_blog', 'add');
+$this->setActionRights(1, 'mini_blog', 'edit');
+$this->setActionRights(1, 'mini_blog', 'delete');
+```
+
+After we've added our rights, we want to create an option so we can add our blog to the frontend. To do this, we need to create some extras. Since we also have a widget with the recent posts, we also need to create an extra for that. We do this by adding the following code:
+
+```
+$miniBlogId = $this->insertExtra('mini_blog', 'block', 'MiniBlog');
+$this->insertExtra('mini_blog', 'widget', 'RecentPosts', 'recent_posts');
+```
+
+The first extra will allow us to show the overview and other actions. The second extra will allow us to add the widget on pages. For this method, the first three parameters are mandatory. Here is a list of parameters:
+
+* module: the module we want to install the extra for
+* type: the type of extra we want, this can be a block or a widget
+* label: this is the label we should use in the dropdown navigation if we select our extra
+* action: the action we should call if this extra is called, if none is given, the base action is index
+
+Last but not least, we want to be able to manage our blog. To do this, we need to add some navigation rules for the backend. 
+
+```
+// set navigation
+$navigationModulesId = $this->setNavigation(null, 'Modules');
+$navigationBlogId = $this->setNavigation($navigationModulesId, 'MiniBlog', 'mini_blog/index', array('mini_blog/add',	'mini_blog/edit'));
+```
+
+At first, we fetch the id for the Modules navigation that you can see at the top of your backend. We do this because we want our module to come in that navigation tree.
+After that, we add a new navigation item. The parameters for this are explained below:
+
+* parentId: the id of the parent (in this case, the modules navigation tree, but this could also be our module itself if we have subnavigation, e.g. categories, comments, ...)
+* label: the label we should use for this navigation item
+* url: the action we should call if we select this item
+* selectedFor: in this case, we want our add and edit action to have the same navigation item as our index action, to do this, we add an array that contains these navigation actions.
+
+## Locale
+
+Fork already has a wide range of labels, messages, errors and actions pre installed. Though, it is possible you'll need some extras. To do this, we provide a locale.xml file that we use in our installer. To parse the data, we use a specific structure. In the screenshot below, you'll see that basic structure, followed by the xml for the mini blog module.
+
+![Locale xml](assets/locale.png)
+
+As you can see, we specify 2 children in the main node. These are backend and frontend (you can use one aswell). Within the application, for each module you have locale parameters, you create a new node with that module name. All the items within this node will be installed for the given module.
+
+## Database
+
+To add the requried database files, we need to create a file called install.sql in the /backend/modules/mini_blog/install/data folder. For the rest, this is pretty basic. It's just a dump of your table.
+
+```
+CREATE TABLE `mini_blog` (
+  `id` int(11) NOT NULL AUTO_INCREMENT,
+  `title` varchar(255) CHARACTER SET utf8 DEFAULT NULL,
+  `introduction` text CHARACTER SET utf8,
+  `text` text CHARACTER SET utf8,
+  `created` datetime DEFAULT NULL,
+  `edited` datetime DEFAULT NULL,
+  `publish` enum('Y','N') CHARACTER SET utf8 DEFAULT 'Y',
+  `user_id` int(11) DEFAULT NULL,
+  `language` varchar(3) CHARACTER SET utf8 DEFAULT NULL,
+  `meta_id` int(11) DEFAULT NULL,
+  `awesomeness` int(11) DEFAULT '0',
+  PRIMARY KEY (`id`)
+) ENGINE=MyISAM AUTO_INCREMENT=8 DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
+```
+
+## Info
+
+We also provide a info.xml with each module. This allows us to see some information about it. The main node is the <module> node. Below is a screenshot of the info.xml file for the mini blog.
+
+![Info xml](assets/info_xml.png)
+
+As you can see, we have several sections in the module node. The upper part(name - authors) is to give some information about the module itself. The lower part(events-cronjobs) is information that we can use for other modules. The events system is already explained in another article.