Supporting Server Side Embedding
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>
<p>Some static stuff</p>
<% request to LJ for page
command to print out the result %>
<p>More static stuff</p>
<body>
</html>
which will look like this by the time it gets to your browser
<html>
<body>
<p>Some static stuff</p>
result of LJ request
<p>More static stuff</p>
<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
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
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
<!-- #exec cgi="/cgi-bin/livejournal.cgi" --> (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
<!-- #exec cgi="http://www.livejournal.com/customview.cgi?user=tinyjo&styleID=101" -->
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.
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>
<p>Some static stuff</p>
<% request to LJ for page
command to print out the result %>
<p>More static stuff</p>
<body>
</html>
which will look like this by the time it gets to your browser
<html>
<body>
<p>Some static stuff</p>
result of LJ request
<p>More static stuff</p>
<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
<!-- #exec cgi="/cgi-bin/livejournal.cgi" --> (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
<!-- #exec cgi="http://www.livejournal.com/customview.cgi?user=tinyjo&styleID=101" -->
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.