Support Category Embedding

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.

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.

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?Collapse )

( FAQ147: Will my embedded journal display my Friends-Only or Private entries?Collapse )

( FAQ146: How do I change the appearance of my embedded journal?Collapse )

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!

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

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.

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 :)

( Supporting Server Side EmbeddingCollapse )

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.

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)

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 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.