About This File
Create forms for CSS design purposes with ease! The CSS Shell app adds new Form Elements that parse and interface CSS code as form input rows.
The app currently includes (other than the actual CssShell class) the sub-classes: Border, BorderRadius, BoxShadow and Gradient (experimental). Each can be used to easily generate its suggested name's CSS code. You can also use these classes as a reference when deriving your very own CSS Shell sub-classes.
Why CSS Shell?
While it's true that creating CSS code is possible using the current form element classes, the process would be tedious for large-scale element redesigns, especially with more complex CSS and even more-so during the value parsing phase.
The CSS Shell was designed to support a simpler interface, one which allows input and output of CSS data with the ease of any old form element class. This becomes extremely useful when generating multi-part CSS code.
Another issue to address was the interface structure, since any form that contains a number of fields for every single piece of data would become extremely demanding in terms of screen-usability.
The last piece of interface support was a preview template, which has a JS controller overlooking its 'Apply preview' button, and allows for a real-time preview of CSS designs, from within the actual form.
CSS Shell in a Nutshell
With a CSS Shell object, you basically have a form element that represents a single line of CSS code, which means you can input and output CSS code as strings.
The CSS Shell is a form element, but also a form in its own right; Use the add(...) method to add regular form elements into the CSS Shell, and they will hold the different parts of the CSS code.
For instance we could have a CSS Shell which generates a 'padding' CSS code with a default value of '1em 5px -5%' and a matching (or higher) amount of Number inputs added to it. There is no real need in designating default values for the Number inputs, since the default CSS code string will be parsed and set onto the appropriate input element upon addition.
Once the form is submitted, retrieving the CSS line is as simple as retrieving any form element value - just get the value from the values array, it will all be in one place, parsed and ready to apply!
Some DEV API:
The CSS Shell object is created like any other Form Element - that means that you call the constructor the exact same way you normally would for any form element.
The above example will create a 'padding' CSS Shell which will default to '1em' and have an unlimited checkbox in order to allow clearing it altogether. The shell will also attach a preview to the '#previewDiv .ipsUserPhoto img' element, and be contained in the '#padding_input_container' element.Code:$paddingInput = new \IPS\cssshell\CssShell( 'padding_input', isset( $defaultValue ) ? $defaultValue : '1em', FALSE, array( 'key' => 'padding', 'preview' => 'previewDiv', 'selector' => '.ipsUserPhoto img', 'unlimited' => '', 'unlimitedLang' => 'none' ), NULL, NULL, NULL, 'padding_input_container' ); $paddingInput->add( new \IPS\Helpers\Form\Number( 'padding_number' ), array( 'suffix' => 'em' ) );
Notice the 'key', 'preview' and 'selector' options? They are the ones to look out for if we want our CSS Shell to automatically attach a preview to a specific preview template.Code:/** * @brief Default Options * @code $defaultOptions = array( 'key' => '...' // The CSS key for this shell. Default is NULL. 'preview' => '...' // The ID of the element to do preview on. Default is NULL. 'selector' => '...' // A selector inside preview element to apply preview to. Default is NULL. 'unlimited' => '...' // If any value other than NULL is provided, an "Unlimited" checkbox will be displayed. If checked, the value specified will be sent. 'unlimitedLang' => 'unlimited' // Language string to use for unlimited checkbox label. 'unlimitedToggles' => array(...) // Names of other input fields that should show/hide when the "Unlimited" checkbox is toggled. 'unlimitedToggleOn' => TRUE // Whether the toggles should show on unlimited checked (TRUE) or unchecked(FALSE). Default is TRUE 'unlimitedIsTheme' => FALSE // Whether unlimited option is a theme variable. Default is FALSE. 'disabled' => FALSE // Disables input. Default is FALSE. 'endSuffix' => '...' // A suffix to go after the unlimited checkbox. ); * @endcode */
- The 'key' option is the CSS code this shell input represents. An example would be 'width', or 'color'. The JS preview controller uses this key to parse the left hand side of the CSS code.
- The 'preview' option is the ID for the preview template, and without it the shell won't attach a preview to the preview template at all.
- The 'selector' option is a CSS selector inside the preview template. This is used to allow doing preview on different elements within a single template.
How about the default value for the object? The element parses CSS strings, without the 'key' being included. That means only the right-hand side of the CSS code will be going into and out of the shell. The left-hand side is not included so as to ease output of theme variablesusing CSS shells.
Further API and demonstrations will be provided in the support thread!