Introduction

Chyrp has a really great hook and filter system that can be built upon really easily with extensions. However if you are new to php then you might have some issues looking where to start. Because of the small size of Chyrp's community every extension is valuable, so the more people that can make modules and submit to the extend section the better!

Set up

Today we are going to make a really simple lorem ipsum module that you can use to dynamically insert lorem ipsum content into your website just by writing [ipsum] in a post, really useful when designing the page layout. We are going to be using the Lorem Ipsum Api to generate the text. First and foremost is the directory structure.

ipsum
    info.yaml
    ipsum.php

This is the bare essentials of what is required to get the plugin working. We have an outer directory named ipsum, and in it a file named ipsum.php. You can name the plugin whatever you want, but these two files must be named the same. Info.yaml contains information about the plugin showed on the install screen, like the plugin name.

Info.yaml

This file is formatted according to the Yaml file format. The basics of it are pretty simple.

name: Ipsum
url: http://chyrp.net/
version: 1.0
description: Generates Lorem Ipsum content.
author:
  name: the Chyrp Team
  url: http://chyrp.net/

The name of the plugin is ipsum, and the url is a link to the plugin page, which might be a blog entry by you about making the plugin. This will be the url that a user goes to if they click on the name of the module. If you don't have a plugin page feel free just to link to chyrp.net. Version is the version of the plugin, if its 1.0 it won't be shown but if you change the version to 2.0 it will be displayed on the extend screen as v2. The description will be shown when you click the little i icon next to a module on an extend screen. Author name will be displayed next to the plugin name on the extend screen in small print, and url is the link clicking the author name will take you too. Generally this is your personal blog.

ipsum.php

This is the main deal, the part that makes your plugin tick. Lets see the full code first, and then I'll explain what it means.

addAlias("markup_text", "ipsum");//whenever the filter markup_text is run we run the function ipsum
           $this->addAlias("markup_post_text","ipsum");
           $this->addAlias("preview", "ipsum");
           $this->addAlias("preview_post", "ipsum");
        }
        public function ipsum($text) {
            return str_replace('[ipsum]', file_get_contents('http://loripsum.net/api'), $text);
        }
    }

Thats not too bad, is it? Lets get the basics out. We have an opening php symbol and then this line

class Ipsum extends Modules {

This line declares this file is a module and that it is a module with a directory of ipsum. The directory part of this, Ipsum, should always be the CamelCased name of your directory. So if your directory was cool_module this line would be

class CoolModule extends Modules {

Next we have a couple of functions, then we close the bracket started on the second line. Easy peasy right? Lets look at the two functions inside this class.

        public function __init() {
           $this->addAlias("markup_text", "ipsum");
           $this->addAlias("markup_post_text","ipsum");
           $this->addAlias("preview", "ipsum");
           $this->addAlias("preview_post", "ipsum");
        }
        public function ipsum($text) {
            return str_replace('[ipsum]', file_get_contents('http://loripsum.net/api'), $text);
        }

Note that both functions are public functions, as opposed to just plain functions. The public allows the functions to be called from external files, and is always needed.
    First, the __init function. This function is a Magic Method, which is a whole other can of worms. Just know that this function is called whenever the ipsum.php file is loaded. In this function we are adding aliases, which basically means that whenever the a certain filter is called we run a function. The name of the filter is specified by the item in the parentheses before the comma, the function what after the comma. In this instance we are adding several aliases. Whenever the post is previewed, shown from a list of posts, or shown individually we run the function ipsum, which coincidentally is the name of our second function. The function that you specify from an alias should always exist in the same file, and should be a public function.
    The ipsum function accepts an argument - $text. This value is the content of the post that is being viewed. We need to check if $text has [ipsum] in it, and if so replace the [ipsum] with some randomly generated text and return the modified text, which is basically what we do in the next line. The return of the modified text is REQUIRED. If you don't return a value, all your posts will show up blank. So what exactly are we returning? First, we get the content from http://loripsum.net/api using file_get_contents. This page will automatically generate the content for us, so we just need to grab what it feeds us. To add in the ipsum, we do a str_replace on the post. What the str_replace does is if it finds [ipsum] in the post content ($text) then replace it with what we get from http://loripsum.net/api. If [ipsum] isn't found, then what we return is the same as what we get.
Thats it! Hope this was useful! If you make a module we'd love if you submit it to our extend section for others to use.

Feel free to download the module if you need an example.