PageRenderTime 156ms CodeModel.GetById 142ms app.highlight 9ms RepoModel.GetById 1ms 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
243// common definitions and initial processing
244include_once '../shared/global.php';
245
246// load localized strings
247i18n::bind('help');
248
249// load the skin
250load_skin('help');
251
252// the title of the page
253$context['page_title'] = i18n::s('Help');
254
255// the date of last modification
256if(Surfer::is_associate())
257	$context['page_details'] .= '<p class="details">'.sprintf(i18n::s('Edited %s'), Skin::build_date(getlastmod())).'</p>';
258
259// the prefix hook for the help page
260if(is_callable(array('Hooks', 'include_scripts')))
261	$context['text'] .= Hooks::include_scripts('help/index.php#prefix');
262
263// where to look for information
264$context['text'] .= Skin::build_block(i18n::s('Where to look for information?'), 'title')
265	.'<ul>'
266	.'<li>'.sprintf(i18n::s('%s and change it if you like.'), Skin::build_link('users/view.php', i18n::s('Review your profile'))).'</li>'
267	.'<li>'.sprintf(i18n::s('%s of this site.'), Skin::build_link($context['url_to_root'], i18n::s('Go to the front page'))).'</li>'
268	.'<li>'.Skin::build_link('sections/', i18n::s('Site map')).'</li>'
269	.'<li>'.Skin::build_link('categories/', i18n::s('Categories')).'</li>'
270	.'<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>'
271	.'<li>'.Skin::build_link('search.php', i18n::s('Full-text search')).'</li>';
272if(!Surfer::is_logged() && (!isset($context['users_without_registration']) || ($context['users_without_registration'] != 'Y')))
273	$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>';
274$context['text'] .= '</ul>';
275
276// everybody, but subscriptors, may contribute
277if(!Surfer::is_logged() || Surfer::is_member()) {
278
279	// how to format text in pages
280	$context['text'] .= Skin::build_block(i18n::s('How to format text in pages?'), 'title')
281		.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>')
282		.'<ul>'
283		.'<li>'.Skin::build_link('smileys/', i18n::s('Smileys available at this system')).'</li>'
284		.'<li>'.sprintf(i18n::s('%s (bold, underline, ...)'), Skin::build_link('codes/basic.php', i18n::s('In-line'))).'</li>'
285		.'<li>'.sprintf(i18n::s('%s (and shortcuts, buttons, ...)'), Skin::build_link('codes/links.php', i18n::s('Links'))).'</li>'
286		.'<li>'.sprintf(i18n::s('%s (with bullets, numbered, ...)'), Skin::build_link('codes/lists.php', i18n::s('Lists'))).'</li>'
287		.'<li>'.sprintf(i18n::s('%s (indentation, script, quote, ...)'), Skin::build_link('codes/blocks.php', i18n::s('Blocks'))).'</li>'
288		.'<li>'.sprintf(i18n::s('%s (with headers, with grids, use CSV data, ...)'), Skin::build_link('codes/tables.php', i18n::s('Tables'))).'</li>'
289		.'<li>'.sprintf(i18n::s('%s (and table of content)'), Skin::build_link('codes/titles.php', i18n::s('Titles and questions'))).'</li>'
290		.'<li>'.sprintf(i18n::s('%s (updates, content, ...)'), Skin::build_link('codes/live.php', i18n::s('Dynamic queries'))).'</li>'
291		.'<li>'.sprintf(i18n::s('%s (twitter, calendar, ...)'), Skin::build_link('codes/widgets.php', i18n::s('Widgets'))).'</li>'
292		.'<li>'.sprintf(i18n::s('%s (charts, ...)'), Skin::build_link('codes/misc.php', i18n::s('Miscellaneous codes'))).'</li>'
293		.'</ul>';
294
295}
296
297// locate a reference server
298Safe::load('parameters/scripts.include.php');
299if(isset($context['reference_server']) && $context['reference_server'])
300	$target = 'http://'.$context['reference_server'].'/';
301else
302	$target = 'http://www.yacs.fr/';
303
304// the suffix hook for the help page
305if(is_callable(array('Hooks', 'include_scripts')))
306	$context['text'] .= Hooks::include_scripts('help/index.php#suffix');
307
308// render the skin
309render_skin();
310
311?>