App Within Minutes Application

XWiki Enterprise comes with the "App Within Minutes" wizard to help you create collaborative applications within minutes which are based on the XWiki Enterprise structured data management system. 

View Your XWiki Applications

To display your available web applications, click on "More applications" then on "Create your own" link in the "Applications" panel to the left.

AppWithinMinutesApplicationsPanel.png

You should then see the main page containing a livetable with all your web applications.

AppWithinMinutesMainPage.png

Create an XWiki Application

To create an application, go to the 'AppWithinMinutes' home page and click on "Create Application" which will open a wizard to guide you through the process.

Set the Name

The first step consists of establishing the name of the application which is used to determine:

  • the name and URL of the home page
  • the URL of the application's Code location
  • the URL and name of the class containing the structure of the application

WizardStep1.png

You can use the "Location" field to set the location of the page hierarchy where to create the application. To modify the default location (i.e. under the wiki's "Main" location), click on the blue editing pen icon and select the parent. You may leave the field empty in order to create a top-level page.

SetAppLocation.png

You can also click the blue hierarchy icon and select the parent from the page tree or to search for it using the integrated finder.

SetAppLocationTree.png

Click on the "Next Step" button once you are done.

Define the Structure of the Application

The second step is about defining the class containing the application structure. The available fields are mapped directly to XClass property types:

App Within Minutes FieldXClass Property Type
Short TextString
Long TextTextArea
NumberNumber
BooleanBoolean
Static ListStatic List
DateDate
UserList of Users
GroupList of Groups
Database ListDatabase List

or mapped to a page field:

  • Content for which the value will be stored in the content of the application entry i.e. the content editable in "Wiki" or "Wysiwyg" mode
  • Title for which the value will be stored in the title of an application entry
Note that you will only be allowed to use one "Content" or "Title" field per application.

Supposing you want to create an application which lists all your present and former employees, you will need 8 properties in the class:

  • a "Title" field for the title of the application entry
  • a "Short Text" field for the first name
  • a "Short Text" field for the last name
  • a "Short Text" field for the email address
  • a "Static List" field for the availability of each employee: active or inactive
  • a Date Picker for the ending date of the contract
  • an "User" field for the manager
  • a "Content" field for any additional comments

To do so, you just have to drag and drop the fields from the palette to the right. For the first name, last name and email address we will choose the "Short Text" field.

WizardStep2.png

"Short Text" is the default "pretty name" of the property. In order to change it to "First Name", click on the text and start editing. You will notice that the background color will change.

WizardStep2EditPrettyName.png

To configure the property, hover it and click on the key icon in the top right corner.

WizardStep2EditProperty.png

In the input just below "First Name" you can enter the default value to use when creating employee entries. The "Name" text-box refers to the name of the class property. 

When you are done, click on the green "Accept" icon in the top right corner to apply the changes.

WizardStep2PropertySaved.png

In case you have changed your mind about using this field, you can delete it by clicking on the red "X" in the top right corner.

For the other 2 fields, "Last Name" and "Email", just repeat this process.

For the "Title" property you must know that visually there is no difference between this field and a "Short Text" field. 

WizardStep1Title.png

In order to define the availability of each employee, we will use a "Static List" field. By default, there are 3 options available.

WizardStep2StaticListOptions.png

To configure the list, click on the "key" icon in the top right corner. If you want to add an option, enter the "Value" and the "ID" then click on the green "+" icon.

WizardStep2EditStaticListOption.png

To remove an option, hover it and click on the "X" in the top right corner.

WizardStep2RemoveStaticListOption.png

Add the "Inactive" option and save the changes.

WizardStep2FinishStaticList.png

For the ending date of the contract, drag-and-drop the "Date" picker field from the palette. You may change the date format and specify the current date as default value by selecting the "Empty Is Today" check-box.

WizardStep2DatePicker.png

For the "Manager" column we will use the "User" field. The XWiki Enterprise User Picker is used by default by all the XCLASS properties of type "List of Users". 

WizardStep2User.png

The picker displays the user avatar and a link to the user profile and it allows you to select one or multiple default values, provided the "Multiple Select" option is checked.

WizardStep2UserSingleton.png

If the "Multiple Select" option is checked, each selected user will be added to the list above the picker.

WizardStep2UserMultipleSelect.png

In case you want to delete the default value in singleton mode, you may either select another user or hover the current user name and click on the red "X" in the top right corner.

WizardStep2DeleteUser.png

In multiple select mode, you may remove all the users from the list by clicking on the "Clear selection" link.

Visually, the "Content" field is equivalent to a "Text Area" property and it will load the default editor you have set in your user preferences page.

WizardStep2Content.png

Click on the "Next Step" button when you are done.

Entries Restrictions

Starting with version 8.4, the App within Minutes wizard has a new step - Entries - that generates a template provider allowing to expose the application in the "Create Page" dialog. This means that from now on you can create entries from both the application home page and using the "Create Page" dialog.

WizardEntriesStep.png

You may associate a Font Awesome icon and a description to the template provider - these 2 elements will be displayed in the "Create Page" dialog. The full list of supported icons is available in the page IconThemes.FontAwesome.

The field "From where to create the entries" allows to enforce visibility restrictions i.e. decide on which locations the application's template provider will be visible to an user who wishes to create entries. To so so, click the + icon and select them from the page tree - in case you don't specify any location, the template will be available from any wiki page.

AWMPageTree.pngAWMLocationsVisibility.png

The second type of restrictions - the field "Where to create the entries" - refers to the list of locations where the template provider of the application allows to create entries. By default, the users are allowed to create pages only in the location storing the application home page (Employees in our case).  

AWMLocations

Another implicit effect of creation restrictions is the automatic fill of the location in the "Create Page" form. This means that the parent location field will be pre-filled with one of the template restrictions, provided the newly selected template has a creation restriction. The restrictions will used in the "Create Page" form to validate the location field.

CreationRestrictionPrefill.png

On the other hand, if the "Don't enforce entry location" option is checked, then the creation restrictions will be used simply for identifying the default parent location that is pre-filled in the creation screen. The user will still be able to change the parent and choose an option outside the restrictions.  

CreationRestrictionSuggestion.png

Customize the Home Page

The last step allows you to customize the web page of your application, by adding a description and by managing the columns of the livetable in which the entries will be displayed.

WizardStep3AddDescription.png

To add a column, select it from the drop-down list then click on the green "+" button. Your may choose between the generic livetable columns or you may add the ones corresponding to the fields created earlier.

WizardStep3AddColumn.png

To remove a column, hover it and click on the "X" in the top right corner. It is also possible to move the columns from right to left with a simple "drag and drop".

WizardStep3RemoveColumn.png

You may associate an icon with your application by providing a reference to an 16x16 icon. In order to make the image selection easier, App Within Minutes provides an icon picker with a default preview for Font Awesome icons. 

AddIconFontAwesome.png

The other available icon set is Silk which corresponds to the images located in the "\webapps\xwiki\resources\icons\silk" folder on your filesystem.

AddIconSilk.png

Click on "Finish" to see the home page of your web application.

AppHomepage.png

The new "Employees" application will then appear in the "Applications" panel to the left.

IconAddedLeftApplicationsPanel.png

At this point, you have 2 options: go back on editing the application class or start adding entries.

Edit the Application

App Within Minutes User Roles

In older XWiki Enterprise versions, the entire structure of an application created with App Within Minutes (class, sheet, template, translation pages and so on) was stored in the same location as the application entries. The main issue was the fact that it was not possible the separate users with rights to modify the application structure from the ones with privileges limited to the application entries only.

This is why XWiki Enterprise has introduced support for user roles and a Code location which is marked as "hidden". The "Code" location holds:

  • The application class page, <CustomAppName>Class
  • The template provider, <CustomAppName>TemplateProvider for exposing the application in the "Create Page" dialog
  • The application sheet, <CustomAppName>Sheet
  • The application template, <CustomAppName>Template
  • The application translation page, <CustomAppName>Translations

ApplicationCodeHome.png

The old Data location was removed and now all application entries are created by default under the application home page. To change this setting, use the fields

  • "From where to create the entries"
  • "Where to create the entries"

and the option "Don't enforce entry location" as explained in the previous section.

This way, you can have a dedicated permissions scheme for:

  • users who can edit or delete the application's structure like the sheet, template and class page and application code pages in general.
  • users with privileges to create, edit and delete application entries, but who cannot modify the application structure.
Before version 7.4, the application wizard was creating a custom live table results page in order to load the live table translations on demand. Starting with 7.4, the translations are loaded on wiki or user scope, based on user rights and as a consequence the LiveTableResults page was removed.

Besides the "Code" location, the App Within Minutes wizard creates the following wiki pages initially:

  • The application home page having the same name as the application.
  • The Preferences page from which you can grant administration rights to the application creator in order to be able to delete all the application entries. In this page you can define a group with privileges to modify the application entries. 

ApplicationsStructure.png

A user with privileges to modify the application structure will see the "Actions" panel below

ApplicationsPanelAllPrivileges.png

whereas users with rights limited to the application entries will see the "Actions" panel below.

ApplicationsPanelLimitedPrivileges.png

Backward compatibility is preserved, so you should still be able to edit existing applications that don't have the new page organization.

Translate Your Application

The App Within Minutes wizard generates a page translation bundle which allows you to translate the pretty names of class properties and livetable columns. In this case there are 2 scenarios. If you already have an application which was created with App Within Minutes, you will just have to edit it and save it in order to generate the new translation bundle. In case your wiki is set for multilingual support go to the application home page and click on "Translate Application" in the "Actions" menu.

TranslateApplication.png

The link will redirect you to the page translation bundle. If you don't need to modify any translation keys, just scroll down and save the page. 

DocumentTranslationBundle.png

Edit the Application Class

In the application home page, click on the "Edit Application" link located in the "Actions" panel.

EditAppClass.png

You will then get back to the second step of the wizard. In order for the changes to be reflected on the class sheet and the class template, the options "Update Class Sheet" and "Update Class Template" are selected by default. 

The App Within Minutes wizard now comes with an extra option in case you want to update the translation bundle. However, for the default language of the application the translation is regenerated each time so you may lose your custom translation keys.

UpdateAppClass.png

Edit the Application Home Page

Click on "Next Step" and you will be redirected to the third step of the wizard where you may modify the description, change the icon as well as the way the columns are displayed. Click on "Finish" when you are done and you will get back to the application main page.

Add Entries

To create an entry either:

  • Go to the application home page and click on the "Add New Entry" link located in the "Actions" panel. A popup will appear, requiring to specify the name of the entry.

    AddEntry.png

  • Go to any location specified in the field "From where to create the entries", click the "+" button and select the option "Employees" under "Type" -> "Templates". As explained in the previous section the parent field should be pre-filled.

    AddEntryCreateScreen.png

By clicking on the green "+" or on the "Create" button respectively, the new page will open in "Inline" mode and will contain all the class fields you have added earlier. To enter a date, just click inside the "Contract Ending Date" text-box which will open the calendar picker.

AddDate.png

After filling in all the fields, click on "Save & View".

FillInFields.png

You will then see the wiki page containing the new entry.

EntryAdded.png

The new entry is also listed in the livetable from the application home page.

EntryAddedLivetable.png

Edit an Entry

To edit an entry, go to the application home page and click on the corresponding "Edit" button in the "Actions" column of the livetable (see in the above image).

Delete the Application Entries

To remove all the application entries without deleting the application, go to the application home page and click on "Delete All Entries".

DeleteEntriesPanel.png

Next, click on "Yes" to confirm and send all the application entries to the recycle bin.

DeleteEntriesConfirm.png

Delete an Application

To delete an application, go to the home page then click on "Delete Application" in the "Actions" panel.

DeleteApplication.png

You will then see an information message announcing you that all pages in the space "Employees" will be moved to "Recycle Bin". Click on "Yes" to confirm.

ConfirmAppDeletion.png

To restore the application, you will have to restore each page of the code and data space. To do so, navigate to the wiki index and click on the "Deleted Pages" tab. Next, enter the value "Employees" in the "Page" column and click on the green icon located in the last column for each page. 

AppRecycleBin.png

In order to correctly restore the values for each field of the class entries, the restore order should be as follows:

  • the application home page (Employees) and preferences page (Preferences)
  • the code space preferences page (Code.Preferences)
  • the application class
  • the application sheet
  • the application template
  • the template provider
  • the translation bundle
  • each of the application entries

       

Search this space