SantaPress 1.7.1 - Documentation
SantaPress
Created: 10/20/2019
Last Update: 10/27/2024
By: codemuc® media GmbH
Email: [email protected]
Thank you for purchasing SantaPress. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!
Table of Contents
- Included Files
- Installing SantaPress
- First Steps (Initial Setup)
- Shortcode
- Doors
- Door categories (multiple calendars on your site)
- Quiz
- Global Settings
- Quiz Settings
- Contact Form 7 hidden fields
- Changing the layout
- Hidden Mode
- Updating SantaPress
- Changelog
- Sources and Credits
A. Included Files - top
If you have selected "All files & documentation" before downloading from CodeCanyon, you will find this documentation and the main plugin archive named santapress.zip which contains all necessary plugin files. To get the installable plugin only please select "Installable WordPress file only".
B. Installing SantaPress - top
If you have selected "All files & documentation":
1. Extract the archive santapress_all.zip.
2. Within the extracted files you will find the main plugin file santapress.zip.
3. Within WordPress goto Plugins > Add New.
4. Click the Upload Plugin button and select the main plugin file from step 2.
5. Click "Install now" to install the plugin.
6. Activate the plugin.
If you have selected "Installable WordPress file only":
1. Within WordPress goto Plugins > Add New.
2. Click the Upload Plugin button and select the main plugin file you have downloaded.
3. Click Install now to install the plugin.
4. Activate the plugin.
If you want to know more about managing plugins, you can find more information on the official WordPress website: https://wordpress.org/support/article/managing-plugins/.
C. First Steps (Initial Setup) - top
After installing and activating the plugin, you should see a new menu item appear within your WordPress dashboard called SantaPress.
Please click it to set up the plugin:
For the initial setup you can choose a Start date (usually the 1st of December), the Number of doors (e.g. 24 or 25 doors), a Layout (which can also be changed later) and the Global door type (which can be set to "Content should open in popup/modal window" or "Content should open in a regular window" in this step). In this context the word "Global" means, that the door type will be set as global setting for all doors but can be changed later on each door individually (also you can set the door type to external URL's or WooCommerce products individually on each door later).
Since Version 1.3.0 you can also initialize a Quiz, which "pre"-fills the doors with sample trivia data (questions and answers) and activates the quiz on each door.
Ready to install? Hit » "Save Changes".
D. Shortcode - top
You can integrate the SantaPress calendar by inserting this shortcode to any post, page, custom post type etc.:
[santapress]
If you use the Block (aka Gutenberg) Editor or a Page Builder (like Elementor or WPBakery) you can add a "Shortcode block" (click the plus button, then goto Widgets, select the Shortcode block).
Other page builders may vary, but almost all of them have the option to integrate shortcodes. However, if you can't find it in your editor, you can simply select a text or code module and insert the shortcode here.
Custom number of columns / doors in each row
SantaPress uses a predefined css set, depending on how many doors you have (24 or 25).
However if you need a custom number of doors per row, you can simply add the attribute "cols" to the shortcode, e.g.:
[santapress cols="2"]
For door categories please see: Multiple Calendars.
For the hidden mode shortcode please see: Hidden Mode.
For additional information about using shortcodes, please see the official WordPress website: https://en.support.wordpress.com/shortcodes/.
E. Doors - top
In the WordPress Back-End you can find a new custom post type called "Doors". Here you can see all doors that have been set up for you during the installation. All doors are scheduled to be published on a certain day1. In the overview you can also find the order number for each door and the clicks (if you have enabled click tracking).
If you edit a door, you can set up the Title and the Content on top.
More settings can be made below the editor: You can set up a Door image (or a Custom door image which can be a PNG/JPG file with a recommended image ratio of 1:1, e.g. 500px x 500px or even a SVG file2). Further you can set the global Door type (which can be set to "Use global setting", "Content should open in a regular window", "Content should open in popup/modal window" or "External link (opens a new tab)". Further you can add Custom Javascript (e.g. for tracking codes3).
The shortcode [sp_icon] will display an icon according to the chosen layout.
1 SantaPress uses scheduled posts, a core WordPress functionality which is itself based on a function called wp-cron. This works very well most times, but in some rare cases (e.g. if you have disabled wp-cron or if the site has low traffic the cron might not be prompted to check for scheduled events and the events can be missed. If you experience issues I highly recommend using this plugin: https://github.com/sLaNGjI/wp-missed-schedule
2 If you experience issues with uploading SVG files, this article might be helpful: https://www.wpbeginner.com/wp-tutorials/how-to-add-svg-in-wordpress/
3 Tracking Codes will not work on external links since the tracking relies on the user to open the door post.
F. Door categories (multiple calendars on your site) - top
Starting with version 1.4.0 SantaPress also has the capability to assign doors to special door categories.
This can be useful if you want to have 2 calendars on your site.
You can modify the shortcode to only fetch doors from a certain door category with the parameter cat_id:
e.g.
[santapress cat_id="1"]
G. Quiz - top
Each door can have a quiz which you can activate on each door. By default the quiz will be appended under the post in the front-end, however you can control the position of the quiz by using the shortcode [sp_quiz] in the editor.
Further, you can add a correct and incorrect response on each door individually or use a global response set under SantaPress > Quiz Settings. To use a global response you need to leave these fields empty.
H. Global Settings - top
Under SantaPress > Settings you can find all global settings for SantaPress:
Preview Mode
If this box is checked, all doors will be visible and clickable for preview. This counts only for logged-in administrators.
Show Title
Shows the post title within the modal and regular pages.
Shuffle doors
Shuffles the doors (in shuffle order) each time a user visits the page.
Disable past doors
Disables past doors, so they won't be clickable anymore after the day is over.
Global door type
Can be set to:
- Content should open in popup/modal window
- Content should open in a regular window
Modal max width in px
Sets the max width in px of the modal window when opening a modal
Auto Layout for Modal
Each calendar layout brings its own modal layout. This is what Auto Layout does.
If you disable it you can set up additional modal settings:
- Modal background color » main modal background color
- Modal background color 2 » if a second color is chosen here, the background will be displayed as a radial gradient
- Show Santa hat in modal » shows a santa hat in the upper left of the modal
- Show Pattern in modal » shows a snowflake pattern within the modal
Modal Mode
Ajax is the default and should work in most cases. If you experience problems with the modal contents or use custom plugins that are not officially supported yet (e.g. gallery, forms, quiz plugins etc.) you might want to try iFrame instead.
Enable Snow
Can be set to:
- Disable snow
- Enable snow on the calendar page
- Enable snow only when the modal opens
If you enable snow on the calendar page, it means that the snow will be displayed on the page where the shortcode is embedded.
Click Tracking
Can be set to
- track only logged out users
- track all users (except administrators)
- disable click tracking
The plugin is GDPR conform, so we do not track IP Adresses or personal data. The tracking only tracks how often a door was clicked.
Additional tracking through javascript can be made on each door (see E. Doors).
Custom CSS
Custom CSS can be applied here, here are some examples:
/* santapress custom style examples */
.santapress-post.modal {
/* custom styles for modal window */
}
.santapress-post {
/* custom styles for door post */
}
.santapress-post.modal.post-1269 {
/* you can also target a specific day using the post id */
}
Reset tracking count
Will reset the tracking count on each door - nothing else.
Use with caution: If this box is checked, it will reset the tracking count on each door after you hit save.
I. Quiz Settings - top
Under SantaPress > Quiz Settings you can find all quiz settings for SantaPress.
Following options are available
One-Try only /
Only allow one try per day
If this box is checked, users will only have try/answer per day. Otherwise they can try as much as they want.
Message to the user
Message to the user after the limit was reached
When to set the "One-Try" cookie
You can either set this to "After an answer" or "After the contact form was sent".
"After the contact form was sent" requires to have a Contact form 7 Shortcode placed within the correct or incorrect content.
Correct response
Message to the user after the answer was correct.
You can integrate a Contact Form 7 Shortcode here.
SantaPress will automatically notice and display it.
You can also place a back button here by using the following shortcode along with your message: [sp_quiz_back message="Try again »"]
Incorrect response
Message to the user after the answer was not correct.
You can integrate a Contact Form 7 Shortcode here.
SantaPress will automatically notice and display it.
You can also place a back button here by using the following shortcode along with your message: [sp_quiz_back message="Try again »"]
J. Contact Form 7 hidden fields - top
Starting with version 1.6.3 SantaPress also supports a few hidden fields that you can use in Contact Form 7 to prefill you some data. Please include them in your form. After that you will be able to also include them in your email template.
[hidden santapress_title]
Will populate your contact form with the title of the door post.
[hidden santapress_question]
Will populate your contact form with the Queston of the door post.
[hidden santapress_answer]
Will populate your contact form with the users answer.
K. Changing the layout - top
If you want to make changes to the layout after you have set up SantaPress, you can always go to SantaPress > Layout to change it.
Please note that choosing a new layout will override all existing door images. However:
Changing the layout will not delete any content or other settings (opening type, tracking etc.) you might have already made on each door.
L. Hidden Mode - top
Hidden Mode is a feature that will initially hide the calendar. You can either let the calendar slide it in after a predefined time or you can manually trigger it via a button or a link that you provide. To enable hidden mode you can use this shortcode:
[santapress hiddenmode="true" timeout="800" title="It's Christmas time!" subtitle="We want to celebrate Christmas with our friends and clients. Here's a special gift for you. Have great holidays!" trigger_class=".show-calendar" show_builtin_trigger="true" hide_after_close="false"]
Shortcode Options
hiddenmode
Set to true will enable the hidden mode
Default: true
timeout
Sets the delay in ms for the calendar to appear. If you want to hide it completely (e.g. for using your own trigger) set this paramater to 0.
Default: 800
title
A title for the calendar which will appear above.
Default: ''
subtitle
A subtitle for the calendar which will appear above but under the title.
Default: ''
trigger_class
You can define your own css class that will open the calendar.
After defined, you can use it in your post, page or template file
<a href="javascript:void(0);" class="show-calendar">open calendar</a>
Default: '.show-calendar'
show_builtin_trigger
Shows a little santa in the upper right corner that will open the calendar when the user clicks it.
Default: true
hide_after_close
Hides the calendar after the user has closed it.
Can either be set to:
a.) session - which will hide the calendar for the current session or until the user has closed the browser
b.) midnight - which will hide the calendar until midnight
c.) 48 - which will hide the calendar for 48 hours (you can of course define any number here)
Default: false
GDPR Notice: The variable "hide_after_close" will add a cookie named "sp_hm_exp". No personal information will be stored whatsoever.
M. Updating SantaPress - top
I recommend using the Envato Market WordPress Plugin to receive
updates after you have purchased the plugin on CodeCanyon.
Further after a new version is published, you should get an informal email from Envato about the update.
N. Changelog - top
== Changelog == = 1.7.1 = * Integrated trim() functions to remove empty lines in ajax answers * CSS fixes = 1.7.0 = * Added compatibility with WordPress 6.6.1 * Added compatibility for ACF 6.3.5 * Added compatibility for Contact Form 5.9.8 = 1.6.5 = * Reduced overall filesize * Fix: Check quiz cookie for each door instead of having it bound to one specific door = 1.6.4 = * Updated ACF from 6.0.2 to 6.2.1 * Added compatibility for WordPress 6.3.1 = 1.6.3 = * Added WPCF7 hidden fields (santapress_title, santapress_question, santapress_answer) * Added DE translation * Added CH translation (thanks to Rolf Müri - mm-design.ch) * fix: warning on 404 pages = 1.6.2 = * fix: fix on acf answer boolean fields = 1.6.1 = * fix: acf compatibility = 1.6.0 = * Added compatibility for WordPress 6.0.2 * Added compatibility for ACF 6.0.2 * Added compatibility for Contact Form 5.6.3 = 1.5.4 = fix: added nonce to answers on regular pages fix: IMPORTANT security bugfix while fetching door content through ajax = 1.5.3 = fix: fixed decoding issue in quiz answers = 1.5.2 = fix: javascript execution after ajax call fix: quiz was loading twice in modal due to a content filter function fix: acf path bugfix when acf was detected on site = 1.5.1 = fix: ACF compatibilty fix: using $this->version instead of $version which led to a warning in class-santapress-admin.php fix: ajax request were not passing the content filter (which also adds the quiz automatically if no shortcode was found) = 1.5.0 = * refactor: all public ajax calls are now made by using WordPress ajax functions * feat: comments are now allowed on single door posts (not modal) * feat: users can now choose number of cols via shortcode attribute (see https://santapress.halloecho.de/docs/#shortcode) * fix: acf enqueue warnings when acf was detected on site * fix: stop playing video after closing the modal * fix: moved santaprass scripts to footer * fix: Contact Form 7 (> v5.4) compatibilty (wpcf7.initForm > wpcf7.init) * fix: css adjustment/fixes and security improvements = 1.4.2 = * feat: New option to select an embed mode for modal within global settings - you can now choose between ajax and iFrame integration * fix: door categories display = 1.4.1 = * build: WordPress 5.8 compatibility check => done * build: updated acf version * fix: acf compatibility issues when ACF is already activated on site = 1.4.0 = * feat: door categories * fix: jquery modal compatibility fixes = 1.3.10 = * fix: modal not appearing on some themes (multiple uses of the_content() within the final door page) = 1.3.9 = * fix: compatibly with newer WC versions * fix: prevent SantaPress from hiding custom field on other post types * fix: disable past doors * fix: CSS improvements * feat: added WPML compatibilty = 1.3.8 = * fix: CSS bugfixes (mobile adjustments) * fix: titles in nav menu disappeared when you open doors as _blank pages * feat: show error message in console when modal content can't be fetched = 1.3.7 = * fix: bugfix modal (jquery-modal should run in noConflict() mode) to be compatible with themes that are using bootstrap modal or other plugins (e.g. Avada) * fix: option "disable past doors" returned indexOf undefined because there was no door link in preview mode * fix: when option "show title" was disbled the door post id couldn't be not fetched * fix: minor js bugfix = 1.3.6 = * fix: css bugfix in modal when showing santapress hat and snow flake pattern * fix: php bugfix = 1.3.5 = * fix: bugfix in regular expression * build: 1.3.5 - tested compatibilty with WP 5.5.1 = 1.3.4 = * feat: new variable „hide_after_close“ in hidden mode shortcode = 1.3.3 = * feat: individual correct/incorrect reponses on each door (not only globally) = 1.3.2 = * fix: wpcf7 integration to regular posts (not only after quiz answers) - thanks to Tojama = 1.3.1 = * Code & security adjustments = 1.3.0 = * New Features * Compiled jQuery Modal CSS into santapress CSS * Compiled jQuery Modal JS into santapress JS * Minfied CSS and JS * Introduced Quiz * Bugfixes * Many Code and graphical changes = 1.2.0 = * Added SantaPress snow * Added auto door layouts * Added hidden mode and more shortcodes * Made door type global * Bugfixes * WPMU compatibility = 1.1.0 = * Added different sections in settings page * Localization changes * Code cleanups = 1.0.0 = * Initial Release
O. Sources and Credits - top
- This plugin uses graphics provided by istockphoto and Vecteezy, distributed under extended/commercial licenses.
- For the modal window this plugin uses jQuery Modal, distributed under the MIT License.
- The plugin uses the webfonts Lobster by Impallari Type and Cyreal released under the Open Font License and Bree Serif by TypeTogether released under the Open Font License.
- For the modal and graphical guidance I thank 2freaks.
Once again, thank you so much for purchasing SantaPress. As I said at the beginning, I'd be glad to help you if you have any questions relating to this plugin. No guarantees, but I'll do my best to assist. If you have a more general question relating plugins on CodeCanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.
2019-2024 - codemuc@ media GmbH