aboutsummaryrefslogtreecommitdiff
path: root/mod/sitepages/README.txt
diff options
context:
space:
mode:
Diffstat (limited to 'mod/sitepages/README.txt')
-rw-r--r--mod/sitepages/README.txt112
1 files changed, 112 insertions, 0 deletions
diff --git a/mod/sitepages/README.txt b/mod/sitepages/README.txt
new file mode 100644
index 000000000..bc4d02007
--- /dev/null
+++ b/mod/sitepages/README.txt
@@ -0,0 +1,112 @@
+Site pages - Quickly generate static pages and customize the front page, CSS, and
+HTML metatags.
+
+CONTENTS:
+ 1. Overview
+ 2. Using Front Page Keywords
+ 2.1 Built-in keywords
+ 2.2 Entities
+ 2.3 Views
+ 3. Custom Front Page Keywords
+ 4. Hints and Quirks
+
+
+1. OVERVIEW
+
+ Site Pages provides a simple way to create static content for About, Terms,
+ and Privacy pages, and also allows simple modifications of the logged in
+ and logged out views, as well as CSS and meta description and tags for SEO.
+
+ The biggest feature of Site Pages is its support for an extensible keyword
+ system that allows end-users to quickly add elements to the front page of
+ their site.
+
+
+2. USING FRONT PAGE KEYWORDS
+
+ Keywords are specially formatted strings that can be used on the logged in
+ and logged out front pages to include lists of objects, views, or plugin-
+ supplied content. All keywords are surrounded by two brackets:
+ [[keyword]]. Some keywords, like views and entity lists, take optional
+ parameters.
+
+ When editing the front pages, a list of available keywords appears in the
+ sidebar.
+
+
+2.1 BUILT IN KEYWORDS
+
+ Site Pages includes a few built-in keywords to get you started:
+ [[login_box]] - This keyword is required on the logged out page to
+ Allow users to log into your site.
+
+ [[site_stats]] - Shows the total members in your site, the currently
+ active members, and other fun stuff.
+
+
+2.2 Entities
+
+ You can generate a list of entities by using the [[entity]] keyword. This
+ keyword takes similar arguments to the elgg_get_entities() function. See
+ documentation in that function for a complete list.
+
+ Additional / changed parameters supported by keywords:
+ * owner: The username owner. (You can still use owner_guid)
+
+ Example: To generate a list of all blog posts by the user named 'admin':
+ [[entities: type=object, subtype=blog, owner=admin]]
+
+ Example: To show newest group created:
+ [[entities: type=object, subtype=group, limit=1]]
+
+
+2.1 Views
+
+ Keywords support outputting arbitrary views with the [[view]] keyword and
+ supports passing arguments as name=value pairs.
+
+ Example: Output a text input field with a default value:
+ [[view: input/text, value=This is a test!]]
+
+ NB: Do NOT quote the name or values when passing them. Also, as of 1.8
+ using commas or = in the name or value is unsupported.
+
+
+3.0 CUSTOM FRONT PAGE KEYWORDS
+
+ Plugins can add their own keywords by replying to the 'get_keywords' hook
+ of type 'sitepages.' Each keyword must be bound to a valid view. Almost
+ all functionality in custom keywords could be implemented using the 'view'
+ keyword, but custom keywords provide a simple way for non-techy users to
+ include ready-made views without the fuss of knowing what they're doing.
+
+ The below example creates the 'my_plugin_keyword' keyword that displays the
+ view at 'my_plugin/keyword_view.'
+
+ This is exactly the same as saying [[view: my_plugin/keyword_view]] but
+ much simpler for the user.
+
+ Example:
+ register_plugin_hook('get_keywords', 'sitepages', 'my_plugin_keywords');
+
+ function my_plugin_keywords($hook, $type, $value, $params) {
+ $value['my_plugin_keyword'] = array(
+ 'view' => 'my_plugin/keyword_view',
+ 'description' => 'Provides the awesome My Plugin keyword'
+ );
+
+ return $value;
+ }
+
+ NB: No variables are passed to the view when using custom keywords.
+
+
+4. HINTS AND QUIRKS
+
+ * A custom keyword is more complicated to implement, but simpler for the
+ end user.
+
+ * The view and entity keywords have limited support for passing arguments,
+ but the arguments cannot contain '=' or ','. If you need complicated
+ arguments, it's best to create a custom keyword with a custom view.
+