Tutorial for Keys and Saving Data in Proboards
Aug 17, 2015 1:52:12 GMT -8
Matej, Chris, and 4 more like this
Post by P̌̓aͧś̀t̀u͒le͆o͂2̀3̃̓ on Aug 17, 2015 1:52:12 GMT -8
If you work with Javascript, it is all about variables. They are the reason we can automate and create
tasks. If you are new to Keys, Cookies, or Web Storage; please take the time to read this post.
Cookies:
Cookies were the original data saver that caught on. Anymore, cookies are used to save information
locally on a small scale as a single string of text. Cookies have a more complicated syntax. The
maximum amount of data an entire site can store should be limited to 20 cookies with a total of all
cookies together not exceeding 4kb. Although the limit is different for every browser.
With the invention of Jquery Cookie, other data types such as Arrays and Objects can be used with
Jquery's special syntax.
*More Information
msdn.microsoft.com/en-us/library/ms178194.aspx
Document Cookies: www.w3schools.com/js/js_cookies.asp
Jquery Cookies: github.com/js-cookie/js-cookie
Web Storage:
This is the HTML5 (newer) way to store data. It can store large amounts of data, around 5mb with easy
syntax. Information can be saved temporarily with Session Storage, or Semi-Permanently with Local
Storage.
*More Information
www.w3schools.com/HTML/html5_webstorage.asp
Keys:
This is the ProBoards way to save data. There are 7 Key types to choose from, and that might be a
little scary. But they were invented to decrease loading times and decrease the strain on ProBoards.
Each type is used in different scenarios, so it is important to choose the right key type for the job.
Super Forum Keys store 32kb of data. Other Keys are 4kb. This data is available to guests, users, and
staff. (With the exception of Tapatalk and other Javascript disabling situations where it is not
loaded.) But it also can be customized to exclude any specific members, guests, or users in general.
This data can also be tied to specific accounts no matter where they log in at. Private Keys can be
completely secure from everyone but the logged in user.
*More Information From Build Plugin
All keys except super forum keys have up to 4,000 bytes of storage space per item the key is applied
to (for example, each user for a super or private user key has 4,000 bytes of storage). Super Forum
Keys have up to 32,000 bytes of storage space. It is recommended that you use as few keys as possible
since eash forum is limited to *the amount of keys they start out with or purchase. ProBoards
recommends using a JSON hash to store multiple key-value pairs instead of creating many keys.
What Should I Use:
Does the data require access from multiple computers for the same account? USE KEYS
Cookies and Storage save onto your local device. If you moved devices, this data would no longer
be accessible to you. Keys store data on the server. This means that it will work for your entire
forum. Not just for a single device.
Are you saving colors, images, autoform, and other non-essential data?
-Are you saving an array or object? USE WEB STORAGE (stringified)
-Are you saving a sentence or word? USE COOKIES
Why Use Both:
You should support Web Storage and Cookies.
See if Web Storage is supported and use it, if not use Cookies.
Most users will never clear their cookies, however some users and optimization programs remove cookies
with your temporary internet files. That is why web storage is slightly safer. But older device
software will not support web storage, so cookies make it reliable.
Types of Keys:
Thread - Store data related to a specific thread. Whenever the thread is loaded on the page, 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. This also allows you to write to other users' keys who are present on the
page. It also limits each user to their own individual 4kb data limit.
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.
*More Information
support.proboards.com/thread/433198/all-plugin-keys
Creating A 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. Type in a title and description and click ok. 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. I would abbreviate the plugin name with a couple letters and
add key to the end. You should never name a key or variable a word that can be found in the
dictionary. Some third party scripts and authors will do this.
Now that you have selected a name, pick a key type from the dropdown. You have the seven types to
choose from. You can also add a note for yourself in the last field. I wouldn't add
a note unless you are working with multiple keys.
Which Key Should I Use:
Different key types could be used to solve the same problem. There are many ways you can solve one
problem, and only a few wrong ways.
Although it can solve most problems, a Super Forum key should only be used as a last resort. This is
because they are prone to security risks being written and accessed by everyone.
A Private User Key should be used when possible. If you need to share data, this is not the case.
Anything you want done in threads should use a Thread or Post Key. If you need to attach information
to specific posts, you should use the Post Key. A Thread Key should also be able to accomplish what a
Post Key should do, but it will be accessible on all pages of the thread, not just the page the post
is located on.
These principles apply to the Conversation and Message Keys, respectively, as well.
A Super User Key can be used to store local data for every user and also allow other users to see that
data. This also allows you to write on another users' data if "their data" is present on the page you
are viewing. User data can be loaded on any page using the pb.member.select() dialog initiated by the
current user.
Writing to Keys:
Super Fourm Key and Private Keys
Where 'value' is your string, number, array, object etc.
All other keys need an object Id.
When leaving out the object_id, Proboards will make an educated guess on where it should be saved.
When adding the id, it will save to the user id, post id, thread id, conversation id, or message id.
Leaving the object_id out when using Conversation and Thread Keys is acceptable because ProBoards will assume
the current thread or conversation you are in as the default id.
Callback Functions:
If you want a function or code to run after you set a key, or if you want to detect for errors in the
key write, you can use the built in callback functions.
*More Information
www.proboards.com/developer/js/class/key#set
support.proboards.com/thread/433198/all-plugin-keys
#Note that this guide uses fail: as the error code callback but fail: will NOT work, error.reason is now error.message, and the code id's are wrong.
Common Reasons For Error Codes:
The most common reason a key won't save is because the user has been logged out. This will then assume that you are not logged in and won't let you do anything.
The second most common would be a 32 permissions error. This usually occurs when a plugin either doesn't have plugin key options enabled under the manage section, or the plugin has them set to staff only. Then when a user tries to use a key, they will receive this error because they are not staff. This happens a lot with new plugin developers not adding the key permissions control and when admins block a user from a key.
An error code 16 will often appear with post/message keys because their limit can be easily exceeded. This means that nothing else can be added to the key because the character limit of 4000 would be exceeded.
An error code 64 is commonly attributed to a case where a key used the .push/pop/shift/unshift commands and the data in the key is not an array.
You will rarely see an error code 1 or 2 and not much information is known about them. Usually refreshing your page or logging back in will resolve this issue.
Other Key Write Commands:
Set is the basic type of key saving method, it automatically overwrites any previous value with a new
one.
Here are some of the other methods, all of them follow the same general syntax.
Prepend - Adds a string or number to the beginning of what value is already stored
Append - Adds a string or number to the end of what value is already stored
Increment - Increases the keys value if it is an integer
Decrement - Decreases the keys value if it is an integer
Push - If the key is an array, adds the item(s) to the end
Pop - If the key is an array, removes the last item(s) from the key and returns them
Unshift - If the key is an array, adds the item(s) to the front of the array
Shift - If the key is an array, removes the first item(s) from the key and returns them
*More Information
www.proboards.com/developer/js/class/key
Setting On Events:
You may also set keys on certain events. This is through the Set_On command. You can set a key using
these events:
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
thread_edit - When the thread's first post is edited
post_edit - When a post is edited that is not the first post of a thread
Example:
But perhaps you want to use a post key and want to save to a different post then the one you created.
12 is the id of a different post.
*More Information
support.proboards.com/thread/433198/all-plugin-keys
Understanding the Key:
can_read([object_id]) - Check if the key can be read for the specified object_id
can_write([object_id]) - Check if the key can be written for the specified object_id
type() - Returns the numeric code of what type the key is
*More Information
www.proboards.com/developer/js/class/key
Key Permissions:
Key permissions default to read by everyone, and write by staff only.
This can be changed in the manage section by adding the Key Permissions field under the User Interface
tab. This is important to add for the user to adjust and be able to block certain groups from access.
This could help ban specific users as well.
*More Information
support.proboards.com/post/5661258
Getting Key Data:
get() - Returns the key's data based on what the page has loaded recently
Example:
If you would like to specify an object_id you can simply put
Having Fresh Key Data:
The moment data is loaded, the data is now obselete. Any number of other members or staff could save a
new value to the key without you even knowing. This is because polling is not allowed on ProBoards.
Polling slows down network bandwidth and is against ProBoards' Terms of Service. (TOS)
However there are a few ways to keep fresh data.
Some Creators have found it easy to create a Countdown Timer from when the page first loads, to when
you can no longer set the key for security reasons. Someone who keeps the tab open for a month could
easily overwrite good data with old and outdated data without knowing it.
pb.member.select() is a dialog that allows the currently logged in user to search for other users by
name, this also returns that users id and up-to-date key data.
Some other ajax calls (loading data from the server) may also update your key's data, such as the search
bar, pagination, or the shoutbox.
This problem has only been solved by the invention of Push, Pop, Unshift, and Shift.
No matter how many people push/pop/shift/unshift on a key, none of the data will overwrite itself.
However there is a problem with these functions that make them hard to work with.
Removing data from the middle of the array is problematic.
You must remove all of the entries between the beginning (or end) and the item you want removed, and
then add all of the data you removed (that you didn't want deleted) back into the key.
You may also elect to removing all of the items in the key with shift/pop and then only push/unshift the values you need back into the array. You still run into the problem of not having loaded up-to-date information before you add to the key.
In some cases I have been able to push a placeholder into the key to receive up to data information. Then I remove the placeholder, evaluate what has changed in the key since page load, and then continue my operation or abort it based on whether anything important has changed.
Example:
Find what position in the array your data is in that you want
removed. Removing all of the data to that point using the num_items flag for pop or shift.
Then while using the values: flag with the returned array (that you got from pop or shift), add the old values back (without the value you dont want), using push or unshift.
*More Information
www.proboards.com/developer/js/class/key
Getting the Object_Id:
You can get your Object_Id from just about anywhere. It could be the id of the row holding each post.
It could be in the window.location.href (current url) for the user's profile page, or the thread id.
But most of the time you just want your own id. You can find this in the pb.data hash. The current
logged in user id is stored in pb.data('user').id variable. Using this as the object_id will make setting your
key simple.
The pb.data Hash:
Alot of good data can be found in this hash. This will assist you when retrieving data from the
current page. The serverDate can help with the date object. It will tell you if the user is a guest,
staff, in a group/what group, smilies, current status, name, id, birthday (if saved), theme, username,
and more depending on the page loaded. Different pages may have different data hash values available.
Typing in proboards.dataHash in the console will allow you to easily view the structure by returning the object.
Example of pb.data():
Limitations To Keys Include:
Codes which use plugin keys to store unrelated data like sharing a single plugin key between multiple
UNRELATED plugins. Sharing keys themselves is acceptable.
Setting a key on page load is prohibited.
Keys must be set by a user initiated action *that can reasonably be assumed to create an additional
server request. You should not bind to a button that is already in existence unless it's obvious the
user knows a key will be set relating to the plugin at hand. This means you should not bind to existing
submit buttons. This is where to use the set_on commands.
*More Information
www.proboards.com/developer-guidelines
support.proboards.com/post/6319142
support.proboards.com/thread/431718/plugin-keys
The Plugin System:
Plugins are an easy way to install custom codes on a ProBoards forum. A plugin generally consists of
Header & Footer codes along with customizable settings. When a developer provides a plugin to a forum
staff member, they can download the plugin file (*.pbp files), and import it directly into their
forum. When the plugin is enabled, it will automatically insert Header & Footer codes into the
correct places on the forum. There is no need for the forum staff to deal with the coding.
Plugins can offer very easy ways for forum staff to customize various options without needing to touch
the actual HTML / JavaScript / CSS code. Plugin authors are given tools to easily build a custom User
Interface where forum staff can input settings for the plugin. These settings are stored in variables
that can then be accessed by the Header & Footer codes of the plugin.
*More Information
support.proboards.com/thread/433194/overview-proboards-v5-plugin-system
support.proboards.com/post/4975826
ProBoard Events:
These can be used to run functions based on user interaction.
afterSearch: will run after an auto-search (note: this occurs when a board or thread page are first
loaded as well) It also fires after a pageChange event, removing the need for pageChange
columnSort: will run when the user clicks on a column title to sort a list
moreActivity: will run when the 'Show More' link is clicked on a user's activity page
moreNotification: will run when the 'Show More' link is clicked on a user's notifications page
pageChange: will run when paginating. Use afterSearch instead unless you are displaying something on the calendar page. (since it can include pages but does not have a search bar)
Each entry also has an accompanying event that will only run once:
afterSearchOne
columnSortOne
moreActivityOne
moreNotificationOne
pageChangeOne
Additional Events have been added by Yootil
*More Information
support.proboards.com/thread/473870/proboards-events
Plugin Main Components:
There are 3 main components you can add in a plugin.
JS, Global, and CSS.
You can have 2 JS components currently. This will hold direct Javascript code that will be loaded as
an external file for speed, and so that it stays in memory. This is keeping you from downloading it
every time you navigate a page, saving bandwidth.
The CSS component moves your css to an external stylesheet for speed and organization much like the JS
component.
The Global component adds a header and footer component that will load on every page. The footer is
good for starting functions after most DOM elements have loaded, but before some images have finished
loading. (for speed) The header is good for extra space for loading css and or scripts.
*More Information
support.proboards.com/thread/460256/adding-features-plugin-using-components
Plugin User Interface:
The User interface allows you to get admin specific variables without them having to go into the
source code. This makes plugins easy to manage, maintain, and automate.
*More Information
support.proboards.com/thread/460252/giving-plugin-user-interface
Plugin Images:
You can also pack images with your plugin and set them as variables throughout.
*More Information
support.proboards.com/thread/460254/uploading-images-use-plugin
Plugin Examples:
These links show a plugin from start to finish.
support.proboards.com/thread/433768/video-plugin-tutorial
support.proboards.com/thread/433716/video-plugin-1
Exporting and Sharing a Plugin:
Plugins can be exported for backup or sharing purposes.
They can also be submitted to the library so that it can be easily found by users looking to add nice
features to their forums.
*More Information
support.proboards.com/thread/460258/exporting-plugin-use
Plugin Code Restrictions:
Codes that make requests to ProBoards' servers except through methods explicitly allowed for by
ProBoards (such as plugin set() functions). Examples of prohibited codes include using <iframe> tags
to access forum content, or making AJAX requests to ProBoards' forums. Not that you can't use iframe
tags to access other web sites not on the ProBoards' domain.
Codes that affect the placement of advertisements on any ProBoards forum, except those specifically
authorized by ProBoards.
Codes which cause automatic redirects on page load to a new URL.
Codes which rely on external code to work properly. Note that using external data is acceptable, so
long as that data is loaded asynchronously.
You may not use another's code in your plugin without permission. Doing so and claiming it as your own
will result in a serious warning and possibly a ban.
You may not add a visual copyright to forums that utilize your plugin; however, you may add a
copyright to the source code of the plugin.
Your plugin must not be malicious in any way.
As always follow forum rules and ProBoards' Terms of Service
*More Information
www.proboards.com/developer-guidelines
support.proboards.com/thread/433518/plugin-creation-rules
www.proboards.com/tos
tasks. If you are new to Keys, Cookies, or Web Storage; please take the time to read this post.
Cookies:
Cookies were the original data saver that caught on. Anymore, cookies are used to save information
locally on a small scale as a single string of text. Cookies have a more complicated syntax. The
maximum amount of data an entire site can store should be limited to 20 cookies with a total of all
cookies together not exceeding 4kb. Although the limit is different for every browser.
With the invention of Jquery Cookie, other data types such as Arrays and Objects can be used with
Jquery's special syntax.
*More Information
msdn.microsoft.com/en-us/library/ms178194.aspx
Document Cookies: www.w3schools.com/js/js_cookies.asp
Jquery Cookies: github.com/js-cookie/js-cookie
Web Storage:
This is the HTML5 (newer) way to store data. It can store large amounts of data, around 5mb with easy
syntax. Information can be saved temporarily with Session Storage, or Semi-Permanently with Local
Storage.
*More Information
www.w3schools.com/HTML/html5_webstorage.asp
Keys:
This is the ProBoards way to save data. There are 7 Key types to choose from, and that might be a
little scary. But they were invented to decrease loading times and decrease the strain on ProBoards.
Each type is used in different scenarios, so it is important to choose the right key type for the job.
Super Forum Keys store 32kb of data. Other Keys are 4kb. This data is available to guests, users, and
staff. (With the exception of Tapatalk and other Javascript disabling situations where it is not
loaded.) But it also can be customized to exclude any specific members, guests, or users in general.
This data can also be tied to specific accounts no matter where they log in at. Private Keys can be
completely secure from everyone but the logged in user.
*More Information From Build Plugin
All keys except super forum keys have up to 4,000 bytes of storage space per item the key is applied
to (for example, each user for a super or private user key has 4,000 bytes of storage). Super Forum
Keys have up to 32,000 bytes of storage space. It is recommended that you use as few keys as possible
since eash forum is limited to *the amount of keys they start out with or purchase. ProBoards
recommends using a JSON hash to store multiple key-value pairs instead of creating many keys.
What Should I Use:
Does the data require access from multiple computers for the same account? USE KEYS
Cookies and Storage save onto your local device. If you moved devices, this data would no longer
be accessible to you. Keys store data on the server. This means that it will work for your entire
forum. Not just for a single device.
Are you saving colors, images, autoform, and other non-essential data?
-Are you saving an array or object? USE WEB STORAGE (stringified)
-Are you saving a sentence or word? USE COOKIES
Why Use Both:
You should support Web Storage and Cookies.
See if Web Storage is supported and use it, if not use Cookies.
Most users will never clear their cookies, however some users and optimization programs remove cookies
with your temporary internet files. That is why web storage is slightly safer. But older device
software will not support web storage, so cookies make it reliable.
Types of Keys:
Thread - Store data related to a specific thread. Whenever the thread is loaded on the page, 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. This also allows you to write to other users' keys who are present on the
page. It also limits each user to their own individual 4kb data limit.
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.
*More Information
support.proboards.com/thread/433198/all-plugin-keys
Creating A 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. Type in a title and description and click ok. 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. I would abbreviate the plugin name with a couple letters and
add key to the end. You should never name a key or variable a word that can be found in the
dictionary. Some third party scripts and authors will do this.
Now that you have selected a name, pick a key type from the dropdown. You have the seven types to
choose from. You can also add a note for yourself in the last field. I wouldn't add
a note unless you are working with multiple keys.
Which Key Should I Use:
Different key types could be used to solve the same problem. There are many ways you can solve one
problem, and only a few wrong ways.
Although it can solve most problems, a Super Forum key should only be used as a last resort. This is
because they are prone to security risks being written and accessed by everyone.
A Private User Key should be used when possible. If you need to share data, this is not the case.
Anything you want done in threads should use a Thread or Post Key. If you need to attach information
to specific posts, you should use the Post Key. A Thread Key should also be able to accomplish what a
Post Key should do, but it will be accessible on all pages of the thread, not just the page the post
is located on.
These principles apply to the Conversation and Message Keys, respectively, as well.
A Super User Key can be used to store local data for every user and also allow other users to see that
data. This also allows you to write on another users' data if "their data" is present on the page you
are viewing. User data can be loaded on any page using the pb.member.select() dialog initiated by the
current user.
Writing to Keys:
Super Fourm Key and Private Keys
pb.plugin.key('key_name_here').set({ value: 'value' });
Where 'value' is your string, number, array, object etc.
All other keys need an object Id.
pb.plugin.key('key_name_here').set({ object_id: 153, value: 'value' });
When leaving out the object_id, Proboards will make an educated guess on where it should be saved.
When adding the id, it will save to the user id, post id, thread id, conversation id, or message id.
Leaving the object_id out when using Conversation and Thread Keys is acceptable because ProBoards will assume
the current thread or conversation you are in as the default id.
Callback Functions:
If you want a function or code to run after you set a key, or if you want to detect for errors in the
key write, you can use the built in callback functions.
pb.plugin.key('key_name_here').set({ value: 'value',
success: function() {
// code to be executed once the key has been successfully set
},
error: function(error) {
// error.code will contain an error code id:
// 1 = Server did not respond / general error
// 2 = Invalid response
// 16 = The key has reached it's maximum length it can hold
// 32 = The current user does not have permission to save to this key
// 64 = Invalid data sent in regards to the data already present
// error.message will contain a friendly response from the server corresponding to the
error code
},
complete: function(){
// code to be executed after success and error have fired
}
});
*More Information
www.proboards.com/developer/js/class/key#set
support.proboards.com/thread/433198/all-plugin-keys
#Note that this guide uses fail: as the error code callback but fail: will NOT work, error.reason is now error.message, and the code id's are wrong.
Common Reasons For Error Codes:
The most common reason a key won't save is because the user has been logged out. This will then assume that you are not logged in and won't let you do anything.
The second most common would be a 32 permissions error. This usually occurs when a plugin either doesn't have plugin key options enabled under the manage section, or the plugin has them set to staff only. Then when a user tries to use a key, they will receive this error because they are not staff. This happens a lot with new plugin developers not adding the key permissions control and when admins block a user from a key.
An error code 16 will often appear with post/message keys because their limit can be easily exceeded. This means that nothing else can be added to the key because the character limit of 4000 would be exceeded.
An error code 64 is commonly attributed to a case where a key used the .push/pop/shift/unshift commands and the data in the key is not an array.
You will rarely see an error code 1 or 2 and not much information is known about them. Usually refreshing your page or logging back in will resolve this issue.
Other Key Write Commands:
Set is the basic type of key saving method, it automatically overwrites any previous value with a new
one.
Here are some of the other methods, all of them follow the same general syntax.
Prepend - Adds a string or number to the beginning of what value is already stored
Append - Adds a string or number to the end of what value is already stored
Increment - Increases the keys value if it is an integer
Decrement - Decreases the keys value if it is an integer
Push - If the key is an array, adds the item(s) to the end
Pop - If the key is an array, removes the last item(s) from the key and returns them
Unshift - If the key is an array, adds the item(s) to the front of the array
Shift - If the key is an array, removes the first item(s) from the key and returns them
*More Information
www.proboards.com/developer/js/class/key
Setting On Events:
You may also set keys on certain events. This is through the Set_On command. You can set a key using
these events:
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
thread_edit - When the thread's first post is edited
post_edit - When a post is edited that is not the first post of a thread
Example:
pb.plugin.key('example_thread_key').set_on('thread_new', 'Hello world');
But perhaps you want to use a post key and want to save to a different post then the one you created.
12 is the id of a different post.
pb.plugin.key('example_post_key').set_on('post_new', 12, 'New plugin data here');
*More Information
support.proboards.com/thread/433198/all-plugin-keys
Understanding the Key:
can_read([object_id]) - Check if the key can be read for the specified object_id
can_write([object_id]) - Check if the key can be written for the specified object_id
type() - Returns the numeric code of what type the key is
*More Information
www.proboards.com/developer/js/class/key
Key Permissions:
Key permissions default to read by everyone, and write by staff only.
This can be changed in the manage section by adding the Key Permissions field under the User Interface
tab. This is important to add for the user to adjust and be able to block certain groups from access.
This could help ban specific users as well.
*More Information
support.proboards.com/post/5661258
Getting Key Data:
get() - Returns the key's data based on what the page has loaded recently
Example:
pb.plugin.key('key_name_here').get();
If you would like to specify an object_id you can simply put
pb.plugin.key('key_name_here').get(153);
Having Fresh Key Data:
The moment data is loaded, the data is now obselete. Any number of other members or staff could save a
new value to the key without you even knowing. This is because polling is not allowed on ProBoards.
Polling slows down network bandwidth and is against ProBoards' Terms of Service. (TOS)
However there are a few ways to keep fresh data.
Some Creators have found it easy to create a Countdown Timer from when the page first loads, to when
you can no longer set the key for security reasons. Someone who keeps the tab open for a month could
easily overwrite good data with old and outdated data without knowing it.
pb.member.select() is a dialog that allows the currently logged in user to search for other users by
name, this also returns that users id and up-to-date key data.
Some other ajax calls (loading data from the server) may also update your key's data, such as the search
bar, pagination, or the shoutbox.
This problem has only been solved by the invention of Push, Pop, Unshift, and Shift.
No matter how many people push/pop/shift/unshift on a key, none of the data will overwrite itself.
However there is a problem with these functions that make them hard to work with.
Removing data from the middle of the array is problematic.
You must remove all of the entries between the beginning (or end) and the item you want removed, and
then add all of the data you removed (that you didn't want deleted) back into the key.
You may also elect to removing all of the items in the key with shift/pop and then only push/unshift the values you need back into the array. You still run into the problem of not having loaded up-to-date information before you add to the key.
In some cases I have been able to push a placeholder into the key to receive up to data information. Then I remove the placeholder, evaluate what has changed in the key since page load, and then continue my operation or abort it based on whether anything important has changed.
Example:
Find what position in the array your data is in that you want
removed. Removing all of the data to that point using the num_items flag for pop or shift.
Then while using the values: flag with the returned array (that you got from pop or shift), add the old values back (without the value you dont want), using push or unshift.
*More Information
www.proboards.com/developer/js/class/key
Getting the Object_Id:
You can get your Object_Id from just about anywhere. It could be the id of the row holding each post.
It could be in the window.location.href (current url) for the user's profile page, or the thread id.
But most of the time you just want your own id. You can find this in the pb.data hash. The current
logged in user id is stored in pb.data('user').id variable. Using this as the object_id will make setting your
key simple.
The pb.data Hash:
Alot of good data can be found in this hash. This will assist you when retrieving data from the
current page. The serverDate can help with the date object. It will tell you if the user is a guest,
staff, in a group/what group, smilies, current status, name, id, birthday (if saved), theme, username,
and more depending on the page loaded. Different pages may have different data hash values available.
Typing in proboards.dataHash in the console will allow you to easily view the structure by returning the object.
Example of pb.data():
proboards.data([['ad_free',0],['time_style',0],['military_time',0],['timezone',"-5.00"],
['serverDate',1439712001000],['search-query-min',3],['search-query-max',50],
['is_current_user_guest',""],['plugin_max_key_length',4000],
['plugin_max_super_forum_key_length',32000],
['login_url',"https://login.proboards.com/login/5500350/1"],
['register_url',"https://login.proboards.com/register/5500350"],['news_items',[{"text":"Welcome to our
new forum!","id":"1"}]],['news_speed',"5000"],['news_animation',"slide"],
['home_new_post_src',"//images.proboards.com/v5/icons/board-no-new-post.png"],
['mark_boards_read_url',"/boards/mark/read"],['forum_id',"5500350"],['_google_analytics_events',
[{"hitType":"pageview"}]],['shoutbox_init',
{"newestAt":null,"lastUpdateTime":1437609384000,"smileyList":
[":)","//images.proboards.com/v5/smiley/smiley.png",":P","//images.proboards.com/v5/smiley/tongue.png"
,":|","//images.proboards.com/v5/smiley/plain.png",":'(","//images.proboards.com/v5/smiley/cry.png",">
:(","//images.proboards.com/v5/smiley/angry.png",":D","//images.proboards.com/v5/smiley/grin.png",":
(","//images.proboards.com/v5/smiley/sad.png","::)","//images.proboards.com/v5/smiley/eyesroll.png",";
)","//images.proboards.com/v5/smiley/wink.png","8
-)","//images.proboards.com/v5/smiley/cool.png",";-|","//images.proboards.com/v5/smiley/squint.png","?
??","//images.proboards.com/v5/smiley/huh.png",":o","//images.proboards.com/v5/smiley/shocked.png","(r
ofl)","//images.proboards.com/v5/smiley/rofl.png","x_x","//images.proboards.com/v5/smiley/dead.png","8
D","//images.proboards.com/v5/smiley/insane.png","(puke)","//images.proboards.com/v5/smiley/sick.png",
":))","//images.proboards.com/v5/smiley/cheesy.png","O_o","//images.proboards.com/v5/smiley/browraise.
png",">:D","//images.proboards.com/v5/smiley/superangry.png",":-
X","//images.proboards.com/v5/smiley/lipssealed.png",":-
*","//images.proboards.com/v5/smiley/kiss.png","8
-|","//images.proboards.com/v5/smiley/nerd.png","B-|","//images.proboards.com/v5/smiley/notamused.png"
,":-/","//images.proboards.com/v5/smiley/undecided.png","(zzz)","//images.proboards.com/v5/smiley/asle
ep.png",":-[","//images.proboards.com/v5/smiley/embarrassed.png",":-
S","//images.proboards.com/v5/smiley/wavey.png","P-)","//images.proboards.com/v5/smiley/pirate.png","(
:))","//images.proboards.com/v5/smiley/ninja.png"]}],['shoutbox_add_url',"/shoutbox/add"],
['shoutbox_edit_url',"/shoutbox/edit"],['shoutbox_message_url',"/shoutbox/get"],
['shoutbox_remove_url',"/shoutbox/remove"],['shoutbox_update_url',"/shoutbox/update"],
['csrf_token',"j1qiXOEv"],['user',{"date_format":"m/d/y","is_logged_in":1,"status":"hi","friends":
{},"group_ids":[1],"avatar":"<div class=\"avatar-wrapper avatar_size_default avatar-1\"><img src=
\"//images.proboards.com/v5/defaultavatar.png\" alt=\"Logan Avatar\"
/></div>","time_format":"12hr","proboards_plus":0,"block_list":{"user_ids":[]},"last_online":
{"unix_timestamp":1439712001},"groups":
{"1":"Administrator"},"url":"/user/1","posts":143,"instant_messengers":
{"icq":"","skype":"","yim":"","aim":"","msn":""},"id":1,"registered_on":
{"unix_timestamp":1387610260},"birthday":{"month":1,"day":28,"string":"Jan 28,
1992","year":1992},"has_new_messages":0,"theme_id":1,"name":"Logan","username":"admin","is_invisible":
0,"rank":{"name":"Full Member","id":3},"is_staff":1}],['page',{}],
['default_avatar',"//images.proboards.com/v5/defaultavatar.png"],['route',{"params":
{},"name":"home"}],['search_system',1],['insite_path',""]]);
Limitations To Keys Include:
Codes which use plugin keys to store unrelated data like sharing a single plugin key between multiple
UNRELATED plugins. Sharing keys themselves is acceptable.
Setting a key on page load is prohibited.
Keys must be set by a user initiated action *that can reasonably be assumed to create an additional
server request. You should not bind to a button that is already in existence unless it's obvious the
user knows a key will be set relating to the plugin at hand. This means you should not bind to existing
submit buttons. This is where to use the set_on commands.
*More Information
www.proboards.com/developer-guidelines
support.proboards.com/post/6319142
support.proboards.com/thread/431718/plugin-keys
The Plugin System:
Plugins are an easy way to install custom codes on a ProBoards forum. A plugin generally consists of
Header & Footer codes along with customizable settings. When a developer provides a plugin to a forum
staff member, they can download the plugin file (*.pbp files), and import it directly into their
forum. When the plugin is enabled, it will automatically insert Header & Footer codes into the
correct places on the forum. There is no need for the forum staff to deal with the coding.
Plugins can offer very easy ways for forum staff to customize various options without needing to touch
the actual HTML / JavaScript / CSS code. Plugin authors are given tools to easily build a custom User
Interface where forum staff can input settings for the plugin. These settings are stored in variables
that can then be accessed by the Header & Footer codes of the plugin.
*More Information
support.proboards.com/thread/433194/overview-proboards-v5-plugin-system
support.proboards.com/post/4975826
ProBoard Events:
These can be used to run functions based on user interaction.
afterSearch: will run after an auto-search (note: this occurs when a board or thread page are first
loaded as well) It also fires after a pageChange event, removing the need for pageChange
columnSort: will run when the user clicks on a column title to sort a list
moreActivity: will run when the 'Show More' link is clicked on a user's activity page
moreNotification: will run when the 'Show More' link is clicked on a user's notifications page
pageChange: will run when paginating. Use afterSearch instead unless you are displaying something on the calendar page. (since it can include pages but does not have a search bar)
Each entry also has an accompanying event that will only run once:
afterSearchOne
columnSortOne
moreActivityOne
moreNotificationOne
pageChangeOne
Additional Events have been added by Yootil
*More Information
support.proboards.com/thread/473870/proboards-events
Plugin Main Components:
There are 3 main components you can add in a plugin.
JS, Global, and CSS.
You can have 2 JS components currently. This will hold direct Javascript code that will be loaded as
an external file for speed, and so that it stays in memory. This is keeping you from downloading it
every time you navigate a page, saving bandwidth.
The CSS component moves your css to an external stylesheet for speed and organization much like the JS
component.
The Global component adds a header and footer component that will load on every page. The footer is
good for starting functions after most DOM elements have loaded, but before some images have finished
loading. (for speed) The header is good for extra space for loading css and or scripts.
*More Information
support.proboards.com/thread/460256/adding-features-plugin-using-components
Plugin User Interface:
The User interface allows you to get admin specific variables without them having to go into the
source code. This makes plugins easy to manage, maintain, and automate.
*More Information
support.proboards.com/thread/460252/giving-plugin-user-interface
Plugin Images:
You can also pack images with your plugin and set them as variables throughout.
*More Information
support.proboards.com/thread/460254/uploading-images-use-plugin
Plugin Examples:
These links show a plugin from start to finish.
support.proboards.com/thread/433768/video-plugin-tutorial
support.proboards.com/thread/433716/video-plugin-1
Exporting and Sharing a Plugin:
Plugins can be exported for backup or sharing purposes.
They can also be submitted to the library so that it can be easily found by users looking to add nice
features to their forums.
*More Information
support.proboards.com/thread/460258/exporting-plugin-use
Plugin Code Restrictions:
Codes that make requests to ProBoards' servers except through methods explicitly allowed for by
ProBoards (such as plugin set() functions). Examples of prohibited codes include using <iframe> tags
to access forum content, or making AJAX requests to ProBoards' forums. Not that you can't use iframe
tags to access other web sites not on the ProBoards' domain.
Codes that affect the placement of advertisements on any ProBoards forum, except those specifically
authorized by ProBoards.
Codes which cause automatic redirects on page load to a new URL.
Codes which rely on external code to work properly. Note that using external data is acceptable, so
long as that data is loaded asynchronously.
You may not use another's code in your plugin without permission. Doing so and claiming it as your own
will result in a serious warning and possibly a ban.
You may not add a visual copyright to forums that utilize your plugin; however, you may add a
copyright to the source code of the plugin.
Your plugin must not be malicious in any way.
As always follow forum rules and ProBoards' Terms of Service
*More Information
www.proboards.com/developer-guidelines
support.proboards.com/thread/433518/plugin-creation-rules
www.proboards.com/tos