Module Tutorials

Modules Tutorials - Atlantis CMS

Patterns (pattern-func) examples in the tutorials can be used as HTML attributes within an arbitrary HTML tag

Atlantis Modules Tutorials

Media

The Media section of the administrative panel can be used to add all kinds of media (predominantly images but you can also upload other type of assets such as PDF files). You can also create galleries from those images. You can reduce the file size of your images by relying on the TinyPNG module which will automatically reduce the file size of your image assets whenever you upload one. In terms of galleries, Atlantis comes preinstalled with a gallery that has the ID of 1 and it is named Page Preview. Whatever you put in this gallery, can be chosen from the Related Images tab of the Add/Edit Pages sections of Atlantis.

Since 1.0.2

To be responsive ready, we've added a new feature. You will find a new config field in under the Config menu called 'Responsive Breakpoint Sizes', where you can define where the breakpoints are. The media by default is creating 3 versions of the file you upload based on the configuration you've entered under 'Responsive Images' config. So when editing pages or patterns you can use the following:

copy
img src="large.jpg" alt="" data-responsive
Which on the page output will be converted to this:
copy
picture
    source media="(max-width: 800px)" src="small.jpg" srcset="small.jpg, medium.jpg 2x"

    source media="(min-width: 801px)" src="medium.jpg" srcset="medium.jpg, large.jpg 2x"

    source media="(min-width: 1201px)" src="large.jpg" srcset="original.jpg 2x"
    
    img src="large.jpg" alt=""
picture
Note that max-width, min-width are dynamic and taken from whatever you have entered under the 'Responsive Breakpoint Sizes'.

Events

The Events module allows you to display and manage Events of all types in your website.

Recurring Events

You may have events which occur every Thursday, or every month, or every day. You may not want to display them in a list with start and end dates but show the actual events that are occurring today, every day. The Events module makes that possible with Recurring events. You can define the event's start and end date, which day of the week it occurs, or if it is monthly or daily. Then, you have two options:
You can use the

copy
data-pattern-func="module:events@all-50,12/12/2017"

pattern function to display the events one time until they expire or after their starting period has been reached and show their starting and ending dates to your users or you can display the actual events which occur on any given day and you do not have to worry what date that is, if you have made a weekly event which lasts for months, the actual date when it will occur will be shown with data-pattern-func="module:events@until-12/12/2017,1000". The first parameter to this until function is the end date (only events occurring before that date will be shown) and the second is the limit of events to show.

Locations

You can assign locations to events. You can even add geographic coordinates (latitude and longitude) and display a map in your views.

Custom fields

You can add custom fields to the events and assign a different value for each custom field to better fit your needs.

Featured events

You can mark events as 'featured'. Those events will generally go in the top of the returned event list, if you want to highlight specific ongoing events.

Displaying Events by their categories

Each event can belong to one or multiple categories and you can show only events for specific categories on desired pages. To do so, you can use the pattern:

copy
data-pattern-func="module:events@getEventsByParams-category.oneDate.featuredFirst,2 

The pattern above includes three filters - category, oneDate (which means it will show the events for one date at a time), and featuredFirst (which will show featured events for the day at the top of the event list), the 2 means the category with an ID of 2 will be shown by default. If you use it, you can switch between categories on the page by adding a ?category= GET parameter or by following this URL scheme for your page: http://site.com/events/12-08-2016/4 where the page here is named 'events:any', the first argument is the date for which events are shown and the second is the ID of the category for which events are shown.

Paginating Recurring Events

It is possible that you want to display a large list of recurring events but do not want the users to scroll for ages. You can use data-pattern-func="module:events@untilPaginate-12/12/2017,1000,15 to create a paginated event list with 15 events per page. Then, you can switch your users between pages by adding the GET parameter ?page=[int]

Displaying the dates on which there are events

You can use the data-pattern-func="module:events@datesFilter-12/12/2017, 12/12/2010 pattern to display the months and days on which there are events. The first parameter is until what date to include events and the second from what date to start counting events in the list.

Displaying the list of categories available

You can use the data-pattern-func="module:events@categoriesList" pattern to get a list of all available Event categories that have been added so far.

The Forms Module

Overview of creating forms

After installing the Forms module from the Modules Repository, you can click on Add Form to create a new form. The Forms Module offers a lot of options. Essentially, you can require arbitrary input from your users in various different types of inputs and the Forms module can also validate that the input is what you actually want to receive from them. When the users submit the form, you can choose where the users get redirected to and add your own custom logic (through the Redirect URL After success field). Anyway, after a user submits the form, the data he inputted will be collected and you would be able to see all submitted user data by navigating to the Forms module dashboard (forms listing) and select Export Form to CSV. When adding a new form, you can choose from a variety of input types that you require from the user (text, password, dropdown, etc.) and validations (image, email, etc.).

Displaying a form

To display a form in your website, you can go to the Forms module dashboard (Forms listing). There, you will see a pattern function field, something like:

copy
data-pattern-func="module:forms@build-1"

but with a different number at the end which represent the particular form ID. You can copy that snippet and insert it into any page you would like and the form would be visible and operational on that page. You can, of course, choose to insert the same form on numerous pages and that is perfectly okay.

Form options

You can give a class to the created form so that you can style it later on or add other customizations using the Form Class option. If you wish the users to not see the form again after they successfully submit their data, you can check the Hide form after successful submission option. You may be aware that standard HTTP requests are slower, take more time, and affect negatively the user experience. For that purpose, you can choose to submit the form with AJAX (without the page being refreshed).

Right-side options

In the right side of the Forms menu, there are some more options to be seen.

You can give out a success message which gets shown when users submit the form without having had any validation errors (assuming you set up some validation for the form fields) using the Successful submit message field.

If you are aware with HTML, you can use the Custom Form Attributes field to add HTML attributes the form element. For example, you may want to turn off autocomplete for the form.

It is also possible to add arbitrary text which will be shown before or after the form in the page with the form's pattern or turn off and on Google Analytics for the form (this will help you assess the views,hits and other user activity around the form) and turn off or on CAPTCHA verification (CAPTCHA verification is aimed to protect your form against automated bots which submit the form with spam/malicious/untrustworthy data).

Adding your Form fields

You must give your form fields a name (mandatory). The label will be shown next to the form input. Not every form field type fits with every validation. For example, if you add a form field of type Text it is logical to check if that text represent an Email, number (Numeric) (in the Validation field) and not against a specific file type (such as CSV file).

Dropdown

If you add a Dropdown field, you can add your options in the Value field of the specific Dropdown form field. Here is an example of a dropdown input collecting data whether users are smokers:

copy
no=>I don't smoke
frequent=>I am a frequent smoker

Thus, you add options by specifying their name (you will see both the name and the value in the exported CSV) and the value that the users will see separated by =>. Now, this example shows one more thing. You can add the ::checked text next to an option's value (right-side) to make it selected by default. Similarly, you can add the ::disabled text to lock users from picking the given option.

Text/TextArea

TextArea and Text represent text fields. They are essentially the same except that TextArea offers more space for users to type text. You can validate them to be emails, not empty or alpha-numeric

Password

As you probably guess, this input will show asterisks instead of the user input when selecting

Checkbox

This input could be used to allow the user to select one or more from an arbitrary number of options

Radio button

This input could be used to allow the user to select only one from an arbitrary number of options

Dropdown countries

This input could be used to allow the user to select one of the world's countries

Dropdown states

This input could be used to allow the user to select one of the United States of America states

File

This input could be used to allow the user to upload a file. You can ask for a specific type of file by adding a Validation. For example, you can require the user to upload an image file (with a certain file size as well), PDF file, CSV file and so on.

Datepicker

This would create a datepicker input in which users can select a specific date. You can make sure that the users did not try to cheat by adding a Validation of Datepicker - Valid or Datepicker - Valid - Not empty if you want to make sure that a date is selected.

Custom templates

It may be the case that you want to build the HTML behind your form manually and do not want the built-in view. In that case, you can tick the Use custom template checkbox and build your own template. To show a form field you can use the following notation: {{formElementName}} To show the errors associated with a form field, you can use the following notation (wherever you want in the custom template): {!!formElementName!!} To add a submit button to the custom template, you can use the: {{submit_button}} pattern. As the Form module allows you to add text that will be displayed before or after the form. With custom templates, that before/after text is not shown by default. You would have to manually add them by using the {{before_form_text}} snippet for the text that is entered to be shown before the form and {{after_form_text}} for the text that is supposed to follow the form. If you have entered your CAPTCHA (ReCaptcha) configuration and have turned it on for the chosen form, you can display that CAPTCHA in the custom template using the: {{captcha}} command. Be aware that those commands are not necessary if you are not using custom template, as they will be added to the form automatically

Using CAPTCHAs

To add a CAPTCHA verification (ReCaptcha) to your form, first you need to open the Config section of the module, register and enter your site and secret keys into that configuration and click on Update. Afterwards, you could take advantage of CAPTCHAs by ticking the Use Captcha field when creating or editing your form.

Emailing form results

Whenever a user submits successfully a form, it gets saved on your server/website. You may also want to email the form results to a specific email. To do so, all you have to do is look at the bottom of the add/edit Form page, tick the Should this form email its results field, and select the email from which the form results should appear to be sent from and the recipients of the email.

Adding to email recipients within the Form pattern function

You can use the

copy
data-append-emails="test@mail.com,test1@mail.com"

to append emails to the recipients for form results. You can also use

copy
data-emails="test@mail.com,test1@mail.com"

to define and override and set specific email recipients for the particular pattern.

Setting Default State or Country in the Dropdown Options

In the 'Values' Box set the Following

copy
AL=>Alabamana::checked
Replace with your state, you can right click on your built form and inspect all the state or coutry values. Or you can use ::disable as well, to disable an item.

You create menus in a way similar to the other modules. You have to click on New Menu, enter some information about the menu and set up the menu items. Finally, you can Save and Close the menu and copy the pattern function to any page you like and the menu will appear there. The pattern functions look like this:

copy
data-pattern-func="module:menu@buildByID-5,true