PageRenderTime 48ms CodeModel.GetById 21ms RepoModel.GetById 0ms app.codeStats 0ms

/help/index.php

https://github.com/altatof/altashop
PHP | 311 lines | 45 code | 14 blank | 252 comment | 11 complexity | 175263dde617f98abb67db48542da3eb MD5 | raw file
  1. <?php
  2. /**
  3. * the main help index
  4. *
  5. * [title]What can I do with YACS?[/title]
  6. *
  7. * Following patterns should be considered only as examples of what can be achieved with YACS.
  8. *
  9. * - Weblogging platform - The powerful templating system of YACS supports various skins,
  10. * and let web writers focus on what they have to say. Moreover, each weblogger can have one or more weblogs to post in.
  11. * Actually any YACS section may become a weblog. Of course, an associate may weblog to any section of one site.
  12. * Also, one or several webloggers can be given editors right to any section.
  13. * Note that YACS has been built-in features to ping information between servers, and to let surfers comment and
  14. * discuss any post. Also, posts are automatically archived by weeks and by months.
  15. *
  16. * - Original content publishing - Declare managing editors as associates, ask contributing
  17. * editors to register as regular members. Use the subscription mechanisms to handle the list of
  18. * readers, and that's it. Note that YACS has built-in features to let managing editors review
  19. * articles submitted by contributing editors.
  20. *
  21. * - Knowledge community - Declare experts as associates, and let interested people register
  22. * as regular members. Experts will use YACS to structure and to share their knowledge.
  23. * Each article may be commented by another expert or by any member. Files and links can be attached to
  24. * any article by any member.
  25. * Note that YACS has built-in features to encourage people to share with others.
  26. * For example, each profile lists last contributions of this user.
  27. *
  28. * - Passionate members - When several people have a common category of interest, they can decide
  29. * to setup a YACS server to support their passion, and become associates of this community.
  30. * Other interested people can register as regular member or as simple e-mail subscribers.
  31. * Note that YACS has been built-in features to share information between servers, enabling
  32. * one community to be extended over time.
  33. *
  34. * Web masters that are discovering the yacs environment may use following guidelines
  35. * to reduce the learning curve. We have assumed that you have a quite strong background
  36. * in php, html, etc.
  37. *
  38. * In a ideal world, the three main layers of a good-looking application
  39. * (i.e., presentation, behaviour, and storage) would be clearly separated.
  40. * We have tried to support this principle as much as possible with YACS.
  41. * However, this (good) rule has explicitly been violated where we had to balance with simplicity.
  42. *
  43. * [title]The presentation layer[/title]
  44. *
  45. * The presentation layer is devoted to php pages. No magic, no complicated
  46. * template, php has been designed from the outset to do that. Create a subdirectory,
  47. * put some php files in it, change the main index.php to link it to these files,
  48. * and that's it.
  49. *
  50. * [subtitle]Skins[/subtitle]
  51. * People that want to make most of their pages look similar will use skins.
  52. * Once again, there is no magic here. The basic mechanism is to declare
  53. * a Skin class at the beginning of your file, to assign the page content to some
  54. * variables, and to include a common php file to deliver the final rendering.
  55. * To ease the process, we have created two functions. Basically, you only
  56. * have to call [code]load_skin()[/code] and [code]render_skin()[/code] to do it. Look at the code in
  57. * the main index.php, this should appear clearly.
  58. *
  59. * Do you want to develop your own skin? Fabulous! As a starting point
  60. * you can copy and rename files from the skins/skeleton directory.
  61. * Then change the skin name through the configuration panel at control/configure.php and start to tune your
  62. * new skin until success.
  63. *
  64. * See also: [script]skins/index.php[/script]
  65. *
  66. * [subtitle]Codes and Smileys[/subtitle]
  67. * By default text submitted to any yacs server is filtered to protect from hackers.
  68. * Also, a special set of safe codes are available to beautify your posts.
  69. *
  70. * See: [link]codes/index.php[/link] and [link]smileys/index.php[/link]
  71. *
  72. * [subtitle]Boxes[/subtitle]
  73. * What is static and what is dynamic in yacs? Numerous web systems are offering a
  74. * administration interface to add some boxes on the left or on the right or the main index page.
  75. * But yacs has no specific administration interface. Boxes are coming from ordinary items
  76. * of information, articles or whatever.
  77. *
  78. * During the setup of the server several sections and categories are created to hold or to flag
  79. * pages that have to be put in some boxes.
  80. *
  81. * By posting articles into following sections you will populate the front page of your server:
  82. * - 'covers' - the last published article in this section is used as the main cover of your server
  83. * - 'navigation_boxes' - each article is displayed into its own box on every page of your server
  84. * - 'extra_boxes' - each article is displayed into its own box, at the site front page only
  85. * - 'menus' - the last published article in this section is used as the main menu of your server
  86. *
  87. * By linking existing articles to following categories you will populate some lists:
  88. * - i18n:c('featured') - list featured articles
  89. *
  90. * See also: [link]sections/index.php[/link], [link]categories/index.php[/link]
  91. * (you will have to be logged as an associate to view special sections and categories)
  92. *
  93. * [subtitle]Blogging[/subtitle]
  94. * Well, we are quite proud of it: yacs has been fully tested with w.bloggar, and the combination is really fun and handy.
  95. * Give it a try!
  96. *
  97. * See also: [script]services/blog.php[/script], [link]http://wbloggar.com/[/link]
  98. *
  99. * [subtitle]Localization[/subtitle]
  100. * What about localization? In previous developments I used to have a separate
  101. * file per language to store all strings for this language. While this design
  102. * has proven to be efficient, it adds a big overhead to the software developer.
  103. *
  104. * In yacs, a lightweight mechanism has been selected for localization. When you need
  105. * a string, declare all variations of this string, but use only one. Take a look
  106. * at [code]i18n::s()[/code] in [script]shared/global.php[/script] to understand it. The big advantage of this design
  107. * is that all languages are available at the same time. You may even have some sections
  108. * of your server in english, and other sections in your native language if you want.
  109. *
  110. * See also: [script]shared/global.php[/script]
  111. *
  112. * [title]The behaviour layer[/title]
  113. *
  114. * As you main know ;-) the behaviour layer of a web server is limited to answering
  115. * to un-related queries of web components. Therefore, talking about the behaviour
  116. * of a web server is equivalent to discuss options on submitting requests to the server.
  117. *
  118. * [subtitle]Addressing space[/subtitle]
  119. * Some people have a tendancy to limit the number of scripts, and use complete sets of parameters
  120. * to build dynamic pages. To handle articles, they will have a single script called
  121. * articles.php. To create, edit or view an article, they may use something like 'articles.php?op=new',
  122. * 'articles.php?op=edit&id=12' and 'articles.php?op=view&id=12' respectively.
  123. *
  124. * We prefer to create numerous scripts with one or zero parameters.
  125. * One important reason is that you have to build complete paths to let search engines index your pages
  126. * extensively. To create, edit or view an article, we are using respectively:
  127. * 'articles/edit.php', 'articles/edit.php/12', and 'articles/view.php/12'.
  128. *
  129. * [subtitle]Module programming interface[/subtitle]
  130. *
  131. * Well, apart from common declarations and libraries placed into the shared directory, and of the skin stuff located
  132. * into the skins directory, there is no special programming interface into yacs.
  133. *
  134. * To create you own module, you will to create a new directory and to put callable scripts in it.
  135. * Of course, it helps to look at existing modules to respect coding standards as much as possible.
  136. *
  137. * [subtitle]Overlays[/subtitle]
  138. * If, during some analysis of your needs, you end up with the conclusion that adding some fields to an
  139. * article would suffice, then consider overlays as the faster track to deliver.
  140. *
  141. * For example, overlays can be used to implement cooking recipes efficiently (i.e., with one single script)
  142. * while retaining all feature available for articles (e.g., images, files, links, codes, etc.)
  143. *
  144. * See: [script]overlays/index.php[/script] for a more complete description of overlays
  145. *
  146. * [subtitle]Links and Hooks[/subtitle]
  147. * Once your scripts are running as expected, you will have to link them with other scripts, and with the site front page.
  148. * The most simple action is to update the main menu of your site (section 'menus') or to add
  149. * boxes with adequate information (sections 'navigation_boxes' or 'extra_boxes').
  150. *
  151. * You can also use existing hooks to trigger your scripts.
  152. * This is a very powerful, while straightforward, mechanism, to extend yacs capabilities.
  153. * For example, the script [script]control/setup.php[/script] has a hook to setup database tables
  154. * that are not part of the basic set of yacs tables.
  155. * Likely, the main configuration panel [script]control/index.php[/script] may be extended
  156. * and reference some of your configuration scripts if necessary.
  157. *
  158. * See: [script]control/scan.php[/script] for a more complete description of hooks
  159. *
  160. * [title]The storage layer[/title]
  161. *
  162. * [subtitle]The database abstraction[/subtitle]
  163. * Usually, we have separated most of the code related to the database in dedicated php files.
  164. * This has allowed us to limit the number of scripts interfacing with mySQL.
  165. *
  166. * Consider for example lists of articles. They only differ in the amount of information displayed,
  167. * in the order of rows, and in the number of rows. Moreover, it is very useful to display the same
  168. * list into several different pages.
  169. *
  170. * To make things clearer we have created static classes to support such queries. Do you want a list
  171. * of the newest articles? Call [code]Articles::list_()[/code] and you will fetch a nice array of labels and related urls.
  172. *
  173. * See: [script]articles/articles.php[/script],
  174. * [script]sections/sections.php[/script], [script]categories/categories.php[/script],
  175. * [script]files/files.php[/script], [script]links/links.php[/script], [script]comments/comments.php[/script],
  176. * [script]images/images.php[/script], [script]tables/tables.php[/script],
  177. * [script]users/users.php[/script]
  178. *
  179. * [subtitle]Tables maintenance[/subtitle]
  180. * The creation and the upgrade of the database schema is made by [script]control/setup.php[/script].
  181. * This script uses PHP arrays to build adequate mySQL statement.
  182. * For example, the table storing articles is described in [code]Articles::setup()[/code],
  183. * in the file [script]articles/articles.php[/script].
  184. *
  185. * One innovative feature of yacs is the ability to link items of information on-demand. Therefore,
  186. * the database schema is simple to handle and to extend, as explained in the next paragrah.
  187. *
  188. * [subtitle]Modules and anchors[/subtitle]
  189. *
  190. * In yacs a module is simply defined by a set of php files and by a related set of tables in the database.
  191. * To build a complete page, you will refer to one or several modules by including related php files.
  192. *
  193. * That's fine, but how to link modules together? Things are very easy when you are considering independant modules.
  194. * However, improving the content of your web server usually requires to link the many stored pieces of information.
  195. * On top of that, you would like to be able to reuse existing modules to link them to new ones with almost no modification.
  196. *
  197. * This is where we have introduced anchors. In yacs, anchors are master items that are related to many sub items.
  198. * Consider for example a section of your site. Hopefully this section will contain several articles. We will say
  199. * that the section is an anchor. To refer to this anchor, we will use a type (here: 'section') and an id (e.g., '12').
  200. * Add a colon ':' in the middle, and you will get the full anchor name: 'section:12'.
  201. *
  202. * Now that we have an anchor, it is easy to link articles to it. We simply have defined a field named 'anchor' in the article
  203. * table to store anchor names, and that's it.
  204. *
  205. * Six months later. You have created a brand new module named ancestors to handle genealogical data. Of course, you would like
  206. * to be able to publish articles for each ancestor. How to do that? Well, you will define 'ancestor' as a new type of anchor
  207. * in your system, and store 'ancestor'-based anchors in the articles table. You don't have to alter the articles table to do it.
  208. *
  209. * How to retrieve items related to an anchor? Just ask for it. If you want to list articles in the section 12, select
  210. * items where anchors = 'section:12'. If you want to list articles related to ancestor 34, select items where
  211. * anchors = 'ancestor:34'.
  212. *
  213. * How to retrieve an anchor related to an item? This is necessary to display a valid context around an item. For example,
  214. * an article related to a section may mention some introductory words on the section it is in. But an article related
  215. * to an ancestor may remember the salient dates for this person. Since we don't want to adapt the module that handle articles,
  216. * we have built a simple interface class named Anchor. This interface, which is the only one used within the articles
  217. * module, is implemented in derivated classes such as Category or Ancestor. Take a look at shared/anchor.php for more information.
  218. *
  219. * As a conclusion, if you want to let items behave as anchors for other modules, you will have:
  220. * <ul><li> to name the type of your anchor (e.g., 'mytype')</li>
  221. * <li> to implement the Anchor interface in one php file (e.g., 'mytype.php')</li>
  222. * <li> to update the load_anchor() function in shared/global.php (e.g., on 'mytype:15', prepare the adequate SELECT statement)</li>
  223. * </ul>
  224. *
  225. * The prefix hook is used to invoke any software extension bound as follows:
  226. * - id: 'help/index.php#prefix'
  227. * - type: 'include'
  228. * - parameters: none
  229. * Use this hook to include any text right before the main content.
  230. *
  231. * The suffix hook is used to invoke any software extension bound as follows:
  232. * - id: 'help/index.php#suffix'
  233. * - type: 'include'
  234. * - parameters: none
  235. * Use this hook to include any text right after the main content.
  236. *
  237. * @author Bernard Paques
  238. * @tester Alain Lesage (Lasares)
  239. * @reference
  240. * @license http://www.gnu.org/copyleft/lesser.txt GNU Lesser General Public License
  241. */
  242. // common definitions and initial processing
  243. include_once '../shared/global.php';
  244. // load localized strings
  245. i18n::bind('help');
  246. // load the skin
  247. load_skin('help');
  248. // the title of the page
  249. $context['page_title'] = i18n::s('Help');
  250. // the date of last modification
  251. if(Surfer::is_associate())
  252. $context['page_details'] .= '<p class="details">'.sprintf(i18n::s('Edited %s'), Skin::build_date(getlastmod())).'</p>';
  253. // the prefix hook for the help page
  254. if(is_callable(array('Hooks', 'include_scripts')))
  255. $context['text'] .= Hooks::include_scripts('help/index.php#prefix');
  256. // where to look for information
  257. $context['text'] .= Skin::build_block(i18n::s('Where to look for information?'), 'title')
  258. .'<ul>'
  259. .'<li>'.sprintf(i18n::s('%s and change it if you like.'), Skin::build_link('users/view.php', i18n::s('Review your profile'))).'</li>'
  260. .'<li>'.sprintf(i18n::s('%s of this site.'), Skin::build_link($context['url_to_root'], i18n::s('Go to the front page'))).'</li>'
  261. .'<li>'.Skin::build_link('sections/', i18n::s('Site map')).'</li>'
  262. .'<li>'.Skin::build_link('categories/', i18n::s('Categories')).'</li>'
  263. .'<li>'.sprintf(i18n::s('Index of most recent %1$s, %2$s, %3$s and %4$s'), Skin::build_link('articles/', i18n::s('pages')), Skin::build_link('files/', i18n::s('files')), Skin::build_link('comments/', i18n::s('threads')), Skin::build_link('users/', i18n::s('people'))).'</li>'
  264. .'<li>'.Skin::build_link('search.php', i18n::s('Full-text search')).'</li>';
  265. if(!Surfer::is_logged() && (!isset($context['users_without_registration']) || ($context['users_without_registration'] != 'Y')))
  266. $context['text'] .= '<li> '.sprintf(i18n::s('%s to access more material, and to receive our newsletters'), Skin::build_link('users/edit.php', i18n::s('Register'))).'</li>';
  267. $context['text'] .= '</ul>';
  268. // everybody, but subscriptors, may contribute
  269. if(!Surfer::is_logged() || Surfer::is_member()) {
  270. // how to format text in pages
  271. $context['text'] .= Skin::build_block(i18n::s('How to format text in pages?'), 'title')
  272. .i18n::s('<p>To ease the production of text YACS has a little code interpreter. You will find in pages listed below descriptions of these codes, but also examples of their visual rendering on your system.</p>')
  273. .'<ul>'
  274. .'<li>'.Skin::build_link('smileys/', i18n::s('Smileys available at this system')).'</li>'
  275. .'<li>'.sprintf(i18n::s('%s (bold, underline, ...)'), Skin::build_link('codes/basic.php', i18n::s('In-line'))).'</li>'
  276. .'<li>'.sprintf(i18n::s('%s (and shortcuts, buttons, ...)'), Skin::build_link('codes/links.php', i18n::s('Links'))).'</li>'
  277. .'<li>'.sprintf(i18n::s('%s (with bullets, numbered, ...)'), Skin::build_link('codes/lists.php', i18n::s('Lists'))).'</li>'
  278. .'<li>'.sprintf(i18n::s('%s (indentation, script, quote, ...)'), Skin::build_link('codes/blocks.php', i18n::s('Blocks'))).'</li>'
  279. .'<li>'.sprintf(i18n::s('%s (with headers, with grids, use CSV data, ...)'), Skin::build_link('codes/tables.php', i18n::s('Tables'))).'</li>'
  280. .'<li>'.sprintf(i18n::s('%s (and table of content)'), Skin::build_link('codes/titles.php', i18n::s('Titles and questions'))).'</li>'
  281. .'<li>'.sprintf(i18n::s('%s (updates, content, ...)'), Skin::build_link('codes/live.php', i18n::s('Dynamic queries'))).'</li>'
  282. .'<li>'.sprintf(i18n::s('%s (twitter, calendar, ...)'), Skin::build_link('codes/widgets.php', i18n::s('Widgets'))).'</li>'
  283. .'<li>'.sprintf(i18n::s('%s (charts, ...)'), Skin::build_link('codes/misc.php', i18n::s('Miscellaneous codes'))).'</li>'
  284. .'</ul>';
  285. }
  286. // locate a reference server
  287. Safe::load('parameters/scripts.include.php');
  288. if(isset($context['reference_server']) && $context['reference_server'])
  289. $target = 'http://'.$context['reference_server'].'/';
  290. else
  291. $target = 'http://www.yacs.fr/';
  292. // the suffix hook for the help page
  293. if(is_callable(array('Hooks', 'include_scripts')))
  294. $context['text'] .= Hooks::include_scripts('help/index.php#suffix');
  295. // render the skin
  296. render_skin();
  297. ?>