goba Mon Aug 12 08:42:31 2002 EDT Added files: /phpdoc/en/chmonly skins.xml specialities.xml Log: Adding information on preferences, example coloring and the first part of the skin development chapter (more to come on that part).
Index: phpdoc/en/chmonly/skins.xml +++ phpdoc/en/chmonly/skins.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <chapter id="chm.skins"> <title>Skin development</title> <para> This edition of the PHP Manual allows users to choose from skins to display the contents, as well as develop custom skins to meet some special needs. We decided to support skins because we realized that one skin cannot satisfy everybodies needs in a such heavily used edition. </para> <para> We included two skins by default inside the CHM. These cannot be modified or removed, so if you have the CHM, you have these two skins inside. The Low skin is optimized for small window display, the High skin is a variation of the Low one with some graphics added to spice it up. </para> <para> A skin must have at least two files, a skin loader JavaScript file and a CSS file. The two inline skins have thes files inside the CHM. The skin loader JS should at least load in the CSS file and display the page contents to the viewer. Theoretically there are two kinds of skins: CSS skins and Full skins. CSS skins only modify the CSS and does not amend the page layout. Full skins also modify the page layout. We have included sample skins for both the CSS skin type and the Full skin type. </para> <sect1 id="chm.skins.display"> <title>Page Display Process</title> <para> If you are going to develop your own skin, you should now how one page is loaded and displayed to the user, and how a skin fits in this process. For these paragraphs, we assume that you have put your CHM into <filename>c:\phpmanual</filename>, so it's accessible as <filename>c:\phpmanual\php_manual_LANG.chm</filename> (where LANG is the language code), and you would like to see the function page of "echo", which is <filename>function.echo.html</filename> inside the CHM. See the <link linkend="chm.integration">sections about integration</link> for more information on CHM contents. <itemizedlist> <listitem> <simpara> First of all the HTML content is loaded in from <filename>function.echo.html</filename>. </simpara> </listitem> <listitem> <simpara> At the top of this file, there is a HTML <script> tag, which loads in the <filename>_script.js</filename> file from the CHM. This file contains all the JS code needed to move on with the process. Most importantly this JS defines many variables (like where the CHM is, or what is the actual page viewed) and many functions to print out the context menu or handle online functions. </simpara> </listitem> <listitem> <simpara> At last <filename>_script.js</filename> loads in the preferences file from outside the CHM (in <filename>c:\phpmanual</filename> in our example). This JS file defines the preference variables, and calls back <literal>prefHandler()</literal> which is also defined in <filename>_script.js</filename>. </simpara> </listitem> <listitem> <simpara> That function loads in the skin JS file as the preferences dictate. The sknin JS file should load in the needed CSS file, and define a <literal>displayPage()</literal> function, which displays the page if called. </simpara> </listitem> <listitem> <simpara> The HTML file (<filename>function.echo.html</filename> in this example) also contains a function call to load in the user notes, which simply puts the notes into this HTML file using DHTML to be displayed as if they were here before... </simpara> </listitem> <listitem> <simpara> The HTML file also contains a body onload attribute which calls the skin-defined <literal>displayPage()</literal> function to show the page to the user. This is the last function called, it should present the page in it's complete form to the user. </simpara> </listitem> </itemizedlist> Every action is syncronized with calling back a function in the previously loaded file when the JS is in memory. The notes loading and skin JS loading is only syncronized with the page's onload event (which as the Microsoft documentation says only fires if the page is completely loaded). </para> <para> This load and callback chain may seem to be too complicated, but so far this seemed to be the best way to do as many things as possible paralelly, while also syncronize some calls. </para> <para> As you can see your skin JavaScript file is loaded in by <filename>_script.js</filename> and it's <function>displayPage()</function> function is called by the body onload event. </para> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 --> Index: phpdoc/en/chmonly/specialities.xml +++ phpdoc/en/chmonly/specialities.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <chapter id="chm.specialities"> <title>Specialities of this Edition</title> <para> The Windows HTML Help Edition of the PHP Manual overperforms the presentational and interactive capabilities offered by other editions (including the online manual). This was possible because currently CHMs can only be viewed on Windows using Internet explorer, so we can develop for one browser family and one operating system. Viewers for other OSes may be developed in the future by third parties. </para> <sect1 id="chm.specialities.prefs"> <title>User Preferences</title> <para> Most of the interactive features of this manual are provided by the viewer application (including full text search, index, favorites list), but we extended this list with PHP Manual specific tools. All these can be adjusted to your needs using a simple desktop application named <filename>php_manual_prefs.exe</filename>. If you run this program you can see three groups of settings: Online Functions, Context Menu, and Skin. All your settings are stored in <filename>php_manual_prefs.js</filename>. </para> <para> Online functions enable you to have elements connected to websites. The two ones you can see on all manual pages are "This page online" and "Report a bug". As you can figure out the first one shows you the same page in the online manual, the second one opens a page from <ulink url="&url.php.bugs;">&url.php.bugs;</ulink> and prefills some bug data for you. You need to select a mirror site to use for "php.net sensitive" online functions. We recommend choosing a close mirror site to get the best speed. Other components that may be limited by this online functions setting include context menu items opening new websites ("Google search selection" for example). Custom designs may also include elements restricted by this setting. </para> <para> The context menu settings enables you to override the system default context menu provided by the HTML Help Viewer and define your own by selecting from a list of predefined menu elements. Three special types of context menu items exist: <table> <title>Context menu items</title> <tgroup cols="3"> <thead> <row> <entry>Type</entry> <entry>Examples</entry> <entry>Comments</entry> </row> </thead> <tbody> <row> <entry>Page Jump</entry> <entry>Function Reference, Function Index</entry> <entry> These items jump to a specific page in the CHM. Page Jump options are not restricted to point inside the CHM though. They can point to websites or other resources. Page jump options with a protocol part in the URL open in new window. </entry> </row> <row> <entry>Function Call</entry> <entry>Print page, Select all, Copy selection to clipboard, Google Search Selection</entry> <entry> These are "function calls" for internally defined context menu functions. The last two examples have the speciality that they only show up in the menu if you rightclicked on a selection. Currently there is no way to extend the context menu with skin defined functions. </entry> </row> <row> <entry>Special display</entry> <entry>Google SearchBox, AlltheWeb SearchBox</entry> <entry> These are displayed as HTML forms, where you can enter search keywords, press ENTER, and receive a new window with the search issued in the appropriate search engine. Currently there is no way to extend specialy displayed context menu items. </entry> </row> </tbody> </tgroup> </table> Possible context menu elements and their "abstract implementations" are stored in <filename>context.ini</filename>. You have the ability to add possible page jump options there, but there is no way currently to extend the context menu system with user (skin) defined functions. The possible mirror sites are listed in <filename>mirrors.ini</filename>. Feel free to suggest more bundled context menu items to us at <ulink url="mailto:&email.php.doc.chm;">&email.php.doc.chm;</ulink>. </para> <para> The skins setting enables you to choose from the two bundled default skins, or from any user defined skins. The Low skin is optimized to display correctly at any small size, the High skin is optimized for your viewing pleasure. Other skins may be developed according to our skins development guide. The recommended place for skins on the file system is the <filename>skins/SKINNAME</filename> subfolder of the PHP Manual directory. Though this is not required, some skins may define other rules (not recommended). We included sample skins for you to see examples of how to develop skins for the PHP Manual. </para> <para> You have three buttons to choose from at the bottom. The Apply button applies your changes without exiting, the OK button applies and closes the application, the Cancel button does not modify your settings and closes the program. </para> </sect1> <sect1 id="chm.specialities.presentation"> <title>Presentational Specialities</title> <para> This edition of the PHP Manual is highly optimized for screen presentation. Skins may be developed to better support printing, as this was not the goal of the included skins. This approach allowed us to make many modifications to the presentation of different parts of the manual. </para> <para> The first thing you'll notice is that all examples are color coded, using the PHP function <function>show_source</function>. The actual colors used are defined by CSS classes. Examples also have links to PHP functions used in them to provide quick access to reference material. All code examples have a "copy to clipboard" link by the side of them with which you can copy the text contents of the example to the clipboard. </para> <para> External links are marked with a special » sign, and open in a new browser window. We also included the "path to this page" information on all pages for you to easily identify where you are and navigate as needed. </para> <para> Other parts of the manual are quite similar to the online ones by default, though custom skins can modify many elements on the pages. </para> </sect1> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t indent-tabs-mode:nil sgml-parent-document:nil sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 -->
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php