Support Category Embedding

So long, and thanks for all the fish

asciident — Fri, 22 Jul 2005 03:52:06 GMT

The merge is done. :) Embedding is dead, long live Style Systems!

This community remains as is for posterity; it's now an out-of-date historical archive, and anyone looking for policies, procedures, and help should take a peek at support_styles and the Style Systems docs.

An S2 style for embedding

tinyjo — Mon, 22 Mar 2004 08:28:56 GMT

I had a brainwave about how this could be done the other night, and am currently working on an S2 style to be used for embedding. It consists of a layout layer, which will contain all the code and a theme layer where you will be able to set properties such as what order you want all the data in, how you want it separated (line breaks, spaces, whatever) with lots of comments to explain how each property works. My plan is to make it extremely customizeable but to be providing almost no formatting, but lots of CSS classes instead. So, my questions are

a) Is there a need for this? I'd like to be doing it with a view to writing up installation instructions for S2howto say, or an FAQ, and getting the layers adopted by an official journal somehow (I'm not quite sure how that would work as Advanced cust doesn't seem to have authas yet).
b) Is someone else already working on this? Obviously, it's not worth duplicating effort really. Is there a zilla task for something like this? I couldn't find one but that doesn't necessarily mean it's not there.

There's a skeleton of how it will work up now - http://www.livejournal.com/customize/advanced/layerbrowse.bml?id=854681 is the layout layer (I haven't bothered to write a separate theme layer yet). http://www.livejournal.com/users/tinyjo/?s2id=1650583 is how it displays.

Embedding FAQ Revisions RFC

asciident — Sat, 14 Feb 2004 09:36:26 GMT

Yes, I'm doing this here too. :) And shamelessly copying & pasting.

Let's talk about the FAQs. Many of them are practically begging for alterations. Please read over the ideas below, and let me know your thoughts.

I also want to know: what should be covered in the FAQs that isn't?

FAQ68: How do I embed my LiveJournal into my website?
Initial thoughts:

Title: change "LiveJournal" to simply "journal".
Remove link to /developer/embedding.bml, use following:
Take all the methods on /developer/embedding.bml to make into series of HowTo docs:
- Each method type gets its own entry, with an index page, much like the color usage guide.
- Edit wording to be more professional for each method.
- Switch PHP include() method for PHP readfile() method.
- Add in methods we've received (e.g. this)
Give instructions to embed both S1 & S2.

FAQ147: Will my embedded journal display my Friends-Only or Private entries?
Initial thoughts:

Link back to FAQ68.
Cover S2.

FAQ146: How do I change the appearance of my embedded journal?
Initial thoughts:

Cover S2.

This is meant to be a more support-needs oriented, casual FAQ discussion. When we hammer out our wants/needs on these, I'll move it to a more formal discussion over in lj_userdoc for final drafting.

Comments, please!

Test Revision Completed

asciident — Fri, 26 Sep 2003 00:19:42 GMT

Both I1 and I2 test revisions have been completed, current access restored, and the queues for the I2 test updated.

Test Revision

asciident — Wed, 24 Sep 2003 04:33:47 GMT

I've taken the tests down tonight, for major updates and revision to reflect current issues in the category.

I'll post again when the new tests are completed and available, and your access will be regranted. The ETA for this is 1-2 days from now.

Supporting Server Side Embedding

tinyjo — Thu, 29 May 2003 08:27:00 GMT

This post covers the basics of server side embedding. It describes the principle behind server side embedding and gives examples of ASP, PHP, CGI and almost Python. It also gives some tips for supporting server side embedding. If you want to know about client side embedding methods you should read Getting Started In Embedding. In fact, you should read it anyway :)

Server side embedding - the basic principles
In essence, what you do when using server side methods is you write a piece of code which will output all or part of the html for your page. Normally, you will only need to use code to write the parts which may change depending on circumstances. The code is indicated by being inside a special set of tags (or delimiters). You can have as many code sections as you want in a single page. The file is then given an appropriate extension to indicate what type of code has been used. When your browser requests to view the page, the web server processes the code, based on the file extension and sends the result to your browser.

In the case of embedding your LiveJournal, there will be a code section which gets the contents of the customview.cgi URL in some fashion and simply puts that into the output which is sent to the browser.

So, most such pages will have a structure something like this...

<html>
<body>
Some static stuff
<% request to LJ for page
command to print out the result %>
More static stuff
<body>
</html>

which will look like this by the time it gets to your browser

<html>
<body>
Some static stuff
result of LJ request
More static stuff
<body>
</html>

Active Server Pages
This method mostly works as described above. The file should be saved as a .asp file and the code sections of the page are delimited by <% and %>. The most common language used with ASP is VBScript (which is the default). It is also possible to write the code sections in other scripting languages like JavaScript or PerlScript if they are installed on the server. If you are doing this, you need to indicate this by making the first line in your file <%@ language=JavaScript%> (or appropriate).

Here is a basic demonstration (source - lines starting ' are comments) of asp embedding. In order for this to work, MSXML needs to be installed on the web server (it's a dll). It's installed by default on newer versions of Windows web servers, but I don't know about Linux/Unix or older Windows servers. As far as I can tell, this code works with all versions of MSXML.

The embedding guide contains an alternate commented out version of the line Set XML = Server.CreateObject("Microsoft.MSXML"), replacing Microsoft.MSXML with MSXML2.ServerXMLHTTP. It shouldn't be necessary to use this unless you want to do clever stuff with cookies (of which more another day). If this is being used, be aware that its not forwards compatible (e.g. for MSXML 4, you would need to use MSXML2.ServerXMLHTTP.4.0).

Note that ASP.NET (file extension .aspx) is very different from ASP and the methods in the embedding guide need considerable modification to work in ASP.NET - enough to put such requests out of scope. The good news is that if ASP.NET is enabled on the server, ordinary ASP will usually work as well.

Embedding guide - ASP

PHP
This method is also basically as described above. The file should be saved as a .php file and the code sections are delimited by <?php and ?>. Unlike ASP, PHP is the name of both the type of file and the programming language the code is written in. You can see a basic demonstration of one of the methods described in the embedding guide here (source). The reason the include method is not recommended is that if there is PHP code in the text retrieved from LiveJournal then that will be run on the web server before the page is returned to the browser, which represents a security risk to the web server. The likelihood of this has been reduced by the fact that the HTML cleaner has become stricter and usually now will replace the angle brackets in the delimiters with < and > rendering the code useless, but it is still possible to get around this. If the user is using this method your answer should include a recommendation that they switch to one of the other methods in the embedding guide.

Embedding guide - PHP

CGI
CGI is the one method which does not work as described above. All the contents of the CGI file must be code, with no plain HTML (although you can write code to produce the static as well as the dynamic portions of your page). As a result, CGI embedding generally involves 2 files. The first is a .cgi file. On many web servers, this will need to be saved in the cgi-bin directory or it won't be processed. This contains the code for getting your journal from LiveJournal, usually written in Perl. The second file is a .shtml file. Somewhere in this file will be the line
 (or whatever the filename is).

When the .shtml page is requested by the browser, the server will replace that line with the output of the cgi file. You can see an basic example of this here. The source for it is here for the .shtml page and here for the .cgi.

Note that you can't just include customview in your page by having a line



because the referenced CGI file must be in the same website as the .shtml page which is referencing it.

Embedding guide - CGI

Python
Another method which works basically as described in the intro. The file should be saved as a .py file and the code sections are delimited by <% and %> like ASP. Like PHP, the name Python refers to both the file and the language. I tried to put a basic example up here but it turned out to be an example of what happens when the method you try to use is not supported by your web server.

Embedding guide - Python

Supporting server side embedding
The main difficulty in supporting server side embedding is that you cannot usually view the code used for the embedding by simply visiting the page with your browser. If you visit the embedded page and the embedded journal does not appear, view the source. You may find that the code sections are still present in the source. This means that the page has not been processed by the server. This can be caused by a few things. The user may have given their page the wrong file extension (often just .htm). A very similar problem is that the user has used the wrong delimiters to indicate the code sections. Be careful in differentiating between these two causes. Compare the text of the code sections to the examples in the embedding guide to try and work out what file extension / delimiters they should be using. If all appears correct, the third possibility is that this method is not supported by the web server the page is hosted on, which is something which they can inquire into with their hosting company.

If the code is not visible at all, then the page is being processed, but there are errors in the code. Most server-side methods will respond to this by printing an error message where the output should have been. If it's not possible to diagnose the problem from the error message, it may be necessary to ask the user to comment with details of the code they're using. Check that the code is actually in the right language - the fact that the file has been processed means that the delimiters and the file extension match, but does the language being used? Check the embedding guide to get some idea of what syntax to expect for the different methods.

Because of the nature of server side embedding, the request to LiveJournal actually comes from the server, not your computer. This means that your login cookie can't be sent to LiveJournal so it's not possible to view your friends only or private entries through your embedded journal using server side methods.

Getting Started in Embedding

asciident — Mon, 17 Feb 2003 02:47:35 GMT

This tutorial assumes that the volunteer has at least some experience in support. How support works, wording, etc. are all learned from experience and entries other than this one.

What is embedding? It's displaying your LiveJournal-hosted journal within your webpage. The possibilites range from simply displaying your LiveJournal as is and putting it in a frame on your site to displaying a customized version using a scripting language.

Be sure to review the Embedding Developer page and watch for update announcements as it may be updated in the near future. Also be sure to read the Summary Codes entry, Policies entry [updated 17 February 2003], and the Category Definition entry. Additionally, review the FAQs referenced throughout this document.

Often, a user will simply want to know how to embed their journal into their webpage. This involves simply providing a FAQ reference.

If the user doesn't mention where their site is embedded, or provide the code they're using, try looking in their userinfo for a website link. Look around their website for any sign of a "journal" or "blog" page. If one isn't provided, wait for a supporthelp to request further information.

Frequently a user will have already embedded their journal and need further assistance. Usually, this comes in the form of wondering why their embedded journal is so "ugly," the date is orange, or is missing comment links. This is indicative of the user simply copying the embedding method exactly including the styleid=101 reference. Style 101 is rather plain (white, black and orange), is missing comment links, and does have a few problems. The user should be directed toward this FAQ.

It's also good to familiarise yourself with the most common embedding methods, which at present are frames and JavaScript. There are two frames methods: <frameset>, and <iframe>.

The first is the original HTML "frameset" which produces one page displayed next to another, at it's most basic form. A very primitive form of this is an example here. This works for any frame-supporting browser (nearly all of them these days), but one can also include a <noframes> clause to provide an alternative should framesets not work.

The second is the inline frame, more commonly known as an iframe. This allows you to put the frame wherever you would like within a specific page, rather than having it confined to sets of frames around each other. A primitive example of this may be viewed here (note my default style doesn't work very well in such a small area).

The easiest method for paid users to use is the JavaScript method. This script basically tells the browser -- by the appended &enc=js to the customview.cgi URL -- to print the entire journal page from one (often very large) document.write statement. This puts any style within a document.write automatically and puts in \n (line break in many scripting/programming languages) wherever a line break occurs. For those unfamiliar with JavaScript, document.write is used to print text (or media) to the screen. A simple example of this may be viewed here. You may want to examine the source code of of the JS-encoded Generator by going here and viewing source.

It's possible for a free user to use JavaScript, with a slightly more complicated script that doesn't involve customview.cgi but rather pulling up your journal as the frames methods do. However, this shouldn't be given as an answer when a user is seeking a method; our official position on this is leaving it as an "easter egg" for users smart enough to find it.

There are three known, system-created embedding styles: Style 101 as referenced above, Style 103 used for Flash, and Style 408, a "fixed" public version of 101. I'm currently attempting to have Style 101 marked public, but you may want to look over the style information for 103 and 408.

Frames and JavaScript, in addition to being the easiest embedding methods, are also the only two able to display protected and private entries utilising the &checkcookies=1 parameter to customview.cgi. This is addressed in this FAQ. Browsers (or "client-side") need to check their cookies against the current server. Since the frames and JavaScript are both directly pulling the journal from LiveJournal.com, the browser is able to authenticate a user and display protected/private entries. The other methods are pushing the journal through a script, which is "server-side," so the browser is unable to authenticate the cookies-to-site match and therefore unable to display protected/private entries.

What is Embedding?

asciident — Sun, 16 Feb 2003 22:43:01 GMT

Embedding is a specialist category, where all requests relate to embedding a LiveJournal into a webpage. A list of what belongs in the category:

- Embedding a journal
-- As a free user
-- As a paid user
- The different methods
-- Pros and cons for each
-- Applications of each
-- Protected entries
- Changing the appearance of an embedded journal
-- Colors/no comments: stuck using 101
-- Creating an embedded style (paid user)
-- Looking just like regular journal (free user/paid user methods)
- Code not working
-- General diagnosis
-- LiveJournal<->Code error
- Embedding bugs
-- Errors in the code given
-- Customview.cgi
- S2<->Embedding interaction

Following that, a list of what looks like it might belong in embedding, but does not:

- "Embedding" some form of media into LiveJournal (posting media into style, post comment, bio; general/unknown)
- Questions about using Flash/scripting on LiveJournal (scripting/flash disallowed; general/unknown)
- Descriptive diagnosis of embedding code (can remain within the category, but should be given an out-of-scope response)
- Request for custom embedding code (again, can remain within the category, but should be given an out-of-scope response)
- Embedded style is not displaying as expected, when the cause is the style, excepting 101 (cust issue; style systems)

Update 31 May 04:
User wants to put his or her journal "into" their (AIM) profile, or are unclear about it (link to it vs. embed it), also falls under Embedding. (link)

Embedding Policies

asciident — Sun, 16 Feb 2003 01:42:03 GMT

Some of these may look familiar as UPI policies. I did review them in terms of application to embedding and have decided they are to apply to both. :)

Policy: Do not offer custom embedding code.
Explanation: This is outside the scope of LiveJournal Support. You may only offer the code described on the Embedding Developer page.
Side Note: This is not to say that you must tell the user they can only use the methods and implementations offered at the developer page, but LiveJournal Support is not responsible for assisting the user in finding new or different ways of implementation.

Policy: Diagnose LiveJournal-related embedding only.
Explanation: It's outside the scope of LiveJournal Support to teach someone to use their choice of embedding method. If they are having difficulties recognising why something is not working, it is acceptable to point out the problem in general and recommend they consult the method's documentation if they do not understand how to resolve the issue.
Side Note: It is also acceptable to recommend they pick another method should they not successfully resolve the issue on their own.

Policy: Effective immediately but not retroactively, interims will be given only to those who are actively working in the category.
Explanation: Only those with experience and knowledge should have interims in embedding -- it seems illogical to remove privileges for inactivity or "tidyness" yet give them to people who may never use them. Additionally, the original logic for giving them was that not everything opened in embedding actually belongs there. It is preferable to have those experienced with embedding determing what to move. There is an abundance of people who are able to move, who do have this experience.
Side Note: Those who have received I2 without working in the category, or have jumped ahead of their current level, will either continue to be worked with to earn their level by merit or will be dropped for inactivity at the normally scheduled intervals of once per quarter.*
Exception: This does not apply to abuse I2s, where confidentiality, security and other sensitive information may factor in.

Policy: Do not show a preference for a certain embedding method.
Explanation: It's not within the scope of LiveJournal Support to lecture users on the pros and cons of each embedding method. It is, if applicable, acceptable to briefly explain the differences of each, though it is preferrable to warn a user that some may not be available to him/her.
Exception: Do not recommend PHP method #4, the include() method. If a user states that he or she is using this method, recommend that another method is chosen immediately. PHP method #4 presents a potential -- though likely obscure -- security problem, and developers may be unwilling to remove the method at present.

Policy: Do not refer users to Zilla items. Always CC me on embedding related Zilla items.
Explanation: If you report a bug that relates to userpics or embedding, please CC me so I can easily track its progress or comment on it without having to find it. Additionally, never tell a user a bug number or give a link in your support request. You may either say it is a known issue and being looked into, or you may say it's been reported (e.g. if you've just reported it). You can additionally offer workarounds if they exist.
Side Note: It is acceptable, if you are able to comment, to request diagnostic information (browser, OS, internet connection, link to the embedded page, embedded style ID, etc.).
Exception: If the user is, for example, a support volunteer or someone else you know to be already familiar with Zilla, you may post a link to the Zilla item.

Policy: All embedding supporthelps are required to watch this community as well as lj_support.
Explanation: There are many discussions going on here that supporthelps should be watching, if not participating in. Participation is preferred, but not mandatory.
Side Note: It is not required that you actually "watch" the community in the sense of having it on your friends list, but the only other way I have of knowing you are keeping up is by participation -- in other words, if you aren't "watching," you will need to be participating.

Policy: All volunteers may be given the embedding tests to earn I1 and I2. Supporthelp is earned by hands-on experience.
Explanation: As embedding is the smallest category, the practical solution to judging experience is to offer a test to earn I1 and I2. However, I feel the best way to effectively learn embedding and earn supporthelp is through actual board experience, thusly supporthelp remains attainable solely through board experience and reviews thereof.

* Regularly scheduled intervals of priv-activity review will be once per quarter: January, April, July, and October.

That's all I can come up with right now. I'll edit this page if I get a flash of inspiration or one of you lovely people has a good addition. :)

Summary Codes

asciident — Sun, 16 Feb 2003 01:09:09 GMT

Summary codes Embedding will be using now:

Code	Meaning
/	Summary text has been changed.
[a]	Request needs to be left for me, Rahaeli or another administrator to handle.
[auc]	Awaiting user comment.
[ui]	Under investigation.
[v]	Validation nag.
[x] or [x?]	Closable or possibly closable.
[ADP]	AOL Server page embedding
[ASP]	ASP embedding
[BML]	BML embedding
[CF]	ColdFusion embedding
[CGI]	CGI embedding
[Flash]	Flash embedding
[Frames]	HTML Frames embedding
[IF]	IFrames embedding
[Java]	Java applet embedding
[JS]	JavaScript embedding
[PHP]	PHP embedding
[Py]	Python embedding

Yes, I know that's insanely long. I don't expect you to memorise this. You might want to bookmark or memorify this entry.

UPI and Embedding: Plan for Training

asciident — Fri, 14 Feb 2003 16:44:41 GMT

Cross-posted to support_embed and support_upi.

Embedding is a small category like UPI, but not so small that there's never any requests.

Here's my general plan for both categories: I will be making two tests for each category. One is to get I1, one is to get I2. The difficulty levels will be appropriately set for either level. In order to gain supporthelp, one needs to have actual board experience and a review (or multiple) thereof. I feel you truly do not have the experience needed to handle actual requests unless you've had practice doing it.

The difference being: UPI, being slightly higher in volume, will only offer tests to low-volume volunteers who simply can't get to the board enough to have a decently-sized review; embedding will offer tests as the only way to gain privs in embedding up until supporthelp, unless you have an amazing amount to review.

I may or may not be keeping parts of the current embedding test, I'm not sure at this point.

I expect to have these tests completed by Sunday at the latest, and will be contacting many people. I will be contacting known low-volume volunteers in UPI and all of you who have indicated you're interested in working in embedding.

I'll also be reviewing embedding's policies and training documents, and posting updates as appropriate.

Let me know if you have any questions or comments!