App Within Minutes Application

Last modified by Admin on 2024/02/26 12:15

application_form_addCreate collaborative web applications within minutes, based on XWiki's powerful structured data management system
TypeXAR
Category
Developed by

XWiki Development Team

Rating
4 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Compatibility

XWiki 3.3RC1+

Installable with the Extension Manager

Description

This application aims to allow end users use XWiki's powerful structured data management system to make collaborative web applications with as little steps as possible. The focus is on solving most common use cases when creating applications. We are not trying to include all types of features (like notifications, complex fields or workflows). These can be added by programmers.

Features

Application Wizard

Start by clicking on "More applications" from the "Applications" panel and then on "Create your own!". This will take you to the App Within Minutes home page.

applications-panel.png

There you can see listed the existing applications. Click on the "Create Application" button to start the wizard.

AppWithinMinutes-Step0.png

Application Location

In the first step you have to provide the application name and location, which will determine the application home page URL. The application code will be generated as nested pages inside the specified location.

AppWithinMinutes-Step1.png

Application Structure

In the second step you define the application structure, i.e. the type of data the application will handle. At the end of this step the wizard will create for you:

  • a page to hold the application structure
  • a template page to store the default field values and to be used ("copied") when creating new application entries
  • a sheet that will be used to display and edit the application entries
  • a translation page to help localize the application

AppWithinMinutes-Step2.png

Field Palette

The second step of the App Within Minutes wizard helps you define the type of data your application will handle. The field palette lists the available field types. Most of these field types are mapped directly to XClass property types:

AppWithinMinutes-FieldPalette.png

Field TypeXClass Property Type
Short TextString
Long TextTextArea
NumberNumber
BooleanBoolean
Static ListStatic List
PagePage
DateDate
UserList of Users
GroupList of Groups
Database ListDatabase List

See the XWiki Data Model documentation to understand what an XClass is and what are all the available property types. The consequence of this mapping is that most of your application structured data will be stored in objects (XClass instances) attached to your application entries (documents). In fact, in this step the App Within Minutes wizard creates an XClass for your application.

Some field types, such as Title and Content are not mapped to an XClass property type but to a document field instead. Visually there's no difference between a Short Text field and the Title field. The difference comes from how the value is stored. In the case of the Title field the value will be stored in the title of an application entry (document). Same with the Content field: the value will be store in the content of the application entry (what you can edit in Wiki edit mode). This has a limitation though: you can use at most one Title/Content field per application.

Application Entries

In the third step you can configure the location where the application entries will be created. The information you enter here will be used in the Create Page dialog.

AppWithinMinutes-Step3.png

Application Presentation

In the last step you can customize the way the home page of your application will look like. You can specify:

  • the application title and description
  • the columns to display in the entries live table
  • the icon to be used on the Applications panel (since XWiki 4.2)

AppWithinMinutes-Step4.png

Home Page

At the end the wizard takes you to the home page of your application, which is the place from where you can manage the application data: edit the application structure, add new entries, edit or delete existing ones.

AppWithinMinutes-HomePage.png

Entry Pages

With the application in place you can now start creating application entries, either using the "Add new entry" link from the application home page or by using the standard Create button and selecting the application entry template that has been generated for you by the application wizard. Each application entry you create is saved as a separate wiki page. The fields of an application entry can be edited in place (since XWiki 12.3).

AppWithinMinutes-EntryPage.png

Applications Panel Entry

Starting with XWiki 4.2 your application is listed in the Applications panel, with the icon you've chosen:

AppWithinMinutes-PanelEntry.png

Create Page Template

Since XWiki 8.4 you can create application entries not only from the application home page ("Add new entry") but also from the Create Page dialog (like you would create a normal wiki page).

AppWithinMinutes-CreatePage.png

Rename Application

Starting with XWiki 11.1 you can rename/move an application by renaming/moving its home page. Note that you can change the application title without renaming the application just by editing the application home page. Be aware that the application code is going to be regenerated if you rename the application, in order to work with the new application location. Code customizations will be overwritten as a consequence, but you can rollback the changes afterwards.

Renaming AppWithinMinutes applications that have been published and installed as XWiki extensions through the Extension Manager is prevented because they usually have custom code that cannot be updated automatically on rename and also because upgrading such a renamed application will lead to many merge conflicts.

Also note that the application code is not updated automatically if the application location changes as a result of renaming or moving one of the parent pages of the application. For instance, if the application is located in Path / To / Books and you rename the "Path" parent page to "New Path" preserving children then you'll get the following warning when visiting the application home page:

awm-rename-parent.png

In order to fix the application code you need to edit the application and go through all the steps of the application wizard, updating the application configuration if necessary.

Customization

Before you start customizing your application you should understand:

Application Pages

All the application pages are generated inside the location specified in the first step of the application creation wizard. The code pages are grouped under the Code page and are marked as hidden (so your users don't see them by default). The location where the application entries are created is configured in the third step. By default the application entries are created directly under the application home page.

appStructure.png

The AppWithinMinutes wizard creates the following wiki pages initially:

  • The application home page (Holiday)
    • The Preferences page (WebPreferences) which gives administration rights over the application's home page and its children to the application creator (so that he can delete all the application's pages)
    • The Code parent page, where the application code is located
      • The class, defining the structured data managed by your application (e.g. Holiday Class)
      • The template provider, which exposes your application in the Create Page dialog (e.g. Holiday Template Provider)
      • The sheet, which is used to display and edit application entries (e.g. HolidaySheet)
      • The template, which keeps the default values to fill when creating new application entries (e.g. HolidayTemplate)
      • The translation bundle, which can be used to internationalize the application (e.g. HolidayTranslations).

Among the advantages of having this separation between code and data, there is:

  • Ability to hide the Edit application options to your users by denying the Edit right on the application's Code page and all its children. This way you can precisely control which users on your wiki are allowed to edit your application and your regular users won't be able to edit/break your application by mistake.
  • Ability to control which users can add new entries or edit/delete existing entries by allowing or denying the Edit right on the application's data location and all its children. 
  • Ability to easily backup your application's data
  • Better overall organization
  • etc.

Before 8.4

There was no "Entries" step (currently the third step) so you couldn't configure the location of your application entries. The location used was the Data page right under the application home page.

Before 7.4M1

The application wizard was creating a custom live table results page (e.g. Holiday RequestLiveTableResults) in order to load the live table translations on demand. Starting with 7.4M1 the translations are loaded on wiki or user scope (based on user rights) and thus we don't need this page any more.

Before 7.3-rc-1

Each application is split into 2 XWiki spaces. If your application is named 'Meeting Manager' then your application's data pages will be stored in the space named 'Meeting Manager' (i.e. the space with the same name as the application) and your application's code pages will be stored in the space named 'MeetingManagerCode' (i.e. the name of the application, minus some special characters such as whitespace, plus the 'Code' suffix).

Before 6.2-milestone-1

Each application corresponds to an XWiki space. Both the application's code documents (class, template, sheet, translations, etc.) and the application's data documents (the entries created by the users) are stored in the same space (the space with the same name as the application).

Localization

Starting with version 4.5 the AppWithinMinutes wizard generates a document translation bundle for the application which allows you to translate class field pretty names, list values (for static list fields) and live table columns names. If you have an application that was created with an older version of AppWithinMinutes you just have to edit and save it to get the new translation bundle.

If your wiki is setup for multilingual support then on the application home page, in the application menu, you have an entry to translate the application. The link takes you to the document translation bundle which is a wiki page so it can be translated in other languages like any other wiki page.

When editing an application you have the option to update the translation bundle. Note that for the moment the translation bundle (its default language) is regenerated so you may lose translation keys you added yourself. In the future we plan to update the translation bundle preserving the custom keys you add.

See the application internationalization guide and the localization module documentation on how to use translation keys in scripts within your application.

Live Table

The live table offers many configuration options that are not available when editing your application. You have to edit the application home page in wiki edit mode to be able to use all the available configuration options.

Post Processing

You can execute code after an application entry is created/edited by using the notification system. Here's an example where the title of a page is adjusted after the page is created/edited.

Color theme

The color theme of your application can be changed from the administration section of your application's data space. Use the 'Space' > 'Administer Space' top menu, then follow 'Look & Feel' > 'Presentation' section.

Field Palette

The field palette from the class editor (second step of App Within Minutes wizard) can be customized easily. You can control both the list of field categories and the list of field types from each category. Field categories are determined by AppWithinMinutes.FormFieldCategoryClass. It's enough to add an object of this class to a wiki page to make it a field category. As you'll see this class has only one property, the priority, which specifies the position in the list of categories on the field palette. The category title is actualy the title of the wiki page.

Field types are determined by AppWithinMinutes.FormFieldClass. Before you add a new field type you need to create a new XClass property type because normally a field type is mapped to a property type as we've shown above. Supposing you have created the "External Image" property type (as explained in the linked tutorial) let's see how we can add a field type based on it.

First of all you need to create a new wiki page. The title of this wiki page will be the title of the new field type and thus will appear on the field palette. We'll use "External Image". Next you need to add an object of type AppWithinMinutes.FormFieldClass to the page we've just created to let App Within Minutes know that this page describes a field type.

AppWithinMinutes-NewFieldType-AddObject.png

You need to specify:

  • the field category
  • the icon that will appear on the field palette before the field title; you can choose an icon from the Silk icon set, as you can see in the image above, or you can attach an icon to this wiki page and put the file name in the icon input
  • the priority, which is the index inside the specified category on the field palette
  • the list of editable meta properties of the corresponding property type; these are the configuration options that you will get for this field type

Save and edit this page using the class editor. We now have to define a template for the "External Image" field type. To do so you just have to add a property of type "External Image" and set the meta properties to the default values you'd like to have when you drag an "External Image" field from the palette to the field canvas in the class editor. Basically, this property template will be copied whenever you add a new "External Image" field to your application.

Save and you're done. Now let's create a new application, or you can edit an existing one. In anycase, you should see the "External Image" field added to the field palette under the right category.

AppWithinMinutes-NewFieldType-Palette.png

Add an "External Image" field to your application and look at the field configuration. You'll see the configuration options that you have listed previously in the AppWithinMinutes.FormFieldClass object.

AppWithinMinutes-NewFieldType-ConfigureField.png

Rights Configuration

Disable Access to the App but Allow to Create Entries from Another Space

From App.WebHome, go to Administer Page, Users & Rights, Rights: Page & Children.
Change the Rights there, for example, check View Rights for XWikiAdminGroup only.

Once done, for all the pages listed below, enable View rights for XWikiAllGroup:

  • App.Code.AppTemplate
  • App.Code.AppTemplateProvider
  • App.Code.AppSheet

Tutorials

On the FAQ Tutorial AWM page you can find a tutorial about how to create a simple FAQ Application using App Within Minutes

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-appwithinminutes-ui 16.1.0):

Tags:
    

Get Connected