How to insert a SWF file in an ASDoc API documentation ?
2012-05-22 23:38
417 查看
ASDoc API documentation is well designed for developers but remain difficult to read for others. Some of my co-workers are web designer. They code a bit but they want API to be simple and they want usage examples.
In the past days I developed some image filters and effects for them. The resulting API has very few meaning without a real example of code and a way to test it. Thus, I wanted them to be able to access the code examples as well as being able to test the result
of each effects, inline, in the ASDoc documentation. Click the image below to see the rendering SWF tester.
Code examples are easy to integrate using the @example and @includeExample (Flex
4), but there is no default way of inserting SWF files directly (as far as I know). In order to insert a SWF file in a generated ASDoc API documentation, one needs to understand the process of generating
documentation with ASDoc. On one side there are packages and classes, on the other side ASDoc templates files. Generating documentation consists for the asdoc.exe application
of parsing the classes for any special comments and injecting what has been found in the templates. The result is output in a directory and is made of a bunch of HTML, CSS, JavaScript files… The type of special comments the ASDoc process is looking for looks
like that :
/**
* Apply an RGB distortion effect on a DisplayObject
*
* @param target The DisplayObject on which to apply the effect
*/
override public function apply(target :
DisplayObject):void{
...
}
Special tags starting with an @ can be used in these comments and will be interpreted
by the ASDoc process. Fortunately HTML tags can be used as well inside these comments and will be output unchanged. I make use of this feature to insert SWF files inside the documentation.
Step 1 : adding the required JavaScript libraries to the ASDoc templates
Note : in the following section you have to download several components to make it works. Ipackaged all of them in a zip file. ASDoc templates are located in a Flex SDK sub-directory by default : FLEX_SDK_DIR\asdoc\templates To
keep unmodified the original templates you can copy this folder outside the Flex directory. In this case to make the ASDoc process being aware of this change use the command parameter -templates-path
‘path/to/your/new/template_folder’ Full ASDoc documentation is located
on Adobe Web site In the template folder locate the file asdoc-util.xsl and in
there search for those lines :
<script language="javascript" type="text/javascript">
<xsl:attribute name="src">
<xsl:value-of select="$baseRef"/>
<xsl:text>asdoc.js</xsl:text>
</xsl:attribute>
</script>
insert the following lines just before the previous ones :
<script language="javascript" type="text/javascript">
<xsl:attribute name="src">
<xsl:value-of select="$baseRef"/>
<xsl:text>jquery.min.js</xsl:text>
</xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
<xsl:attribute name="src">
<xsl:value-of select="$baseRef"/>
<xsl:text>swfobject.js</xsl:text>
</xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
<xsl:attribute name="src">
<xsl:value-of select="$baseRef"/>
<xsl:text>swf-loader.js</xsl:text>
</xsl:attribute>
</script>
As you may guess we will use jQuery and SWFObject to achieve our goal. Download jQuery and SWFObject and
put the files in the templates directory (rename the files to match the previous lines). From the SWFObject download ZIP file, extracts the expressInstall.swf file
in the templates directory as well. The third file is made by myself and will help substitute special HTML tags in the documentation by SWF files. Save the following code in the file templates/swf-loader.js
$(document).ready(function(){
var idBase = "swfLoader";
var idNum = 0;
var width, height;
var params = {
quality: "high",
scale: "noscale",
allowscriptaccess: "always",
bgcolor: "#FFFFFF"
};
var flashvars = {};
$("div[src]").each(function(){
$(this).attr("id",idBase + idNum);
width = $(this).attr('width') || "100%";
height = $(this).attr('height') || "100%";
var flasvarsString = $(this).attr("flashvars");
var flashvarsArray = flasvarsString.split("&");
for ( var i = 0; i < flashvarsArray.length; i++) {
var flasvar = flashvarsArray[i].split(":");
flashvars[flasvar[0]] = flasvar[1];
}
swfobject.embedSWF(
$(this).attr("src"),
idBase + idNum,
width,
height,
"10.0.0",
"expressInstall.swf",
flashvars,
params,
{}
);
idNum++;
});
});
Step 2 : adding special HTML Tag in ASDoc classes comments
Now that the files are in place it’s possible to add special HTML tags in comments to insert SWF files :/**
* Creates an RGB distortion effect (Timed effect).
* <div src='../../../swf/effectTester.swf'
* width='780px' height='550px' flashvars='form:mosaicForm'></div>
*/
The div tag will be replaced by the SWF files located at ‘../../../swf/effectTester.swf’ passing width, height and flashvars parameters.
Flashvars must be of the following form : var1:value1&var2:value2&var3:value3.
Step 3 : where to put the SWF files
Put the SWF files in the doc_output_directory/swf.相关文章推荐
- How To Generate An XML File As A Target Datastore Using ODI In An Integration Interface ? [ID 454268
- How to create an OCM Response file to apply patch in silent mode - opatch silent (Doc ID 966023.1)
- Need to specify class name in environment or system property, or as an applet parameter, or in an application resource file: j
- How to store an image file to SQliteDB in android
- how to make a authorware file in an environment without authorware
- [转]How to insert a row between two rows in an existing excel with HSSF (Apache POI)
- how to use a SQLite database in a standalone program with an HTML interface and VBScript as the programming language
- How to use an external dll file in VisualStudio project
- How To Trace The Remote File Server (RFS) Process In Physical Standby Database (Doc ID 1481125.1)
- How to use an external dll file in VisualStudio project
- git tip: How to undo an uncommitted change/deletion for a specific file in your working directory
- About UID and How to autostart an application on boot up in 3rd- Startup List Management API
- R12: How to add Microsoft Excel as Type to the Create Template List of Values in BI Publisher (Doc ID 1343225.1)
- HowTo compile native C codes to a library for iOS development in Xcode – take Mosquitto as an exampl
- How can I force Python's file.write() to use the same newline format in Windows as in Linux (“\r\n”
- prjGetWriteINIFile - How to Read-Write INI file using VB & API - 读取/写入INI文件 - VB6 + API - SourceCode - HackerJLY
- How to Run a Program as an Administrator in Windows 7
- How to Run a Program as an Administrator in Windows 7
- How to create an XTR file from XML in Delphi XE4 using XML Mapper?(delphi中如何通过xmlmapper创建xtr文件)
- How to provision a Domain Controller as File Share Witness for an Exchange 2010 DAG