Explored. Designed. DeliveredSM
|
|
Use JavaScript for Dynamic Content Syndication
|
Explored. Designed. DeliveredSM |
Use JavaScript for Dynamic Content Syndication |
 (@NetlabLoligo)
|
Conventions:
Creativyst® JSMsg Webpage Display ConventionUse JavaScript syndication to display dynamic content on static or dynamic pagesAuthor: Dominic (John) Repici
Why Use JSMsg?
Overview
This paper documents a recommendation for the "JSMsg" file
format. The JSMsg convention is a JavaScript that allows dynamically changing
content to be displayed on webpages directly, or to be shared with outside
scripts. The JSMsg convention places no restrictions on how its content is
formatted by the webmaster or JavaScript display program.
JavaSript programs that display content in interesting and creative ways are perfect candidates to have JSMsg client capabilities added to them. Such scripts will be enhanced by JSMsg support because they will no longer need to ask their users to change the static information to be displayed. For example, an information display script, when told to use a JSMsg file from a news service, will display the news information as it changes automatically, without needing intervention from the webmaster. Just as importantly, such a script will work with dynamic OR static content from ANY JSMsg file, not just the news service. This JSMsg recommendation is a specification for a JavaScript file, functions, and naming conventions which may be included by outside webmasters in their pages, allowing display of their provided content in whatever style and layout the outside webmaster chooses. The convention is also useful as an easy means of content display at the source website. The JSMsg convention shall be used in many of Creativyst's custom and COTS web page content applications to permit simple dynamic content display on web pages, and promote sharing that content with others. We openly share this convention with all who wish to use it and contribute to it. Our licensing terms will be free to personal and commercial projects, and detailed in the permissions section.
Design Philosophy & Goals
The design of the JSMsg convention will enable publication of dynamic
content for presentation on outside web pages and within outside JavaScripts
without restrictions on the format, layout, and style in which the syndicated
content may be displayed.
A primary motivation in developing this convention is to allow the millions of webmasters with client-side-only scripting capabilities to share and use dynamic content on their Web pages. We are documenting this convention and granting permission to others to use it un-altered because interface consistency benefits everyone. Another design goal for this specification is to allow separate outside JavaScript programs to easily display any dynamic content from any JSMsg file without prior knowledge of the JSMsg file or the application that produced it. In a word, the design philosophy for this project is Simplicity. The specification defined here shall be easy to understand, easy to implement, and easy to use. It must also be concisely and unambiguously defined, flexible, and enabling of applications beyond those that can be envisioned at the time of initial definition.
The JSMsg File
The file may simply be named "JSMsg.js", though it does not
have to be. One useful convention is to name the file the same as the
namespace used (see below). A JSMsg file shall contain
JavaScript that is v1.1 compliant or lower. It SHOULD support the lowest
version of JavaScript possible.
File names MAY be sequentially enumerated in cases where multiple JSMsg.js files require sequential but separate storage in the same location. For example "JSMsg01.js, JSMsg02.js", or "JSMsgMon.js, JSMsgTue.js", etc.
Namespaces
Namespaces are simply a means of labeling a group of function and variable
names so they do not conflict with identical names used by outside processes.
JSMsg requires namespaces so that content in JSMsg files from diverse sources
may be used together on a single web page.
JSMsg shall employ a single JavaScript class as a simple namespace mechanism. All function names, globally scoped (otherwise) variable names, and array names within a JSMsg file, WILL be wrapped in a single class named with the namespace. This class name SHALL serve as the namespace, and SHOULD be kept relatively short to preserve typing and bandwidth. The class constructor function name itself SHALL be preceded with the namespace. The namespace name, being the class name, MUST be comprised of letters, numbers, or underscores and must not begin with a number. Applications that produce JSMsg files (servers) SHOULD give users the ability to change the namespace. This is REQUIRED for applications where a single outside webpage may want to include content from multiple outside sources that may all use the same application. Such sources could be blogs, or news and announcement services. In these cases, the application user (the source) may be instructed to pick their own namespace based on their URL or a legally protected trademark or service mark. In any case, server applications should include a default name space if the user does not configure one, or configures one improperly.
Function Calls
The following seven functions MUST be provided by the JSMsg file and
encapsulated in the namespace/class
(... is used here in place of the namespace)
Usage Examples
A particular JSMsg.js file is use by including it in the header
with a script tag and then calling the functions within the remainder of your
html file. Normally only the display functions are required to display
information in the body of an HTML document. More advanced presentation can be
accomplished using the GET functions.
The JSMsg.js file used in this example will be the one generated by Creativyst® Quote Catcher which has a name space of cqc.
First, include the script in the header
Use ...Msg() to display parts of a message that change randomly each time you reload the page. To try it click here and then use your browser's refresh or reload button.
This will display the message "Body" followed by a double dash and the message "Attrib" ("Attribute") for a randomly chosen message. Each time you reload the page, a new message will be selected at random and displayed.
Use ...MsgDay() to display parts of a message that change once a day.
Unlike the example above that changes every time you re-load the page, this one will only change once a day.
Use ...MsgN() to display a part of the Nth message in the current short list.
This will display a message that only changes when the current list changes. That is to say, when you run the application that re-builds the JSMsg.js file. If there are less than 10 messages in the current list in the above example, it will wrap around and start counting up from the beginning again. The ...MsgN() and ...GetN() function is very useful for displaying a formatted list of the top N messages in the list, as you might do for example, in a list of recent news stories.
Use ...Get..() functions in your JavaScript code to retrieve message strings in identical fashion to how the ...Msg..() functions display them.
You may use ...Get..() functions as well as ...Msg..() functions from within your JavaScript scripts for nearly unlimited flexibility when displaying message parts. Had the application constructed a JSMsg file containing a list of news stories in most-recent-first order, the above JavaScript would have shown the three most recent ones. Note also, that the message numbers start at zero.
The random functions; ...Msg() and ...Get() may optionally take an extra offset parameter to add to the random number produced. To try it click here and then use your browser's refresh or reload button.
We've used the ...Get() function above, but it would have worked just the same way had we used the ...Msg() function to display the messages directly. Here, instead of a single message that changes every time the page reloads, there are three messages changing every time the page reloads. You can add as many as you'd like to such a list (they will simply wrap around to the beginning if there aren't enough messages in the JSMsg file).
Message Parts
Message parts are labels used to access various parts of a message, such as the
Title, Body,
Description, etc.
Message parts are all optional but at least one message part MUST be supported and provided in the JSMsg.js file. Message parts provided MUST be well documented for users. The message parts provided MUST be one or more of the following. Case should be ignored (i.e. Title, is the same as title, is the same as TiTlE).
Arrays
Arrays like all variables in the file, are wrapped in the class to encapsulate
them in the namespace.
Don't use these arrays directly in your JavaScript. Use the access functions to get at the information within them. In the future the names will likely be shortened to just their first letter or two. If you use the access functions such as Get...(), your scripts will continue to work fine no matter how the array names change. Each array holds the content of a single supported message part for all the messages in the JSMsg.js file (the shortlist) in parallel with other arrays holding other message parts. A specific Array SHOULD only be provided if its respective message part is supported/provided by the implementation producing the JSMsg.js file. Each array included in the JSMsg file, if used, MUST be named with specific names defined in this specification. Here are the specified array names for version 1.0a of this convention, with "..." substituted in place of the name spaces.
JSMsg Version Token
For webmasters using the content, JSM file is normally meant to be run as a
JavaScript. But aggregators will likely read and parse JSMsg files as plain
text in order to glean information from them. Because the array names are free
to change and new array names may be added, some mechanism must be provided to
tell the aggregator what names to look for when gleaning the information from
them. The version token serves this purpose.
The token is "JSMsgVersion:" followed immediately by the version number of this JSMsg recommendation document. The current version number is version "1.0a" without the quotes. The token should be placed somewhere in the file. Preferably near the top. It generally must be placed in a comment so it doesn't conflict with the running of the code.
/* * The following version token is * required by aggregators * ------- * JSMsgVersion:1.0a * ------- */ Note that the only part that's really required for aggregators in the above example is: JSMsgVersion:1.0a
JSMsg Buttons
There are two buttons defined for JSMsg links. You may download
these for use directly from your site. Do not link directly to them
here at Creativyst.com (do not inline).
Example JSMsg.js Code
JSMsg Servers
If you write a content management application that includes syndication
formats, adding support for JSMsg will make it easy for webmasters of every
stripe to incorporate your application's content into their pages.
Q. I already support RSS and other syndication formats. What are the advantages of adding yet another one? 1. Unlike RSS and other syndication formats, JSMsg is simple, and displays without plugins on any browser with JavaScript. Webmasters of all levels of expertise, from XHTML gurus, to AOL script runners will be able to easily incorporate content from your JSMsg file into their sites. 2. While JSMsg works fine as a stand-alone content format, it is also designed to make content available to display scripts. Any fancy display script that supports JSMsg will automatically be able to work with your application's content. 3. Webmasters will not have to insist their users run a single browser type. No data islands or DOM "extensions". Just simple, plain, well understood and supported JavaScript with a small set of consistent and openly shared access methods. Coding support? This paper is just gearing up. I'm currently using the JSMsg Server Demo page to debug some Perl functions. Once they're decent (halfway stable) I'll make them available under one of the many public licenses. They are very deliberately written and so should be easy to port to PHP. Applications that produce JSMsg files are called JSMsg Servers. If you've added JSMsg server support to your application, please let me know so I can list your application, a link to your site, and your application's default JSMsg namespace here.
JSMsg Clients
A JSMsg Client is a JavaScript program that, given only a string with a
namespace, can display the content from any JSMsg.js file listed
above it.
JavaSript programs that display content in interesting and creative ways are
perfect candidates to have JSMsg client capabilities added to them.
The following four functions may be pasted into display scripts directly to
allow easy access to any JSMsg.js files included above them on the HTML page.
These work just like the .Get() functions in JSMsg files but take
an added namespace parameter so the calling script may specify which
namespace's content to display.
/*
* JSMsg Client Interface Code
*
* (C) Copyright 2003-2005 Creativyst, Inc.
* creatvisyt.com
* ALL RIGHTS RESERVED
*
* Developers may use these functions
* freely in their code, modified or
* unmodified as long as this entire
* comment is included and intact.
*
*/
/*
* These work the same as their JSMsg Counterparts
* except they take an extra namespace parameter
* as their first parameter.
*
* They will return the message part just as if
* the function of the same name was called
* with the namespace prefixed.
*
*/
function jsmGetN(ns,MsgPart,number)
{
var rv, c, er;
c = "rv = " + ns + ".GetN('" + MsgPart + "'," + number + ");";
er = eval(c);
return(rv);
}
function jsmGet(ns,MsgPart,offset)
{
var rv, c, er;
c = "rv = " + ns + ".Get('" + MsgPart + "'," + offset + ");";
er = eval(c);
return(rv);
}
function jsmGetDay(ns,MsgPart)
{
var rv, c, er;
c = "rv = " + ns + ".GetDay('" + MsgPart + "');";
er = eval(c);
return(rv);
}
function jsmMetaMsg(ns,MsgPart)
{
var rv, c, er;
c = "rv = " + ns + ".MetaMsg('" + MsgPart + "');";
er = eval(c);
return(rv);
}
/*
* JSMsg Client Interface Code
*
* (C) Copyright 2003 - 2005 Creativyst, Inc.
* creatvisyt.com
* ALL RIGHTS RESERVED
*
* Developers may use the following
* JSMsg client interface functions
* freely in their code, modified or
* unmodified as long as this entire
* comment is included and intact.
*
*/
/*
* JSMsgIf() (Array Interface function):
*
* This function takes an array of messages
* to display. If there are no JSMsg
* namespaces defined it will return
* the array unchanged. Otherwise
* it will append the entries from the
* JSMsg feeds on to whatever is already
* in the array.
*
* msgAr Message array to be appended
* with messages from the feeds
* (for use by the scroller app).
*
* myNs String containing namespaces for
* each JSMsg feed you want to display
* messages from. Leave "" to simply
* return your array without additions.
*
* mySeq Messages from multiple JSMsg files
* are normally interleaved. Set this
* to 1 to present each JSMsg file
* end-to-end.
*
* Example call:
*
* JSMsgNs = "ciq cvs"; // namespaces setting var
* JSMsgSeq = 0; // sequence setting var
* myArray = JSMsgIf(myArray,JSMsgNs,JSMsgSeq);
*
*/
function JSMsgIf(msgAr, myNs, mySeq)
{
var TotNS,LongestNS;
var NSAr = new Array();
var i,j,k,o;
if(!myNs) {
myNs = "";
}
if(!mySeq) {
mySeq = 0;
}
/* get the offset
*/
o = msgAr.length;
if(myNs) {
NSAr = myNs.split(" ");
TotNS = NSAr.length;
/* Get longest length
*/
LongestNS = 0;
j = 0;
for(i = 0;i < TotNS;i++) {
j = jsmMetaMsg(NSAr[i], "MetaCount");
if(j > LongestNS) {
LongestNS = j;
}
}
if(!j) {
return(msgAr);
}
/* Interleave for now,
* eventually do Seq
*/
k = o; // offset
if(mySeq) {
for(j = 0;j < TotNS;j++) {
for(i = 0;i < LongestNS;i++) {
if(jsmMetaMsg(NSAr[j],"MetaCount") <= i) {
continue;
}
msgAr[k] = jsmGetN(NSAr[j], "LinkTitle", i);
if(!msgAr[k]) { // no linktitle, use body
msgAr[k] = jsmGetN(NSAr[j], "Body", i);
msgAr[k] += "<br> -";
t = jsmGetN(NSAr[j], "Attrib",i);
if(t.length > 17) {
t = t.substr(0,14);
t += "...";
}
msgAr[k] += t;
}
k++;
}
}
}
else {
for(j = 0;j < LongestNS;j++) {
for(i = 0;i < TotNS;i++) {
if(jsmMetaMsg(NSAr[i],"MetaCount") <= j) {
continue;
}
msgAr[k] = jsmGetN(NSAr[i], "LinkTitle", j);
if(!msgAr[k]) { // no linktitle, use body
msgAr[k] = jsmGetN(NSAr[i], "Body", j);
msgAr[k] += "<br> -";
t = jsmGetN(NSAr[i], "Attrib",j);
if(t.length > 17) {
t = t.substr(0,14);
t += "...";
}
msgAr[k] += t;
}
k++;
}
}
}
}
return(msgAr);
}
This is a primary goal of the JSMsg specification; to allow separate JavaScript programs to display any JSMsg file's content, without prior knowledge of the application that produced that JSMsg file. For those who write JavaScripts that display information in interesting ways, it would be helpful to have a simple set of functions that they can bolt on to their scripts so the information can come from a JSMsg file. I'll try and write such a set of functions and make them available from here when they're done. If you've written interesting display JavaScripts for which you'd like to add JSMsg support please let me know. so I can list it and a link to your site here.
Aggregating JSMsg Files
The JSMsg specification allows for a simple script to be written to aggregate
the content in other JSMsg.js files included on the page. For functions to help
do this, see the section titled
JSMsg Client Functions above.
Aggregating services will likely passively parse the content arrays
directly. They should take care to discern between the array names specified
here and future array names which will be one or two characters long to
preserve WAN bandwidth [TBD].
Permissions
This recommendation is © Copyright, Creativyst, Inc. 2004-2007 ALL RIGHTS
RESERVED.
Permission to use this unmodified convention as a component in the designs of commercial or personal products and software offerings is hereby granted. Links to this paper are always welcome. However, you may not copy, modify, or distribute this work without first obtaining express written permission from Creativyst, Inc. Those wishing to obtain permission to distribute this paper or derivatives in any form should contact Creativyst. Permissions printed over code, DTD, and schema files are supported as our permission statement for those constructs.
Want to Contribute?
If you're interested in improving or promoting this convention please contact me. If used,
your code and contributions will be attributed to you with a link to your site.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
