Skip to content

Latest commit

 

History

History
95 lines (84 loc) · 10.7 KB

README.md

File metadata and controls

95 lines (84 loc) · 10.7 KB
Raw

Ninja Demo

Ninja Demo is a commercial plugin available from http://ninjademo.com. The plugin is hosted here on a public Github repository in order to better faciliate community contributions from developers and users alike. If you have a suggestion, a bug report, or a patch for an issue, feel free to submit it here. We do ask, however, that if you are using the plugin on a live site that you please purchase a valid license from the website. We cannot provide support to anyone who does not hold a valid license key.

Setting Up Ninja Demo

Ninja Demo is extremely easy to get up and running; this document will show you how.

1. Create a multisite installation of WordPress

Ninja Demo runs exclusively on multisite WordPress installations to create sandboxes for each of your users.
  • Create a Network.
  • Only use a subdirectory install for your demo site.
  • Make sure your site url and main site title are unique from each other. (i.e. localhost/demo/ - My Demo is not ok, while demo.mysite.com - My Demo is ok.)
Because of its reliance on multisite, it isn't possible to demonstrate multisite-specific products with Ninja Demo.

2. Network Activate Ninja Demo

Ninja Demo should be network activated to give it full access to the main site and all sandboxes.

3. Set up your Ninja Demo settings

Pick the site on your network that you'd like to create sandboxes from. Visit the Ninja Demo settings and configure the options as you would like. At this point, you may want to leave your demo in Offline Mode until you have set up the demo site's content as you intend it to be presented to your users.

4. Set up your main site's content

All that's really left is setting up your site the way you would like for the demo. Some things you might consider:
  • What theme you want activated for your demo.
  • Install and activate any plugins that you will need available.
  • Create any pages, posts, or other site-specific content needed for your demo.
Once you're done, there is only one thing left to do.

5. Add your "Try Demo" shortcode

Once you've gotten your site setup the way you want, you'll add this shortcode to your site: [try_demo].

If you'd like, you can place this shortcode on your main site and clone another subsite by adding the source_id (the ID of the blog that you want to create a sandbox from) parameter to your shortcode: [try_demo source_id=4].

6. Turn off Offline Mode

This will turn your demo on for the world to see. Let people know about your demo and let the sand fly.

Plugin Settings

This is an overview of the Ninja Demo settings page and the purpose of each setting.
  • Offline Mode - Puts the demo into an "offline" state. Both new users who visit and those currently in sandboxes will be shown a message letting them know that the demo site isn't available. All current sandboxes will be removed.
  • Prevent New Sandboxes - New visitors to your demo site will be greeted with the "offline" message, but users who currently have sandboxes will not be disturbed.
  • Auto-Login Users As - When a sandbox is created, the visitor to your demo site will be automatically logged-in with this user account.
  • With this role - What role should this user be given in the new sandbox?
  • Delete All Sandboxes - Does what it says on the tin. Everyone currently using a sandbox that is cloned from this site will be redirected to demo site.
  • Restriction Settings - A white-list of wp-admin pages that a user can access. This doesn't give users capabilities that their role doesn't permit. For example, if your plugin has an admin menu that is restricted to admins, only admin users will be able to see it if the page is checked. Anything in the wp-admin that isn't checked will not be accessible by anyone who is not a network admin.
  • Enable Logging - Create a log file for every sandbox created. These are saved in: WP_CONTENT/nd-logs/

Shortcodes

  • [try_demo source_id=] - This simple shortcode outputs everything you need to allow your users to create their first sandbox. The source_id parameter is optional. If it is specified, the sandbox will clone the desired blog_id. If it is omitted, the source_id will default to the current blog_id. You can place this in a text widget or any page or post to display a simple anti-spam question and a button to begin the demo.
  • [is_sandbox][/is_sandbox] - Use this shortcode to wrap any content that you want to only be displayed if the user is in a sandbox.
  • [is_not_sandbox][/is_not_sandbox] - Use this shortcode to wrap any content you only want displayed on the main site (non-sandbox).
  • [is_sandbox_expired][/is_sandbox_expired] - Use this shortcode to wrap any content that you want displayed to a user returning to an expired sandbox.

    • Action Hooks

    These are the action hooks currently available in the Ninja Demo plugin, along with a description of each. If you are in need of an action hook that isn't currently available, please feel free to contact us or submit a support ticket with the suggestion. We are happy to add reasonable hooks to the plugin.
    • nd_ip_lockout - Fired after a user IP address is locked out. Passes one argument, the user's $ip.
    • nd_create_sandbox - Fired after a new sandbox is created. Passes one argument, the $id of the newly created blog.
    • nd_delete_sandbox - Fired before a sandbox is deleted, whether automatically or manually. Passes one argument, the $id of the blog about to be deleted.

    Filter Hooks

    These are the filters currently available in the Ninja Demo plugin, along with a description of each. If you are in need of a filter that isn't currently available, please feel free to contact us or submit a support ticket with the suggestion. We are happy to add reasonable filters to the plugin.

    Error Messages

    • nd_offline_msg - Message shown to all users when the demo is in "offline mode" or to new users when the "prevent new sandboxes" option is selected. Found in classes/restrictions.php Line 48 and classes/sandbox.php Line 71.
    • nd_block_msg - Message shown to all users when a page has been disallowed. Found in classes/restrictions.php Lines 194, 200, 206, 225, 231, and 305.

    Access Restrictions

    • nd_allowed_pages - Used to white-list pages for view that do not appear in the admin menu and therefore aren't selectable in the Ninja Demo settings. Passed an array of allowed pages like: array( 'options.php', 'index.php' ). Found in classes/restrictions.php Line 93 (See here for a usage example)
    • nd_show_menu_pages - Passed an array of top-level menu pages that were white-listed in the Ninja Demo settings. This can be used to show or hide top-level admin pages to specific users or specific sandboxes. Found in classes/restrictions.php Line 98.
    • nd_show_submenu_pages - Passed an array of submenu pages that were white-listed in the Ninja Demo settings. This can be used to show or hide submenu pages to specific users or specific sandboxes. Found in classes/restrictions.php Line 99.
    • nd_allowed_cpts - Passed an array of allowed post types gathered from the Ninja Demo settings. The array is an associative array of arrays structured like: array( 'post' => array( 'edit' => 1, 'new' => 0 ), 'cpt' =>array( 'edit' => 1, 'new' => 1 ) ). Again, this is a white-list, so post types that are not on this list will be unaccessible.  Found in classes/restrictions.php Line 170.
    • nd_allowed_cts - Passed an array of allowed taxonomies gathered from the Ninja Demo settings. The array is an associative array of arrays structured like: array( 'post_type' => 'categories' => array( 'edit' => 1 ) ). Again, this is a white-list, so taxonomies that are not on this list will be unaccessible. Found in classes/restrictions.php Line 173.

    Sandboxes

    • nd_global_tables - An array of tables that should not be cloned when creating a new sandbox. Found in classes/sandbox.php Line 54.
    • nd_create_redirect - After a sandbox has been successfully created, this is the url that the user will be redirected to. It is passed the address of the current site, along with the blog id for the newly created sandbox. Found in classes/sandbox.php Line 638.
    • nd_purge_sandbox - When a sandbox is purged, or automatically deleted, this filter is passed a bool and the $blog_id. If false is returned from the filter, the sandbox will not be purged. Can be used to keep specific sandboxes alive longer than the 'nd_sandbox_lifespan' setting. Found in classes/sandbox.php Line 279.
    • nd_sandbox_lifespan - By default, sandboxes are destroyed after 15 minutes of inactivity. This filter is passed the amount of idle time allowed in seconds. Found in classes/sandbox.php Line 304.
    • nd_activate_plugin - When a new sandbox is created, should active plugins be re-activated on the new sandbox site? This filter is ran individually for every active plugin and is passed a bool false and the name of the plugin in question. Expects a bool; defaults to false. Found in classes/sandbox.php Line 617.

Other Functions

Here are a few helpful methods and functions that can be used when customizing your demo for product. They can all be called from anywhere in your php files.
  • Ninja_Demo()->is_admin_user() - Returns bool( true ) if the current user is a network admin. Wrapper for: current_user_can( 'manage_network_options' ).
  • Ninja_Demo()->is_sandbox()  - Returns bool( true ) if the code is being used inside a sandbox.