Post by VS Admin on Nov 23, 2012 15:25:58 GMT -8
Plugin keys give you the ability to store data on ProBoards' servers related to users, threads, posts, conversations, and messages. This guide is an in-depth look at plugin keys and how they function. If you are unfamiliar with the ProBoards v5 Plugins System, please read this topic first.
When to use a Plugin Key
Plugin keys should be used when you want to store data that you can access later. Here are some examples of scenarios that can benefit from using a plugin key:
Key Types
There are seven types of plugin keys that you should be aware of:
Creating a Plugin Key
Creating a plugin key is simple. Go to your forum's Admin Panel > Plugins > Build page. If you already have a plugin you want to add the key to, click on that plugin. If you have not yet created a plugin, click the "Create New Plugin" button to create one. You should now be on the Plugin "Settings" tab. Click on the "Keys" tab at the top. This page lists the keys that your plugin currently is using, and allows you to add more.
To add a key, you will first need to give it a unique name. Two different plugins can not share the same key names, so pick a unique name. For example, I might pick a unique name that combines my initials, the plugin name, and what the key will be used for. If I was making a zombie plugin I might call a user key "pc_zombie_plugin_user" -- the point is to be unique. Don't call a key "post" or "user" - you will run into problems when other plugin authors do the same thing.
Now that you have selected a name, pick a key type from the dropdown. You have the seven types described above to choose from. You can also add a note for yourself in the last field (this is optional).
Storing Data in a Plugin Key
To store data in a plugin key, you need to use JavaScript.
User Keys
To store data in a plugin key for the currently logged in user, the code is:
Super Forum Keys
To store data in a super forum key, the code is:
All other keys
Every other type of key requires two parameters to the set() function call. The first is the object id and the second is the value. For example, let's say you had a Post Plugin Key with the id pc_post_example. If you wanted to store data related to post id 153 in this key, the code would be:
Callback functions
You can be notified when a key value has been successfully set, or has failed to be set, by passing in event handlers like so:
Retrieving Data from a Plugin Key
On each page a user views, the plugin key data is only available for the content that is currently displayed on the screen. For example, if you are viewing a thread that has 5 posts, you will have access to any plugin keys for the thread and any key data for the 5 posts. You will not have access to plugin key data for posts in other topics. You will have access to any data stored in a super forum key.
Similar to how you store data in keys using JavaScript, you also use JavaScript to retrieve the value from a key.
User Keys
User keys store data related to the currently logged in user. Here is how you can retrieve data from a plugin user key:
Super Forum Keys
Super Forum keys store global information. Since there is no id associated with them, you can retrieve them like this:
All other keys
To retrieve data from other types of keys, you must provide a parameter to the get() function to specify the id that you want to retrieve. For example, if you have a Post Plugin Key with the id pc_post_example, you can retrieve the data for post id 153 like so:
Plugin Key Events
We offer a few different event bindings that you can use to change plugin key data when certain actions happen. These events are:
Using these events, you can set a plugin key's data only when the event listed has occurred.
Here is sample code on how to bind to a plugin key event:
You will notice that the above code did not specify the id of the thread that it wants to set this key value for. The plugin key system will detect that example_thread_key is a Thread Plugin Key, and when a thread is created the "Hello world" value will automatically be saved for the new thread.
Alternatively, the set_on() function allows you to specify an id parameter if you want. Here's an example of how you can manipulate the data for thread id 12 when a new post is made:
When to use a Plugin Key
Plugin keys should be used when you want to store data that you can access later. Here are some examples of scenarios that can benefit from using a plugin key:
- Create a "Like" system (v5 comes with one for posts, but you could create one for Threads, Conversations, etc)
- Storing user preferences. For example, you could have a plugin that collapses / expands categories. A plugin key could store the user's preference to have a category expanded or collapsed.
- Zombie Outbreak Plugin! In this plugin preview video, we showed how a plugin could be used to change another user's avatar on the forum. Using a plugin key we were able to identify which users were turned into zombies and which were not.
Key Types
There are seven types of plugin keys that you should be aware of:
- Thread - Store data related to a specific thread. Whenever the thread is displayed on the screen, the plugin key data will be available to access.
- Post - Posts are the messages inside of thread. Post keys store data related to a specific post.
- Conversation - Stores data related to a specific conversation. A conversation is like a thread, except between only specific people.
- Message - A message is the individual message inside of a conversation, similar to how posts are inside of threads.
- Private User - This key will store data related to a user on the forum. The key data is only accessible by the user themselves. Use this key to store a member's preferences, since the data stored in the key only applies to this user and not anyone else.
- Super User - A super user is a special type of plugin key. Unlike a private user key (which stores data that only the current logged in user has access to), a super user key can store that is accessible by everyone on the forum. Whenever a user is displayed on the screen, their plugin key data will be available to access.
- Super Forum - A super forum is the only key that is loaded on every page, and is therefore suitable for storing information globally across your forum.
Creating a Plugin Key
Creating a plugin key is simple. Go to your forum's Admin Panel > Plugins > Build page. If you already have a plugin you want to add the key to, click on that plugin. If you have not yet created a plugin, click the "Create New Plugin" button to create one. You should now be on the Plugin "Settings" tab. Click on the "Keys" tab at the top. This page lists the keys that your plugin currently is using, and allows you to add more.
To add a key, you will first need to give it a unique name. Two different plugins can not share the same key names, so pick a unique name. For example, I might pick a unique name that combines my initials, the plugin name, and what the key will be used for. If I was making a zombie plugin I might call a user key "pc_zombie_plugin_user" -- the point is to be unique. Don't call a key "post" or "user" - you will run into problems when other plugin authors do the same thing.
Now that you have selected a name, pick a key type from the dropdown. You have the seven types described above to choose from. You can also add a note for yourself in the last field (this is optional).
Storing Data in a Plugin Key
To store data in a plugin key, you need to use JavaScript.
User Keys
To store data in a plugin key for the currently logged in user, the code is:
<script>
pb.plugin.key('key_name_here').set({ value: 'value' });
</script>Super Forum Keys
To store data in a super forum key, the code is:
<script>
pb.plugin.key('super_forum_key_name_here').set({ value: 'value' });
</script>All other keys
Every other type of key requires two parameters to the set() function call. The first is the object id and the second is the value. For example, let's say you had a Post Plugin Key with the id pc_post_example. If you wanted to store data related to post id 153 in this key, the code would be:
<script>
pb.plugin.key('pc_post_example').set({ object_id: 153, value: 'value' });
</script>Callback functions
You can be notified when a key value has been successfully set, or has failed to be set, by passing in event handlers like so:
<script>
pb.plugin.key('key_name_here').set({ value: 'value',
success: function() {
// code to be executed once the key has been successfully set
},
fail: function(error) {
// error.code will contain an error code id:
// 1 = value is too big
// 2 = server did not respond / general error
// 3 = this user does not have permission to change this key
// 4 = Invalid data received by the server
// error.reason will contain a friendly response from the server corresponding to the error code
}
});Retrieving Data from a Plugin Key
On each page a user views, the plugin key data is only available for the content that is currently displayed on the screen. For example, if you are viewing a thread that has 5 posts, you will have access to any plugin keys for the thread and any key data for the 5 posts. You will not have access to plugin key data for posts in other topics. You will have access to any data stored in a super forum key.
Similar to how you store data in keys using JavaScript, you also use JavaScript to retrieve the value from a key.
User Keys
User keys store data related to the currently logged in user. Here is how you can retrieve data from a plugin user key:
<script>
pb.plugin.key('key_name_here').get();
</script>Super Forum Keys
Super Forum keys store global information. Since there is no id associated with them, you can retrieve them like this:
<script>
pb.plugin.key('super_forum_key_name_here').get();
</script>All other keys
To retrieve data from other types of keys, you must provide a parameter to the get() function to specify the id that you want to retrieve. For example, if you have a Post Plugin Key with the id pc_post_example, you can retrieve the data for post id 153 like so:
<script>
pb.plugin.key('pc_post_example').get(153);
</script>Plugin Key Events
We offer a few different event bindings that you can use to change plugin key data when certain actions happen. These events are:
- thread_new - When a thread is created
- post_new - When a post is made
- post_quick_reply - When a post is made using the quick reply
- conversation_new - When a conversation is created
- message_new - When a reply to a conversation is made
Using these events, you can set a plugin key's data only when the event listed has occurred.
Here is sample code on how to bind to a plugin key event:
<script>
pb.plugin.key('example_thread_key').set_on('thread_new', 'Hello world');
</script>
You will notice that the above code did not specify the id of the thread that it wants to set this key value for. The plugin key system will detect that example_thread_key is a Thread Plugin Key, and when a thread is created the "Hello world" value will automatically be saved for the new thread.
Alternatively, the set_on() function allows you to specify an id parameter if you want. Here's an example of how you can manipulate the data for thread id 12 when a new post is made:
<script>
pb.plugin.key('example_thread_key').set_on('post_new', 12, 'New plugin data here');
</script>