资源说明：Widgets for MojoMotor
# MojoBlocks for MojoMotor v1.2.4
MojoMotor is an open source add-on for [MojoMotor](http://ellislab.com/mojomotor) that allows you to create editable "blocks" for special content. Got a headline that needs to be an h3? Use the H block. Need to add a Twitter stream? Use the Twitter stream block. With over 13 ready to use blocks and an API to easily create more, MojoBlocks is your Swiss Army knife for MojoMotor.
## Installation
Installation consists of just dropping the mb folder into **system/mojomotor/third_party**. That’s it! The necessary database table is created automatically. You are now ready to use MojoBlocks.
MojoBlocks automatically creates a table if it doesn’t find one when it installs. If for some reason your setup doesn’t allow MojoBlocks to do this, you can do it manually with this MySQL command:
CREATE TABLE `mojo_blocks` (
`id` int(9) NOT NULL AUTO_INCREMENT,
`created` datetime DEFAULT NULL,
`updated` datetime DEFAULT NULL,
`block_reach` enum('local','global') DEFAULT 'local',
`block_type` varchar(50) DEFAULT NULL,
`block_id` varchar(100) DEFAULT NULL,
`block_content` blob, `page_url_title` varchar(100) DEFAULT NULL,
`layout_id` int(5) DEFAULT NULL,
`tag_settings` blob,
`cache` longblob,
`cache_process` varchar(200) DEFAULT NULL,
`cache_expire` varchar(60) DEFAULT NULL,
`tag_data` blob,
PRIMARY KEY (`id`) ) ENGINE=MyISAM DEFAULT CHARSET=utf8;
_Note: If you are using something other than "mojo" as your table prefix, make sure to change it in the above code so it matches the rest of your MojoMotor tables._
## Basic Usage
A MojoBlock is created using a similar syntax to region MojoMotor regions. Here is what you need to tell MojoBlocks:
* The ID of the block. This is something unique that you make up
* The type of block you want to create
* Whether you want to create a local or global block
Here is an example of a local Vimeo block in the layout:
{mojo:mb:block type="vimeo" id="home_video"}
Here is an example of a global Vimeo block in the layout:
{mojo:mb:block type="vimeo" id="home_video" reach="global"}
As you can see, the only difference is the global block has a class of **mojoblock\_global\_region** instead of **mojoblock\_region** and the MojoBlocks tag has the reach="global" parameter set. Other than that you need to put the block slug in the name parameter of the div and the type parameter of the tag. You also need to put the id you create for the block in the id parameter of the div, and the id parameter of the tag. The reach parameter is required in the tag only for a global block.
Once that is in place, that’s all you need to do. Refresh the page, and you’ll see a block block area. Local blocks are in blue, global blocks will show up in green. Click on the block, and you’ll get the update interface.
Enter the necessary information, click submit, and you've created your first block!
## Setting Defaults
Every block comes with different variables to provide the block with custom data. For the Twitter block, for example, you provide the desired user’s Twitter handle, and the number of tweets you want to show. For the YouTube block, you provide the video ID (or URL) and the height and width you want the embed to be.
In some cases, however, you want to pass information directly to the block without having to worry about the person editing the site’s content either being confused by it in the editor or worse: changing the value and damaging the design.
That’s why MojoBlocks allows you pass data directly into the block in the code. Once you have passed that data, it simply won’t show up in the editor.
Let’s take a look at a simple example:
We have a header, but we want it to be an H1 tag. The H block allows you a drop down to choose H1-H6, but why would we want someone to change that?
To make this foolproof, we simply find the variable for the H tag number in the documentation, and insert it into the tag as a parameter.
## Working With Layouts
Very simple blocks don’t require customized output. A YouTube embed is a YouTube embed give or take a few parameters. An H1 tag is an H1 tag.
However, some tags require a higher degree of control. You may not want to show how long ago a tweet was, but you may want to show what software the tweet was sent with.
That’s why some blocks support MojoMotor layouts and can pass variables to them. To create a new layout for a block, make a new layout just like you would any other one in MojoMotor.
After creating your new layout, refresh the page, and edit you block details. You’ll see a list of layouts to choose from, with “Block Default” being the top choice. Choose the layout you just created, and the data from the block will be passed to that layout.
Each block that supports layouts has a list of variables in its documentation. Each single variable can be accessed by putting the variable in curly brackets. For example:
{user_name}
For layouts that have multiple instances of something, like multiple tweets, you can cycle through them by using an opening and closing bracket:
{tweets}
{text}
Posted {how_long_ago}
{/tweets}
Layouts give you an easy way to make sure that you can take the data from a more complex block and format it the way you need to.
## Blocks
MojoMotor comes with the following block:
| Block |
Description |
| Evernote |
Displays a "save to Evernote" button. |
| Facebook Like |
Displays a Facebook like button. |
| Flickr |
Show Flickr images from a user or set. |
| H |
Show an H tag with text content. |
| HTML |
Render HTML. |
| Pages |
Display pages in a list with access to content. |
| RSS |
Show content from an RSS feed. |
| Sub Page |
Display sub pages from a given page. |
| Text |
Display text. |
| Twitter Button |
Display a tweet button. |
| Twitter Search |
Display twitter search results. |
| Twitter User |
Display tweets from auser. |
| Vimeo |
Display a Vimeo embed. |
| YouTube |
Display a YouTube embed. |
Most of these block types are self-explanatory, but a few have some specific instructions.
### RSS Block
The RSS block utilizes layouts. Below is a table of variables available in your layout.
#### Single Variables
Below are a table of single variables available to the template.
| Variable Slug |
Description |
| {feed_title} |
Title of the feed |
| {copyright} |
Feed Copyright |
| {description} |
Description of the feed |
| {encoding} |
Feed character encoding |
| {total_items} |
Total number of items found in the feed |
| {language} |
Language of the feed (ex: "en" for English) |
| {feed_url} |
URL of the feed |
#### {items}
RSS items that are found are put into the RSS item variable pair. Also included are link URLs to bookmark the item on social media sites.
{items}
{example_variable}
{/items}
| Variable Slug |
Description |
| {title} |
Item title |
| {description} |
Item description |
| {content} |
Item content |
| {content_plain} |
Item content with tags stripped (except for strong and em tags) |
| {preview} |
A short preview of the content with tags removed |
| {permalink} |
The permalink to the item |
| {date_posted} |
Date the item was posted |
| {id} |
Item ID |
| {author_name} |
Name of the item author (if available) |
| {author_email} |
Email address of the author (if available) |
| {author_link} |
Author link URL (if available) |
| {blinklist_link} |
Link URL to bookmark on Blinklist |
| {blogmarks_link} |
Link URL to bookmark on Blogmarks |
| {delicious_link} |
Link URL to bookmark on Delicious |
| {digg_link} |
Link URL to bookmark on Digg |
| {furl_link} |
Link URL to bookmark on Furl |
| {magnolia_link} |
Link URL to bookmark on Magnolia |
| {newsvine_link} |
Link URL to bookmark on Newsvine |
| {reddit_link} |
Link URL to bookmark on Reddit |
| {segnalo_link} |
Link URL to bookmark on Segnalo |
| {simpy_link} |
Link URL to bookmark on Simpy |
| {spurl_link} |
Link URL to bookmark on Spurl |
| {wists_link} |
Link URL to bookmark on Wists |
### Twitter User Block
The Twitter User block utilizes layouts. Below is a table of variables available in your layout
Below are a table of single variables available to the template.
| Variable Slug |
Description |
| {name} |
Name of the Tweeter |
| {id} |
ID of the Tweeter |
| {screen_name} |
Twitter handle of the Tweeter |
| {description} |
Description of Tweeter from their profile |
| {lang} |
Language of the Tweeter (ie: en for English) |
| {followers_count} |
Number of followers the Tweeter has |
| {friends_count} |
Number of users the Tweeter is following |
| {listed_count} |
Number of lists the Tweeter appears in |
| {statuses_count} |
Number of tweets the Tweeter has posted |
| {profile_background_image_url} |
URL of the background image of the Tweeter’s profile |
| {favourites_count} |
Number of tweets the Tweeter has marked as their favorite |
| {profile_image_url} |
URL of the profile image of the Tweeter |
#### {tweets}
Contains data for the tweets retrieved by the block, including some basic information about the tweeter for use if necessary.
{tweets}
{example_variable}
{/tweets}
| Variable Slug |
Description |
| {text} |
Text of the tweet. |
| {tweet_url} |
Twitter URL to the tweet. |
| {how_long_ago} |
How long ago the tweet was posted (ex: "2 hours ago") |
| {text_no_links} |
Text of the tweet but without any hyperlinks for hashtags, @, etc. |
| {username_link} |
URL to the profile of the tweeter. |
| {id} |
ID of the tweet. |
| {retweet_count} |
Number of times the tweet has been re-tweeted. |
| {source} |
Program used to post tweet with hyperlink. |
| {in_reply_to_user_id} |
If applicable, the user ID of the tweeter that the tweet was in reply to. |
| {in_reply_to_status_id} |
If applicable, the status ID of the tweet that the tweet was in reply to. |
| {in_reply_to_screen_name} |
If applicable, the Twitter handle of the tweeter that the tweet was in reply to. |
| {user_screen_name} |
Twitter handle of the tweeter. |
| {user_name} |
Full name of the tweeter. |
| {user_url} |
URL from the profile of the tweeter. |
| {user_profile_image_url} |
URL to the profile image of the tweeter. |
## Developing Blocks
Blocks follow a simple structure that can be used to make very simple blocks to much more complicated ones. The following is an overview of the basic structure of a block.
Each block has a **slug**, or short name with no spaces in all lower case. In this case, our slug is h for the H tag block. It could "twitter" or "bananas" or anything you want.
Each block is a folder with the same name as the slug, a file that is named block.block_slug.php, and a 32×32 icon named icon.png. For example:
- h
- block.h.php
- icon.png
Save this folder in the third_party folder in the mb MojoBlocks addon folder.
A block is a class that follows a basic structure. Here's an [example](https://gist.github.com/adamfairholm/1335663).
#### Class Variables
You must provide the following class variables for the block class:
| Variable Slug |
Description |
| block_name |
A name for the block (you don’t need to include the word “Block”) |
| block_version |
A version for your block (ex: “v1.0”) |
| block_slug |
The slug for your block |
| block_desc |
A short, one line description of what your block does |
| block_fields |
The information your block needs. For more information, see Block Data Types |
#### Sending Output With render()
**render()** is the only function a block is required to have. It is provided with an associative array of saved data for the block for you to parse and use as you see fit. Just remember to return your output and not echo it.
#### Using CodeIgniter
MojoMotor is build on [CodeIgniter](http://ellislab.com/codeigniter), which means you can use all the CodeIgniter libraries and goodies that it offers. For full documentation on CodeIgniter, see the [CI User Docs](http://ellislab.com/codeigniter/user-guide/). To get a copy of the CI super object, use the following code in your constructor and reference objects as
$this->block:
$this->block =& get_instance();
#### Block Data Types
One of the best things about MojoBlocks is you get a built-in method to save data for a block! Neat-o!
To define that data, you need to create a class variable called
block_fields. Each key needs to be the slug of the field, and each node needs to be an array of configuration. Here’s an example of a field from the Vimeo block:
'width' => array(
'label' => "Width of video",
'validation' => "trim|numeric"
)
The following options are accepted as field configuration options:
| Option |
Description |
Value |
| label |
Label for the editor form |
Any text string |
| validation |
A validation string |
See CodeIgniter docs for acceptable values. Separated by a pipe character |
| type |
The type of field. |
Defaults to “input”. Can be any one of the values detailed in “Data Types” below |
| values |
For use with the dropdown data type |
As associative array of possible values |
MojoBlocks can save certain types of data and display the proper form for input. This can be set as an array node named type which is assumed to be input if it isn’t set.
The following are the current data types that MojoBlocks supports:
| Type Slug |
Description |
| input |
This is the default data type and is just a normal form input |
| dropdown |
This is a simple drop down select box. It is populated by the values array |
| textbox |
This is a multi-line textbox |
| layout |
This creates a dropdown that gives the user an option to choose an external layout. |
#### Caching Data
MojoBlocks comes with two built in caching options. To use either, you need to add three class variables to your block:
var $cache_output = true;
var $cache_expire = '+1 hour';
var $cache_data = '';
| cache_ouput |
A boolean variable that controls whether the block will be cached or not. Other cache variables are ignored if this is set to FALSE. |
| cache_expire |
A string of how far in the future the cache should expire. This string needs to be readable by strtotime() |
| cache_data |
MojoBlocks uses this to store cache data. Should be set to an empty string |
The simplest way to cache a block is to simply cache the entire block output. If you have added the three variables above, congratulations! You have just cached the block output and it will be refreshed in the interval of time you have specified.
Sometimes, however, you don’t want to simply cache the entire output of a block. Sometimes, you want to cache something like an API data call so variables that are being calculated based on current conditions (such as how long ago a tweet was) can still be used.
To cache a single function in a block, just name it cache\_data\_call. All you need to do is check for the cache\_data variable and return the data that you want cached if the cache is empty. For example:
function cache_data_call($block_data)
{
if ($this->cache_data) {
return $this->cache_data;
} else {
// Return data to be cached
}
}
Make sure you do not serialize arrays or objects you are returning yourself, or else MojoBlocks will not know to unserialize it before giving it to your render function.
English
